Research program 03

Bosun — the deck officer of autonomous engineering

Bosun is a fully open-source, experimental control plane for autonomous software engineering. It plans and routes work across AI coding agents, automates the pull-request lifecycle, and recovers from failure on its own — while keeping human operators in command of the operation.

Status: experimental — actively developed, open source
License: Apache-2.0
Install: npm install -g bosun · requires Node.js 22.13+
Home: bosun.engineer · github.com/virtengine/bosun

01The name, the idea

It orchestrates the work. Humans stay in command.

The name comes from “boatswain” — the ship's officer responsible for coordinating deck work, keeping operations moving, and translating command into disciplined execution. That is precisely the design: Bosun does not replace the captain or the crew.

What it is

Bosun is a control plane for autonomous software engineering. Given a task board — its own kanban, GitHub Issues, GitHub Projects v2, or Jira — it plans and decomposes work, routes each task to the best available AI executor, enforces quality gates on the resulting pull requests, and watches its own runs for stalls, failures, and stale claims. Operators steer the whole operation from a Telegram bot, a Mini App dashboard, or a desktop app.

It ships as a single npm package (bosun), runs from a repository checkout, Docker, or the Electron desktop shell, and configures itself through an interactive setup wizard on first run.

Why the foundation runs it

Two reasons, both public-benefit. First, autonomous-engineering infrastructure should not be a proprietary advantage: Bosun is published whole, Apache-2.0, so any team can inspect, run, and improve the machinery — consistent with the foundation's education purpose of open specifications and implementation guidance.

Second, it is an evidence base. The foundation's DSEMA program asks how multi-agent AI systems can be made safe, accountable, and auditable — questions that are easy to theorise about and hard to test. Bosun is a working system in which task routing, failure recovery, review gates, and execution ledgers meet real code, real CI, and real deadlines every day: Bosun-driven pull requests and commits ship production code across the VirtEngine organisation daily.

02Architecture

Board → supervisor → executors → gates — and a loop that heals

Bosun's lifecycle is a closed loop. Work enters from a task board, a supervisor plans and routes it across the executor pool, results must pass PR gates before merging, and an observe-and-recover layer returns anything that stalls or fails back to the board — escalating to a human when the machinery cannot help itself.

fig 01 — the Bosun lifecycle: task board, supervisor, executor pool, PR gates, observe & recover

Planning & routed execution

Trigger intake consumes issues, comments, schedules, and webhook events; planning converts goals into scoped tasks with execution context. Dispatch picks the best executor profile per task, with retries, weighted distribution across N executors, and automatic failover with cooldowns when one misbehaves. Setup profiles range from Manual Dispatch through Balanced to Autonomous.

Gates before merge

Nothing merges on an agent's say-so. Bosun creates the PR, watches CI, labels failures for repair, auto-rebases, and merges only when checks are green — and only through a watchdog with a mandatory review gate. The same discipline is enforced in its own repository: pre-commit and pre-push hooks, syntax checks, and prepublish validation.

Recovery before escalation

Runs persist to disk and auto-resume after restarts. Stalled or broken states are detected by the monitor loop; autofix patterns repair known failure classes; circuit breakers stop futile retries; heartbeat-based reclaim frees tasks claimed by dead workers. When self-healing runs out, the system escalates to an operator with clear signals rather than failing silently.

Fleet, not just one machine

Multiple workstations coordinate through shared state — atomic claims so two machines never take the same task, presence so the fleet knows who is alive, and shared knowledge so learnings travel. An execution ledger records what every agent did, feeding weekly work summaries operators can pull from Telegram.

03Capability inventory

What ships in the box

The inventory below is drawn from the open repository — its README, module index, and package manifest — not from a roadmap.

Executor routing

Plans and routes tasks across GitHub Copilot, Claude, Codex, and OpenCode executors with weighted distribution, automatic failover, and per-executor cooldowns when an executor degrades.

PR lifecycle automation

Creates pull requests, monitors CI, auto-rebases against the moving base branch, labels failing PRs for repair, and merges on green through the PR Watchdog — behind a mandatory review gate that prevents destructive merges.

Self-healing recovery

Autofix patterns repair known failure classes; circuit breakers stop repeated futile retries; heartbeat-based stale-claim reclaim returns abandoned tasks to the board; workflow runs persist to disk and auto-resume on restart.

Task boards

A built-in kanban board plus adapters for GitHub Issues, GitHub Projects v2, and Jira — with bidirectional synchronisation, so the board of record can live wherever the team already works.

Operator control

A Telegram bot with 30+ commands and a sentinel companion process, a Mini App dashboard over a stable tunnel hostname, and optional WhatsApp notifications. Escalations reach a human with clear signals.

Fleet coordination

Multiple workstations coordinate through shared state: atomic task claims, presence tracking, shared knowledge, and a workspace registry — so concurrent machines do not trample each other's work.

Container isolation

Optional execution isolation via Docker, Podman, or Apple Container keeps agent workloads contained, complementing git-level safety helpers and quality gates.

Setup & surfaces

An interactive setup wizard configures executors, boards, and channels on first run; an Electron desktop app and a web dashboard provide graphical operation alongside the CLI.

Execution ledger

Agent work is logged as a structured event stream — an execution ledger of what each agent did, when, and why — supporting audits, weekly work reports, and post-hoc review.

04Relationship to DSEMA

The applied track that keeps the research honest

Bosun and DSEMA answer to the same underlying question — how multi-agent AI systems stay safe, accountable, and auditable — from opposite ends. DSEMA is the formal architecture; Bosun is the working practice.

What Bosun contributes to the research

Operating experience. Every mechanism DSEMA studies formally has a pragmatic counterpart running in Bosun today: task decomposition and merit-based routing, quality gates before irreversible actions, tamper-resistant activity records, human oversight channels, and recovery under adversity. Watching where those pragmatic mechanisms hold — and where they strain — supplies the research program with grounded failure modes instead of hypothetical ones.

What we do not claim

Bosun is not an implementation of the DSEMA architecture and does not claim conformance with it. There is no blockchain control plane, no constitutional safety layer, and no on-chain reputation system in Bosun — its guarantees are engineering guarantees (gates, ledgers, sandboxes, human control), not cryptographic ones. It is the applied engineering track that informs the research, described here exactly as what it is: fully open source, and experimental.

05Status

Where the program stands — stated plainly

Bosun is experimental software under active development, published in full.

What exists today

The complete source, published under Apache-2.0 at github.com/virtengine/bosun, with a module-by-module agent guide and long-form documentation
A released npm package (bosun) with an interactive setup wizard, Docker images on Docker Hub, and an Electron desktop app
A public documentation site at bosun.engineer, generated from the same markdown sources kept in the repository
Daily production use: Bosun-driven pull requests and commits ship code across the VirtEngine organisation's repositories

What we don't claim

Bosun is experimental. Interfaces, configuration, and behaviour change quickly; running autonomous agents against real repositories carries real risk, which is why the defaults favour review gates, containment options, and operator escalation. We publish no adoption numbers, no user counts, and no reliability statistics — the verifiable artifacts are the repository, the package, and the commit history, and we prefer you inspect those.

06Go deeper

The program in the open

bosun.engineer Source code npm package Documentation DSEMA program