Reference
Environment variables
Every env var the daemon, relay, and CLI accept. Defaults, scope, when to use each.
| Variable | Default | What it does |
|---|
VIEWPORT_HOME | ~/.viewport | Daemon home directory. Holds config, logs, pidfiles, identity files. |
VPD_HOME | (alias of above) | Same as VIEWPORT_HOME. Preferred in scripts. |
VIEWPORT_API_URL | https://api.getviewport.com | Control plane base URL. Set for self-hosted control plane. |
VIEWPORT_APP_URL | https://app.getviewport.com | Where vpd pair opens in the browser. |
VIEWPORT_DAEMON_LISTEN | 127.0.0.1:7070 | Local API listen address. Accepts host:port, port, or unix socket path. |
VIEWPORT_DAEMON_PROFILE | local | One of local, lan, relay. Profile changes default listen + CORS. |
VIEWPORT_DAEMON_AUTH | (off) | Set to 1 to require token auth on the local API. |
VIEWPORT_DAEMON_LOG_LEVEL | info | One of debug, info, warn, error. |
VIEWPORT_BUILT_IN_AGENTS | claude,codex,aider,gemini | Which built-in agents the hook installer detects. |
VIEWPORT_RELAY_TLS_INSECURE | (off) | Skip TLS verification when connecting to the relay. Local dev only. |
| Variable | Default | What it does |
|---|
RELAY_LISTEN_PORT | 7781 | Port to bind. |
RELAY_INTERNAL_KEY | (required) | Shared secret for relay→platform internal calls. |
RELAY_VALIDATE_URL | (required) | https://api.getviewport.com/api/runtime/internal/relay/validate or self-hosted equivalent. |
RELAY_JWKS_URL | (required) | Where the relay fetches platform JWT signing keys. |
RELAY_ADMIN_TOKEN | none | Bearer token for /state, /logs, /metrics. |
RELAY_ENABLE_ADMIN_HTTP | 0 | Set to 1 to expose admin endpoints. |
RELAY_BACKPLANE_MODE | single | single / server / redis. |
RELAY_BACKPLANE_URL | none | Backplane endpoint when mode != single. |
RELAY_CLIENT_REDIRECT_ENABLED | 0 | Allow the relay to redirect clients to the relay holding their daemon. |
RELAY_LOG_LEVEL | info | One of debug, info, warn, error. |
RELAY_FRAME_MAX_BYTES | 1048576 (1 MiB) | Reject frames larger than this. |
RELAY_RATE_LIMIT_PER_IP | 60/min | Frames per IP. Set to 0 to disable. |
RELAY_PROMETHEUS_BUCKETS | (defaults) | Override histogram buckets. |
Full env-var reference for the relay lives in services/relay/README.md in the OSS repo.
| Variable | Default | What it does |
|---|
VITE_API_URL | https://api.getviewport.com | Where the web app calls the control plane. |
VITE_APP_BUILD_ID | (git sha) | Build id surfaced in the footer for support. |
VITE_WORKOS_CLIENT_ID | (required) | WorkOS SSO client id. |
VITE_FEATURE_FLAGS | none | Comma-separated feature flag toggles. |
VITE_SUPPORT_EMAIL | hello@getviewport.com | Where the footer links go. |
| Variable | Purpose |
|---|
APP_KEY | Laravel encryption key. Required. php artisan key:generate. |
DB_* | Postgres connection (preferred) or MySQL. |
WORKOS_API_KEY, WORKOS_CLIENT_ID | SSO. |
MAIL_MAILER, RESEND_KEY | Transactional email. |
RELAY_PUBLIC_URL | Where pairings should connect. |
RELAY_INTERNAL_KEY | Must match the relay's RELAY_INTERNAL_KEY. |
VIEWPORT_AUDIT_RETENTION_DAYS | Default audit retention. |