Server configuration

The Envoy control plane reads its YAML configuration at startup:

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

Docker deployments normally set ENVOY_CONFIG_PATH and invoke the same command through the image entrypoint.

Minimal configuration

server:
  port: 3000
  host: 0.0.0.0
  cors_origin: https://envoy.example.com
  secure_cookies: true
 
store:
  type: sqlite
  path: /app/state/envoy-server.db
 
runs:
  log_store: db
  log_dir: /app/state/logs/runs
  max_concurrent: 50
  retention:
    max_age_days: 30
    delete_runs: false
    cleanup_cron: "0 3 * * *"
 
encryption_key: ${ENVOY_ENCRYPTION_KEY}
tasks_dir: ./tasks
jobs_dir: ./jobs

Use HTTPS with secure_cookies: true in production. Restrict cors_origin to the browser origin instead of leaving it as *.

Environment substitution

Any YAML value may reference an environment variable:

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

The server resolves these references before validating the configuration.

Server

State backend

store.type accepts sqlite, mssql, or postgres.

SQLite

store:
  type: sqlite
  path: /app/state/envoy-server.db

SQLite is the runtime default. Put the file on durable storage and back it up with its encryption key.

Microsoft SQL Server

store:
  type: mssql
 
mssql:
  server: sql.example.database.windows.net
  database: envoy
  user: envoy_app
  password: ${MSSQL_PASSWORD}
  port: 1433
  encrypt: true
  trust_server_certificate: false
  pool_size: 20

The mssql section is also required when runs.log_store is mssql.

PostgreSQL

store:
  type: postgres
 
postgres:
  connection_string: ${POSTGRES_URL}
  ssl: require
  pool_size: 5
  connection_timeout: 10
  idle_timeout: 30
  max_lifetime: 600
  query_timeout: 30000
  execute_timeout: 300000

The postgres section is required when either the state backend or run log store uses PostgreSQL.

Run logs, concurrency, and retention

runs:
  log_store: file
  log_dir: ./logs/runs
  max_concurrent: 50
  retention:
    max_age_days: 30
    delete_runs: false
    cleanup_cron: "0 3 * * *"

runs.log_store accepts file, db, mssql, postgres, or victoria_logs.

• max_concurrent: 0 means no server-side limit.
• max_age_days <= 0 disables scheduled retention.
• delete_runs: false removes expired log content but keeps run rows.
• delete_runs: true also removes expired run rows and their metrics.

See Run and log retention.

Executor

Omit executor or use type: local to run subprocesses on the server host:

executor:
  type: local

Use HTTP mode for separate executors:

executor:
  type: http
  config:
    callback_url: http://control-plane:3000
    executor_key: ${ENVOY_EXECUTOR_KEY}

The same executor key must be available to every participating control plane and executor. See Control plane and executors.

Branding

branding:
  app_name: Envoy
  logo_url: /branding/logo.png
  icon_url: /branding/icon.png
  favicon_url: /branding/favicon.ico

Relative URLs refer to assets served with the UI. Deployment automation can set the corresponding ENVOY_APP_NAME, ENVOY_LOGO_URL, ENVOY_ICON_URL, and ENVOY_FAVICON_URL values when generating first-boot config.

See Branding and white-label configuration for asset requirements and fallback behavior.

Scheduler and uploads

scheduler:
  max_inflight_age_minutes: 60
 
connectors:
  upload_max_bytes: 26214400

The scheduler threshold prevents an abandoned in-flight job from blocking a schedule indefinitely. Connector upload size is a server-wide cap; the shown value is 25 MiB.

Authentication

auth:
  totp_required: true
  providers:
    microsoft:
      client_id: ${MICROSOFT_CLIENT_ID}
      client_secret: ${MICROSOFT_CLIENT_SECRET}
      tenant_id: organizations
    google:
      client_id: ${GOOGLE_CLIENT_ID}
      client_secret: ${GOOGLE_CLIENT_SECRET}

TOTP is required for password flows unless explicitly set to false. OAuth providers appear only when configured. OAuth uses Authorization Code with PKCE; MFA policy for OAuth remains with the identity provider.

Secret providers

Without an explicit secrets.default, new secrets use the encrypted provider matching store.type.

secrets:
  default: azure_key_vault
  azure_key_vault:
    vault_url: https://my-vault.vault.azure.net/
    name_prefix: envoy-

Existing secret records retain their original provider and handle. Changing the default affects new writes; it does not automatically migrate existing records.

Azure Key Vault values can be used during bootstrap:

mssql:
  password: ${secret://azure_key_vault/envoy-sql-password}

In-database providers are not available early enough to resolve server YAML. Only the Azure Key Vault form is valid there.

AI assistant

ai:
  provider: anthropic
  api_key: ${ANTHROPIC_API_KEY}
  model: claude-opus-4-8
  embeddings:
    provider: local
    local:
      model_path: ./models
      wasm_path: ./ort

The API key can also be stored from Settings. Keep model and compaction tuning at their runtime defaults unless you have tested a reason to change them. See AI assistant.