The console (control node) supports both a config.toml file and environment variables.
Configuration file
Set CONSOLE_CONFIG_FILE to use a specific file. If it is not set, the console looks for config.toml next to the console binary and then in the current working directory. When no file is found, it continues with environment variables and built-in defaults.
Environment variables take precedence over config.toml, which takes precedence over built-in defaults. TOML keys use the environment variable name without the CONSOLE_ prefix and in lowercase; for example, CONSOLE_HTTP_ADDR becomes http_addr. Nested tables map to underscore-separated names.
http_addr = ":8089"grpc_addr = ":50051"db_path = "./db/onlyboxes-console.db"log_level = "info"[mcp_tool.python_exec]description = "Execute Python code in a sandbox."
Keep secrets such as hash_key, dashboard_password, jit_signing_key, and export_file_sk in environment variables when possible. See the annotated configuration template for all available keys.
Environment variables
Core
Variable
Required
Default
Description
CONSOLE_HASH_KEY
Yes
HMAC key for hashing worker secrets and access tokens
CONSOLE_HTTP_ADDR
No
:8089
Dashboard and REST API listen address
CONSOLE_GRPC_ADDR
No
:50051
Worker gRPC listen address
Database
Variable
Required
Default
Description
CONSOLE_DB_PATH
No
./db/onlyboxes-console.db
SQLite database file path
CONSOLE_DB_BUSY_TIMEOUT_MS
No
5000
SQLite busy timeout (ms)
CONSOLE_TASK_RETENTION_DAYS
No
30
Retention days for completed task records
Initial admin account
These variables are only used during first startup when no admin account exists. They are ignored on subsequent runs.
Variable
Required
Default
Description
CONSOLE_DASHBOARD_USERNAME
No
Initial admin username
CONSOLE_DASHBOARD_PASSWORD
No
Initial admin password
CONSOLE_INITIAL_ADMIN_API_KEY
No
Explicit initial admin API key
Account
Variable
Required
Default
Description
CONSOLE_ENABLE_REGISTRATION
No
false
Allow admin to register non-admin accounts
Tool management
Variable
Required
Default
Description
CONSOLE_HIDDEN_TOOLS
No
Comma-separated internal capability IDs to hide from MCP tools/list (echo, pythonExec, terminalExec, computerUse, readImage, exportFile). Always use the built-in IDs here — never the renamed value supplied via CONSOLE_MCP_TOOL_<TOOL>_NAME. Hidden tools remain callable if the client already knows the tool name.
CONSOLE_MCP_TOKEN_QUERY_PARAM
No
token
Query parameter name for the /mcp URL-token fallback used by clients that cannot send custom headers. Bearer headers remain recommended.
CONSOLE_COMPUTER_USE_SESSION_ID_PREFIX
No
CU:
Case-sensitive prefix that makes readImage and exportFile interpret the suffix as a caller-owned Worker System ID. Changing it changes session-ID interpretation and is generally not recommended. Empty or whitespace-only values fall back to CU: with a warning. TOML key: computer_use_session_id_prefix.
Tool description / parameter overrides
These env vars let you rewrite what each tool advertises to the model without recompiling. Unset variables keep the built-in defaults. The tool name segment uses UPPER_SNAKE_CASE (e.g. pythonExec → PYTHON_EXEC), and the parameter segment is the uppercased snake_case JSON key (e.g. session_id → SESSION_ID).
Variable
Required
Default
Description
CONSOLE_MCP_TOOL_<TOOL>_NAME
No
built-in
Override the tool's name exposed via tools/list (the routing key used by tools/call). Must match ^[a-zA-Z0-9_-]{1,64}$; empty / invalid values fall back to the default with a warn log. Overrides that collide with another tool's built-in default name (e.g. setting ECHO_NAME=pythonExec) also fall back. After changing this, MCP clients must refresh their cached tools/list, otherwise tools/call against the old name returns "tool not found". CONSOLE_HIDDEN_TOOLS keeps using the internal capability ID (echo), not the renamed value.
CONSOLE_MCP_TOOL_<TOOL>_TITLE
No
built-in
Override the tool's human-readable title in tools/list and annotations.title. An empty string falls back to the default and logs a warning.
CONSOLE_MCP_TOOL_<TOOL>_DESCRIPTION
No
built-in
Override the tool's description. An empty string falls back to the default and logs a warning.
CONSOLE_MCP_TOOL_<TOOL>_PARAM_<PARAM>_DESCRIPTION
No
built-in
Override a single parameter's description in inputSchema.properties.<param>. Setting this to an empty string hides the parameter from tools/list: the entry is removed from properties and required, and the schema's additionalProperties flips to true so MCP / HTTP callers may still transmit the field (the handler still receives it). Every hidden parameter emits a startup WARN hiding MCP tool parameter ... required=<bool>; hiding a required parameter means the model cannot construct a valid call.
# Rename the echo tool to "ping", replace its description, and hide terminalExec's session_id parameterCONSOLE_MCP_TOOL_ECHO_NAME="ping"CONSOLE_MCP_TOOL_ECHO_DESCRIPTION="ping-only echo"CONSOLE_MCP_TOOL_TERMINAL_EXEC_PARAM_SESSION_ID_DESCRIPTION=""
Export file object store
These variables enable the MCP exportFile tool. The tool is registered in tools/list only after the following environment variables are configured.
CONSOLE_EXPORT_FILE_ENDPOINT
CONSOLE_EXPORT_FILE_REGION
CONSOLE_EXPORT_FILE_BUCKET_NAME
CONSOLE_EXPORT_FILE_EXPORT_PREFIX
CONSOLE_EXPORT_FILE_AK
CONSOLE_EXPORT_FILE_SK
Variable
Required
Default
Description
CONSOLE_EXPORT_FILE_ENDPOINT
No
S3-compatible endpoint URL used for presigned upload/download
HMAC-SHA256 signing key for Dashboard JIT tokens (obx_dashboard_jit_v1.*). Must differ from CONSOLE_JIT_SIGNING_KEY. Unset disables Dashboard JIT auth.
Worker management
Variable
Required
Default
Description
CONSOLE_HEARTBEAT_INTERVAL_SEC
No
5
Expected worker heartbeat interval (seconds)
CONSOLE_OFFLINE_TTL_SEC
No
15
Seconds before a silent worker is marked offline
CONSOLE_REPLAY_WINDOW_SEC
No
60
Replay window for request deduplication (seconds)
CONSOLE_WORKER_CONNECTION_CONFLICT_POLICY
No
REPLACE
Policy when the same worker is already connected: REPLACE disconnects the existing connection and accepts the new one; REJECT keeps the existing connection and rejects the new one
Public preview proxy
These variables enable the public preview proxy. Keep it disabled until Nginx and worker ingress are ready. See Public Preview Proxy for the full deployment guide.
Variable
Required
Default
Description
CONSOLE_PROXY_ENABLED
No
false
Enable the public preview proxy
CONSOLE_PROXY_PUBLIC_BASE_DOMAIN
No
Base domain for preview URLs, e.g. public-preview.example.com; requires wildcard DNS/TLS
CONSOLE_PROXY_PUBLIC_SCHEME
No
https
Preview URL scheme; accepts http or https only. Use https in production; http is for trusted local development
CONSOLE_PROXY_INTERNAL_AUTH_TOKEN
No
Shared internal auth token between Nginx and Console; prefer providing it via environment variable rather than the config file
CONSOLE_PROXY_ALLOWED_WORKER_CIDRS
No
Comma-separated CIDR allowlist for worker proxy ingress; accepts unicast IPs only — no hostnames, loopback, unspecified, or out-of-allowlist addresses
CONSOLE_PROXY_ALLOWED_WORKER_PORTS
No
Comma-separated port allowlist for worker proxy ingress
CONSOLE_PROXY_ALLOWED_DIRECT_DOMAINS
No
e2b.app
Comma-separated suffix allowlist for E2B direct origins; restrict to the E2B domains used by the deployment
CONSOLE_PROXY_ROUTE_TTL_SEC
No
86400
Preview route TTL in seconds, max 604800 (7 days); Console refuses to start if exceeded
CONSOLE_PROXY_ROUTE_KEY_LENGTH
No
26
Length of newly generated route keys, range 8..26; existing routes remain valid after changes. Values below 16 are recommended only for trusted local or low-risk deployments
CONSOLE_PROXY_ROUTE_MAX_PER_ACCOUNT
No
16
Maximum number of active preview routes retained for one account
CONSOLE_PROXY_ROUTE_MAX_PER_SESSION
No
2
Maximum number of active preview routes retained for one terminal session
