Environment Variables

Complete reference for all configuration options.

Authentication

Variable	Description	Default
`AUTH_SECRET`	Session encryption secret (required for production)	Auto-generated in dev
`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)	`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

OAuth Providers

Variable	Description
`GITHUB_CLIENT_ID`	GitHub OAuth client ID
`GITHUB_CLIENT_SECRET`	GitHub OAuth client secret
`GOOGLE_CLIENT_ID`	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret
`DISCORD_CLIENT_ID`	Discord OAuth client ID
`DISCORD_CLIENT_SECRET`	Discord OAuth client secret

Passkeys (WebAuthn)

Variable	Description	Default
`PASSKEY_RP_ID`	Relying party ID (your domain)	`localhost`
`PASSKEY_RP_NAME`	Display name for passkey prompts	`OpenCode Manager`
`PASSKEY_ORIGIN`	Origin URL for WebAuthn (backend port)	`http://localhost:5003`

Push Notifications (VAPID)

Variable	Description	Required
`VAPID_PUBLIC_KEY`	VAPID public key for push notifications	Yes
`VAPID_PRIVATE_KEY`	VAPID private key for push notifications	Yes
`VAPID_SUBJECT`	Contact email for VAPID (MUST use `mailto:` format)	Yes

Generating VAPID Keys

Generate VAPID public/private key pair:

pnpm dlx web-push generate-vapid-keys

Add to .env:

VAPID_PUBLIC_KEY=BMx-1234567890abcdefghijklmnopqrstuv...
VAPID_PRIVATE_KEY=abcd1234567890abcdef...
VAPID_SUBJECT=mailto:you@example.com

iOS/Safari Requirement

VAPID_SUBJECT MUST use mailto: format for iOS/Safari push notifications to work. Apple's push service rejects https:// subjects.

Correct: VAPID_SUBJECT=mailto:you@yourdomain.com Incorrect: VAPID_SUBJECT=https://yourdomain.com

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`

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`)

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

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`
`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

# Server
PORT=5003
HOST=0.0.0.0
NODE_ENV=development

# Required for production
AUTH_SECRET=generate-with-openssl-rand-base64-32

# Pre-configured admin (optional)
ADMIN_EMAIL=admin@example.com
ADMIN_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:5003
AUTH_SECURE_COOKIES=false

# OAuth providers (optional)
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

# Passkeys (optional - use BACKEND port)
PASSKEY_RP_ID=localhost
PASSKEY_RP_NAME=OpenCode Manager
PASSKEY_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

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
===========================================

iOS/Safari Requirement

VAPID_SUBJECT MUST use mailto: format for iOS/Safari push notifications to work.

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.