Quick Start

This guide gets Bosun installed, configured, and running with the current CLI surface. It assumes you want a working local operator setup first, then optional integrations after that.

Prerequisites

Node.js 18+ on PATH.
Git installed and working in your target repository.
PowerShell 7+ or Bash for the wrapper scripts Bosun may invoke.
GitHub CLI recommended for repository and PR workflows.
Optional: cloudflared, Docker/Podman, Telegram bot credentials, and executor API keys depending on which features you enable.

If you are evaluating Bosun for the first time, start with the default web setup flow. It is the current primary onboarding path.

Step 1: Install Bosun

npm install -g bosun

Verify the install:

bosun --version
# bosun v0.42.6

Step 2: Run setup

From the repository you want Bosun to supervise:

cd your-repo
bosun --setup

Current setup entrypoints:

bosun --setup launches the web-based setup wizard.
bosun --setup-terminal runs the legacy terminal wizard.
bosun --where shows the resolved Bosun config directory.

The setup flow typically asks you to choose:

Project identity and repository/workspace shape.
Executor defaults like Codex, Copilot, Claude, Gemini, or OpenCode.
Task backend such as internal, GitHub, or Jira-backed flows.
Control surfaces like Telegram Mini App, sentinel, and optional desktop behavior.
Credentials for providers and integrations you want enabled.

Step 3: Start Bosun

Foreground run:

bosun

Common runtime variations:

# Start detached
bosun --daemon

# Start daemon plus sentinel companion
bosun --daemon --sentinel

# Stop detached daemon
bosun --stop-daemon

# Hard-stop all Bosun-related processes
bosun --terminate

Step 4: Validate the environment

bosun --doctor

This validates your current config surface, including resolved config files and common runtime dependencies.

Useful follow-up checks:

bosun --daemon-status
bosun --sentinel-status
bosun --workspace-list
bosun task list --json

What setup writes

.env for environment-based settings.
bosun.config.json for structured executor and routing config.
Workspace and profile state under the Bosun config directory shown by bosun --where.

The canonical environment template is .env.example in the repo root. The canonical structured example is bosun.config.example.json.

What to do next

Read Configuration before turning on Mini App, Cloudflare, GitHub, or container execution.
Use CLI Reference when operating Bosun day to day.
Read Integrations before wiring Telegram, GitHub, Jira, or Cloudflare.
Read Architecture before editing workflows, task lifecycle code, or runtime plumbing.