Integrations

Bosun integrates with multiple platforms for task management, notifications, and agent execution. All integrations are configured through environment variables and the JSON config file.

GitHub

Full GitHub integration for issues, projects, and PR automation.

GitHub Issues (Default)

KANBAN_BACKEND=github
GITHUB_REPO=your-org/your-repo

Features:

Task listing from open issues
Claim tracking with codex:claimed, codex:working, codex:stale labels
Task exclusion via codex:ignore label
Structured comments with JSON state for agent coordination
Shared state persistence via issue labels and comments

GitHub Projects v2

KANBAN_BACKEND=github
GITHUB_PROJECT_MODE=kanban
GITHUB_PROJECT_OWNER=your-org
GITHUB_PROJECT_NUMBER=3
GITHUB_PROJECT_AUTO_SYNC=true

Features:

Phase 1 (Read) — Read tasks directly from Projects v2 boards
Phase 2 (Write) — Sync task status back to the board Status field
Bidirectional mapping between codex statuses and project status options
Safe fallback to issues mode when project metadata is unavailable

Custom Status Mapping

GITHUB_PROJECT_STATUS_TODO=Todo
GITHUB_PROJECT_STATUS_INPROGRESS=In Progress
GITHUB_PROJECT_STATUS_INREVIEW=In Review
GITHUB_PROJECT_STATUS_DONE=Done
GITHUB_PROJECT_STATUS_CANCELLED=Cancelled

Primary control channel with rich bot features and a full web UI.

Bot Setup

Create a bot via @BotFather on Telegram
Copy the bot token to TELEGRAM_BOT_TOKEN
Run bosun-chat-id to find your chat ID
Set TELEGRAM_CHAT_ID

Bot Commands

Command	Description
`/help`	Show help with inline keyboard
`/status`	Fleet status overview
`/tasks`	Active task list
`/agents`	Agent pool status
`/threads`	Active execution threads
`/worktrees`	Git worktree status
`/pause`	Pause supervisor
`/resume`	Resume supervisor
`/restart`	Restart supervisor
`/retry`	Retry last failed task
`/executor`	Switch executor
`/sdk`	SDK shell commands
`/kanban`	Board management
`/maxparallel`	Adjust concurrency
`/app`	Open Control Center Mini App

Mini App (Control Center)

TELEGRAM_MINIAPP_ENABLED=true
TELEGRAM_UI_PORT=3080

A full interactive web UI that runs inside Telegram as a Mini App with 7 tabs: Dashboard, Tasks, Agents, Infra, Control, Logs, and Settings.

Features: real-time WebSocket updates, haptic feedback, native Telegram theming, dark/light mode.

HTTPS via Cloudflare Tunnel

Telegram requires HTTPS. Two options:

Quick tunnel (default) — random *.trycloudflare.com URL, zero config
Named tunnel — persistent custom domain that never changes

# Named tunnel (persistent)
CLOUDFLARE_TUNNEL_NAME=my-tunnel
CLOUDFLARE_TUNNEL_CREDENTIALS=/home/user/.cloudflared/tunnel-id.json
TELEGRAM_UI_BASE_URL=https://fleet.yourdomain.com

Sentinel (Independent Watchdog)

BOSUN_SENTINEL_AUTO_START=true
SENTINEL_AUTO_RESTART_MONITOR=true

Keeps Telegram command availability even when the main monitor is down. Detects crash loops and can auto-restart the monitor or run a repair agent.

Jira

KANBAN_BACKEND=jira
JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=you@example.com
JIRA_API_TOKEN=your-token

Features:

Full status vocabulary mapping (same as GitHub adapter)
Shared state via custom fields
Interactive setup with project/issue type selection

Status and Custom Field Mapping

# Status mapping
JIRA_STATUS_TODO=To Do
JIRA_STATUS_INPROGRESS=In Progress
JIRA_STATUS_INREVIEW=In Review
JIRA_STATUS_DONE=Done
JIRA_STATUS_CANCELLED=Cancelled

# Shared state custom fields
JIRA_CUSTOM_FIELD_OWNER_ID=customfield_10042
JIRA_CUSTOM_FIELD_ATTEMPT_TOKEN=customfield_10043
JIRA_CUSTOM_FIELD_HEARTBEAT=customfield_10045
JIRA_CUSTOM_FIELD_RETRY_COUNT=customfield_10046

Optional notification channel alongside Telegram.

# Authenticate
bosun --whatsapp-auth

# Or use pairing code instead of QR
bosun --whatsapp-auth --pairing-code

Once authenticated, WhatsApp receives the same status updates and alerts as Telegram. Controlled via /whatsapp Telegram command.

Container Isolation

Optionally run agent executions inside containers for sandboxed isolation.

CONTAINER_ENABLED=1
CONTAINER_RUNTIME=auto    # auto | docker | podman | container
CONTAINER_IMAGE=node:22-slim
MAX_CONCURRENT_CONTAINERS=3

Runtime	Platform	Notes
Docker	All	Most common, best compatibility
Podman	Linux, macOS	Rootless, daemon-less
Apple Container	macOS	Native macOS containerization

AI Agent Executors

Executor	Transport	Models
Copilot	`sdk`, `cli`, `url`	Claude Opus 4.6, GPT-4.1, Claude Sonnet 4
Codex	`sdk`, `cli`	o4-mini, o3, gpt-4.1
Claude	`sdk`, `cli`	Claude Opus 4.6, Sonnet 4

All executors support persistent sessions via SDK transport (recommended). The agent pool manages selection, weighted distribution, and automatic failover.

Cloudflare Tunnel

For persistent HTTPS access to the Mini App:

# Create tunnel
cloudflared tunnel create my-fleet-tunnel

# Add DNS
cloudflared tunnel route dns my-fleet-tunnel fleet.yourdomain.com

# Configure in .env
CLOUDFLARE_TUNNEL_NAME=my-fleet-tunnel
CLOUDFLARE_TUNNEL_CREDENTIALS=/home/user/.cloudflared/tunnel-id.json
TELEGRAM_UI_BASE_URL=https://fleet.yourdomain.com