Self-Hosting

If you want full control over your data and infrastructure, you can run Orcha on your own server. The setup is a single script, and updates are a one-liner.

Prerequisites

• Hardware: 2 CPU cores, 4 GB RAM, 20 GB disk (more for large file uploads)
• OS: Linux with Docker and Docker Compose installed
• Network: A domain name with a DNS A record pointing to your server’s public IP

Quick start

Clone the repository, run the setup script, and start the stack:

git clone https://github.com/whileTrueYield/orcha.git
cd orcha
./orcha-setup.sh
make prod

The setup script walks you through configuration: domain name, email provider, admin credentials, and secrets. It generates your .env file and TLS certificates are handled automatically on first boot.

Encryption at rest

Orcha encrypts stored secrets at rest with AES-256, and the backend will not boot without a key. Set ORCHA_ENCRYPTION_KEY in your .env to a real, 32-byte base64 value, unique per environment:

openssl rand -base64 32

Set this before first boot, and don’t change it

Rotating the key invalidates everything previously encrypted with the old one, and there is no rotation tooling yet, so treat it as fixed for the life of the environment. Keep it out of version control and back it up alongside your database.

Architecture

Orcha runs as a Docker Compose stack behind a Traefik reverse proxy. Traefik handles automatic TLS via Let’s Encrypt and routes traffic by path:

Path	Service
/	Frontend (React/Vite)
/api	Backend (Node.js/TypeScript)
/ws	Hocuspocus (real-time collaboration via Yjs CRDTs)
/scheduler	Scheduler (Python)
/uploads	MinIO (file storage)

The backend is Node.js/TypeScript with Hocuspocus handling real-time collaboration. The scheduler is a separate Python service that uses NumPy to sample PERT distributions during Monte Carlo simulation — it runs independently and communicates results back to the backend.

All services run on a single machine. Traefik is the only container that binds to ports 80 and 443.

Connect a coding agent

Your self-hosted instance exposes the same external surface as the hosted service: a REST API and an MCP server under your backend’s /api path. Connect MCP clients over OAuth (preferred) — note that OAuth requires Orcha to be served over HTTPS, which the Traefik setup above already provides. Coding agents without browser OAuth can use the alternative: a Personal Access Token.

Email

Orcha needs an email provider for invitations and notifications. The setup script supports two options:

• SMTP: Any standard SMTP server (Postfix, Mailgun, SES, etc.)
• Resend: API-based delivery — just provide your API key

Configure your choice during setup. You can switch later by editing the .env file and restarting.

Backups

Three things to back up:

# Postgres -- your projects, tickets, and team data
pg_dump -U orcha orcha > backup.sql

# MinIO -- uploaded files and attachments
tar -czf minio-backup.tar.gz ./data/minio

# Redis is ephemeral -- used for caching and pub/sub only, no backup needed

Run these on a cron schedule that matches your tolerance for data loss. Daily is a reasonable starting point.

Updating

Pull the latest changes and rebuild:

git pull && make prod

Docker Compose rebuilds only the containers that changed. Migrations run automatically on startup. Downtime is typically under a minute.