by virtengine
Autonomous Engineering
# Add to your Claude Code skills
git clone https://github.com/virtengine/bosunBosun is a production-grade control plane for an autonomous software engineer. It plans and routes work across executors, automates PR lifecycles, and keeps operators in control through Telegram, the Mini App dashboard, and optional WhatsApp notifications.
The name "Bosun" comes from "boatswain", the ship's officer responsible for coordinating deck work, keeping operations moving, and translating command into disciplined execution.
That maps directly to the Bosun project: it does not replace the captain or crew, it orchestrates the work. Our Bosun plans tasks, routes them to the right executors, enforces operational checks, and keeps humans in control while the system keeps delivery moving. Autonomous engineering with you in control of the operation.
npm install -g bosun
cd your-repo
bosun
First run launches setup automatically. You can also run setup directly:
bosun --setup
Run Bosun with no local Node.js install — pull from Docker Hub:
docker run -d --name bosun -p 3080:3080 \
-v bosun-data:/data \
-e BOSUN_API_KEY=your-secret-key \
virtengine/bosun:latest
Or build from the cloned repo:
git clone https://github.com/virtengine/bosun.git && cd bosun
docker compose up -d
Open https://localhost:3080 to start the setup wizard.
All installation options — npm, source, Docker Hub, docker-compose, Electron desktop — are documented in
INSTALL.mdand on bosun.engineer/docs/installation.
No comments yet. Be the first to share your thoughts!
Requires:
.sh wrappers) or PowerShell 7+ (for .ps1 wrappers)gh) recommendedBosun defaults the Mini App tunnel to named mode so the Telegram URL can stay stable (<user>.<base-domain>), with quick tunnels only as explicit fallback.
Required Cloudflare settings:
CLOUDFLARE_TUNNEL_NAMECLOUDFLARE_TUNNEL_CREDENTIALSCLOUDFLARE_BASE_DOMAIN (for example bosun.det.io)CLOUDFLARE_ZONE_IDCLOUDFLARE_API_TOKEN (Zone DNS edit scope for the target zone)Useful optional settings:
CLOUDFLARE_TUNNEL_HOSTNAME (explicit hostname override)CLOUDFLARE_USERNAME_HOSTNAME_POLICY=per-user-fixedTELEGRAM_UI_ALLOW_QUICK_TUNNEL_FALLBACK=falseFallback admin auth (secondary path) is available and stores only Argon2id hash + salt, never plaintext. Use:
POST /api/auth/fallback/set to set/rotatePOST /api/auth/fallback/rotate as explicit rotate aliasPOST /api/auth/fallback/reset to clearPOST /api/auth/fallback/login to mint normal ve_session cookiebosun-needs-fix when CI fails (Build + Tests)Bosun workflows provide a professional, end-to-end execution loop for autonomous delivery:
Setup profiles for default workflow behavior:
| Executor | primaryAgent value | Key env vars |
| ----------------- | -------------------- | ------------------------------------------------------------------------------------- |
| Codex (OpenAI) | codex-sdk | OPENAI_API_KEY |
| Copilot (VS Code) | copilot-sdk | VS Code session |
| Claude | claude-sdk | ANTHROPIC_API_KEY |
| OpenCode | opencode-sdk | OPENCODE_MODEL (e.g. anthropic/claude-opus-4-6), OPENCODE_PORT (default 4096) |
Set primaryAgent in .bosun/bosun.config.json or choose an executor preset during bosun --setup.
bosun --daemon starts the long-running daemon/monitor.bosun --sentinel starts only the Telegram sentinel companion process.bosun --daemon --sentinel starts daemon + sentinel together (recommended for unattended operation).bosun --terminate is the clean reset command when you suspect stale/ghost processes.Telegram operators can pull the weekly agent work summary with /weekly [days] or /report weekly [days]. To post it automatically once per week, set TELEGRAM_WEEKLY_REPORT_ENABLED=true together with TELEGRAM_WEEKLY_REPORT_DAY, TELEGRAM_WEEKLY_REPORT_HOUR, and optional TELEGRAM_WEEKLY_REPORT_DAYS.
Published docs (website): https://bosun.engineer/docs/
Source docs (markdown): _docs/ is the source of truth for long-form documentation. The website should be generated from the same markdown content so docs stay in sync.
Product docs and implementation notes: docs/ contains focused guides, design notes, and operator-facing references that are kept alongside the codebase.
Key places to start:
README.md - install, setup, and operational overview_docs/WORKFLOWS.md - workflow system and built-in templatesdocs/workflows-and-libraries.md - workflow composition and library behaviordocs/agent-logging-quickstart.md - agent work logging quickstartdocs/agent-work-logging-design.md - logging design and event modelIf preflight reports an interactive git editor such as code --wait, vim, or nano, Bosun can deadlock while Git waits for an editor session to close.
Run this from the repo root to switch the local repo config to a non-interactive editor:
node git-editor-fix.mjs
Preflight checks both GIT_EDITOR and git config --get core.editor. No warning is shown when core.editor is already non-interactive, for example :.
Bosun enforces a strict quality pipeline in both local hooks and CI:
CLAUDE:SUMMARY annotations.npm test and blocks push if site/index.html or site/ui/demo.html fails to load required assets.Use bosun audit to generate and validate repo-level annotations that help future agents navigate the codebase without extra runtime context:
# Coverage report for supported source files
bosun audit scan
# Add missing file summaries and risky-function warnings
bosun audit generate
bosun audit warn
# Rebuild lean manifests and the file responsibility index
bosun audit manifest
bosun audit index
bosun audit trim
# CI-safe conformity gate
bosun audit --ci
Notes:
bosun audit --ci exits non-zero on missing summaries, stale warnings, stale INDEX.map entries, or credential-like secrets..githooks/pre-commit already warns on newly staged files that are missing CLAUDE:SUMMARY.BOSUN_AUDIT_CI=1.Local commands you can run any time:
# Syntax + tests for bosun package
npm test
# Annotation conformity gate
npm run audit:ci
# Prepublish safety checks
npm run prepublishOnly
# Install local git hooks (pre-commit + pre-push)
npm run hooks:install
cli.mjs — CLI entrypoint for setup, daemon, desktop, and operator commandssetup.mjs — interactive setup flow and config bootstrapinfra/ — monitor loop, recovery, lifecycle services, and runtime plumbingworkflow/ and `wo