v0.3.0

AgentBus 0.3 lets you talk to many agents in one conversation, and run them on other machines.
Your code stays on your machine until you say "apply".

Talking to agents

• A session is a conversation. You write and an agent answers. Ask for anything else in plain
  words in the chat.
• Saved agents. An agent is a harness (claude or codex), its access, a model and a name.
  Access is your own subscription, or an OpenRouter key read from a variable by name. Add agents
  with POST /api/v0/agents or "+ Agent" in the cockpit.
• Switch model or agent on any message. The conversation carries on with the new one.
• Messages queue. Send the next message while a turn runs. It runs after it.
• Agents ask agents. An agent can hand work to another agent, or to several at once. Each
  answer comes back as the next turn of the session. Ask in the chat: "have codex review this".
  The asked agent is told who asked it and can read that turn's changes.
• Rename a session with PATCH /api/v0/sessions/<id>.

Your folder is safe

• Each conversation works in its own copy of your folder, uncommitted edits included. Your
  folder does not change while agents work.
• Every turn has a diff: each file added, changed or removed, with its own text diff.
• Apply up to a turn, all or nothing. POST /api/v0/turns/<turn>/apply brings in every turn
  not yet applied, up to that one, in one step. If a file in your folder changed since, nothing is
  written and you get each file and why.
• Review is optional. Read the diff and say "apply", or ask another agent to check it first.

Three roles, one or more machines

• One program, three roles. Control keeps the API, the queue, the record, the settings and the
  gateway. A connector owns the folders on its machine. A runner runs agents.
• agentbus up runs all three in one process. One person on one machine needs nothing else.
• agentbus server, agentbus connector and agentbus runner run them apart. Keep control and
  the connector where your code is. Run runners anywhere, such as a Linux VM. Runners pull their
  work, so they work behind a router.
• File contents travel by hash. Each side sends only what the other lacks. A second session on
  a big folder sends almost nothing.
• A runner's turn shows live in a cockpit pointed at control: events, model calls and replies.

Runners hold no secrets

• Control gives each runner turn a token of its own. Control's gateway swaps it for the real
  credential on the way out.
• An OpenRouter key stays in control's environment, read by the variable's name.
• Your own Claude subscription can serve your own runners. Connect it once on control with
  agentbus connect claude, or Connect in the cockpit. It is off by default: set
  subscriptions_on_runners = "own" in permissions.toml.

Network control (Linux)

• Off by default. Turn it on in permissions.toml:
  [network] contain = "on" and allow = ["github.com", ...].
• Then each agent reaches only its gateway, control and the hosts you allow. Everything else is
  refused and recorded as network.refused.
• A runner that cannot close an agent off (a Mac, for example) refuses the turn and says why.

Settings

• permissions.toml decides edits, limits on asking, the agents' API and network control.
• instructions.md holds the text every turn gets.
• Both have API routes. A runner on another machine reads them from control.

Failures end clearly

• An interrupted transfer, a restarted role, a repeated request, a connector that went away and a
  file edited before apply each end with a clear error or a clean result. Never half-applied work.

Known limits

• OpenRouter turns show a cost of $0. The price table has no OpenRouter prices yet.
• A session stays on one runner. Its copy lives there.
• Copies on shared or network disks are slow. Fast copies need APFS, xfs or btrfs, with the folder
  and the data folder on the same disk.
• The first transfer of a big folder is slow: about 30 s for 50,000 files (414 MB). Later sessions
  take about 4 s.
• Network control is Linux only. On macOS, contain = "on" refuses every turn.
• An asked agent reads the asker's changes through the API. Its own copy is made from your folder,
  so it cannot run those changes.
• codex on a subscription cannot run on a remote runner yet. Use an OpenRouter agent there, or
  agentbus up.
• The v0 API may still change. 0.4 will reshape some routes.

Upgrading from 0.1

• Read "Versions" in docs/CLIENT_API.md: what 0.2 changed, then what 0.3 changed.
• Your 0.1 turns still work. The seeded claude and codex agents keep them unchanged.

Install

• brew install staysup/tap/agentbus, or
• curl -fsSL https://raw.githubusercontent.com/staysup/agentbus/main/install.sh | sh

AgentBus is open code under FSL-1.1-ALv2. Each release becomes Apache 2.0 two years after it is
published.