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.
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.tomlTELL_CONFIG environment variable — export TELL_CONFIG=/etc/tell/config.tomltell-config.toml in the current directoryconfig.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 charactersallow_registration — set to true to let users self-register after initial setupjwt_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"
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 = ""
[query]
clickhouse_sink = "clickhouse"
Local (Polars)
[query]
backend = "polars"
data_dir = "./data"
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
/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"
format = "json" for machine-readable output.
Integrations
[[plugins]]
name = "github"
entity = "all"
config.token = "${GITHUB_TOKEN}"
[[plugins]] entry with a name, entity, and service-specific config fields. See Integrations for details.
