Environment variables
Look up the environment values used by the server and pane integrations.
Server configuration
Before changing a value, use Files and paths to locate the active configuration and choose the correct environment layer.
The server checks the process environment first, then config.env, the development .env, and finally its built-in defaults. CLI initialization saves production paths and generates an authentication secret, so an initialized installation can differ from the defaults below.
| Variable | Default or behavior |
|---|---|
SERVER_PORT | 3080. |
HOST | 0.0.0.0. |
APP_BASE_URL | http://localhost:<SERVER_PORT> on raw boot. |
TRUSTED_ORIGINS | Operator extras; raw default includes localhost Vite origins on ports 5174 and 5173. Derived origins are added separately. |
BETTER_AUTH_SECRET | Unique secret generated by initialization. Production refuses the built-in placeholder. |
SUBSHELL_SERVER_CONFIG_DIR | ~/.config/subshell-server. |
DATABASE_PATH | Raw default ./data/subshell.db; initialization selects the deployment's persistent path. |
SUBSHELL_SERVER_DATA_DIR | Defaults to the database's directory, resolved absolutely. |
SUBSHELL_NODE_ARTIFACTS_DIR | node-artifacts beneath server data. |
SUBSHELL_RELEASE_URL | Project GitHub release API; empty disables release fetches. |
SUBSHELL_PLUGIN_REGISTRY_URL | Default npm registry; operator-selected mirrors are trusted configuration. |
SUBSHELL_FS_ROOT | Unset allows broad server-side browser filesystem exploration; set restricts that picker to a resolved tree. |
SUBSHELL_EMERGENCY_PASSWORD | Unset; when enabled, emergency admin sign-in rewrites the password. |
Retention and diagnostics
| Variable | Default or behavior |
|---|---|
SUBSHELL_DB_BACKUPS_KEEP | Five database snapshots. |
SUBSHELL_LOG_RETENTION_DAYS | Thirty days for terminated pane logs; zero disables the sweep. |
SUBSHELL_VERBOSE | 1 or true increases console detail. |
SUBSHELL_DEBUG_LOGGING | Additional file logging; false by default. |
SUBSHELL_TERMINAL_REPLAY_LINES | Default 100 lines for initial terminal replay. |
SUBSHELL_ATTACH_DEBUG | Debug screen dumps when enabled; these may contain sensitive output. |
SUBSHELL_DASHBOARD_PORT | Override the node's loopback management listener. |
Binary detection
Harness manifests declare CLAUDE_PATH, CODEX_PATH, GEMINI_PATH, QWEN_PATH, CLINE_PATH, INTERPRETER_PATH, OPENHANDS_PATH, OPENCLAW_PATH, GROK_PATH, OPENCODE_PATH, HERMES_PATH, OMP_PATH, and PI_PATH. Network manifests declare TAILSCALE_PATH, NETBIRD_PATH, and CLOUDFLARED_PATH. The terminal type selects an executable through SHELL (Terminal) or SUBSHELL_SSH_PATH (SSH).
These select binaries in the applicable execution environment. Setting one in a shell doesn't automatically change an existing service's environment.
Pane identity
The host injects SUBSHELL_API_KEY, SUBSHELL_ID, SUBSHELL_BASE_URL, SUBSHELL_DATA_DIR, and optional SUBSHELL_NAME for MCP. They identify the pane and its storage; don't replace them with a shared system key.
SUBSHELL_CHANNEL_PIN defaults to strict peer-key pinning. trust disables the pin check and persistence.
Installer settings
The server installation script accepts SUBSHELL_SERVER_VERSION, release API/base overrides, and address variables prefixed SUBSHELL_SERVER_. SUBSHELL_NO_SERVICE=1 skips its service setup. These installer variables are distinct from the server's persisted configuration names.
See also
Configuration, Files and paths, and MCP configuration.
Edit on GitHubLast updated on
