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)	`true` in prod, `false` in dev

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`	Logging level	`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_PUBLIC_URL`	Public URL passed to OpenCode for OAuth callbacks	-
`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 required when binding OpenCode to a non-loopback host. Can also be set via UI (Settings → OpenCode → Server Auth). DB-stored passwords override this env var.	-
`OPENCODE_SERVER_USERNAME`	Basic Auth username	`opencode`

OpenCode Import

Variable	Description	Default
`OPENCODE_IMPORT_CONFIG_PATH`	Existing standalone OpenCode `opencode.json` to import on first startup	-
`OPENCODE_IMPORT_STATE_PATH`	Existing standalone OpenCode state directory to import on first startup	-

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_INTERVAL_MS`	Health check polling interval	`5000`
`HEALTH_CHECK_TIMEOUT_MS`	Health check 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	`http://localhost:5003`
`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.