Installation & Deployment

Bosun can be installed and run in several ways depending on your environment and use case. This page covers every option: npm global install, building from source, Docker Hub image, docker‑compose from the cloned repo, and the Electron desktop app.

Prerequisites

At least one AI provider key is needed for executor functionality:

Option 1 — Install from npm

The fastest path for most users.

# Install globally
npm install -g bosun

# Verify
bosun --version

Navigate to the repository you want Bosun to supervise and run setup:

cd your-repo
bosun --setup

The setup wizard opens a browser-based UI on https://localhost:3080 where you configure your executor, task backend, Telegram, and credentials.

Start Bosun

# Foreground (interactive)
bosun

# Background daemon
bosun --daemon

# Daemon + Telegram sentinel
bosun --daemon --sentinel

# Stop background daemon
bosun --stop-daemon

# Hard-stop all Bosun processes
bosun --terminate

Validate

bosun --doctor          # Health check
bosun --daemon-status   # Daemon heartbeat
bosun --workspace-list  # Registered workspaces

Option 2 — Install from source

Use this when you want to develop, contribute, or run the latest unreleased code.

# Clone the repository
git clone https://github.com/virtengine/bosun.git
cd bosun

# Install dependencies
npm install

# Run directly
node cli.mjs --setup

# Or link globally
npm link
bosun --setup

Development commands

# Run tests
npm test

# Lint / annotation audit
npm run audit:ci

# Prepublish checks
npm run prepublishOnly

# Install local git hooks
npm run hooks:install

Option 3 — Docker (from Docker Hub)

Run Bosun as a container with zero Node.js setup on the host. The image is published to Docker Hub.

Quick start

docker run -d \
  --name bosun \
  -p 3080:3080 \
  -v bosun-data:/data \
  -e BOSUN_API_KEY=your-secret-key-here \
  -e OPENAI_API_KEY=sk-... \
  virtengine/bosun:latest

Open https://localhost:3080 in your browser. The first visit launches the setup wizard. Accept the self-signed certificate warning — Bosun auto-generates a TLS certificate on first start.

Environment variables

Persistent data

The container stores all state (config, sessions, logs, caches) in /data. Mount a Docker volume to retain data across restarts:

-v bosun-data:/data

Health check

The image includes a built-in health check on /healthz. Docker reports the container as healthy once the server is ready:

docker ps   # STATUS column shows "(healthy)"

Authentication

When BOSUN_API_KEY is set, all API and portal requests require authentication:

• Header: X-API-Key: <key> or Authorization: Bearer <key>
• WebSocket: wss://host:3080/ws?apiKey=<key>
• Browser: the setup wizard handles session cookies automatically.

Without BOSUN_API_KEY, the server falls back to session-based auth only.

Mount a local workspace

To give the container access to repositories on the host:

docker run -d \
  --name bosun \
  -p 3080:3080 \
  -v bosun-data:/data \
  -v /path/to/your/repos:/workspace:rw \
  -e BOSUN_API_KEY=your-secret-key-here \
  virtengine/bosun:latest

Option 4 — Docker (from source with docker‑compose)

Build and run from the cloned repository using the included docker-compose.yml.

# Clone the repository
git clone https://github.com/virtengine/bosun.git
cd bosun

# Copy and edit environment
cp .env.example .env
# Edit .env — set at least one AI provider key

# Build and start
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f bosun

# Stop
docker compose down

Customise docker-compose.yml

The provided file includes commented environment variables. Uncomment and set the ones you need:

services:
  bosun:
    build: .
    ports:
      - "${BOSUN_PORT:-3080}:3080"
    volumes:
      - bosun-data:/data
      # Mount local repos:
      # - /path/to/your/repos:/workspace:rw
    environment:
      - BOSUN_API_KEY=your-secret-key-here
      - OPENAI_API_KEY=sk-...
      # - TELEGRAM_BOT_TOKEN=...
      # - GITHUB_TOKEN=...

Build the image manually

If you prefer building without docker‑compose:

docker build -t bosun .
docker run -d --name bosun -p 3080:3080 -v bosun-data:/data bosun

Option 5 — Electron desktop app

Bosun includes an Electron wrapper for a native desktop experience.

# From the bosun directory
npm install
npm run desktop

The desktop app starts a local Bosun daemon and opens the portal in a native window. It can also connect to a remote Bosun server:

1. On launch, choose Connect to Remote in the connection dialog.
2. Enter the server endpoint (e.g. https://bosun.example.com:3080).
3. Enter the API key configured on the server (BOSUN_API_KEY).

Post-install: first-run setup

Regardless of installation method, the first visit to https://localhost:3080 launches the Setup Wizard. It walks through:

1. Project identity — repository name and workspace shape.
2. Executor defaults — Codex, Copilot, Claude, Gemini, or OpenCode.
3. Task backend — internal, GitHub Issues, Jira, or Vibe-Kanban.
4. Control surfaces — Telegram Mini App, sentinel, desktop settings.
5. Credentials — API keys, tokens, and integration secrets.

Re-run setup at any time:

bosun --setup              # Web-based wizard
bosun --setup-terminal     # Legacy terminal wizard

Configuration files

bosun --where   # Show resolved config directory

Troubleshooting

Port already in use

# macOS / Linux
lsof -i :3080

# Windows
netstat -ano | findstr 3080

Docker container unhealthy

docker logs bosun
docker inspect bosun --format='{{json .State.Health}}'

Self-signed TLS warning

Bosun auto-generates a self-signed certificate on first start. Your browser will show a security warning — this is expected for local development. Accept the certificate or use curl -k for API calls.

Reset everything

bosun --terminate
rm -rf $(bosun --where)   # Caution: deletes all Bosun config and state