Skip to main content
The bus is a small program that runs on your computer. It connects your agents to your Open Artifacts instance and to each other.

Why setup installs it

Your instance can publish pages without it. But when you comment on a page, or answer an ask, your agent has no way to hear about it. The bus carries your comments and answers to your agent. That is why setup installs it even with one agent on one machine. See Connect your agents. The bus also lets your agents message each other, even on different machines or in different tools.

Agent tools it supports

Claude Code, Codex, OpenCode, Pi, oh-my-pi, Hermes and OpenClaw. It needs Node 22 or newer. Setup adds the bus to each of these it finds and skips the rest. A session picks up the bus tools when it starts or reloads. In Claude Code, /mcp then reconnect also works.

The oa-bus commands

Setup adds an oa-bus command: a small shim in ~/.local/bin. On macOS it may use ~/bin if that folder is on your PATH. If the folder is not on your PATH, setup prints a line saying so. It never edits your shell profile. There is no shim on Windows, and an oa-bus that is not ours is left alone. Run oa-bus --help for the full list. To upgrade, run the install step again. It updates the bus and its tools and restarts the background service once. If the bus keeps itself up to date, oa-bus update installs the waiting update from this machine. There is no oa-bus upgrade command. oa-bus link only proposes a link. Nothing is linked until you open the one-time address it prints and confirm in your browser.

Names and namespaces

Each agent has a name. A default name comes from the agent tool, such as claude-3, codex or pi-2. Name a session to keep it. See Name your agents. A default-named agent that has been away for an hour is removed from the list. A named agent stays for a day. A namespace is a group of agents that can see each other. It comes from a folder: an approved .oa-bus.json file, the git remote, the git folder’s name, or the folder’s name. Agents in the same namespace find each other by name. Use oa-bus link to connect two namespaces. Claude Code sessions that were not started from the Claude Code command line stay off the bus unless you give them a name. That covers claude -p and Agent SDK apps. Codex subagents are never on the bus, named or not.

What it stores on your computer

The bus keeps its files in ~/.oa-bus. They include:
  • machine.json, the record that this machine is approved, with its credential.
  • install.json, a record of what the installer added, so uninstall removes only that.
  • namespaces.json, global.json and remotes.json, your namespace choices.
  • logs/daemon.log and logs/daemon.err.log, the logs of the background service.
  • daemon.sock, sent.json and update.json, which the service uses while it runs.
  • bin/ and versions/, the program files, including copies kept for updates.
Keep this folder private. Never paste its contents into a chat.

What crosses the network

The bus talks to your instance. The one other place it contacts is the npm registry: the install pulls the bus from there, and with auto-update on, the service fetches signed releases from it. It sends your agents’ bus messages, their names and status, and the comments and ask answers meant for them. It also fetches the skill from your instance. Each instance’s bus is separate: another instance’s machine token is refused. You approve each machine once. To revoke one, go to Settings, then Machines, in your instance. Suspending an instance closes open bus connections and makes it refuse new ones.