Configuration

All configuration is stored in a single SQLite database at ~/.anna/anna.db. There are no YAML config files. To set up or modify your configuration, run anna --open to open the web admin panel.

The home directory defaults to ~/.anna and can be changed by setting the ANNA_HOME environment variable.

Database Tables

Configuration is spread across several tables in the SQLite database.

settings

A key-value store for global settings. Each row has a key (text) and a value (JSON text). Known keys:

settings_agents

One row per agent.

settings_channels

One row per channel instance. Multiple rows can share the same platform type, such as multiple Feishu bot instances.

settings_users

Maps external platform users to agents.

settings_channel_agents

Routes a specific group chat to a specific agent.

Composite primary key: (channel_id, chat_id).

Runner Settings

Stored in the settings table under the runner key as a JSON object.

Channel Config Blobs

Each platform stores its own JSON structure in the config column of settings_channels.

Telegram

{
  "token": "BOT_TOKEN",
  "enable_notify": false,
  "notify_chat": "123456789",
  "channel_id": "@my_channel",
  "group_mode": "mention",
  "allowed_ids": [136345060]
}

QQ

{
  "app_id": "QQ_BOT_APP_ID",
  "app_secret": "QQ_BOT_APP_SECRET",
  "enable_notify": false,
  "group_mode": "mention",
  "allowed_ids": []
}

Feishu

{
  "app_id": "FEISHU_APP_ID",
  "app_secret": "FEISHU_APP_SECRET",
  "encrypt_key": "",
  "verification_token": "",
  "enable_notify": false,
  "notify_chat": "oc_xxx",
  "group_mode": "mention",
  "allowed_ids": []
}

group_mode accepts mention, always, or disabled.

Directory Layout

• anna.db is the single source of truth for all configuration, memory, and scheduler data.
• workspaces/ contains per-agent data. Each agent gets its own directory keyed by agent ID.
• cache/ contains regenerable data. Run anna models update to rebuild.
• agent sandbox config lives on each agent record (settings_agents.sandbox). The agent form edits network policy; backend can also be set in the stored JSON.
  • backend: auto (default), boxsh, or docker
  • network.mode: disabled (default), allow_all, or whitelist
  • network.allowlist: required only when mode is whitelist
  • Linux and macOS validate the managed boxsh backend when selected. Runner startup fails closed when the sandbox backend is unavailable or cannot enforce the configured network mode.
  • auto selects boxsh on Linux/macOS; on other platforms it fails closed — configure docker explicitly.
  • Current boxsh client builds may reject whitelist mode at runtime; use it only when your runtime supports whitelist enforcement.
  • docker runs each session in a dedicated container built from the bundled plugins/sandbox/docker/Dockerfile. The image is version-locked to the anna binary: dev builds use a local anna-sandbox:dev tag (produced by mise run sandbox:docker:build), and tagged releases pull ghcr.io/vaayne/anna-sandbox:<version> from GHCR. It is opt-in; auto does not select it. Requires a reachable docker daemon. Useful on Windows (where boxsh is unavailable) and for workflows that need a specific Linux userspace.
  • The docker backend takes no per-agent knobs. The image, the in-container user (anna, UID 1000), and bind-mount layout are all fixed by the shipped image. When anna itself runs inside a container and talks to a host docker daemon (Docker-outside-of-Docker), set the ANNA_HOME_HOST environment variable — anna auto-derives the path translation from it.
  • Docker backend does not currently implement whitelist network mode or HTTP mediation — it fails closed, the same as boxsh. Use disabled or allow_all.
  • Docker bind-mounts the workspace root at /home/anna/workspace and each read-only path at /home/anna/readonly/<index>. Scripts that rely on absolute host paths will need to use the in-container path instead.

Example JSON for a docker-backed agent's sandbox field:

{
  "backend": "docker",
  "network": { "mode": "allow_all" }
}

Environment Variables

The old ANNA_* prefix overrides for all config fields are removed. Only the following environment variables are recognized:

All other configuration must be set through the admin panel (anna --open) or directly in the database.

Memory Defaults

Lossless Context Management settings are currently hardcoded defaults. They will become configurable in a future release.

Heartbeat

Heartbeat only runs in server mode (anna). Configuration is stored in the settings table under the heartbeat key. Each tick first uses the fast model to decide skip vs run, and only run decisions are sent into the main heartbeat session and then delivered through the notifier. Instructions are read from the agent's HEARTBEAT.md file.

Plugins

Plugins are stored in the settings table under the plugins key as a JSON array. Each entry has a path to a JS file and an optional config object:

[
  { "path": "~/plugins/hello.js" },
  { "path": "/abs/path/notify.js", "config": { "webhook_url": "https://example.com" } }
]

Runtime Plugin Bindings

Subprocess plugin bindings are stored separately under the runtime_plugins key:

{
  "tools": {
    "read": "tool/read",
    "bash": "tool/bash"
  },
  "channels": {
    "telegram": "channel/telegram",
    "qq": "channel/qq"
  }
}

These bindings control which runtime plugin ID handles each built-in tool or channel slot. If a slot has no explicit override, anna falls back to the bundled first-party plugin for that slot. Use anna plugin runtime list to inspect the effective bindings and anna plugin runtime bind ... to change them.