Self-Hosted Deployment

Quick Start (Self-Hosted Setup)

Get Orcha Agent OS running locally on your workstation or private server in under 5 minutes using Docker Compose and the automated bootstrap script.

Prerequisites

Node.js 20+ & pnpm / npm

Required for running Next.js SaaS frontend & API server.

Docker & Docker Compose

Runs self-hosted Convex, MySQL, Prometheus, Grafana, and embeddings.

Clerk Account

Handles multi-tenant organization authentication & JWT tokens.

LLM API Key (OpenAI / Anthropic)

Provides underlying model intelligence for semantic SQL synthesis.

One-Command Setup (Recommended for Windows / PowerShell)

Orcha includes an automated bootstrap script (setup.ps1) that launches Docker containers, provisions local self-hosted Convex admin keys, syncs schema definitions, and configures local environment variables in a single step:

powershell

.\setup.ps1

💡 Tip: Use .\\setup.ps1 -SkipBuild to skip Docker image rebuilds, or .\\setup.ps1 -SkipDeps to skip npm install on subsequent runs.

Manual Step-by-Step Setup

1Clone & Install Dependencies

bash

git clone https://github.com/your-repo/orcha-agent-os.git
cd orcha-agent-os
npm install
npm install mysql2 pg

2Launch Local Docker Infrastructure

Starts the self-hosted Convex backend, sample databases, Prometheus metrics collector, and Grafana:

bash

docker-compose up -d

3Generate Admin Key & Configure Convex Secrets

Generate an admin token from the running backend container:

bash

docker compose exec backend ./generate_admin_key.sh

Set up encryption and authentication environment variables inside Convex:

bash

npx convex env set ENCRYPTION_KEY "YOUR_LOCAL_KEY" --url http://localhost:3210 --admin-key "convex-self-hosted|YOUR_KEY"
npx convex env set CLERK_ISSUER_DOMAIN "https://your-clerk-domain.clerk.accounts.dev" --url http://localhost:3210 --admin-key "convex-self-hosted|YOUR_KEY"

Deploy database schemas and serverless functions to the self-hosted instance:

bash

npx convex deploy --url http://localhost:3210 --admin-key "convex-self-hosted|YOUR_KEY"

4Run Next.js Application Server

bash

npm run dev

Open http://localhost:3000 to start exploring the Modeler, Command Center, and Databook.

Troubleshooting & Windows Tips

Pipe Character Escaping Error in PowerShell

If running npx convex fails with '{key_part}' is not recognized as an internal or external command, invoke the CLI through Node directly:

powershell

node node_modules/convex/bin/main.js deploy --url "http://localhost:3210" --admin-key "convex-self-hosted|YOUR_ADMIN_KEY"

Node.js IPv6 DNS Resolution (Clerk "fetch failed")

If Clerk authentication fails with network timeouts on Node 18+, configure Node to prioritize IPv4:

powershell

[System.Environment]::SetEnvironmentVariable("NODE_OPTIONS", "--dns-result-order=ipv4first", "User")