Guide
Configuration
All environment variables for configuring the AI Agent — LLM provider, model picker, access control, and conversation persistence.
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.
| Variable | Default | Purpose |
|---|---|---|
LLM_API_KEY | — | Provider API key. Required to enable the agent. |
LLM_API_BASE | https://openrouter.ai/api/v1 | OpenAI-compatible base URL. |
LLM_MODEL | picked automatically | Model identifier (provider:modelId). Optional. |
You do not need to set LLM_MODEL. The default model is picked from whichever provider key is present (AnyRouter first, then OpenRouter, then NVIDIA NIM). If LLM_MODEL names a provider that has no key, the agent logs one warning and uses that automatic default instead of failing.
LLM_API_KEY=sk-or-...
LLM_API_BASE=https://openrouter.ai/api/v1
LLM_MODEL=openrouter:openrouter/autoProvider-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.
| Variable | Provider | Notes |
|---|---|---|
OPENROUTER_API_KEY | OpenRouter | Alias for LLM_API_KEY when using OpenRouter. |
OPENROUTER_API_BASE | OpenRouter | Override base URL. |
OPENROUTER_REFERER | OpenRouter | HTTP referer sent with requests (for leaderboard attribution). |
OPENROUTER_APP_NAME | OpenRouter | App name sent with requests. |
OPENROUTER_MODELS_API | OpenRouter | Override models list URL. |
NVIDIA_API_KEY | NVIDIA NIM | NIM API key. |
NVIDIA_API_BASE | NVIDIA NIM | NIM base URL (defaults to NVIDIA's hosted endpoint). |
ANYROUTER_API_KEY | AnyRouter | AnyRouter API key. |
ANYROUTER_API_BASE | AnyRouter | AnyRouter base URL. |
ANYROUTER_DYNAMIC_MODELS | AnyRouter | Set to false / 0 / off to disable live catalog enrichment (static registry only). On by default when ANYROUTER_API_KEY is set. |
ANYROUTER_TOP_MODELS_N | AnyRouter | Max usage-ranked models to add to the picker (default 8, max 32). |
ANYROUTER_METRICS_CANDIDATE_CAP | AnyRouter | Max catalog models to score via /models/{id}/metrics (default 24, max 64). |
ANYROUTER_PRESETS | AnyRouter | Set to false / 0 / off to hide your workspace presets from the picker. On by default when ANYROUTER_API_KEY is set. |
ANYROUTER_PRESETS_MAX | AnyRouter | Max presets to surface (default 8, max 32). |
ANYROUTER_OAUTH_CLIENT_ID | AnyRouter | Pin a pre-registered OAuth client for "Sign in with AnyRouter". Optional — the server registers one on first use. |
OPENROUTER_DYNAMIC_MODELS | OpenRouter | Set to false / 0 / off to disable live catalog enrichment (curated registry only). On by default when OPENROUTER_API_KEY is set. |
OPENROUTER_TOP_MODELS_N | OpenRouter | Max dynamically ranked models to add to the picker (default 12, max 32). |
NVIDIA_DYNAMIC_MODELS | NVIDIA NIM | Set to false / 0 / off to disable live catalog enrichment (curated registry only). On by default when NVIDIA_API_KEY is set. |
NVIDIA_TOP_MODELS_N | NVIDIA NIM | Max catalog models to add to the picker (default 12, max 32). |
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.
NVIDIA dynamic models (curated allowlist)
When NVIDIA_API_KEY is set, GET /api/v1/agents/models also loads NVIDIA's
public NIM catalog (GET {NVIDIA_API_BASE}/models) and appends a bounded set
of hosted models on top of the curated registry.
That catalog is much thinner than the other two: it returns ids only — no pricing, no context length, and no tool-calling flags. So the picker
- gates eligibility on a curated allowlist of NIM-hosted models verified to drive the agent tool loop (the agent cannot use a model that does not),
- reports a single default context size rather than a per-model claim, and
- shows no cost, because you bill NVIDIA directly on your own key.
The curated registry remains the floor, so an upstream outage degrades to the static list rather than an empty picker.
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 with their own AnyRouter account from the model picker (or the Provider & Models settings tab), so agent requests run on their AnyRouter credits instead of the deployment's key.
The feature is controlled by one flag:
| Variable | Default | Purpose |
|---|---|---|
CHM_AGENT_ANYROUTER_SIGNIN_ENABLED | false | Turn on "Sign in with AnyRouter". The hosted product sets it to true. When false, the sign-in routes return 404 and the agent behaves exactly as before. |
GET /api/v1/config reports it as agent.anyrouterSignin, and the UI only
shows the sign-in button when it is true.
How it works:
- Sign-in. The server runs an OAuth 2.1 authorization-code + PKCE flow in
a popup (
GET /api/v1/agents/anyrouter/login→ AnyRouter →GET /api/v1/agents/anyrouter/callback). The popup hands the token to the page, which keeps it in that browser and sends it with each agent request as the BYOKapiKey. - Guests. Anonymous visitors may sign in too. A guest request with their
own token runs on their AnyRouter account: it may use any
anyrouter:model and does not count toward the free daily cap. The per-IP rate limit, the demo-host restriction, and the ban on custom MCP servers still apply. Without a token, guests get the free demo model and the daily cap as usual. - Signed-in users. The token is also saved on the server, encrypted with
AES-256-GCM, so it follows the user to other devices
(
PUT/GET/DELETE /api/v1/agents/anyrouter/token). TheGETonly reports{ connected, expiresAt }; the token is never returned or logged. Storage uses theCHM_CLOUD_D1binding (tableuser_provider_tokens) and the same key as user connections:CHM_USER_CONNECTIONS_ENCRYPTION_KEY, or one derived fromCLERK_SECRET_KEY. Without a key or D1 binding, the token route returns503and nothing is stored; the browser copy still works. - Which key is used. The key sent with the request comes first. If there
is none, a signed-in user's stored AnyRouter token is used for
anyrouter:models. Otherwise the deployment key is used, with the normal plan limits. A request that uses the user's own key is never metered against included credits. - Expiry. AnyRouter tokens last about 30 days and have no refresh token.
When AnyRouter rejects a user token with
401, the agent returns anauth_errorwithcode: "anyrouter_token_expired", and the UI asks the user to sign in again.
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:
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.- Router aliases when present in the catalog — e.g.
anyrouter/agent,anyrouter/free,anyrouter/coding. - 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 ofopenrouter,nvidia,anyroutermodelId— model ID passed to the provider (may contain colons)contextLength— optional integer token count; defaults to128000description— optional display label; defaults tomodelId
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
| Variable | Default | Purpose |
|---|---|---|
CHM_FEATURE_AGENT_ACCESS | public | Set to authenticated to require login before using the agent. |
AGENT_API_TOKEN | — | Shared Bearer token accepted by POST /api/v1/agent. |
AGENT_ENABLE_CONTROL_TOOLS | on for self-hosted, off in cloud | Controls optimize_table, kill_query, and kill_mutation. Unset: on in self-hosted (auth none, or a signed-in caller), off for anonymous visitors and in cloud mode. false disables them everywhere; true enables them, except for anonymous cloud visitors. |
CHM_AGENT_FIRECRAWL_MCP | true | Connect Firecrawl's hosted MCP (no API key) on every agent request. Set false to disable. |
CHM_AGENT_FIRECRAWL_ALLOW_DOMAINS | (empty) | Comma-separated hostnames Firecrawl may scrape/crawl/map. Empty / unset = unrestricted. Apex tokens also match subdomains; *.example.com is subdomain-only (not the apex). Search-only calls (no URL) stay allowed. |
RATE_LIMIT_AGENT_PER_MIN | 10 | Max POST /api/v1/agent requests per minute, applied per signed-in identity and per IP. |
RATE_LIMIT_AGENT_GUEST_PER_MIN | 5 | Cloud-only tighter per-guest identity limit (key agent:guest:guest:<hash>). OSS anonymous callers stay IP-only. |
CHM_GUEST_AI_REQUESTS_PER_DAY | 3 | Cloud-only daily AI messages for anonymous visitors. Tracked in D1 ai_usage_daily per guest:<ip-hash>. Signed-in users keep their plan cap (Free 5 / Pro 100 / …). OSS is not gated. |
AGENT_DEBUG | false | When truthy (1/true/yes/on), logs verbose agent request/usage details. Leave off in production — it prints message keys, resolved user ids, and token usage. |
Require auth on public deployments:
CHM_FEATURE_AGENT_ACCESS=authenticatedProtect the API endpoint with a bearer token:
AGENT_API_TOKEN=your-secret-tokencurl -H "Authorization: Bearer $AGENT_API_TOKEN" \
-d '{"message":"...","hostId":0}' \
https://your-host/api/v1/agentCross-source Postgres tools
The agent's read-only Postgres tools (run_postgres_select_query,
get_postgres_metrics, list_postgres_slow_query_patterns,
get_postgres_table_stats) turn on by themselves when a POSTGRES_HOST is set
and answers SELECT 1 within the probe budget (see
Integration tool defaults). Set
CHM_FEATURE_POSTGRES_SOURCE=true to force them on, or false to turn them off. 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.
| Variable | Default | Purpose |
|---|---|---|
CHM_FEATURE_POSTGRES_SOURCE | unset (auto) | Three-state gate: unset = on when a host is configured and reachable, true = on when a host is configured, false = off. true also turns on the Postgres UI and API routes. |
POSTGRES_HOST | — | Comma-separated Postgres hosts (host or host:port). Defines the pgHostId id space. |
POSTGRES_PORT | 5432 | Ports (used when a host has no inline :port). |
POSTGRES_USER | postgres | Users; a single value applies to all hosts. |
POSTGRES_PASSWORD | — | Passwords; a single value applies to all hosts. |
POSTGRES_DATABASE | postgres | Database names. |
POSTGRES_SSLMODE | — | libpq sslmode (disable | require | verify-full). |
POSTGRES_NAME | — | Display names for the sources. |
Env hosts only, for now
The agent's Postgres tools read env-configured hosts (POSTGRES_*), like the
ClickHouse tools read CLICKHOUSE_*. Per-user (D1) Postgres connections managed
in the UI are not yet visible to the agent — the same limitation the ClickHouse
agent tools already have. Env Postgres hosts are operator-supplied and trusted
(no SSRF re-guard), matching the CLICKHOUSE_HOST precedent.
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.
POSTGRES_HOST=db.internal:5432
POSTGRES_USER=readonly
POSTGRES_PASSWORD=secret
POSTGRES_DATABASE=appdbPeerDB mirror tool
The agent's read-only PeerDB tools (get_peerdb_mirror_status,
get_peerdb_metrics) read through the same read-only server-side proxy as the
/peerdb pages, so PEERDB_API_URL (and PEERDB_PASSWORD /
PEERDB_AUTH_SCHEME if your PeerDB API needs auth) must be configured — see
PeerDB. They turn on by themselves when PeerDB is
configured and reachable (see
Integration tool defaults). Set
CHM_FEATURE_PEERDB_AGENT=false to keep them away from the model while
keeping the /peerdb pages.
| Variable | Default | Purpose |
|---|---|---|
CHM_FEATURE_PEERDB_AGENT | unset (auto) | Three-state gate: unset = on when PeerDB is configured and reachable, true = on when configured, false = off. CHM_FEATURE_PEERDB_ENABLED=false keeps the tools out even when this is true. |
PEERDB_API_URL | — | PeerDB API base URL (already required for the /peerdb pages). The tool fail-closes with a not-configured message when unset. |
Env PeerDB only, for now
The agent's PeerDB tool reads the env-wide deployment (PEERDB_API_URL),
like the ClickHouse tools read CLICKHOUSE_*. Per-connection (?connection=)
PeerDB links managed in the UI are not yet visible to the agent — the same
limitation the ClickHouse agent tools already have. The model supplies at most
a mirror name (validated, never a URL); mirror config blocks are stripped
before results reach the model, and mutating PeerDB operations are unreachable.
PEERDB_API_URL=https://peerdb.example.com/apiIntegration tool defaults
The Postgres and PeerDB tools are read-only, so they turn on without a flag when the integration is configured and reachable. Each conversation decides once, on its first message, and keeps that tool set for its later turns.
| Flag | Configured | Reachable | Result |
|---|---|---|---|
false | any | any | off |
| any | no | — | off |
true | yes | any | on (errors show when a tool runs) |
| unset | yes | yes | on |
| unset | yes | no, or probe too slow | off |
- Anonymous cloud visitors never get them.
- Signed-in cloud users, and requests on a user's own connection, need the
flag set to
true: the sources are deployment-wide, so they are the operator's data. - Probe: PeerDB gets one read-only API call; Postgres gets
SELECT 1on the first source. The agent waits at mostCHM_AGENT_INTEGRATION_PROBE_TIMEOUT_MS(default and maximum1500). A slow probe counts as unreachable for that conversation and keeps running in the background for the next one. - Cache: results are reused per server instance for
CHM_AGENT_INTEGRATION_PROBE_TTL_MS(default60000), failures for at most 15 seconds. - The tools stay out of the always-loaded core set. When any are on, the
system prompt says so, and the agent finds them with
search_tools. - The server logs one
agent.integration_toolsline each time the result changes, with a reason such asauto,flag_false,unconfigured,unreachable:<kind>,probe_timeout,cloud_anonorneeds_opt_in. It never logs URLs or credentials.
| Variable | Default | Purpose |
|---|---|---|
CHM_AGENT_INTEGRATION_PROBE_TIMEOUT_MS | 1500 | Probe wait budget. Can only lower the default. |
CHM_AGENT_INTEGRATION_PROBE_TTL_MS | 60000 | How long a successful probe result is reused. |
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_logcan contain credentials embedded in query text (e.g. aCREATE ... IDENTIFIED BYor ans3(...)call another client ran).system.users,system.grants, andsystem.quotasexpose 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;Control tools are on by default in self-hosted
Self-hosted deployments give the agent the mutating tools (optimize_table,
kill_query, kill_mutation) unless you set AGENT_ENABLE_CONTROL_TOOLS=false.
Set it to false if the dashboard is shared with people who should not kill
queries. A readonly = 1 ClickHouse user is a second line of defense: the
tools are offered but ClickHouse refuses the writes.
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
| Variable | Type | Default | Purpose |
|---|---|---|---|
VITE_FEATURE_CONVERSATION_DB | Build-time | false | Enable server-side conversation storage. Derived from canonical CHM_FEATURE_CONVERSATION_DB — set that one before pnpm run build. Requires Clerk. |
CONVERSATION_STORE_BACKEND | Runtime | (auto) | Backend: agentstate, d1, postgres, or memory. Auto-selects when unset. |
For per-backend env vars and setup, see Conversation history and Store backends.
Where to set these
- Cloudflare Workers —
wrangler secret put LLM_API_KEYfor secrets;[vars]inwrangler.tomlfor non-secret values in your own worker. (In this repo's hosted deploy, non-secret config lives inapps/dashboard/.env.productionand there is no[vars]block.) See Deploy to Cloudflare. - Docker —
environment:block indocker-compose.ymlor--env-file .env. See Deploy with Docker. - Kubernetes —
Secretfor keys,ConfigMapfor non-secret values. See Deploy to Kubernetes. - Vercel / self-hosted — environment variables in the project dashboard or
.env.local.
Keep LLM keys server-side
Never put LLM API keys in VITE_* variables. Anything prefixed VITE_ is baked into browser JavaScript at build time and is visible to anyone who opens DevTools. Use plain (non-VITE) variables for all keys — they stay on the server.