Hub configuration
The Hub reads settings from environment variables or a private .env file in hub-backend/. Names are case-insensitive; this page uses upper case. The source launcher and the Docker launcher set the values they need for you.
Never commit .env. Keep secrets in a secret manager or the deployment environment.
Environment and database
| Variable | Default | Notes |
|---|---|---|
SODUWORK_ENV | development | production turns on the production checks |
DATABASE_URL | sqlite+aiosqlite:///./box_hub.db | Use postgresql+asyncpg://… outside development |
DB_MIGRATION_MODE | auto | auto migrates at start (single instance). check expects a release job to migrate first |
DB_POOL_SIZE | 10 | 1–100 |
DB_MAX_OVERFLOW | 20 | 0–100 |
DB_POOL_TIMEOUT | 15 | Seconds, 1–120 |
DB_POOL_RECYCLE | 1800 | Seconds, at least 60 |
DB_STATEMENT_TIMEOUT_MS | 30000 | 0 disables |
Identity and access
| Variable | Default | Notes |
|---|---|---|
ADMIN_USER | admin | Used only to create the first administrator when there are no users |
ADMIN_PASS | empty | Generated in development; required otherwise |
AUTH_SECRET | empty | Signing key for tokens. Generated in development; required otherwise |
TOKEN_TTL_HOURS | 168 | Seven days |
CORS_ORIGINS | * | Comma-separated. * is refused in production |
DEVICE_AUTH_COMPAT | true | Must be false in production. Accepts legacy device headers during a migration |
HUB_PUBLIC_URL | empty | The HTTPS address people use. Required in production; used for OAuth callbacks |
OIDC_HTTP_TIMEOUT_SECONDS | 10 | Timeout for enterprise SSO calls |
Execution
| Variable | Default | Notes |
|---|---|---|
HUB_LOCAL_EXECUTION_ENABLED | true | Whether the Hub itself may run agents. The Docker setup sets false |
CLOUD_EXECUTION_RUNNER_IDS | empty | Comma-separated allowlist of runner IDs for cloud chats. Empty keeps normal routing |
OFFLINE_AFTER_SECONDS | 30 | When a silent client counts as offline |
Connectors
| Variable | Default | Notes |
|---|---|---|
CONNECTOR_OAUTH_KEY | empty | Fernet key that encrypts connector authorizations |
CONNECTOR_GOOGLE_CLIENT_ID, CONNECTOR_GOOGLE_CLIENT_SECRET | empty | Google app |
CONNECTOR_MICROSOFT_CLIENT_ID, CONNECTOR_MICROSOFT_CLIENT_SECRET | empty | Microsoft app |
CONNECTOR_MICROSOFT_TENANT | organizations | |
REPOSITORY_SYNC_INTERVAL_SECONDS | 900 | Repository catalog refresh; 0 disables |
See Integrations.
Files
| Variable | Default | Notes |
|---|---|---|
ATTACH_MAX_MB | 20 | Maximum size of one task attachment |
LIBRARY_STORAGE_BACKEND | local | local, remote or auto |
LIBRARY_STORAGE_DIR | uploads/library | For local |
LIBRARY_MAX_MB | 0 | 0 means no application limit; your proxy can still set one |
VIDEO_MAX_MB | 256 | 20–2048 |
Remote library storage (S3-compatible or NFS) has its own LIBRARY_MINIO_* and LIBRARY_NFS_* settings in hub-backend/app/config.py.
Client updates
| Variable | Default | Notes |
|---|---|---|
CLIENT_UPDATE_PUBLIC_KEYS | empty | JSON of trusted Ed25519 public keys. Empty uses the checked-in trust file |
Keep the signing private key out of the long-running Hub. Mount it only where releases are signed.
Where to find the rest
hub-backend/app/config.py lists every setting with its default and range. Settings not on this page are for clustering, optional integrations or internal features, and most deployments don't need them.