Session and credential encryption secret. Required for production outside Docker
Docker: generated on first start and kept in /app/data/.auth-secret; dev: random per start
ADMIN_EMAIL
Pre-configured admin email
-
ADMIN_PASSWORD
Pre-configured admin password
-
ADMIN_PASSWORD_RESET
Set to true to reset admin password
false
AUTH_TRUSTED_ORIGINS
Comma-separated list of trusted origins (frontend + backend). Browser requests that change state from another site (Sec-Fetch-Site: same-site or cross-site) are rejected unless their Origin is listed here. Never list the preview gateway origin.
http://localhost:5173,http://localhost:5003
AUTH_SECURE_COOKIES
Use secure cookies (HTTPS only)
Runtime: true in prod, false in dev; Compose: false unless set
When configured, users can enable push notifications in Settings → Notifications to receive background alerts for agent events.
Server
Variable
Description
Default
PORT
Server port
5003
HOST
Server bind address
0.0.0.0
NODE_ENV
Environment (development or production)
development
CORS_ORIGIN
CORS origin for frontend
http://localhost:5173
LOG_LEVEL
Accepted but currently unused; debug output is controlled by DEBUG
info
DEBUG
Enable debug logging
false
Preview Gateway
The preview gateway serves dev servers through an authenticated, separate origin (see Preview).
Variable
Description
Default
PREVIEW_PORT
Port for the preview gateway. Set to 0 to disable preview entirely. If the port is already in use, the Manager starts anyway, logs a warning and reports preview as unavailable.
5004
PREVIEW_PUBLIC_URL
Same-site HTTPS origin that proxies the preview gateway; do not add it to AUTH_TRUSTED_ORIGINS. Set this when the Manager is served over HTTPS or behind a reverse proxy, where mixed content and third-party cookies otherwise block the preview iframe.
empty
Database
Variable
Description
Default
DATABASE_PATH
Path to SQLite database file
./data/opencode.db
Workspace
Variable
Description
Default
WORKSPACE_PATH
Path to workspace directory
./workspace (Docker: /workspace)
REPO_BROWSE_ROOT
Root directory the folder browser may browse. When unset, folder browsing is disabled
empty (disabled)
OpenCode Server
Variable
Description
Default
OPENCODE_SERVER_PORT
Port for the OpenCode CLI server
5551
OPENCODE_HOST
OpenCode server bind address
127.0.0.1
OPENCODE_HEALTH_WATCH_ENABLED
Enable OpenCode health watcher and recovery
true (false in tests)
OPENCODE_HEALTH_POLL_MS
OpenCode health watcher poll interval
30000
OPENCODE_HEALTH_FAILURE_THRESHOLD
Failed health checks before recovery starts
2
OPENCODE_SERVER_PASSWORD
Basic Auth password for the managed OpenCode server. OpenCode 2 always requires one: when unset, OpenCode Manager generates and persists a password (override it any time via Settings → OpenCode → Server Auth). DB-stored passwords override this env var. The default docker-compose.yml does not forward this variable from .env; add it to the compose environment: block or set it via Settings → OpenCode → Server Auth.
auto-generated
OPENCODE_BIN
Path to an externally managed OpenCode binary. Overrides binary discovery; while set, in-app upgrade and version install are disabled (HTTP 409)
-
Upgrade note:OPENCODE_PUBLIC_URL is no longer used. MCP OAuth redirects now point at the Manager's /api/mcp-oauth-proxy/callback, built from the request: the scheme comes from X-Forwarded-Proto (first value, http or https only), then the Origin header, then http; the host comes from X-Forwarded-Host when present, otherwise Host. Behind a reverse proxy, forward X-Forwarded-Proto and X-Forwarded-Host (or preserve Host) and remove OPENCODE_PUBLIC_URL; the Manager logs a warning at startup while it is still set.
OpenCode Import
Variable
Description
Default
OPENCODE_IMPORT_CONFIG_PATH
Existing standalone OpenCode config file to import on first startup. When set to a single file, only that file is imported. When unset, the host's opencode.json, opencode.jsonc, and legacy config.json are mirrored into the workspace, workspace copies absent on the host are removed, and the mirrored legacy file is folded into the workspace config
-
OPENCODE_IMPORT_STATE_PATH
Existing standalone OpenCode state directory to import on first startup
-
Agent Sandboxing
Sandboxed agent commands run inside a microVM managed by msb (see Agent Sandboxing). Requires a Linux host with /dev/kvm and the sandbox compose overlay.
Variable
Description
Default
MSB_PATH
Path to the msb executable
msb
MSB_LIBKRUNFW_PATH
Path to the libkrunfw firmware library used by msb (set in the container image)
/opt/microsandbox/lib/libkrunfw.so
MSB_BACKEND
Backend the microsandbox client uses
local
MSB_HOME
Microsandbox home directory for state
~/.microsandbox
MSB_PROFILE
Microsandbox profile passed through to the client
-
MSB_API_URL
Microsandbox API URL passed through to the client
-
MSB_API_KEY
Microsandbox API key passed through to the client
-
SANDBOX_IMAGE
OCI image the microVM boots from. Digest-pinned by default so a rebuilt guest image is actually adopted; see Sandbox Guest Image for what the default ships and how to build your own
docker.io/cstechdev/ocm-sandbox@sha256:9df035cf…
SANDBOX_MEMORY
MicroVM memory (e.g. 4G)
4G
SANDBOX_CPUS
MicroVM CPU count
2
SANDBOX_EXEC_USER
Guest identity sandboxed commands run as: a numeric uid, a numeric uid:gid, or a guest username. A numeric uid must match the Manager's effective uid (PUID); the compose overlay defaults it to ${PUID:-1000}. A guest username is resolved to the Manager's effective uid:gid so writes to the mounted project roots always succeed. When a configured numeric identity cannot write the workspace, enforcement is reported unavailable
${PUID:-1000} via the overlay, otherwise node
SANDBOX_NET
Network mode for the microVM: public, private, or host, or a comma-separated composition (for example public,host). Passed to msb run --net and attested against the profile's canonical network policy
public
SANDBOX_START_TIMEOUT_MS
Timeout for microVM startup, in milliseconds
300000
SANDBOX_EXEC_TIMEOUT_MS
Timeout for a single sandboxed command, in milliseconds
600000
Timeouts
Variable
Description
Default
PROCESS_START_WAIT_MS
Wait time for OpenCode process to start
2000
PROCESS_VERIFY_WAIT_MS
Wait time for process health verification
1000
HEALTH_CHECK_TIMEOUT_MS
OpenCode liveness probe timeout
30000
File Limits
Variable
Description
Default
MAX_FILE_SIZE_MB
Maximum file size for reading/preview
50
MAX_UPLOAD_SIZE_MB
Maximum upload file size
50
Frontend (Vite)
Variable
Description
Default
VITE_API_URL
Backend API URL for frontend. Empty (the default) means same-origin requests; the Vite dev server proxies /api to the backend
empty (same origin)
VITE_SERVER_PORT
Backend port hint for frontend
5003
VITE_OPENCODE_PORT
OpenCode server port hint
5551
VITE_MAX_FILE_SIZE_MB
File size limit for frontend
50
VITE_MAX_UPLOAD_SIZE_MB
Upload size limit for frontend
50
Example .env File
# ServerPORT=5003HOST=0.0.0.0NODE_ENV=production# Required for production outside Docker (Docker generates one when unset)AUTH_SECRET=generate-with-openssl-rand-base64-32# Pre-configured admin (optional)ADMIN_EMAIL=admin@example.comADMIN_PASSWORD=your-secure-password# Remote access (optional - include both frontend and backend ports)AUTH_TRUSTED_ORIGINS=http://localhost:5173,http://localhost:5003,http://192.168.1.244:5003AUTH_SECURE_COOKIES=false# OAuth providers (optional)GITHUB_CLIENT_ID=your-client-idGITHUB_CLIENT_SECRET=your-client-secret# Passkeys (optional - use BACKEND port)PASSKEY_RP_ID=localhostPASSKEY_RP_NAME=OpenCode ManagerPASSKEY_ORIGIN=http://localhost:5003# Push notifications (optional)VAPID_PUBLIC_KEY=BMx-1234567890abcdefghijklmnopqrstuv...VAPID_PRIVATE_KEY=abcd1234567890abcdef...VAPID_SUBJECT=mailto:you@example.com
Generating Secrets
AUTH_SECRET
Docker generates and persists one automatically, so this is only needed outside Docker or to manage the secret yourself. Generate a secure random secret:
openssl rand -base64 32
Output example:
K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=
VAPID Keys
Generate VAPID public/private key pair for push notifications:
pnpm dlx web-push generate-vapid-keys
Output example:
=======================================
Public Key:
BMx-1234567890abcdefghijklmnopqrstuv...
Private Key:
abcd1234567890abcdef...
Subject:
mailto:you@example.com
===========================================
Environment Precedence
Local runtime loads .env from the project root with dotenv without overriding variables that are already present in the process environment. Docker Compose reads .env for interpolation, then passes the explicit environment entries from docker-compose.yml into the container.