Configuration

Chvor is configured through a combination of environment variables and a runtime config file. Environment variables handle secrets and infrastructure. The config file (and the Settings UI) handles everything else.

Important: Currently, Chvor runs locally on your machine. Do not expose your instance to the public internet without authentication (set CHVOR_TOKEN). Agent mode — allowing your AI to serve users publicly with built-in auth, rate limiting, and multi-tenant support — is coming soon.

The .env file

Your .env file lives in the project root (or is passed to Docker via env_file). Here is a complete reference:

# ──────────────────────────────────────────────
# LLM Providers (at least one required)
# ──────────────────────────────────────────────
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AI...

# ──────────────────────────────────────────────
# Authentication
# ──────────────────────────────────────────────
# Protects the web UI and API. If unset, anyone with
# network access to the server can use your instance.
CHVOR_TOKEN=your-secret-token

# ──────────────────────────────────────────────
# Channel Tokens
# ──────────────────────────────────────────────
TELEGRAM_BOT_TOKEN=123456:ABC-...
DISCORD_BOT_TOKEN=MTIz...
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=abc123...

# ──────────────────────────────────────────────
# Server
# ──────────────────────────────────────────────
PORT=5173
HOST=0.0.0.0

# ──────────────────────────────────────────────
# Data
# ──────────────────────────────────────────────
# Where Chvor stores its SQLite database, memory,
# and uploaded files. Defaults to ~/.chvor/
CHVOR_DATA_DIR=~/.chvor

Security: Never commit your .env file to version control. The .gitignore in the repository already excludes it.

---

LLM provider setup

Chvor supports multiple LLM providers simultaneously. You can switch between them per conversation or set a default.

Anthropic (Claude)

1. Get an API key from console.anthropic.com.
2. Set ANTHROPIC_API_KEY in your .env.
3. Available models: claude-sonnet-4-20250514, claude-haiku-235-20241022, and others as Anthropic releases them.

OpenAI

1. Get an API key from platform.openai.com.
2. Set OPENAI_API_KEY in your .env.
3. Available models: gpt-4o, gpt-4o-mini, o1, o3-mini, and others.

Google (Gemini)

1. Get an API key from aistudio.google.com.
2. Set GOOGLE_API_KEY in your .env.
3. Available models: gemini-2.5-pro, gemini-2.5-flash, and others.

Selecting the default model

In the Settings UI, go to the Models tab to set which provider and model are used by default. You can also override this in the config file:

{
  "model": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }
}

Each conversation can override the default — click the model selector at the top of the chat panel.

---

Authentication with CHVOR_TOKEN

Setting CHVOR_TOKEN enables token-based authentication across the entire platform:

• Web UI: On first visit, you are prompted for the token. It is stored in your browser’s local storage.
• API: All requests to the Hono server must include an Authorization: Bearer <token> header.
• Channels: Telegram, Discord, and Slack connections are authenticated by their own platform tokens, but the internal API calls they make still respect CHVOR_TOKEN.

If CHVOR_TOKEN is not set, the instance is open to anyone who can reach it on the network. This is fine for local development but dangerous in production.

---

Channel configuration

Chvor can simultaneously serve conversations across multiple channels. Each channel runs as an adapter on the same server — one instance, many frontends.

Telegram

1. Create a bot with @BotFather on Telegram.
2. Copy the token BotFather gives you.
3. Set TELEGRAM_BOT_TOKEN in your .env.
4. Restart Chvor. The bot connects automatically using long polling — no webhook URL needed for development.

For production with webhooks, also set:

TELEGRAM_WEBHOOK_URL=https://your-domain.com/api/channels/telegram/webhook

Discord

1. Create an application at discord.com/developers.
2. Under the Bot tab, click Reset Token and copy it.
3. Under Privileged Gateway Intents, enable Message Content Intent.
4. Set DISCORD_BOT_TOKEN in your .env.
5. Invite the bot to your server using the OAuth2 URL generator (select the bot scope and Send Messages, Read Message History permissions).
6. Restart Chvor.

Slack

1. Create a Slack app at api.slack.com/apps.
2. Under OAuth & Permissions, add these bot token scopes: chat:write, app_mentions:read, channels:history, im:history.
3. Install the app to your workspace.
4. Copy the Bot User OAuth Token and Signing Secret.
5. Set SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET in your .env.
6. Under Event Subscriptions, set the request URL to https://your-domain.com/api/channels/slack/events.
7. Subscribe to message.im and app_mention events.
8. Restart Chvor.

Channel status

You can see which channels are active on the Brain Canvas — each connected channel appears as a lit node. In the Settings UI, the Channels tab shows connection status, message counts, and lets you enable or disable channels without removing their tokens.

---

Config through UI vs environment variables

Chvor has two configuration layers:

Setting	Environment Variable	UI / Config File	Which Wins?
API keys	.env	Not available in UI	.env only
CHVOR_TOKEN	.env	Not available in UI	.env only
Channel tokens	.env	Not available in UI	.env only
Default model	—	Settings > Models	Config file
AI identity	—	Settings > Identity	UI (stored in config)
Port / host	.env	—	.env only

Rule of thumb: Secrets go in .env. Everything else goes in the Settings UI, which writes to ~/.chvor/config.json.

---

The data directory

By default, Chvor stores all persistent data in ~/.chvor/. You can change this with CHVOR_DATA_DIR.

~/.chvor/
├── config.json        # Runtime configuration (identity, model prefs, etc.)
├── chvor.db           # SQLite database (conversations, messages, memory)
├── chvor.db-wal       # SQLite write-ahead log
├── memory/            # Long-term memory embeddings and indexes
└── uploads/           # Files uploaded through the chat interface

Backing up your data

The SQLite database is the single source of truth. To back up:

# Stop the server first to avoid a partial snapshot
cp ~/.chvor/chvor.db ~/.chvor/chvor.db.backup

Or, if you are using Docker with a named volume:

docker run --rm -v chvor-data:/data -v $(pwd):/backup \
  alpine cp /data/chvor.db /backup/chvor.db.backup

Resetting to a clean state

To start fresh, stop the server and delete the data directory:

rm -rf ~/.chvor

On next launch, Chvor recreates the directory and initializes a new database.

---

Next steps

Your instance is configured. Explore the Core Concepts section to learn about the memory system, MCP tools, and custom skills — or jump straight into the Guides for practical walkthroughs.