Configuration

All Choir static resource configuration lives in ~/.choir.d/config.json. Secret values live in ~/.choir.d/secrets.json. Runtime state (sessions, events, memory) lives in Postgres.

Secret Management Pattern

Secret values are never stored in config.json. Every resource that needs a secret contains a "secret" field referencing a named secret in ~/.choir.d/secrets.json (authoritative source for v1). choirctl secret set|delete updates that file.

# Set a secret
echo 'sk-...' | choirctl secret set openrouter-key

# List secret names (never values)
choirctl secret list

# Push the current secrets.json snapshot to choird + running agents
choirctl secret apply

choirctl config apply does not reload secret values; secrets are refreshed only via choirctl secret apply.

Two-Phase Load/Apply

Configuration changes follow a two-phase workflow:

1. Edit config.json on disk.
2. choirctl config load – read and validate the file, stage in choird.
3. choirctl config diff – review staged vs running changes (categorized as hot-reloadable or restart-required).
4. choirctl config apply – push hot-reloadable changes to running agents.
5. For restart-required changes, use choirctl agent update <agent-id> or choirctl agent update-all.

Full config.json Reference

global_repo

URL and ref for the shared tools/skills/identity git repository.

"global_repo": {
  "url": "git@github.com:org/choir-global.git",
  "ref": "main"
}

Host-side choird git operations for global_repo and agent image builds inherit the host’s normal git behavior directly (~/.gitconfig, credential helpers, ssh-agent, ~/.ssh/config).

workspaces

Named workspace definitions with explicit host paths. Workspaces are exclusive resources – only one agent may lease a workspace at a time.

"workspaces": {
  "main-ws": { "path": "/var/lib/choir/workspaces/main" },
  "scratch": { "path": "/var/lib/choir/workspaces/scratch" }
}

models

Named LLM model/provider pairs. Models are shared resources. Must support OpenAI-compatible tool calling.

"models": {
  "sonnet": {
    "provider": "openrouter",
    "model": "anthropic/claude-sonnet-4-20250514",
    "endpoint": "https://openrouter.ai/api/v1",
    "temperature": 0.7,
    "reasoning_effort": null,
    "secret": "openrouter-key"
  }
}

tts

Named text-to-speech provider configurations. Shared resources. v1 supports ElevenLabs only.

"tts": {
  "eleven": {
    "provider": "elevenlabs",
    "model_id": "eleven_multilingual_v2",
    "endpoint": "https://api.elevenlabs.io/v1",
    "secret": "elevenlabs-key"
  }
}

voice_profiles

Named voice configurations referencing a TTS provider. Shared resources.

"voice_profiles": {
  "default-en": {
    "tts": "eleven",
    "voice_id": "...",
    "output_format": "opus_48000_128",
    "voice_settings": {
      "stability": 0.5,
      "similarity_boost": 0.75,
      "style": 0.0,
      "use_speaker_boost": true,
      "speed": 1.0
    }
  }
}

git_identities

Named git identities with name, email, and auth credentials for agents. Exclusive resources – at most one agent may lease a given identity at a time.

"git_identities": {
  "dev-identity": {
    "name": "Dev Agent",
    "email": "dev@choir.local",
    "secret": "git-dev-token",
    "ssh_key": "git-dev-ssh-key",
    "ssh_secret": "git-dev-ssh-secret"
  }
}

notion_integrations

Named Notion integrations. Exclusive resources.

"notion_integrations": {
  "personal-wiki": {
    "secret": "notion-personal-key"
  }
}

email_accounts

Named email accounts with SMTP/IMAP configuration. Exclusive when sharing is "exclusive", shared when "shared".

"email_accounts": {
  "primary-email": {
    "smtp_host": "smtp.example.com",
    "smtp_port": 587,
    "imap_host": "imap.example.com",
    "imap_port": 993,
    "sharing": "exclusive",
    "secret": "email-primary-creds"
  }
}

search

Named search provider configurations. Shared resources.

"search": {
  "brave": {
    "secret": "brave-api-key"
  }
}

embedding

Embedding model configuration. Singleton (one per installation). Used by choird for memory vectorization.

"embedding": {
  "provider": "openrouter",
  "model": "text-embedding-3-small",
  "dimensions": 1536,
  "endpoint": "https://openrouter.ai/api/v1",
  "secret": "openrouter-key"
}

gateways

Named Telegram bot instances. Each gateway is a bot with its own token.

"gateways": {
  "bot-main": {
    "type": "telegram",
    "secret": "tg-bot-main-token"
  }
}

dms

Named DM bindings. Each DM references a gateway and a Telegram user ID. The set of DMs for a bot implicitly forms that bot’s allowlist – messages from unconfigured user IDs are silently ignored.

"dms": {
  "admin-dm": { "gateway": "bot-main", "user_id": "123456789", "admin": true },
  "user-dm":  { "gateway": "bot-main", "user_id": "987654321", "admin": false }
}

postgres

PostgreSQL connection configuration. choird manages per-agent schemas automatically.

"postgres": {
  "host": "localhost",
  "port": 5432,
  "database": "choir",
  "secret": "postgres-admin-creds"
}

agents

Named agent definitions. Each agent references a per-agent git repo and a set of default resource bindings.

"agents": {
  "agent-1": {
    "repo": {
      "url": "git@github.com:org/choir-agent-1.git",
      "ref": "main"
    },
    "defaults": {
      "workspace": "main-ws",
      "llm": "sonnet",
      "voice_profile": "default-en",
      "git_identity": "dev-identity",
      "notion": "personal-wiki",
      "email": "primary-email",
      "dm": "admin-dm"
    }
  }
}

All defaults are overridable at agent start time via flags.

Tunable Defaults

Top-level numeric fields for runtime behavior:

"heartbeat_interval_ms": 5000,
"crash_detection_threshold_ms": 10000,
"rate_limit_retry_ms": 1000,
"log_archive_threshold_lines": 100000

Resource Classification

Exclusive resources are leased at agent start and released at session end (stop, crash, terminate). If an exclusive resource is already leased, the start is rejected.

For the full design specification, see DESIGN.md.