Production

Reverse proxy

The workspace uses Server-Sent Events for realtime — your proxy must not buffer them.

Caddy (TLS included, simplest):

workspace.yourcompany.com {
    reverse_proxy /v1/* backend:8000 { flush_interval -1 }
    reverse_proxy frontend:3000
}

nginx:

location /v1/ {
    proxy_pass http://backend:8000;
    proxy_buffering off;          # SSE
    proxy_read_timeout 120s;      # long-polls
    proxy_set_header Connection '';
    proxy_http_version 1.1;
}
location / { proxy_pass http://frontend:3000; }

Then set CORS_ORIGINS=https://workspace.yourcompany.com on the backend and NEXT_PUBLIC_API_URL=https://workspace.yourcompany.com on the frontend (same-origin via the proxy keeps CORS simple).

Scaling

• 1 replica: Postgres is enough.
• 2+ replicas: set REDIS_URL — poll caching and event fan-out require it.
• Watch Postgres connections: replicas × workers × pool_size must stay under your server's limit. Front with pgbouncer beyond ~2 replicas (this is how the hosted deployment runs).
• The backend is CPU-light and IO-bound; 2 vCPU / 4 GB per replica is a comfortable start for tens of concurrent users + agents.

Health & monitoring

• GET /health → liveness for your orchestrator.
• Structured logs on stdout; ship them wherever you ship logs.

Security notes

• Keep AUTH_MODE=workspace_token instances off the public internet or treat tokens as passwords (they are).
• Set CORS_ORIGINS explicitly — the * default is for development.
• Run migrations (alembic upgrade head) as a pre-deploy step, not at runtime, when you have multiple replicas.