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 | Server API base URL. |
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 | Which built-in agents the hook installer detects. |
VIEWPORT_CUSTOM_AGENT_COMMAND | none | Command path for a PTY-backed custom workflow agent. |
VIEWPORT_CUSTOM_AGENT_ID | custom-command | Agent id reported by the custom command adapter. Use it when a policy targets that custom agent. |
VIEWPORT_CUSTOM_AGENT_NAME | Custom command agent | Display name for the custom command agent. |
VIEWPORT_CUSTOM_AGENT_ARGS_JSON | [] | JSON array of default command arguments for the custom command agent. Preferred over whitespace splitting. |
VIEWPORT_CUSTOM_AGENT_ARGS | empty | Whitespace-split fallback arguments for the custom command agent. |
VIEWPORT_CUSTOM_AGENT_PROMPT_MODE | stdin | How the initial prompt is delivered for custom command agents: stdin, positional, or a flag name. |
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_VIEWPORT_SERVER_URL | https://getviewport.com | Base hosted URL used when an explicit API URL is not set. |
VITE_VIEWPORT_API_URL | https://api.getviewport.com/api | Where the web app calls the server API. |
VITE_VIEWPORT_RELAY_WS_BASE_URL | wss://relay.getviewport.com/ws | Relay WebSocket base URL. |
VITE_POSTHOG_KEY | empty | Optional product analytics key. Analytics stay off until the user allows them. |
VITE_POSTHOG_HOST | https://us.i.posthog.com | Optional PostHog host override. |
| Variable | Purpose |
|---|
APP_KEY | Server-side app secret. Required for self-hosted deployments. |
DB_CONNECTION / database-specific vars | Server database connection. |
WORKOS_CLIENT_ID, WORKOS_API_KEY, WORKOS_REDIRECT_URL | Login provider credentials. |
MAIL_MAILER, RESEND_API_KEY, MAIL_FROM_ADDRESS | Transactional email. |
VIEWPORT_RELAY_HTTP_URL | Relay HTTP base URL for internal calls. |
VIEWPORT_RELAY_INTERNAL_KEY | Must match the relay's internal key. |
VIEWPORT_ALERT_WEBHOOK_URL | Optional endpoint for structured API exception alerts. |
VIEWPORT_ALERT_WEBHOOK_SECRET | Optional HMAC signing secret for alert webhooks. |
VIEWPORT_ALERT_WEBHOOK_TIMEOUT | Alert webhook timeout in seconds. Defaults to 2. |
VIEWPORT_CLIENT_EVENT_INGEST_ENABLED | Enables authenticated client diagnostics ingest. Defaults to true. |
VIEWPORT_CLIENT_EVENT_MAX_CONTEXT_BYTES | Max diagnostic context stored per event. Defaults to 4096. |
VIEWPORT_ACTION_BROKER_WEBHOOK_ALLOWED_HOSTS | Comma-separated HTTPS host allowlist for sandbox webhook action-provider proposals. Defaults to localhost,127.0.0.1,actions.example.test. |