Server configuration

The Envoy control plane reads one YAML file at startup. loadServerConfig in src/server/config.ts parses it, resolves environment variables, merges it over built-in defaults, and validates it before the server starts:

envoy server --config /path/to/envoy-server.yaml

Docker deployments set ENVOY_CONFIG_PATH and let the image entrypoint generate this file on first boot from environment variables. After first boot the persisted YAML is authoritative — changing an environment variable does not regenerate it. See Docker.

Annotated example

server:
  port: 3000
  host: 0.0.0.0
  cors_origin: https://envoy.example.com
 
store:
  type: sqlite
  path: /app/state/envoy-server.db
 
runs:
  log_store: db
  log_dir: ./logs/runs
  max_concurrent: 50
  retention:
    max_age_days: 30
    delete_runs: false
    cleanup_cron: "0 3 * * *"
 
branding:
  app_name: Envoy
  logo_url: ""
  icon_url: ""
  favicon_url: ""
 
scheduler:
  max_inflight_age_minutes: 60
 
connectors:
  upload_max_bytes: 26214400
 
encryption_key: ${ENVOY_ENCRYPTION_KEY}
tasks_dir: ./tasks
jobs_dir: ./jobs
 
executor:
  type: http
  config:
    callback_url: http://control-plane:3000
    executor_key: ${ENVOY_EXECUTOR_KEY}
 
auth:
  totp_required: true
  providers:
    microsoft:
      client_id: ${MICROSOFT_CLIENT_ID}
      client_secret: ${MICROSOFT_CLIENT_SECRET}
      tenant_id: common
 
secrets:
  default: azure_key_vault
  azure_key_vault:
    vault_url: https://my-vault.vault.azure.net/
    name_prefix: envoy-
 
ai:
  provider: anthropic
  api_key: ${ANTHROPIC_API_KEY}

How the config is loaded and validated

loadServerConfig runs these steps in order. Any failure throws and the server does not start.

1. The file must exist, otherwise: Server config file not found: <path>.
2. The YAML is parsed and every ${VAR} reference is replaced with the value of that environment variable. A missing variable fails the boot. Tokens of the form ${secret://...} are left alone at this stage (see below).
3. The result is deep-merged over the built-in defaults, so you only write the keys you change.
4. encryption_key must be present: encryption_key is required in server config. Set ENVOY_ENCRYPTION_KEY env var or provide it directly. The key must be valid base64 that decodes to 32 bytes; otherwise boot fails with Encryption key "default" is not valid base64. Generate one with: openssl rand -base64 32 or the 32-byte variant of that message.
5. Cross-field checks run, each with a verbatim error:
   • mssql config is missing required fields: <fields> — mssql is present but lacks server, database, user, or password.
   • runs.log_store is "mssql" but no mssql config section is provided
   • runs.log_store is "victoria_logs" but no victoria_logs.url is provided
   • store.type is "mssql" but no mssql config section is provided
   • store.type is "postgres" but no postgres.connection_string is provided
   • runs.log_store is "postgres" but no postgres.connection_string is provided
   • secrets.default must be one of: sqlite, mssql, postgres, azure_key_vault (got "<value>")
   • secrets.default is "azure_key_vault" but no secrets.azure_key_vault section is provided
   • secrets.default is "mssql" but the state store is not mssql (and the equivalent messages for sqlite and postgres)
   • secrets.azure_key_vault.vault_url is required

Environment substitution

Any YAML value may reference an environment variable:

encryption_key: ${ENVOY_ENCRYPTION_KEY}
postgres:
  connection_string: ${ENVOY_POSTGRES_CONNECTION_STRING}

Secret URIs

After environment substitution, values of the form ${secret://<provider>/<handle>} are resolved through the registered secret providers:

mssql:
  password: ${secret://azure_key_vault/envoy-prod-mssql-pwd}

Referencing a provider that is not registered fails with Cannot resolve "<token>": SecretProvider "<provider>" is not registered. See Hardening, RBAC, and secrets for the provider model.

server

store

type: mssql requires the top-level mssql section; type: postgres requires postgres.connection_string. See Backups and upgrades for what to back up per backend.

logging

Both keys are declared optional in ServerConfig and default to an empty section. Structured server logs are written to logs/envoy.log by the pino logger regardless.

runs

Retention behavior is covered in Retention; the victoria_logs store in VictoriaLogs.

branding

See Branding.

scheduler

connectors

encryption_key

Losing this key makes stored secrets unrecoverable. Keep it with your backups. See Hardening, RBAC, and secrets.

tasks_dir and jobs_dir

Startup import is create-only and can be skipped with ENVOY_SKIP_SEED_IMPORT=true. See Seed import.

executor

See Control plane and executors.

ai

The assistant itself is documented in AI assistant.

mssql

Required when store.type or runs.log_store is mssql.

postgres

Required when store.type or runs.log_store is postgres.

auth

Callback URL registration is covered in OAuth redirect URIs.

secrets

An in-database default (sqlite, mssql, postgres) must match store.type; validation rejects mismatches at boot. Changing default affects new writes only — existing secret records keep their original provider and handle.

saffron

Deployment configuration for the optional embedded credential vault and connect UI served under /saffron. Document values come from your delivery; the keys are:

cardamom

Deployment-level catalog defaults. When configured, Envoy registers one connector type per catalog integration at boot; the keys are deployment configuration only.

Environment variables take precedence over the YAML values. See Customer builds and catalog.

victoria_logs

Required when runs.log_store is victoria_logs.

Full backend behavior is documented in VictoriaLogs.

Related

• Docker — how the entrypoint generates this file on first boot
• Control plane and executors — the executor section in practice
• Retention — what runs.retention deletes and keeps
• Hardening, RBAC, and secrets — encryption_key, auth, and secrets in depth