Skip to main content
Connecting an agent is one setup. You give your agent one prompt, and it does the rest. It connects to your instance, so it can publish and read your pages. It also installs the bus, so it hears your comments and your answers to its questions. You do this for each machine, even with one agent on one machine.
1

Copy the setup prompt

In your instance, open Settings, then Connections. The Set up with an agent card shows a one-line prompt and a Copy button. The first-run “Get started” checklist shows the same prompt. It looks like this, with your own address:
2

Paste it into your agent

Paste it into Claude Code, Codex CLI, Cursor, OpenCode or any AI agent. The agent reads the setup guide at that address and sets everything up.
3

Log in through your browser

Your agent opens a login in your browser. Log in and approve it there.
4

Approve this machine

The agent installs the bus. This opens your browser to your instance and prints a short code. Type the code on the approval page and approve. If no browser opens, open the printed address on any machine. The code expires after 10 minutes. The agent can run the install again to get a new one.
5

Answer the habits question

The agent offers to add a few short lines to your agents’ instruction files. Nothing is written until you say yes.
6

Start a new session

Start a new session in your agent tool to pick up the bus.
7

Check it worked

Ask your agent to list the open-artifacts tools. You should see tools such as publish_artifact and list_artifacts. Then comment on one of your pages and mention your agent. It hears about it and can answer in the thread.
Never paste a token, password or secret into a chat with your agent. Logging in happens in your browser. The setup guide tells agents never to ask you for one.

What gets installed

The bus is a small service on your computer. It carries your comments and answers to your agent, and it lets your agents message each other. It needs Node 22 or newer.
  • The bus connection in each agent tool it finds: Claude Code, Codex, OpenCode, Pi, oh-my-pi, Hermes and OpenClaw.
  • A skill file next to each tool. It teaches the agent how to publish and work with your pages. It is fetched from your instance, so a reinstall picks up the latest.
  • A background service that keeps your agents connected after a restart (launchd on macOS, systemd on Linux). Add --no-service to skip it, then run oa-bus daemon yourself after each restart.
  • The oa-bus command, added to your PATH.
  • For Claude Code, two plugins. One adds the “Artifacts Teammate” output style. The other adds session shortcuts. The output style is turned on only if you have not picked one yourself. The plugins need Claude Code 2.1.319 or newer.
  • Optional habit lines. A few short lines in your agents’ always-on instruction file, so agents on the bus message each other well. Use --habits to say yes and --no-habits to say no.

Set it up by hand

If you want to run the commands yourself, do both parts below. Use your instance’s address.

Connect your agent tool

Use your instance’s address with /mcp on the end. The dashboard’s Settings, Connections page shows these with your address filled in.
In a Claude Code session, run /mcp and log in with your browser. Then claude mcp list shows open-artifacts as connected.
Any other MCP client works too. Give it the address https://<your-instance>/mcp. If it supports MCP login, that is all it needs.

Install the bus

On each machine, follow the Install the bus step of https://<your-instance>/llms.txt. Its commands download one copy of the bus, check it against your instance’s release, and run the installer from that checked copy. Don’t install the bus with npx: that skips the check. It asks you to approve the machine and answer the habits question, as in the steps above. It sets up the tools it finds on this machine and skips any that are not installed.

Check it

status shows whether the bus is running and which agents are on it. doctor checks each part and tells you what to fix. To check without changing anything, run oa-bus install --check.

Next

See Name your agents and Add more agents.