Configuration

Configure the agent entirely through environment variables. Start with the core LLM settings, then add provider keys, access control, and persistence as you need them.

Core LLM settings

These three variables cover most deployments.

LLM_API_KEY=sk-or-...
LLM_API_BASE=https://openrouter.ai/api/v1
LLM_MODEL=openrouter:openrouter/auto

Provider-specific keys

Set the key for each provider you want to use. Only providers with a key configured appear as selectable in the model picker.

OpenRouter dynamic models (relevance ranking)

When OPENROUTER_API_KEY is set, GET /api/v1/agents/models also loads OpenRouter's public catalog (GET {OPENROUTER_MODELS_API}) and appends a bounded set of tool-capable models on top of the curated registry.

Unlike AnyRouter, OpenRouter exposes no usage-ranking API — the order query parameter is accepted but ignored, and the ranking endpoints behind openrouter.ai are not public. The ranking is therefore a deterministic relevance score (curated-registry membership, well-known model authors, free variants, context size, recency), not measured usage. Models without tool calling are excluded, since the agent cannot use them.

AnyRouter presets

When ANYROUTER_API_KEY is set, the authenticated catalog response also carries your workspace's presets, which the picker lists as anyrouter:@preset/<slug>. Selecting one sends the preset's own model, system prompt, and sampling settings.

Sign in with AnyRouter (bring your own credits)

Users can sign in to AnyRouter directly from the model picker (or the Provider & Models settings tab) instead of relying on the deployment's key. The server runs an OAuth 2.1 authorization-code + PKCE flow in a popup; the resulting token is held in that browser only and replayed per request through the existing BYOK path, so it is never persisted or logged server-side. AnyRouter tokens last about 30 days and have no refresh token — signing in again mints a fresh one.

Sign-in is offered only when ANYROUTER_API_KEY is not set. With a key configured the provider already works for everyone, so the flow is hidden; without one, it unlocks AnyRouter models that would otherwise be unavailable.

AnyRouter dynamic models (usage ranking)

When ANYROUTER_API_KEY is set, GET /api/v1/agents/models also loads AnyRouter’s public catalog (GET {ANYROUTER_API_BASE}/models) and ranks a bounded set of tool-capable models by real usage (GET .../models/{id}/metrics → request_count). List-level sort=usage is not supported by AnyRouter — ranking is always metrics-based.

The picker then includes:

1. anyrouter:auto — default when AnyRouter is configured. The agent route resolves it at request time to the current top tool-capable model by usage (cached ~5 minutes), falling back to the curated static default (anyrouter:google/gemma-4-26b-a4b-it) if the catalog/metrics are unavailable.
2. Router aliases when present in the catalog — e.g. anyrouter/agent, anyrouter/free, anyrouter/coding.
3. Top-N concrete models by request_count (function-calling preferred).

Failures are fail-soft: OpenRouter-only / OSS deploys without AnyRouter keep the static MODEL_REGISTRY path with no live dependency on anyrouter.dev.

Extra models

LLM_EXTRA_MODELS adds entries to the model picker without touching code. Format:

provider:modelId[|contextLength][|description]

• provider — one of openrouter, nvidia, anyrouter
• modelId — model ID passed to the provider (may contain colons)
• contextLength — optional integer token count; defaults to 128000
• description — optional display label; defaults to modelId

Comma-separate multiple models:

LLM_EXTRA_MODELS="nvidia:meta/llama-3.3-70b|131072|Llama 3.3 70B,openrouter:x-ai/grok-2"

Extra models are appended after the built-in registry. If an extra entry shares a provider:modelId key with a built-in, the built-in wins.

Access & safety

Require auth on public deployments:

CHM_FEATURE_AGENT_ACCESS=authenticated

Protect the API endpoint with a bearer token:

AGENT_API_TOKEN=your-secret-token

