agent-orchestrator/docs/config/ref-settings.md

Configuration Reference

All configuration paths, environment variables, database files, and per-project settings for Agents Orchestrator.

Environment variables

Core

Variable	Default	Description
AGOR_TEST	unset	Set to 1 to enable test mode. Disables file watchers, wake scheduler, and telemetry.
AGOR_OTLP_ENDPOINT	unset	OpenTelemetry OTLP/HTTP endpoint (e.g. http://localhost:4318). When unset, telemetry is console-only.
AGOR_TEST_DATA_DIR	unset	Override data directory in test mode. Isolates SQLite databases.
AGOR_TEST_CONFIG_DIR	unset	Override config directory in test mode. Isolates groups.json and plugins.
AGOR_TEST_CTX_DIR	unset	Override ctx database directory in test mode.
AGOR_EDITION	community	Set to pro to enable commercial features (used by vitest and CI).

Provider-specific

Provider environment variables (CLAUDE_*, CODEX_*, OLLAMA_*) are stripped from the sidecar process environment to prevent cross-contamination. The whitelist CLAUDE_CODE_EXPERIMENTAL_* is preserved.

Variables the sidecar runner may read:

Variable	Provider	Description
ANTHROPIC_API_KEY	Claude	API key (used by Claude CLI internally)
OPENAI_API_KEY	Codex	API key for Codex SDK
OPENROUTER_API_KEY	Aider	API key for OpenRouter-routed models
CLAUDE_CONFIG_DIR	Claude	Override Claude config directory (multi-account)
BTMSG_AGENT_ID	All (Tier 1)	Injected for management agents to enable btmsg/bttask CLI

Config files

Base directory: ~/.config/agor/

groups.json

Primary configuration file. Defines project groups, projects, and management agents.

~/.config/agor/groups.json

Schema: GroupsFile (see src/lib/types/groups.ts).

Structure:

{
  "version": 1,
  "groups": [
    {
      "id": "group-id",
      "name": "Group Name",
      "projects": [ ... ],
      "agents": [ ... ]
    }
  ],
  "activeGroupId": "group-id"
}

Managed via the Settings tab in the UI or by editing the file directly. Changes are picked up on next group load.

accounts.json (Pro edition)

Commercial multi-account configuration.

~/.config/agor/accounts.json

Only present when AGOR_EDITION=pro. Not included in the community build.

plugins/

Plugin discovery directory. Each plugin is a subdirectory containing a plugin.json manifest.

~/.config/agor/plugins/
  my-plugin/
    plugin.json
    index.js

Plugins run in Web Worker sandboxes with permission-gated APIs. See src/lib/plugins/plugin-host.ts.

Database files

Base directory: ~/.local/share/agor/

All databases use SQLite WAL mode with 5-second busy timeout for concurrent access.

sessions.db

Session persistence, layout state, settings, session metrics, and anchors.

~/.local/share/agor/sessions.db

Tables:

Table	Description
sessions	Session state (project_id, group_name, layout data)
agent_messages	Per-project message persistence
project_agent_state	SDK session ID, cost, status per project
session_metrics	Historical session data (tokens, turns, cost, model)
session_anchors	Preserved turns through compaction chains
settings	Key-value application settings

btmsg.db

Shared database for inter-agent messaging (btmsg) and task board (bttask).

~/.local/share/agor/btmsg.db

Created by the btmsg CLI on first btmsg register. Used concurrently by Python CLIs and the Rust backend.

Tables:

Table	Description
agents	Registered agents (id, name, role, group_id, tier, model, status)
messages	Direct messages between agents
channels	Named broadcast channels
channel_messages	Messages posted to channels
contacts	ACL for agent-to-agent visibility
heartbeats	Agent liveness tracking
dead_letter_queue	Undeliverable messages
audit_log	Agent action audit trail
seen_messages	Per-message read tracking (session_id, message_id)
tasks	Kanban task board entries
task_comments	Comments on tasks

search.db

FTS5 full-text search index.

~/.local/share/agor/search.db

Virtual tables:

Table	Description
search_messages	Indexed agent messages
search_tasks	Indexed task board entries
search_btmsg	Indexed btmsg messages

Rebuilt on demand via the search overlay (Ctrl+Shift+F).

Tauri configuration

src-tauri/tauri.conf.json

Community edition Tauri config. Defines window properties, permissions, updater endpoint, and bundle metadata.

src-tauri/tauri.conf.commercial.json

Commercial edition overlay. Merged with the base config when building with --config src-tauri/tauri.conf.commercial.json. Changes bundle identifier, product name, and updater URL.

Theme settings

17 themes in 3 groups, all mapping to the same 26 --ctp-* CSS custom properties.

Group	Themes
Catppuccin	Mocha (default), Macchiato, Frappe, Latte
Editor	VSCode Dark+, Atom One Dark, Monokai, Dracula, Nord, Solarized Dark, GitHub Dark
Deep Dark	Tokyo Night, Gruvbox Dark, Ayu Dark, Poimandres, Vesper, Midnight

Settings keys (persisted in sessions.db settings table):

Key	Default	Description
theme	mocha	Active theme ID
ui_font_family	system sans-serif	UI element font
ui_font_size	14 (px)	UI font size (feeds CSS --ui-font-size)
term_font_family	system monospace	Terminal font
term_font_size	14 (px)	Terminal font size (feeds CSS --term-font-size)
default_shell	system default	Default shell for terminal panes
default_cwd	~	Default working directory

All font settings are restored from SQLite on startup via initTheme().

Per-project settings

These fields are set in groups.json per project entry (ProjectConfig):

Field	Type	Default	Description
provider	ProviderId	claude	Agent provider
model	string	provider default	Model identifier override
profile	string	default	Claude profile name
useWorktrees	boolean	false	Git worktree isolation per session
sandboxEnabled	boolean	false	Landlock filesystem sandbox
autonomousMode	string	restricted	restricted or autonomous
anchorBudgetScale	string	medium	Anchor budget: small (2K), medium (6K), large (12K), full (20K)
stallThresholdMin	number	15	Minutes before idle agent is marked stalled (range 5--60)

Agent-specific fields

Set on GroupAgentConfig entries in the agents array:

Field	Type	Default	Description
role	string	required	manager, architect, tester, or reviewer
wakeIntervalMin	number	3	Auto-wake check interval (Manager only)
wakeStrategy	string	smart	persistent, on-demand, or smart
wakeThreshold	number	0.5	Threshold for smart wake strategy (0.0--1.0)
systemPrompt	string	none	Custom system prompt appended to generated prompt