Configuration

Bosun uses layered configuration across CLI flags, environment variables, .env, and bosun.config.json. The current authoritative examples are .env.example and bosun.config.example.json in the repo root.

Load order

CLI flags
Environment variables
.env
bosun.config.json
Built-in defaults

Use bosun --doctor after configuration changes. It is the quickest way to check whether the active environment matches what you think Bosun is loading.

Config files

`.env`

This is the primary place for runtime toggles, credentials, transport settings, channel controls, and provider-specific options. The shipped template groups settings by topic, including:

task claims and shared-state coordination
Telegram bot, Mini App, Cloudflare tunnel, and sentinel
voice and desktop settings
kanban, GitHub, Jira, and merge/reconciliation behavior
executor SDKs including Codex, Copilot, Claude, Gemini, and OpenCode
workspace, git, runtime, and container execution settings

`bosun.config.json`

Use structured JSON when you need explicit executor lists, failover policy, workflow-first ownership, repository metadata, prompt overrides, or complexity-routing models.

{
  "$schema": "./bosun.schema.json",
  "projectName": "my-project",
  "primaryAgent": "codex-sdk",
  "workflowFirst": false,
  "kanban": { "backend": "internal" },
  "internalExecutor": { "mode": "internal" },
  "executors": [
    {
      "name": "codex-default",
      "executor": "CODEX",
      "variant": "DEFAULT",
      "weight": 100,
      "role": "primary"
    }
  ],
  "failover": {
    "strategy": "weighted-random",
    "maxRetries": 3,
    "cooldownMinutes": 5,
    "disableOnConsecutiveFailures": 3
  }
}

Executors and routing

Current Bosun builds support multiple execution backends and transports.

Area	Current knobs
Primary routing	`PRIMARY_AGENT`, `EXECUTOR_MODE`, `EXECUTORS`
SDK enable/disable	`CODEX_SDK_DISABLED`, `COPILOT_SDK_DISABLED`, `CLAUDE_SDK_DISABLED`, `GEMINI_SDK_DISABLED`, `OPENCODE_SDK_DISABLED`
Transport	`CODEX_TRANSPORT`, `COPILOT_TRANSPORT`, `CLAUDE_TRANSPORT`, `GEMINI_TRANSPORT`
OpenCode	`OPENCODE_PORT`, `OPENCODE_MODEL`
Failover	JSON `failover` block or related env-driven routing behavior
Complexity routing	`complexityRouting` in `bosun.config.json`

EXECUTORS=COPILOT:CLAUDE_OPUS_4_6:50,CODEX:DEFAULT:50
PRIMARY_AGENT=codex-sdk
EXECUTOR_MODE=internal

Telegram, Mini App, and sentinel

Telegram remains the primary remote control surface.

Feature	Key settings
Bot	`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, polling and batching settings
Mini App	`TELEGRAM_MINIAPP_ENABLED`, `TELEGRAM_UI_PORT`, `TELEGRAM_UI_BASE_URL`
Cloudflare	`CLOUDFLARE_TUNNEL_NAME`, `CLOUDFLARE_TUNNEL_CREDENTIALS`, `CLOUDFLARE_BASE_DOMAIN`, `CLOUDFLARE_ZONE_ID`, `CLOUDFLARE_API_TOKEN`
Fallback auth	`TELEGRAM_UI_FALLBACK_AUTH_ENABLED` plus related rate-limit and lockout knobs
Sentinel	`BOSUN_SENTINEL_AUTO_START`, `SENTINEL_AUTO_RESTART_MONITOR`, repair-agent settings

TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...
TELEGRAM_MINIAPP_ENABLED=true
TELEGRAM_UI_TUNNEL=named
TELEGRAM_UI_ALLOW_QUICK_TUNNEL_FALLBACK=false

GitHub, Jira, and task backends

Bosun can run against multiple task-board backends. The current default in .env.example is internal.

Backend	Key settings
Internal	`KANBAN_BACKEND=internal`
GitHub Issues / Projects	`KANBAN_BACKEND=github`, `GITHUB_REPOSITORY`, `GITHUB_PROJECT_NUMBER`, OAuth/App settings
Jira	`KANBAN_BACKEND=jira`, `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`

GitHub auth and portal-related settings currently include:

BOSUN_GITHUB_CLIENT_ID=...
BOSUN_GITHUB_CLIENT_SECRET=...
BOSUN_GITHUB_APP_ID=...
BOSUN_GITHUB_PRIVATE_KEY_PATH=/absolute/path/to/app.pem
GITHUB_REPOSITORY=your-org/your-repo
GITHUB_PROJECT_NUMBER=3

Containers, voice, and optional surfaces

These features are optional but first-class in the current repo.

Surface	Key settings
Containers	`CONTAINER_ENABLED`, `CONTAINER_RUNTIME`, `CONTAINER_IMAGE`
Voice	`VOICE_ENABLED`, `VOICE_PROVIDER`, `VOICE_MODEL`, `VOICE_DELEGATE_EXECUTOR`
Desktop	`BOSUN_DESKTOP_AUTO_START_DAEMON`, `BOSUN_DESKTOP_AUTO_UPDATE`
WhatsApp	Auth is CLI-driven, with runtime delivery controlled by the Bosun channel settings

Recommended profiles

Local development

DEVMODE=true
SDK transports enabled where available
Mini App optional, often local-only
Container isolation off unless you are testing sandbox behavior

Operator or hosted usage

Mini App behind named Cloudflare tunnel
Fallback auth enabled
Sentinel enabled
Explicit executor and board config committed via setup-managed files

This page summarizes the active config model. For the full variable list, always check .env.example in the repo because it is more complete and changes more often than this summary page.