Quick Start

Get Bosun running in under 5 minutes. This guide covers install, setup, and your first supervised run.

Prerequisites

Node.js 18+ — Download (v22 recommended)
git — installed and on your PATH
GitHub CLI (gh) — Install (recommended for PR operations)

💡

Run gh auth status to verify your GitHub CLI is authenticated before setting up Bosun.

Step 1: Install

npm install -g bosun

Verify the installation:

bosun --version
# bosun v0.26.2

Step 2: Run Setup

Navigate to your project directory and run the setup wizard:

cd your-project
bosun --setup

The wizard starts with two modes:

Recommended Mode (default)

Prompts only for important decisions
Auto-generates .env based on .env.example with inline docs
Auto-configures VS Code settings for Copilot agent defaults
Sets up proven defaults for hooks, orchestrator, and failover

Advanced Mode

Full control over repository layout and failover strategy
Custom hook targets and event overrides
Explicit VK URL/port wiring
Optional channel and runtime tuning

Key decisions in setup:

Project identity — name and GitHub repo
Executor preset — which AI agents to use and their weights
AI provider credentials — API tokens for your chosen executors
Telegram — bot token and chat ID (optional but recommended)
Board backend — Internal, GitHub Issues, GitHub Projects v2, or Jira
Execution mode — Internal, VK, or Hybrid

Step 3: Launch

bosun

That's it! Bosun connects to your configured board, initializes the agent pool, and starts the supervisor loop.

Run Modes

Foreground (default)

bosun

Runs in your terminal with live log output. Press Ctrl+C to stop.

Daemon Mode

# Start as background daemon
bosun --daemon

# Check status
bosun --daemon-status

# Stop
bosun --stop-daemon

Startup Service

# Auto-start on login
bosun --enable-startup

# Check status
bosun --startup-status

# Remove
bosun --disable-startup

Interactive Shell

bosun --shell

Opens an interactive session inside the running monitor for live debugging.

Step 4: Validate

After setup, validate your configuration:

bosun --doctor

This checks:

.env file presence and validity
bosun.config.json schema compliance
GitHub CLI authentication
Telegram bot token validity
Executor pool configuration
Kanban backend reachability

What's Next?

Configuration Reference — deep dive into all settings
CLI Reference — every flag and command
Integrations — connect Telegram, GitHub Projects, Jira
Architecture — understand how it all fits together