Orpheus configuration
Process settings are supplied through ENV. The application does not load .env itself. Compose does. The serve command flags take precedence for listener addresses.
| Variable | Default | Purpose |
|---|---|---|
DATABASE_URL | required | PostgreSQL for API, worker and migrations |
ORPHEUS_CONFIG_FILE | orpheus.toml | Credential-store and service configuration path |
ORPHEUS_MIGRATIONS_DIR | migrations | Migration directory. The --dir flag takes precedence |
PUBLIC_API_KEYS | [] | JSON array of Bearer keys with equal access |
ENV_ENCRYPTION_KEY | required | 32-byte base64url key for environment encryption |
HARNESS_ENV_ALLOWLIST | [] | JSON array of extra permitted worker ENV names. Combined with all service ENV names |
AGENTBOX_API_KEY | required on worker | AgentBox access. Also supply to API for template registration |
AGENTBOX_API_URL | unset | Explicit AgentBox API origin. Use the same endpoint settings on API and worker |
AGENTBOX_DOMAIN | agentbox-runtime.ru | Domain used for https://api.<domain> when no explicit API URL is set |
AGENTBOX_DEBUG | false | Select http://localhost:3000 unless an explicit API URL is set |
SANDBOX_PROXY_URL | https://sandbox-proxy.agentbox.ru:65181 | Agent proxy: HTTP, HTTPS, SOCKS5 or SOCKS5H. Empty disables injection. See proxy and authentication compatibility |
MAX_CONCURRENT_SESSIONS | 50 | Occupied execution slots, including preparation and finalization |
DEFAULT_MAX_SESSION_TOKENS | 100000000 | Default token budget for new sessions |
MAX_TOOL_RESULT_BYTES | 524288 | Retained tool output bytes |
MAX_HOOK_OUTPUT_BYTES | 524288 | Retained hook stdout/stderr bytes |
MAX_REQUEST_BYTES | 1048576 | API request body limit in bytes |
DATABASE_PING_TIMEOUT | 2 | Database probe timeout, seconds |
CANCEL_GRACE_SECONDS | 30 | Graceful cancellation wait, seconds |
WORKER_POLL_SECONDS | 1 | Worker polling interval, seconds |
SANDBOX_PROVISION_TIMEOUT_SECONDS | 120 | Initial sandbox creation and connection deadline, seconds. Applies to new attempts |
SANDBOX_PAUSED_RETENTION_DAYS | 14 | Worker setting: paused reusable sandbox retention after the latest run finishes, integer 1–100 days |
SANDBOX_CLEANUP_BATCH_SIZE | 1000 | Sessions selected per worker cleanup pass, including retries. Positive integer |
RPC_TIMEOUT_SECONDS | 30 | Individual agent RPC timeout, seconds |
ORPHEUS_HOST / ORPHEUS_PORT | 0.0.0.0 / 8000 | API listener |
ORPHEUS_SYSTEM_HOST / ORPHEUS_SYSTEM_PORT | 0.0.0.0 / 9100 | Process probes and service metrics. Keep access within a trusted network |
ORPHEUS_BROWSER_AUTH | api_only | api_only, anonymous or saml |
ORPHEUS_PUBLIC_URL | unset | Exact external origin for browser writes. HTTPS required for SAML |
SAML_SP_ENTITY_ID | unset | SP entity ID |
SAML_IDP_METADATA_FILE | unset | Path to IdP metadata XML |
SAML_SP_CERT_FILE | unset | Path to SP certificate |
SAML_SP_KEY_FILE | unset | Path to SP private key |
BROWSER_SESSION_TTL_SECONDS | 43200 | Browser session lifetime, 300-86400 seconds |
required marks a required value. unset means no value is configured. SAML fields are required in saml mode. Supply integration variables such as HELPDESK_TOKEN to the worker. Register their names in a service, or use HARNESS_ENV_ALLOWLIST for names outside the catalog.
API and worker must share credential-store and service configuration, allowed environment names and encryption key. Recreate containers after ENV changes. Practical setup.