# Server configuration

> Source: https://docs.clonepartner.com/deployment/server-configuration/

The Envoy control plane reads its YAML configuration at startup:

```bash
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

```yaml
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:

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

The server resolves these references before validating the configuration.

:::callout{type="warning"}
The Docker entrypoint generates the YAML only when the configured file does not exist. After first boot, inspect and update the persisted YAML rather than assuming an environment-variable change rewrote it.
:::

## Server

| Field | Runtime default | Purpose |
|---|---:|---|
| `server.port` | `3003` | Listen port; standard containers override it to `3000` |
| `server.host` | `0.0.0.0` | Listen address |
| `server.cors_origin` | `*` | Allowed browser origin |
| `server.secure_cookies` | `false` | Add secure cookie protection for HTTPS |

## State backend

`store.type` accepts `sqlite`, `mssql`, or `postgres`.

### SQLite

```yaml
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

```yaml
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

```yaml
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

```yaml
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](/operations/retention).

## Executor

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

```yaml
executor:
  type: local
```

Use HTTP mode for separate executors:

```yaml
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](/deployment/control-plane-and-executors).

## Branding

```yaml
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](/deployment/branding-and-white-label) for asset requirements and fallback behavior.

## Scheduler and uploads

```yaml
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

```yaml
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`.

```yaml
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:

```yaml
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

```yaml
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](/ui/ai-assistant).