Bosun

A persistent, distributed harness for AI coding jobs.

Bosun runs coding jobs on any infrastructure. A job arrives from an issue tracker, from a change waiting for review, from a schedule, or from a person typing a request. Bosun runs it on one of your machines, gives the agent the standards you have set, and reports what happened. The job runs in the background on that machine, so closing your terminal does not stop it, and each job gets its own agent, working copy and permission, so one job does not disturb another.

Capacity grows with the machines you add: each one runs its own node and dials out to the control plane, so no machine needs an open inbound port.

Bosun is written in Rust. Sessions run on your control plane, tool calls execute on the node the session works on, and you drive sessions from a terminal client or the web pane.

Status

Single-user MVP. One control plane holds every session: there is no security model, no scheduler, and no automatic placement yet, so run it on a network you trust and name the node each job runs on.

Shipped so far:

• Sessions that outlive the client. A session runs on the control plane and its node, so closing the terminal or the browser does not stop it, and bosun open reattaches to a live one.
• Sessions in a tree. A session spawns children and names the node and directory each one runs on, and a child can spawn its own. A child reports to its parent by ending its turn. The reader talks to the root only: the pane and bosun open show a chat with the root, a Crew view with the tree as a chain of command and the orders, reports and questions between agents, and a read-only screen for each agent with its own thread and log.
• Forks. The pane's actions sheet forks a session's conversation into a new root session. The fork keeps the same model, persona, permission, MCP servers and thread, and gets its own clone of the same repository; the original is left as it was.
• Project map. Every branch that sessions work on in one repository, as lanes off the main branch: where each is checked out, which crew works there, what is not committed or not pushed, the branch's pull request on GitHub, and the files two branches both change. The pane's Projects tab and bosun map keep it up to date while the crews work.
• Context control. The transcript states the session's context size once a turn, from half the window up, so the session can see how close it is to compaction. A session can also clear its own context, giving a reason, and continue from a fresh prompt; the reader's transcript keeps everything. The pane's actions sheet lets the reader clear the session's context too: the session waits for the reader's next message, which starts the new thread.
• Remote skill packages. Skills come from GitHub repositories the operator manages in the web pane, and reach sessions through the skill tool.
• MCP support. The control plane connects to external MCP servers over HTTP. The operator manages the server list and each session's selection in the web pane, and the chosen servers' tools reach the model beside the canonical tools.
• Session summaries. Each session's own model writes a one-line description of what the session is for and what it is doing now. The session's loop refreshes it once the session goes idle, and the web pane leads the session row with it.
• A mobile-first web pane. The pane lists nodes and sessions, starts a session, follows a live transcript, and manages skill repositories and MCP servers. The open session is one browser history entry addressed by a #s= fragment, so a phone's back gesture returns to the list, and a mermaid fence renders as a diagram in both clients.
• An installable pane. A phone or desktop installs the pane as an app, with its own icon and window. Served over HTTPS, it opens from a copy on the device when the control plane cannot be reached, and its bell turns on notifications for when a session tree asks a question or completes its tasks.
• Updates. Nodes converge on the control plane's version, and a deployment re-issues the call each working session had in flight, once. The CLI self-updates from GitHub Releases.

The current sprint and the planned roadmap are tracked in docs/sprints.

How it works

• Control plane (bosun serve) runs one agent loop per session, keeps the session store, manages skill repositories and MCP servers in the web pane, and holds one shared connection per enabled MCP server.
• Nodes (bosun node) dial out to the control plane, one node per machine. Each session runs its tools in-process on the node, scoped to the session's working copy and permission.
• Clients are one binary: bosun clone starts a session from a repository, bosun dev starts one in an existing directory on a node, bosun list shows sessions, bosun open attaches to a live session, and bosun map shows a project's branches.
• Sessions hold their own transcript, store, and model calls. Tool output streams back to the client live; assistant text renders as markdown.
• Skills are packages fetched from GitHub repositories the operator adds in the web pane, stored in the session store, and loaded on demand through the skill tool beside the working copy's own skills. Versions are commit SHAs; an update re-resolves the tracked ref and replaces the packages.

The crew

