> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# Server Configuration

> TOML configuration reference for Tell server, API, auth, and query backend.

Tell server configuration lives in a single TOML file. This page covers the server-side settings — API server, authentication, query backend, logging, and integrations. For pipeline configuration (sources, sinks, routing), see [Pipeline Configuration](/pipeline/configuration).

## Config resolution

Tell looks for a config file in this order:

1. `--config` flag — `tell run --config /path/to/config.toml`
2. `TELL_CONFIG` environment variable — `export TELL_CONFIG=/etc/tell/config.toml`
3. `tell-config.toml` in the current directory
4. `config.toml` in the current directory

On servers, set `TELL_CONFIG` so all commands use the right config without flags. See [Self-hosting](/running-tell/self-hosting) for setup.

## Minimal server config

A Tell server with local auth and ClickHouse query backend:

```toml theme={null}
[api_server]
port = 3000

[auth]
provider = "local"
jwt_secret = "your-secret-key-at-least-32-characters-long"

[query]
clickhouse_url = "http://localhost:8123"
clickhouse_database = "tell"
```

## API server

```toml theme={null}
[api_server]
enabled = true
host = "::"
port = 3000
audit_logging = false
control_db = "~/.tell/control.db"
```

| Field           | Default              | Notes                                         |
| --------------- | -------------------- | --------------------------------------------- |
| `port`          | 3000                 | HTTP port                                     |
| `host`          | `"::"`               | Bind address (dual-stack IPv4+IPv6)           |
| `audit_logging` | false                | Log all HTTP requests                         |
| `control_db`    | `~/.tell/control.db` | SQLite database for workspaces, boards, users |
| `tls_cert_path` | —                    | TLS certificate PEM path                      |
| `tls_key_path`  | —                    | TLS private key PEM path                      |

## Authentication

Tell supports local auth (built-in) and WorkOS (SSO).

### Local auth

```toml theme={null}
[auth]
provider = "local"
jwt_secret = "your-secret-key-at-least-32-characters-long"
jwt_expires_in = "24h"

[auth.local]
db_path = "data/users.db"
allow_registration = false
```

* `jwt_secret` — required, must be at least 32 characters
* `allow_registration` — set to `true` to let users self-register after initial setup
* `jwt_expires_in` — how long tokens last (default: 24 hours)

### WorkOS (SSO)

```toml theme={null}
[auth]
provider = "workos"

[auth.workos]
api_key = "sk_live_..."
client_id = "client_..."
redirect_uri = "https://your-domain.com/auth/callback"
```

Both `api_key` and `client_id` are required when using WorkOS.

## Query backend

Tell auto-detects the query backend. If a ClickHouse sink is configured, it uses ClickHouse. Otherwise, it falls back to the local Polars engine.

### ClickHouse (recommended)

```toml theme={null}
[query]
clickhouse_url = "http://localhost:8123"
clickhouse_database = "tell"
clickhouse_username = "default"
clickhouse_password = ""
```

Or reference an existing sink by name:

```toml theme={null}
[query]
clickhouse_sink = "clickhouse"
```

### Local (Polars)

```toml theme={null}
[query]
backend = "polars"
data_dir = "./data"
```

Reads Arrow IPC files from disk. Good for development and small deployments.

## Logging

```toml theme={null}
[log]
level = "info"
format = "console"
output = "stdout"
```

| Field    | Default     | Options                                             |
| -------- | ----------- | --------------------------------------------------- |
| `level`  | `"info"`    | `trace`, `debug`, `info`, `warn`, `error`           |
| `format` | `"console"` | `"console"` (human-readable), `"json"` (structured) |
| `output` | `"stdout"`  | `"stdout"`, `"stderr"`, or a file path              |

## MCP server

```toml theme={null}
[mcp]
http_enabled = true
stdio_enabled = true
```

HTTP transport runs on the API server at `/api/v1/mcp`. Stdio transport is available via `tell mcp`. See [MCP](/tools/mcp) for details.

## LLM integration

```toml theme={null}
[llm]
enabled = true
provider = "anthropic"
model = "claude-sonnet-4-5-20250929"
```

| Field      | Default                        | Notes                                      |
| ---------- | ------------------------------ | ------------------------------------------ |
| `enabled`  | false                          | Enable AI assistant features               |
| `provider` | `"anthropic"`                  | `"anthropic"` or `"openai-compatible"`     |
| `model`    | `"claude-sonnet-4-5-20250929"` | Model ID                                   |
| `api_key`  | —                              | API key (env variable takes priority)      |
| `base_url` | —                              | Custom URL for OpenAI-compatible providers |

## API client

Settings for the `tell` CLI when connecting to a remote server:

```toml theme={null}
[api]
url = "http://localhost:3000"
credential_store = "file"
```

| Field              | Default                 | Options                            |
| ------------------ | ----------------------- | ---------------------------------- |
| `url`              | `http://localhost:3000` | Server URL                         |
| `credential_store` | `"file"`                | `"file"`, `"keyring"`, or `"auto"` |

## Metrics reporting

```toml theme={null}
[metrics]
enabled = true
interval = "1h"
format = "human"
```

Controls pipeline metrics output — batches processed, bytes written, connection counts. Set `format = "json"` for machine-readable output.

## Integrations

```toml theme={null}
[[plugins]]
name = "github"
entity = "all"
config.token = "${GITHUB_TOKEN}"
```

Each integration is configured as a `[[plugins]]` entry with a name, entity, and service-specific config fields. See [Integrations](/tracking/integrations/overview) for details.