Skip to content

Configure Chat

The chat agent is a core capability. It reuses the shared inference variables — see Inference — and adds a chat-completion model identifier and a receipt-chain signing key.

When ARIS_INFERENCE_PROVIDER is empty or mock, or when ARIS_INFERENCE_CHAT_MODEL is empty, the chat handler is not mounted and the rest of the server runs as before.

These variables belong in the core container's environment.

Chat model

Variable Required Default What it does
ARIS_INFERENCE_CHAT_MODEL yes — Chat model identifier. See Approved models for the supported set.

The chat agent speaks OpenAI-compatible /v1/chat/completions, so the configured provider must be one of openai, openai-compatible, or litellm. For Anthropic and Google models, front them with a LiteLLM proxy and point ARIS at the gateway. See Inference — supported providers.

Approved models

The chat agent runs a multi-turn tool-using loop, so picks lean toward quality over cost — flagship Opus / GPT-5.5-pro / Gemini Pro-preview tiers are approved on request but not the default recommendation; tiny "nano" / "flash-lite" tiers tend to fail tool-call reliability.

Vendor Model Provider value Context
Anthropic claude-sonnet-4-6 litellm 1M tokens
OpenAI gpt-5.4 openai —
Google gemini-2.5-pro litellm 1M tokens

Verified against vendor model lists in May 2026. Check the vendor's documentation for current availability, pricing, and context limits before committing to a deployment: Anthropic, OpenAI, Google Gemini.

Receipt-chain signing

Every tool call the chat agent makes is logged in a per-conversation receipt chain, signed with an ed25519 key. In production, configure a stable signing key so receipts remain verifiable across restarts.

Variable Required Default What it does
ARIS_CHAT_RECEIPT_SIGNING_KEY_PATH yes (production) — Path to a PKCS#8 PEM ed25519 private key. If unset, the server generates an ephemeral keypair at boot and logs a warning — receipts will not verify across restarts.
ARIS_CHAT_RECEIPT_SIGNING_KEY_ID yes when _PATH is set auto-minted in dev Stable identifier for the signing key, written into every receipt. Required whenever _PATH is set. In dev mode, the server mints a process-unique value (dev-ephemeral-<uuid>) so successive restarts don't collide on a stable id.

Generate a key:

openssl genpkey -algorithm ed25519 -out chat-signing-key.pem

Then set:

ARIS_CHAT_RECEIPT_SIGNING_KEY_PATH=/run/secrets/chat-signing-key.pem
ARIS_CHAT_RECEIPT_SIGNING_KEY_ID=chat-2026-05

Use a date-stamped or version-stamped id. When you rotate the key, ARIS keeps the old public key in chat_signing_keys so historical receipts continue to verify; the new id is stamped onto receipts going forward.

Operator kill switches

Three independent switches let an operator disable parts of the chat surface without redeploying.

Variable Default Effect
ARIS_CHAT_ENABLED true When false, all /v1/chat/* endpoints return 503 service_disabled and the web UI hides the chat panel.
ARIS_CHAT_SQL_TOOL_ENABLED true When false, the agent's query_sql/list_tables/describe_table tools are removed from the per-turn allowlist. The agent is told via system prompt that SQL is unavailable.

Switches are read at startup. Toggling requires an aris-server restart.

Verifying the configuration

After setting the variables and restarting aris-server:

  1. Sign in to the web UI as an operator.
  2. Open the chat panel. Ask a question that exercises a tool — for example, "How many people are in the Engineering org?"
  3. The answer should stream in with visible citation chips. Open one to confirm the source.
  4. In aris-server logs, you should see no chat agent disabled (...) line at startup.

If chat is silently disabled, the startup log line names the missing setting:

  • chat agent disabled (ARIS_INFERENCE_PROVIDER unset or mock)
  • chat agent disabled (ARIS_INFERENCE_CHAT_MODEL unset)

If a signing key path is set but the id is missing, the server fails to start with ARIS_CHAT_RECEIPT_SIGNING_KEY_ID is required when ARIS_CHAT_RECEIPT_SIGNING_KEY_PATH is set.

See also