Help us improve
Share bugs, ideas, or general feedback.
npx claudepluginhub cameronsjo/bosun --plugin bosunHow this skill is triggered — by the user, by Claude, or both
Slash command
/bosun:onboardThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guide the user through getting started with **Bosun** and help them understand how it works. Use resource files for deep dives into specific topics.
Creates p5.js generative art with seeded randomness, noise fields, and interactive parameter exploration. Use for algorithmic art, flow fields, or particle systems.
Share bugs, ideas, or general feedback.
Guide the user through getting started with Bosun and help them understand how it works. Use resource files for deep dives into specific topics.
Bosun is a single-binary CLI tool that brings GitOps workflows to homelab Docker Compose deployments. Write short manifest files, bosun generates Docker Compose + Traefik + Gatus configs. Push to git, bosun reconciles your server automatically. No Kubernetes required.
The pitch: Write a 10-line manifest, get a fully configured service with routing, monitoring, health checks, and compose orchestration -- all deployed automatically when you push to git.
Everything uses nautical/Below Deck naming:
| Term | Meaning |
|---|---|
| Yacht | Your server running Docker Compose |
| Crew | Your containers |
| Captain | GitHub (gives orders via webhooks) |
| Manifest | Service definitions (what to deploy) |
| Provisions | Reusable config templates (how to deploy) |
| Radio | Webhook/tunnel for receiving push events |
| Bosun | The CLI tool itself (receives orders, deploys crew) |
Before setting up Bosun, ensure the following are installed:
docker compose version to verifyage-keygen to generate keys, sops CLI for encryption)bosun radioPick one method:
# Quick install (recommended) -- downloads, verifies checksum, installs to /usr/local/bin
curl -fsSL https://raw.githubusercontent.com/cameronsjo/bosun/main/scripts/install.sh | bash
# Via Go
go install github.com/cameronsjo/bosun/cmd/bosun@latest
# From source
git clone https://github.com/cameronsjo/bosun.git
cd bosun && make build # output at build/bosun
Update an existing install:
bosun update # Update to latest release
bosun update --check # Check for updates without installing
Generate an Age encryption key (if not already done):
age-keygen -o ~/.config/sops/age/keys.txt
Create .sops.yaml in the project root with the public key from step 1.
Initialize the project:
bosun init # Interactive setup wizard
bosun init --yes # Non-interactive (for CI/CD)
bosun init my-homelab # Initialize in a new directory
Run pre-flight checks:
bosun doctor
Validates Docker, Git, SOPS, Age key, manifest directory, and webhook status.
Start your services:
bosun yacht up
| Group | Commands | Purpose |
|---|---|---|
| Setup | init, doctor, update | Project creation, health checks, updates |
| Yacht | yacht up/down/restart/status | Manage Docker Compose stacks |
| Crew | crew list/logs/inspect/restart | Manage individual containers |
| Manifest | provision, provisions, create, lint, render, chart | Build and validate service configs |
| GitOps | daemon, reconcile, trigger, drift | Automated deployment pipeline |
| Radio | radio test/status | Webhook and tunnel connectivity |
| Alerts | alert status/test | Deploy notification testing and status |
| Diagnostics | status, log, doctor, validate | Health monitoring and debugging |
| Emergency | mayday, overboard, restore | Error triage, rollback, force-remove, backup restore |
| Utilities | update, completion | Self-update, shell completions |
For complete command details with all flags and examples, see @resources/commands.md.
For manual deployments:
bosun provision mystack # Render manifest -> compose/traefik/gatus files
bosun provision mystack -n # Preview without writing (dry run)
bosun yacht up # Start/update services
bosun crew list # Verify containers are running
bosun drift --live # Check for drift between config and running state
For automated GitOps:
bosun daemon # Run long-lived daemon (webhook + polling)
# ... push changes to git ...
# Bosun automatically: pulls repo -> decrypts secrets -> templates configs -> deploys
bosun trigger # Or manually trigger reconciliation
bosun drift # Check for drift between deploys
For full GitOps setup details, see @resources/gitops.md.
A manifest describes what to deploy. Provisions describe how. Bosun renders both into Docker Compose, Traefik, and Gatus configs.
Minimal example (a web app with routing and monitoring):
# manifest/services/myapp.yml
name: myapp
provisions: [container, reverse-proxy, monitoring]
config:
image: ghcr.io/org/myapp:latest
port: 3000
subdomain: myapp
domain: example.com
Full example (web app with Postgres sidecar, health checks, and homepage entry):
name: norish
provisions: [container, healthcheck, homepage, reverse-proxy, monitoring]
config:
image: ghcr.io/norishapp/norish:latest
port: 3000
subdomain: recipes
domain: example.com
group: Apps
icon: mdi-food
description: Recipe manager
services:
postgres:
version: 17
db: norish
db_password: "{{ $secrets.apps.norish.db_password }}"
For the complete manifest schema, variable interpolation rules, and provision types, see @resources/manifests.md.
Bosun finds its project root by searching upward from the current directory for:
bosun.yaml or bosun.yml config filebosun/ directory with docker-compose.ymlmanifest/ or manifests/ directoryFor the full config file reference and environment variables, see @resources/configuration.md.
| Task | Command |
|---|---|
| Start all services | bosun yacht up |
| Start specific services | bosun yacht up traefik redis |
| Check container health | bosun crew list |
| View container logs | bosun crew logs <name> -f |
| Preview rendered config | bosun provision mystack -n |
| Show diff before applying | bosun provision mystack -d |
| Run one-shot deploy | bosun reconcile |
| Dry-run deploy | bosun reconcile -n |
| Check for drift | bosun drift --live |
| View recent errors | bosun mayday |
| Rollback to snapshot | bosun mayday -r interactive |
| Force-remove stuck container | bosun overboard <name> |
| Scaffold new service | bosun create webapp myapp |
| Validate manifests | bosun lint |
| Check system health | bosun status |
| Restore from backup | bosun restore or bosun restore -l |
| Test alert providers | bosun alert test |
| Set up shell completions | bosun completion bash | sudo tee /etc/bash_completion.d/bosun |
| Problem | Fix |
|---|---|
| "project root not found" | Ensure you're inside a bosun project, or use bosun --root /path |
| "connect to docker" | Check Docker is running (docker ps), check socket permissions |
| "sops decrypt failed" | Verify sops --version, check age key at ~/.config/sops/age/keys.txt |
| "docker compose: command not found" | Install Docker Compose v2: docker compose version |
| SSH failures (remote deploy) | Test ssh user@host exit, check ssh-add -l |
Run bosun doctor to diagnose most setup issues.
All commands have nautical aliases. Run bosun yarr to see them:
| Command | Alias |
|---|---|
yacht | hoist |
crew | scallywags |
provision | plunder, loot, forge |
radio | parrot |
status | bridge |
doctor | checkup |
mayday | mutiny |
overboard | plank |
init | christen |
When working on Bosun itself:
| Path | Purpose |
|---|---|
cmd/bosun/main.go | CLI entry point |
internal/cmd/ | Cobra command definitions (one file per command) |
internal/manifest/ | YAML rendering engine for service manifests |
internal/reconcile/ | GitOps engine (clone, decrypt, template, deploy) |
internal/docker/ | Docker SDK wrapper |
internal/config/ | Configuration loading and project discovery |
Makefile | Build, test, lint, CI targets (make help for full list) |
make build # Build binary -> build/bosun
make test # Run tests
make test-cover # Run tests with coverage report
make lint # Run linter (requires golangci-lint)
make ci # Run full CI pipeline locally via Dagger
make run ARGS="doctor" # Run without building
For deeper information on specific topics:
@resources/commands.md -- Every CLI command with flags, examples, and behavior@resources/manifests.md -- Manifest system: schemas, provisions, stacks, interpolation@resources/gitops.md -- GitOps pipeline: daemon, reconciliation, webhooks, drift@resources/configuration.md -- Config file reference, environment variables, project structure