Deploy for a team
Choose a deployment
| Run from source | Docker (single server) | Your own production setup | |
|---|---|---|---|
| Command | python start.py | python ops/self-host/deploy.py up | Run the Hub yourself |
| Database | SQLite | PostgreSQL 16 in Compose | Your PostgreSQL |
| Reachable from | This computer | This server; your team through your HTTPS proxy | Your team |
| Secrets | Generated in the data directory | Generated in deployment.json | Your secret store or environment |
| Guide | Run from source | Deploy with Docker | This page |
The Docker launcher covers most single-server teams. Use this page if you run the Hub with your own process manager, reverse proxy and database.
Production requirements
Set SODUWORK_ENV=production. The Hub then refuses to start unless all of these are true:
| Setting | Requirement |
|---|---|
DATABASE_URL | PostgreSQL, for example postgresql+asyncpg://soduwork:<PASSWORD>@db.example.com:5432/soduwork. SQLite is not allowed |
ADMIN_PASS | Set, and not a known default |
AUTH_SECRET | A strong random signing key, not a known default |
CORS_ORIGINS | Explicit origins. * is not allowed |
DEVICE_AUTH_COMPAT | false |
HUB_PUBLIC_URL | The HTTPS address people use, for example https://work.example.com |
Outside development, the Hub never generates missing secrets for you.
Also set:
CONNECTOR_OAUTH_KEYto encrypt connector authorizations.DB_MIGRATION_MODE=autofor a single instance, so versioned migrations run at start. Never run two migrations against the same database at once.
Keep these values in your secret manager or environment, not in a committed file. Use a dedicated database and a least-privilege database account.
Run the Hub
cd hub-backend
python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 9080
Build the admin console with npm ci && npm run build in hub-frontend/. When hub-frontend/dist exists, the Hub serves it on the same origin. Use GET /healthz for liveness and GET /readyz for readiness.
Reverse proxy
Put an HTTPS reverse proxy in front of the Hub.
- Forward HTTPS to the Hub's local port.
- Support WebSocket upgrades. Clients and runners use WebSockets.
- Allow long streaming responses and file uploads.
- Don't add
/apior credentials to the public address.
After it's live, check sign-in, file upload, a WebSocket connection and a streaming chat through the proxy.
Where work runs
The Hub doesn't need to run agents. Local work runs in each client, and cloud work runs on registered runners (Runners and cloud environments). In the Docker setup, HUB_LOCAL_EXECUTION_ENABLED=false keeps agents out of the Hub container.
Multiple Hub nodes
The launchers set up one node. Several Hub nodes need shared file storage and coordination that you design yourself.