Each secret must be a unique value. MCPBox checks on startup that secrets are different and logs a warning if duplicates are detected (startup continues).
Optional
Variable
Default
Description
JWT_SECRET_KEY
derived from MCPBOX_ENCRYPTION_KEY
JWT signing key for admin panel auth. Set explicitly for better security.
MCPBOX_FRONTEND_PORT
3000
Host port for the web UI (Docker port binding only)
MCPBOX_BACKEND_PORT
8000
Host port for the backend API (Docker port binding only)
CORS_ORIGINS
http://localhost:3000
Admin CORS origins (only needed for direct backend access)
Enable HSTS header in nginx. Set to true only when behind a TLS-terminating reverse proxy.
CLOUDFLARED_API_KEY
(falls back to SANDBOX_API_KEY)
Dedicated API key for the cloudflared container. Limits blast radius if cloudflared is compromised.
Sandbox
Variable
Default
Description
SANDBOX_MAX_RESULT_SIZE
1048576 (1 MB)
Maximum size in bytes for tool return values. Results exceeding this are truncated with a notice.
SANDBOX_MAX_RESPONSE_SIZE
10485760 (10 MB)
Maximum HTTP response body size in bytes. Responses exceeding this limit are aborted with a ResponseTooLargeError. Prevents memory exhaustion from large API responses.
SANDBOX_MAX_MEMORY_BYTES
268435456 (256 MB)
Per-execution memory limit (RLIMIT_AS). This is the per-tool-execution limit, not the container limit.
SANDBOX_MAX_CONCURRENT_EXECUTIONS
3
Maximum number of Python tool executions that can run simultaneously. Additional requests queue and wait for a slot. Prevents memory exhaustion when multiple heavy tools run concurrently in the memory-constrained sandbox container. MCP passthrough tools are not counted.
SANDBOX_EXECUTION_QUEUE_TIMEOUT
120 (seconds)
How long a queued execution waits for a concurrency slot before returning a “sandbox busy” error.
SOCKS5 Proxy (Sandbox Egress)
These are set in docker-compose.yml on the sandbox service, not in .env. All sandbox outbound traffic routes through the SOCKS5 proxy.
Variable
Default
Description
HTTPS_PROXY
socks5h://socks-proxy:1080
SOCKS5 proxy for HTTPS traffic (httpx, pip). The h suffix means proxy-side DNS resolution.
HTTP_PROXY
socks5h://socks-proxy:1080
SOCKS5 proxy for HTTP traffic.
SOCKS_PROXY
socks5h://socks-proxy:1080
SOCKS5 proxy for raw TCP via SafeSocket.
NO_PROXY
backend,localhost,127.0.0.1
Hosts excluded from proxy routing (internal service communication).
HTTP Client
Variable
Default
Description
HTTP_TIMEOUT
30.0
HTTP client timeout in seconds
HTTP_MAX_CONNECTIONS
10
Maximum HTTP connection pool size
HTTP_KEEPALIVE_CONNECTIONS
5
HTTP keepalive connection pool size
JWT Authentication
Variable
Default
Description
JWT_ACCESS_TOKEN_EXPIRE_MINUTES
15
Access token expiry in minutes
JWT_REFRESH_TOKEN_EXPIRE_DAYS
7
Refresh token expiry in days
JWT_ALGORITHM
HS256
JWT signing algorithm
Port changes affect MCP client config. If you change MCPBOX_BACKEND_PORT, you must also update your MCP client configuration to match. For example, if you set MCPBOX_BACKEND_PORT=9000, your MCP client URL becomes http://localhost:9000/mcp instead of http://localhost:8000/mcp.
Database
Variable
Default
Description
DATABASE_URL
(from compose)
PostgreSQL connection string
DB_POOL_SIZE
20
Base connection pool size
DB_MAX_OVERFLOW
20
Additional connections allowed above pool size
DB_POOL_TIMEOUT
30
Seconds to wait for a connection
DB_POOL_RECYCLE
1800
Recycle connections after this many seconds
Cloudflare Worker
Variable
Default
Description
CF_WORKER_COMPATIBILITY_DATE
2025-03-01
Cloudflare Worker compatibility date
CF_WORKER_COMPATIBILITY_FLAGS
nodejs_compat
Cloudflare Worker compatibility flags
Runtime Settings (Admin UI)
The following settings can be configured via the admin UI or API (PATCH /api/settings/security-policy). RATE_LIMIT_REQUESTS_PER_MINUTE and ALERT_WEBHOOK_URL can also be set as environment variables for initial defaults.
Security policy settings in the admin UI.
Setting
Default
Description
Log retention days
30
How long to keep activity and execution logs
Rate limit requests per minute
100
Per-IP API rate limit (also settable via RATE_LIMIT_REQUESTS_PER_MINUTE env var)
Alert webhook URL
(none)
Webhook for critical alerts — Discord, Slack, or generic HTTP (also settable via ALERT_WEBHOOK_URL env var)
Remote Access
Remote access tokens (tunnel token, service token, OIDC credentials) are stored in the database and managed by the setup wizard. No additional environment variables are needed.
After completing the wizard, run ./scripts/deploy-worker.sh --set-secrets to push tokens to the Cloudflare Worker.
Security policy settings in the admin UI.