All keys are shown with their defaults. Unless marked environment-only, each option can be set in config.yaml or via the listed environment variable, which takes precedence. Invalid values (non-positive timeouts, zero concurrency, out-of-range TTLs) abort startup with a config: validate: error naming the offending key.
| Key | Env var | Default | Description |
|---|
env | VISION_ENV | development | Deployment environment: development | staging | production. Governs validation strictness |
| Key | Env var | Default | Description |
|---|
http.addr | VISION_HTTP_ADDR | :3303 | Listen address and port |
http.read_timeout | VISION_HTTP_READ_TIMEOUT | 15s | Max time to read a full request |
http.write_timeout | VISION_HTTP_WRITE_TIMEOUT | 30s | Max time to write a response |
http.idle_timeout | VISION_HTTP_IDLE_TIMEOUT | 60s | Keep-alive idle timeout |
http.shutdown_grace | VISION_HTTP_SHUTDOWN_GRACE | 10s | Grace period for in-flight requests on shutdown |
http.pre_drain_delay | VISION_HTTP_PREDRAIN_DELAY | 5s | Delay after /readyz starts failing before shutdown (for load balancers) |
http.secure_cookies | VISION_HTTP_SECURE_COOKIES | true | Mark session/auth cookies Secure (HTTPS-only). vision install writes false (plain http://); set true once HTTPS is in front |
http.allowed_origins | VISION_ALLOWED_ORIGINS | ["http://localhost:3303"] | CORS allow-list. Staging and production reject * and an empty list at startup |
http.internal_addr | VISION_HTTP_INTERNAL_ADDR | (empty) | Separate listener for /healthz, /readyz, /metrics |
Origins are matched as scheme://host[:port], case-insensitively, against the request’s Origin header. Cross-origin requests may use only the headers Authorization, Content-Type, X-Request-ID, Idempotency-Key, and Last-Event-ID — the header allow-list is fixed, and anything else fails preflight. The effective origin list is logged at startup as CORS allow-list. Production enables HSTS automatically. Every response also carries X-Frame-Options: DENY; the UI cannot be embedded in an iframe, and there is no toggle.
| Key | Env var | Default | Description |
|---|
db.path | VISION_DB_PATH | ./data/vision.db | SQLite file path (parent dir must exist) |
db.connect_timeout | VISION_DB_CONNECT_TIMEOUT | 5s | Connection open timeout |
db.query_timeout | VISION_DB_QUERY_TIMEOUT | 30s | Single-query timeout |
| Key | Env var | Default | Description |
|---|
log.level | VISION_LOG_LEVEL | info | debug | info | warn | error |
log.format | VISION_LOG_FORMAT | json | json (production) | text (development) |
| Key | Env var | Default | Description |
|---|
auth.jwt_secret | VISION_AUTH_JWT_SECRET | (empty) | JWT signing secret. Required in staging/production |
auth.access_ttl | VISION_AUTH_ACCESS_TTL | 15m | Lifetime of the short-lived access token (> 0, ≤ 1h) |
auth.refresh_ttl | VISION_AUTH_REFRESH_TTL | 168h | Lifetime of the rotating refresh session (> 0, ≤ 720h). An idle browser session expires after this |
auth.oauth2_secret | VISION_OAUTH2_SECRET | (empty) | Base64 32-byte secret for inbound OAuth2 client-credentials tokens. When unset, POST /api/v1/events is not mounted |
crypto.encryption_keys | VISION_ENCRYPTION_KEY, _V2, _V3, … | [] | Environment-only. Base64 AES-256-GCM keys for encrypted DB fields. First key is active; older keys decrypt during rotation. Required in staging/production |
Generate a key with openssl rand -base64 32. A YAML value for crypto.encryption_keys is ignored; keep every key in /etc/vision/vision.env. Number rotated keys without gaps (_V2, _V3, …), because loading stops at the first missing number. The JWT secret accepts standard or URL-safe base64, padded or unpadded, and must decode to exactly 32 bytes.
These values seed the first admin user only while the users table is empty and are ignored afterwards — editing them once an admin exists has no effect. In development, missing values fall back to admin@localhost / admin (with a startup warning). In staging and production, the seed aborts startup when the database has no users and either value is missing. The installer generates both into /etc/vision/vision.env.
| Key | Env var | Default | Description |
|---|
bootstrap.admin_email | ADMIN_EMAIL | (empty) | Initial admin email. Dev fallback: admin@localhost |
bootstrap.admin_password | ADMIN_PASSWORD | (empty) | Initial admin password. Dev fallback: admin |
Alta server connection details (base URL, credentials, and the per-server callback base URL) live in the database and are managed in the UI. These keys tune the shared client only.
| Key | Env var | Default | Description |
|---|
alta.default_timeout | VISION_ALTA_DEFAULT_TIMEOUT | 10s | Per-attempt timeout for CRUD calls |
alta.long_timeout | VISION_ALTA_LONG_TIMEOUT | 30s | Per-attempt timeout for Preview/VOD calls |
alta.breaker_threshold | VISION_ALTA_BREAKER_THRESHOLD | 5 | Consecutive failures before the circuit breaker opens |
alta.breaker_open_for | VISION_ALTA_BREAKER_OPEN_FOR | 30s | How long the breaker stays open |
alta.bulkhead_capacity | VISION_ALTA_BULKHEAD_CAPACITY | 64 | Max concurrent in-flight Alta calls |
alta.stream.hls_token_ttl | VISION_ALTA_STREAM_HLS_TOKEN_TTL | 5m | TTL for HLS playlist tokens (≤ 1h) |
alta.stream.webrtc_token_ttl | VISION_ALTA_STREAM_WEBRTC_TOKEN_TTL | 2m | TTL for WHEP bearer tokens (≤ 1h) |
alta.stream.archive_token_ttl | VISION_ALTA_STREAM_ARCHIVE_TOKEN_TTL | 5m | TTL for archive (VOD) playback tokens (≤ 1h) |
alta.stream.preview_list_max_window | VISION_ALTA_STREAM_PREVIEW_LIST_MAX_WINDOW | 2h | Max time span a single preview-list request may cover (≤ 24h) |
alta.stream.auth_mode | VISION_ALTA_STREAM_AUTH_MODE | jwt | jwt (production) | none (dev-only, logs a warning) |
| Key | Env var | Default | Description |
|---|
workers.enabled | VISION_WORKERS_ENABLED | standard workers | Comma-separated allow-list from {clips, cleanup, health_server, health_camera, health, alta_prober, alerts, notifications, io, reconcile}. true enables the standard set (excluding withdrawn io); false enables none. motion and screenshots are invalid and abort startup |
workers.health_probe_concurrency | VISION_WORKERS_HEALTH_PROBE_CONCURRENCY | 8 | Max concurrent Alta health probes per tick (≥ 1) |
workers.clips_output_path | CLIPS_OUTPUT_PATH | /var/lib/vision/clips | Legacy path retained for existing records; new exports require an output storage |
workers.clips_ffmpeg_binary | CLIPS_FFMPEG_BINARY | ffmpeg | Path to the ffmpeg executable |
workers.clips_ffprobe_binary | CLIPS_FFPROBE_BINARY | ffprobe | Path to ffprobe, used when adding RTSP cameras and measuring exported clips |
workers.clips_worker_timeout | CLIPS_WORKER_TIMEOUT | 5m | Per-clip ffmpeg deadline |
workers.clips_worker_concurrency | CLIPS_WORKER_CONCURRENCY | 2 | Max concurrent ffmpeg subprocesses |
workers.screenshots_output_path | SCREENSHOTS_OUTPUT_PATH | /var/lib/vision/screenshots | Legacy path retained for existing records; new captures require an output storage |
workers.notifications_dispatch_concurrency | VISION_NOTIFICATIONS_DISPATCH_CONCURRENCY | 8 | Max concurrent goroutines dispatching emails, push, and webhooks |
workers.drain_timeout | VISION_WORKERS_DRAIN_TIMEOUT | 10s | Total budget to drain workers on shutdown |
The io worker remains available only for compatibility and logs a warning when explicitly enabled; its UI has been withdrawn. The alta_prober worker pings each Alta server about once a second to detect outages and restarts quickly; its cadence is the Server ping interval system setting below.
The reconcile worker runs hourly and deletes orphaned Alta-side resources — but only ones this installation can prove it created (a durable ownership record, not a name-pattern guess), so one installation can never delete another’s resources on a shared Alta server. See Connect an Alta Server for what this means day to day, and the Reconcile rows below for the settings that bound how much it deletes per pass.
The cleanup worker enforces retention. The audit-log policy below is seeded on first install; once written, the runtime source of truth is the in-app setting under Settings → Storages.
| Key | Env var | Default | Description |
|---|
retention.audit_days | VISION_RETENTION_AUDIT_DAYS | 365 | First-install seed for audit-log retention, in days |
Health polling and reconcile tuning live in the database, not config.yaml. Every key below is writable via PUT /api/v1/settings/{key}; the UI column shows which ones also have a control on Settings → Connections today — the rest are settings-API/CLI-only for now.
| Key | UI | Default | Range | Description |
|---|
connection.camera_health_interval | Camera health interval | 3 | 1–30 | Camera health poll interval, in seconds |
connection.server_ping_interval | Server ping interval | 1 | 1–10 | Alta availability probe interval, in seconds. Sets how fast outages and restarts are detected |
connection.server_health_interval | Server status | 15 | 10–300 | Host/storage telemetry poll, plus the reachability corroboration and clean-poll debounce that clears a flapping server. Does not set outage-detection speed — that’s the ping interval above |
connection.server_config_interval | Server config | 300 | 60–3600 | Config-drift inspection cadence — how often the full Alta configuration is fetched to detect manual edits. The heaviest Alta call; keeping it infrequent is safe and doesn’t affect outage detection |
connection.reconcile_grace_seconds | (none) | 600 | 60–86400 | How long an Alta resource with no matching Vision record must stay unreferenced and unclaimed before the reconcile worker deletes it. This isn’t a sweep kill switch — the same key throttles the health worker’s crash-recovery path; drop reconcile from workers.enabled to disable the sweep instead |
connection.reconcile_max_deletes_per_tick | (none) | 20 | 1–1000 | Per-server, per-tick cap on how many resources the reconcile sweep deletes; the remainder waits for the next tick |
connection.reconcile_candidate_ratio_guard | (none) | 1 | 0–100 | Refuses a server’s whole reconcile pass when delete candidates exceed references × this ratio — a brake against a bad reference read wiping a server. 0 disables the guard, for an intentional bulk cleanup |
connection.server_health_interval and connection.server_config_interval were split from one setting (ADR-0045): reachability/status/telemetry polling and the heavier config-drift scan now run on independent cadences, so drift inspection can stay slow without also slowing outage detection. The two reconcile rails were added alongside the ownership-claim ledger — see Connect an Alta Server for what the sweep does with them.
| Key | Env var | Default | Description |
|---|
maps_background_path | MAPS_BACKGROUND_PATH | (empty) | Filesystem root for floor-plan images. Empty uses a maps directory beside db.path; the installer writes /var/lib/vision/maps |
| Key | Env var | Default | Description |
|---|
metrics.enabled | VISION_METRICS_ENABLED | true | Expose Prometheus metrics at /metrics |
readiness.timeout | VISION_READINESS_TIMEOUT | 5s | Overall deadline for /readyz |
readiness.check_workers | VISION_READINESS_CHECK_WORKERS | true | Include worker liveness in readiness |
readiness.check_schema | VISION_READINESS_CHECK_SCHEMA | true | Include schema-version check |
readiness.worker_stale_multiplier | VISION_READINESS_WORKER_STALE_MULTIPLIER | 2.0 | A worker is stale when its last heartbeat is older than multiplier × tick |
| Key | Env var | Default | Description |
|---|
security.csp_strict_mode | VISION_SECURITY_CSP_STRICT | false | Opt in to strict CSP in dev (always strict in production) |
startup.check_schema | VISION_STARTUP_CHECK_SCHEMA | true | Verify DB schema on boot |
startup.check_environment | VISION_STARTUP_CHECK_ENVIRONMENT | true | Verify environment on boot |
startup.check_keyring | VISION_STARTUP_CHECK_KEYRING | true | Verify encryption keyring on boot |
startup.check_alta | VISION_STARTUP_CHECK_ALTA | true | Verify Alta reachability on boot. Passes when no server is added yet |
startup.timeout | VISION_STARTUP_TIMEOUT | 10s | Total budget for startup checks |
Per-user token bucket, keyed on user ID. Public endpoints (/healthz, /readyz, /metrics, /auth/verify) are exempt.
Live video (starting and stopping streams) and PTZ use a separate real-time budget of 300 requests per minute, so paging a wall never eats the edit budget. A 429 says how long to wait.
| Key | Env var | Default | Description |
|---|
rate_limit.enabled | VISION_RATE_LIMIT_ENABLED | true | Enable the limiter |
rate_limit.read_per_min | VISION_RATE_LIMIT_READ_PER_MIN | 60 | Read requests per minute |
rate_limit.write_per_min | VISION_RATE_LIMIT_WRITE_PER_MIN | 60 | Write requests per minute |
rate_limit.burst | VISION_RATE_LIMIT_BURST | 0 | Burst allowance (0 = use per-minute budget) |
Independent of the per-user limiter above, this protects unauthenticated login, refresh, and password-reset requests. Login must pass both the configured per-email budget and a fixed 60/minute source-IP budget. Email lockout is a flat 60 seconds. Session refresh is keyed by source IP and only rate-limited, never locked out — a burst of page reloads waits a few seconds instead of signing out. Password reset is keyed by source IP and uses the progressive lockout settings below. Counters are in-process and reset on restart.
| Key | Env var | Default | Description |
|---|
auth_rate_limit.enabled | VISION_AUTH_RATE_LIMIT_ENABLED | true | Enable the auth throttle/lockout |
auth_rate_limit.per_min | VISION_AUTH_RATE_LIMIT_PER_MIN | 5 | Sustained attempts per minute per key |
auth_rate_limit.burst | VISION_AUTH_RATE_LIMIT_BURST | 5 | Bucket capacity (0 = use per_min) |
auth_rate_limit.max_failures | VISION_AUTH_RATE_LIMIT_MAX_FAILURES | 5 | Consecutive failures before lockout |
auth_rate_limit.lockout_base | VISION_AUTH_RATE_LIMIT_LOCKOUT_BASE | 1m | First lockout; doubles each further failure |
auth_rate_limit.lockout_max | VISION_AUTH_RATE_LIMIT_LOCKOUT_MAX | 15m | Cap on the progressive backoff |
auth_rate_limit.ttl | VISION_AUTH_RATE_LIMIT_TTL | 15m | Idle window before a key is evicted |
auth_rate_limit.max_keys | VISION_AUTH_RATE_LIMIT_MAX_KEYS | 4096 | Hard cap on tracked keys (bounds memory) |