OwnPilot Setup Guide

This guide covers setting up OwnPilot from scratch, including prerequisites, automated setup, and manual configuration.

Prerequisites

Required Software

Software	Version	Purpose
Node.js	22+	Runtime
pnpm	10+	Package manager
Docker	Latest	PostgreSQL database
Git	Latest	Version control

OS-Specific Setup

Windows

1. Install Node.js 22+: https://nodejs.org/
2. Install Docker Desktop: https://www.docker.com/products/docker-desktop/
3. Install pnpm: npm install -g pnpm

macOS

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js 22
brew install node@22

# Install Docker Desktop
brew install --cask docker

# Install pnpm
npm install -g pnpm

Linux (Ubuntu/Debian)

# Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt-get install -y nodejs

# Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# pnpm
npm install -g pnpm

---

Automated Setup (Recommended)

Quick Start

Linux/macOS

git clone https://github.com/ownpilot/ownpilot.git
cd ownpilot
./setup.sh

Windows PowerShell

git clone https://github.com/ownpilot/ownpilot.git
cd ownpilot
.\setup.ps1

The interactive wizard will guide you through the complete setup.

Setup Modes

Mode	Description
Full (default)	Complete setup: Docker, dependencies, database, build, dev server
Minimal	Only install dependencies and create .env
DockerOnly	Only Docker + PostgreSQL database
SkipInstall	Skip pnpm install (for already installed deps)

Usage Examples

# Linux/macOS
./scripts/setup.sh --minimal          # Skip Docker
./scripts/setup.sh --docker-only      # Only database
./scripts/setup.sh --skip-install     # Already have deps

# Windows PowerShell
.\scripts\setup.ps1 -Mode Minimal
.\scripts\setup.ps1 -Mode DockerOnly
.\scripts\setup.ps1 -Mode SkipInstall

---

Manual Setup

If you prefer to set up manually or need more control:

1. Clone Repository

git clone https://github.com/ownpilot/ownpilot.git
cd ownpilot

2. Install Dependencies

pnpm install

3. Configure Environment

# Copy example environment file
cp .env.example .env

Edit .env with your settings. The defaults work with Docker Compose PostgreSQL:

# Server
PORT=8080
UI_PORT=8199
HOST=127.0.0.1
NODE_ENV=development

# Database (Docker Compose defaults)
POSTGRES_HOST=localhost
POSTGRES_PORT=25432
POSTGRES_USER=ownpilot
POSTGRES_PASSWORD=ownpilot_secret
POSTGRES_DB=ownpilot

# Authentication
AUTH_TYPE=none

# Logging
LOG_LEVEL=info

4. Start PostgreSQL

Option A: Docker Compose (Recommended)

docker compose --profile postgres up -d

Option B: Manual Docker

docker run -d \
  --name ownpilot-db \
  --restart unless-stopped \
  -e POSTGRES_USER=ownpilot \
  -e POSTGRES_PASSWORD=ownpilot_secret \
  -e POSTGRES_DB=ownpilot \
  -p 25432:5432 \
  -v ownpilot-postgres-data:/var/lib/postgresql/data \
  pgvector/pgvector:pg16

Wait for PostgreSQL to be ready (usually 5-10 seconds):

docker exec ownpilot-db pg_isready -U ownpilot

5. Initialize Database

cd packages/gateway

# Run initial schema (if exists)
psql -h localhost -p 25432 -U ownpilot -d ownpilot -f src/db/migrations/postgres/001_initial_schema.sql

# Or use seed script
pnpm run seed

6. Build Project

pnpm build

7. Start Development Server

pnpm dev

---

Starting OwnPilot

Development Mode

# Linux/macOS
./start.sh

# Windows PowerShell
.\start.ps1

Start Options

Option	Description
--dev	Development mode with hot reload (default)
--prod	Production mode (build & serve)
--docker	Start with Docker Compose
--no-ui	Gateway only, without UI
--port PORT	Gateway API port (default: 8080)
--ui-port PORT	UI dev server port (default: 8199)

Manual Start

# Install dependencies (if not done)
pnpm install

# Start development servers
pnpm dev

---

Services & URLs

After starting, these services are available:

Service	URL	Description
Gateway API	http://localhost:8080	REST API server
UI	http://localhost:8199	Web interface
PostgreSQL	localhost:25432	Database

---

Configuration

AI Providers

AI provider API keys are configured via:

1. Web UI: Config Center (Settings page)
2. CLI: ownpilot config set <provider>-api-key <key>

Supported providers:

• OpenAI (OPENAI_API_KEY)
• Anthropic (ANTHROPIC_API_KEY)
• Google (GOOGLE_API_KEY)
• Azure OpenAI (AZURE_OPENAI_*)
• Ollama (OLLAMA_BASE_URL)
• Custom LLM endpoints

Environment Variables

Variable	Default	Description
PORT	8080	Gateway API port
UI_PORT	8199	UI dev server port
POSTGRES_HOST	localhost	Database host
POSTGRES_PORT	25432	Database port
NODE_ENV	development	Environment
LOG_LEVEL	info	Logging level

---

Docker Compose Profiles

Profile	Services	Usage
postgres	PostgreSQL	Database only
(default)	All	Full stack

# Database only
docker compose --profile postgres up -d

# Full stack
docker compose up -d

---

Troubleshooting

Port Already in Use

# Find process using port 8080
lsof -i :8080    # macOS/Linux
netstat -ano | findstr :8080  # Windows

# Kill process or change PORT in .env

PostgreSQL Connection Failed

# Check if container is running
docker ps | grep ownpilot

# Check logs
docker logs ownpilot-db

# Restart container
docker restart ownpilot-db

pnpm Install Failed

Close VS Code (locks native .node modules on Windows) and retry:

pnpm install

Node.js Version Too Old

# Check version
node --version

# Update via nvm (recommended)
nvm install 22
nvm use 22

# Or reinstall from nodejs.org

---

Additional Resources

• Architecture Overview
• Database Schema
• API Reference
• Deployment Guide
• Contributing Guide