A session and the sessions it spawns are a crew. The root session is the lead. You give the lead its instructions, and the lead gives orders to the agents it spawns. Each of those agents can spawn its own. Every agent reports to the agent that spawned it. A question climbs the chain to you, and your answer goes straight back to the agent that asked it.

• Chat is your conversation with the lead. It shows the lead's orders as cards, with one row for each agent and its state, and each report from an agent as one line. A question that came up the chain names the agent that asked it and the path to you. The message box sends to the lead only.
• Crew shows the chain of command as a tree. Each agent has its avatar, its persona, its state and what it is doing now. Below the tree, Flow lists every order, report, question and answer between the agents, newest first.
• A crew member's screen opens from the tree, an order row or Flow. It shows that agent's own thread and its Log. It has no message box: to change an agent's work, tell the lead. Ask Lead opens Chat with the agent's name in the message box.

bosun open has the same views. Alt+1 to Alt+4, or F1 to F4, switch between Chat, Crew, Tasks and Files. In Crew, ↑ and ↓ pick an agent, Enter opens its thread, Alt+5 or F5 opens its Log, and Esc returns to Crew.

Requirements

• Rust stable, with edition 2024 support, to build from source.
• Rust nightly, for formatting. The options in rustfmt.toml are nightly-only, so the pre-commit hook runs cargo +nightly fmt.

Install

Each release publishes one archive per platform, with a .sha256 file beside it:

• Linux: x86_64 and aarch64, statically linked against musl
• macOS: x86_64 and aarch64
• Windows: x86_64

Download the archive for your platform from the latest release, unpack it, and put bosun on your PATH. bosun update then updates the binary to the control plane's version. To run from source instead, see Build and test.

Run

Three pieces make a working setup: a control plane, at least one node, and a client. Config files are TOML; commented templates live in cmd/bosun/settings/. A control plane also needs at least one model and one persona, as cmd/bosun/settings/serve.toml describes.

# 1. Control plane. Models and their API keys are configured here.
bosun serve --config cmd/bosun/settings/serve.toml

# 2. A node on the machine that does the work.
bosun node --config cmd/bosun/settings/node.toml

# 3. Client commands, from anywhere that can reach the control plane.
bosun nodes
bosun dev --node node-1          # pick a directory interactively
bosun clone --node node-1 https://github.com/you/repo.git   # clone a repo
bosun list
bosun open <session-id>          # attach to a live session
bosun map                        # the project's branches, kept up to date
bosun stop <session-id>

The control-plane URL defaults to http://127.0.0.1:8090 and can be set per command with --cp-url, stored with bosun config set cp-url, or exported as BOSUN_CP_URL.

The web pane is served at the control-plane root (/ or /ui). Open it in a browser to see the node list, start a session, follow its live transcript, and manage skill repositories and MCP servers.

To install the pane as an app and get notifications, serve it over HTTPS, for example with tailscale serve, or with tls_cert and tls_key and a certificate the phone trusts. A browser allows the offline copy and notifications only over HTTPS or on the control plane's own machine. Over plain HTTP to another machine the pane works as a page. On an iPhone, add the pane to the Home Screen before turning notifications on.

Repository layout

Path	Purpose
cmd/bosun	The bosun binary: control plane, node daemon, and client
crates/bosun-control	Control plane: agent loops, session API, web pane
crates/bosun-node	Node daemon: session and executor management, polling
crates/bosun-agent	Agent loop and model-provider streaming
crates/bosun-executor	Per-session executor and its tool set
crates/bosun-common	Shared types, config, and protocol framing
crates/bosun-store	SQLite session store

Build and test

cargo build --release
cargo test
cargo clippy --workspace
cargo +nightly fmt --check

The binary lands at target/release/bosun. The repository also ships pre-commit hooks that run formatting, clippy, and cargo deny; see docs/developer/workflows/setup.md.

Documentation

• Developer standards: the rules to follow while writing code here, and the procedures around it.
• Architecture decisions: the ADRs behind the current design.
• Sprint notes: how the project got here and where it is going.

Contributing

Set up a development environment with docs/developer/workflows/setup.md, then read docs/developer/README.md before you change code.

License

Licensed under either of Apache License, Version 2.0 or MIT at your option.