Deployment
This page covers running OrcFlows beyond a local make start — building production binaries, what each piece of infrastructure is for, and what to swap out for a hardened deployment.
Binaries
make build
produces three binaries in bin/:
| Binary | Entry point | Role |
|---|---|---|
bin/api | cmd/api | HTTP API server (chi router), serves /api/v1/*, /webhooks/*, /run/*. Stateless — scale horizontally behind a load balancer. |
bin/worker | cmd/worker | Temporal worker — polls goagents-main and goagents-fast task queues and executes workflow steps. Scale horizontally; Temporal handles work distribution. |
bin/cli | cmd/cli | Database migrations (migrate up/migrate down) and admin tasks. |
The frontend (web/) is a static SvelteKit build:
cd web && npm install && npm run build
Serve web/build/ from any static host or CDN, with PUBLIC_API_URL (or equivalent build-time config) pointing at your API server's public URL.
Infrastructure dependencies
docker-compose.yml is a development stack. For production, replace each piece with an appropriately managed equivalent:
| Component | Dev (docker-compose.yml) | Production guidance |
|---|---|---|
| PostgreSQL | postgres:16-alpine, port 5433 | Managed Postgres (RDS, Cloud SQL, etc.) with backups and connection pooling (PgBouncer). All app state lives here — see Multi-Tenancy & Data Model. |
| Redis | redis:7-alpine, port 6380 | Managed Redis for caching/rate limiting. |
| Temporal | temporalio/auto-setup + temporal-ui | Self-hosted Temporal cluster (Postgres-backed) or Temporal Cloud. Set TEMPORAL_HOST_PORT/TEMPORAL_NAMESPACE accordingly, and TEMPORAL_ENCRYPTION_KEY for payload encryption (see Temporal Execution Model). |
| SearXNG | self-hosted container | Keep self-hosted (no external API key needed for web_search), or point agents at a paid search API instead. |
Chromium (chromedp/headless-shell) | local container, port 9222 | Run as a sidecar next to each worker, or a shared browser pool; set PLAYWRIGHT_WS_ENDPOINT. |
| Weaviate | optional, port 8082 | Only needed if Knowledge Bases use the Weaviate backend (large-scale RAG). Postgres float4[] + cosine_similarity works without it. |
| MinIO | port 9000/9001 | Swap for real S3 (S3_ENDPOINT, S3_BUCKET, credentials) — used for workspace files exported from the sandbox. |
| LiveKit | --dev mode | Self-hosted LiveKit cluster or LiveKit Cloud for livekit-* voice/video nodes. |
| Docker (sandbox) | Docker Desktop socket | Workers need access to a Docker daemon to run the sandbox — either Docker-in-Docker, a sibling Docker socket mount, or a remote Docker host per worker pool. Build the sandbox image (goagents-sandbox:latest) and ensure it's available wherever workers run. |
Configuration
All runtime configuration is environment variables — see Configuration Reference for the full list. At minimum for production:
- Set a strong, random
JWT_SECRET(also used to derive the AES-256-GCM key for secrets/OAuth encryption — rotating it invalidates existing encrypted secrets). - Set
TEMPORAL_ENCRYPTION_KEY(base64 32-byte key). - Configure
DATABASE_URLto point at managed Postgres. - Configure OAuth redirect URLs (
*_REDIRECT_URL) to your real public domain. - Set LLM provider API keys, or leave them unset and require per-tenant keys via the credential picker.
Migrations
Run bin/cli migrate up (or make migrate) against the production database before starting the API/worker for the first time and after every deploy that adds a migration in internal/db/migrations/.
Scaling model
- API server — stateless, scale by adding instances behind a load balancer. SSE execution streams are per-instance long-lived connections; use sticky sessions or a load balancer that supports long-lived HTTP/2/SSE connections.
- Worker — scale by adding instances; Temporal distributes activities across all workers polling the same task queues. Separate worker pools can be dedicated to
goagents-main(heavy: agents, code, STT/TTS) vsgoagents-fastif you need different instance sizes. - Sandbox containers — one Docker container per execution that uses code/terminal tools, destroyed on completion. Ensure the Docker host(s) backing your workers have enough headroom (512 MB / 1 CPU per concurrent sandboxed execution, per the sandbox limits).
Health & observability
GET /healthz(API) for load balancer health checks.- Temporal Web UI (port 8081 in dev) for inspecting workflow execution history independent of the OrcFlows UI.
audit_eventstable for security-relevant actions (see Teams, Organizations & Roles).- Workflow health checks surface stuck/long-running executions per workflow.