curl -H "Authorization: Bearer $AGENT_API_TOKEN" \
     -d '{"message":"...","hostId":0}' \
     https://your-host/api/v1/agent

Cross-source Postgres tools

Set CHM_FEATURE_POSTGRES_SOURCE=true to expose the agent's read-only Postgres tools (run_postgres_select_query, get_postgres_metrics, list_postgres_slow_query_patterns, get_postgres_table_stats). They resolve a per-call pgHostId against the POSTGRES_* env lists below — a flat positional index, exactly like a ClickHouse hostId indexes the CLICKHOUSE_* lists. All lists are comma-separated and index-aligned with POSTGRES_HOST; a single POSTGRES_USER / POSTGRES_PASSWORD broadcasts to every host.

Point the Postgres user at a read-only role. The tools pin the session read-only and gate the SQL, but a least-privilege user is defense in depth.

CHM_FEATURE_POSTGRES_SOURCE=true
POSTGRES_HOST=db.internal:5432
POSTGRES_USER=readonly
POSTGRES_PASSWORD=secret
POSTGRES_DATABASE=appdb

Least-privilege ClickHouse user

The agent's query tool (and the MCP server) run read-only SELECTs that the model composes. Because the model can read any table the connection user can, point it at a dedicated, restricted user — not default or an admin account. Two concerns in particular:

• system.query_log can contain credentials embedded in query text (e.g. a CREATE ... IDENTIFIED BY or an s3(...) call another client ran).
• system.users, system.grants, and system.quotas expose your access model.

Create a monitoring user restricted to the system tables the dashboard needs and deny the sensitive ones:

CREATE USER chmonitor_agent IDENTIFIED BY 'a-strong-password'
  SETTINGS readonly = 1;

-- Read-only access to the metrics/monitoring tables the dashboard reads.
GRANT SELECT ON system.* TO chmonitor_agent;

-- Revoke the tables that leak secrets or your access model.
REVOKE SELECT ON system.query_log FROM chmonitor_agent;
REVOKE SELECT ON system.users FROM chmonitor_agent;
REVOKE SELECT ON system.grants FROM chmonitor_agent;
REVOKE SELECT ON system.quotas FROM chmonitor_agent;

Built-in Firecrawl MCP

The agent connects Firecrawl's hosted MCP (https://mcp.firecrawl.dev/v2/mcp) on every request. No API key is required for scrape, search, and parse (rate- limited). Set CHM_AGENT_FIRECRAWL_MCP=false to disable. Register the same URL with a bearer token to override the built-in server.

To restrict which sites Firecrawl may fetch, set CHM_AGENT_FIRECRAWL_ALLOW_DOMAINS to a comma-separated list of hostnames (clickhouse.com,chmonitor.dev,github.com). Unset or empty leaves scrape/crawl/map unrestricted (the OSS default). When set, any url / urls argument whose host is not on the list is blocked before the MCP call; tools with no URL (for example search with only a query) stay allowed. An apex token matches that host and its subdomains (clickhouse.com covers docs.clickhouse.com). A leading *. is subdomain-only (*.example.com matches foo.example.com but not example.com). The same allowlist applies to a user-registered Firecrawl server (mcp.firecrawl.dev or a sanitized name of firecrawl), so renaming the server cannot bypass it.

Conversation persistence

For per-backend env vars and setup, see Conversation history and Store backends.

Where to set these

• Cloudflare Workers — wrangler secret put LLM_API_KEY for secrets; [vars] in wrangler.toml for non-secret values in your own worker. (In this repo's hosted deploy, non-secret config lives in apps/dashboard/.env.production and there is no [vars] block.) See Deploy to Cloudflare.
• Docker — environment: block in docker-compose.yml or --env-file .env. See Deploy with Docker.
• Kubernetes — Secret for keys, ConfigMap for non-secret values. See Deploy to Kubernetes.
• Vercel / self-hosted — environment variables in the project dashboard or .env.local.

Related