Server Configuration

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.

Config resolution

Tell looks for a config file in this order:

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

On servers, set TELL_CONFIG so all commands use the right config without flags. See Self-hosting for setup.

Minimal server config

A Tell server with local auth and ClickHouse query backend:

[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

[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

[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)

[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)

[query]
clickhouse_url = "http://localhost:8123"
clickhouse_database = "tell"
clickhouse_username = "default"
clickhouse_password = ""

Or reference an existing sink by name:

[query]
clickhouse_sink = "clickhouse"

Local (Polars)

[query]
backend = "polars"
data_dir = "./data"

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

Logging

[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

[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 for details.

LLM integration

[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:

[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

[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

[[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 for details.

Getting Started

Tracking

Pipeline

Analytics

Installing

Server Configuration

Config resolution

Minimal server config

API server

Authentication

Local auth

WorkOS (SSO)

Query backend

ClickHouse (recommended)

Local (Polars)

Logging

MCP server

LLM integration

API client

Metrics reporting

Integrations

​Config resolution

​Minimal server config

​API server

​Authentication

​Local auth

​WorkOS (SSO)

​Query backend

​ClickHouse (recommended)

​Local (Polars)

​Logging

​MCP server

​LLM integration

​API client

​Metrics reporting

​Integrations

Config resolution

Minimal server config

API server

Authentication

Local auth

WorkOS (SSO)

Query backend

ClickHouse (recommended)

Local (Polars)

Logging

MCP server

LLM integration

API client

Metrics reporting

Integrations