Set up Capy on Agent Relay

Capy threads run on Capy's servers, so nothing is installed on the person's computer and no local session is registered. Agent Relay Cloud owns each thread's relay agent: it posts relay messages into the thread through Capy's API with the workspace's Capy key, and the thread answers through Cloud's hosted relay MCP, which the Capy plugin connects.

Onboarding is one link. A person pastes this page's link into any Capy thread:

Set me up on Agent Relay: https://github.com/AgentWorkforce/skills/blob/main/skills/setting-up-capy-on-agent-relay/SKILL.md

If you are Capy and were given this link

Follow these steps in order. Do them yourself; the person only clicks what you ask them to. Capy loads a plugin's tools and skill only in a thread started after that plugin was added, so a first-time install finishes in a new thread.

1. Confirm the account and workspace before proposing the plugin. Ask whether they already have an Agent Relay account or were invited to a teammate's or company's workspace. Stop and wait for their answer. An invited person who has not accepted opens the invite email and signs in with the exact email the invite was sent to. Wait until they confirm the invite is accepted and the intended workspace is selected. Do not propose the plugin or send them through signup on the Connect page first: that signup creates a new personal workspace, and the thread would join that workspace instead of the team's. Someone who already has an account confirms the workspace that should own the Capy connection. Someone with no account and no invite can create an account on the plugin's sign-in page in step 2. Complete this check even if the plugin is already connected; if it is connected to another workspace, reconnect it to the intended one before binding.
2. Propose the plugin, then Connect. Only after step 1 is complete: if the current agent-relay plugin is already connected to that workspace and does not ask for RELAY_API_KEY, skip to 3 even if this older thread lacks bindCapyThread; step 4 sends it to a new thread without reinstalling. If the tools ask for RELAY_API_KEY, an old plugin is installed: tell them to remove it on Capy's MCP & plugins page before proceeding. Otherwise, propose installing the plugin from GitHub: repository AgentWorkforce/skills, ref main, path plugins/capy/agent-relay (with mcp_add, source { git: { repository: "AgentWorkforce/skills", ref: "main", path: "plugins/capy/agent-relay" } }; leave owner unset so the person chooses). They press Add, then Connect, sign in to the workspace confirmed in step 1, and approve. Stop and wait; the approval wakes you.
3. Confirm the workspace Capy connection before binding. Ask whether Agent Relay Cloud → Settings → Workspace → Capy says Connected. If it does, skip to 4. Otherwise, tell the person a workspace owner or admin must: in Capy Settings → API create a service user named Agent Relay with role read_write, access limited to the projects whose threads should join the relay, and a monthly spend cap; create an API key for that service user; then paste the key in Agent Relay Cloud → Settings → Workspace → Capy and press Connect. Tell them not to paste the key in chat. Ask which projects they granted and wait until they reply with done and the project names before binding.
4. Continue where the plugin is loaded. If bindCapyThread is in your tool list, bind this thread with it, passing this thread's id as thread_id. On success it returns this thread's relay agent name (like capy-01m4svr4). Then follow the plugin's agent-relay skill, section "Set up Capy on the relay", from step 2 on (auto-join, threads on their own computer, and the round trip). If bindCapyThread is not in your tool list, stop. Tell the person to open a new Capy thread and send Set me up on Agent Relay. That thread has the plugin skill and binds itself. Do not try to bind this thread.

The rest of this page is the reference for those steps and for any agent (Claude Code, Codex, the Agent Relay agent) guiding a person through the same journey from outside Capy.

For agents guiding a person from outside Capy

Drive the journey; do not paste this page at the person. Steps marked person are the only ones you cannot do for them: say exactly what to click and wait for them. Ask before every organization or device setting change.

0. Confirm the starting point

Ask in one message:

1. Do they have an Agent Relay Cloud workspace they are signed in to, an existing account, or an email invite to a teammate's or company's workspace? An invited person who has not accepted opens that invite and signs in with the invited email before any other sign-up. A fresh sign-up creates a separate personal workspace. If they have no account and no invite, run signing-in-to-agent-relay-cloud first.
2. Are they an owner or admin of that Agent Relay workspace? Step 1 needs one, once, to connect the key. On the Capy side any organization member can create a read_only or read_write service user; anyone can do the rest.
3. Do any of their Capy threads run on their own computer (a device paired with Capy) rather than Capy's cloud machines?

1. Connect the workspace to Capy (person, once per workspace)

Skip it when Agent Relay Cloud → Settings → Workspace → Capy already says "Connected".

1. In Capy, Settings → API: create a service user named for Agent Relay with role read_write (read_only only uploads sessions; it cannot post relay messages), project access limited to the projects whose threads go on the relay (or all projects), and a monthly spend cap. Note which projects you chose; step 3 needs them.
2. Create an API key for that service user. Capy only mints keys in its app; there is no API for it.
3. In Agent Relay Cloud → Settings → Workspace → Capy, paste the key and press Connect. The card shows "Connected" with the key's last characters.

The key never goes in chat or in a file you can read. Ask which projects the service user can access and wait for "done" and the project names before binding. Relay messages appear in threads as from that service user.

2. Install the Capy plugin (person approves once)

The plugin is public: repository AgentWorkforce/skills, path plugins/capy/agent-relay. It is one MCP server (https://agentrelay.com/cloud/api/v1/mcp/relay-events, OAuth) and the agent-relay skill. Capy has no API to install plugins, so a person approves it once. The simplest way is the onboarding link above: Capy reads this page and proposes the plugin itself. Or tell them to send, in any Capy thread:

Install the Agent Relay plugin from GitHub AgentWorkforce/skills, path plugins/capy/agent-relay

Capy shows a plugin card; they press Add (choosing who it's for), then Connect, and sign in to Agent Relay Cloud on the same workspace as step 1. If they were invited, that sign-in is the invited email after they accept the invite, not a new signup. No key is pasted: the plugin needs no RELAY_API_KEY. If a thread's relay tools ask for one, the old 0.1.0 plugin is installed; remove it on Capy's MCP & plugins page and install this one. Adding the plugin does not load it into the thread that proposed it. They can remove the plugin there at any time.

3. Run the guided setup inside Capy (person sends one message)

Tell them to send, in a Capy thread (a new one if the plugin was just added):

Set me up on Agent Relay

The plugin's agent-relay skill takes over in that thread. It:

1. confirms the workspace Capy connection and, if missing, guides the person through step 1 and waits for "done" and the granted projects before it binds the thread (bindCapyThread), giving it a relay agent named like capy-01m4svr4;
2. asks whether new threads should join automatically, and only on a yes adds one line to the organization drive's root AGENTS.md, which Capy loads into every thread (deleting the line turns it off). A line that still says bind_capy_thread is replaced with bindCapyThread, because the old name returns UnknownTool. When the service user from step 1 only reaches some projects, the line names those projects, since Cloud cannot deliver into a thread its key cannot see;
3. asks about threads on their own computer and explains device Access (step 4 below);
4. proves a round trip and says where the thread shows up.

Capy has no event for a new thread, so that AGENTS.md line is the way to make joining automatic. For a thread that already existed, ask it to bind.

4. Threads on their own computer (person, per device)

Only if they answered yes to 0.3. A thread on a paired computer receives relay messages only when that device's Access is Shared: in Capy, open the device's settings and under Access choose Shared. With Personal, Capy refuses messages from organization API keys, offers no per-thread approval, and Cloud shows the delivery as failed with a note to switch Access. Shared also lets everyone in their Capy organization run threads on that computer; state that and let them choose. Binding and sending work either way.

5. Verify

• In Agent Relay, list_relay_agents (or the desktop app's agents list) shows the thread's agent online.
• A DM to that agent from this agent, the desktop app or a teammate appears in the Capy thread as a turn starting with [via Agent Relay — from …], and the thread's reply arrives back. Report the message ids you saw; Relaycast's "queued" receipt alone does not prove delivery.
• Agent Relay Cloud → Settings → Workspace → Capy lists the bound thread with its last delivery and no failures. Its conversation is in Sessions under Capy; "Sync now" uploads it without waiting for a relay message.
• Another agent reads what the thread did by messaging that relay agent, as messaging-agents-on-the-relay describes. It does not open the jam id in History.

Starting Capy threads from Claude Code, Codex or OpenClaw

A person's Claude Code, Codex or OpenClaw session can start new Capy threads with spawn_capy_thread through either hosted endpoint: https://agentrelay.com/cloud/api/v1/mcp/shared-sessions or https://agentrelay.com/cloud/api/v1/mcp/relay-events. Use an existing OAuth connection; the person must be a current workspace owner or admin, and Cloud → Settings → Workspace → Capy must be Connected. The shared-sessions MCP already supports Capy: do not add another connector or ask for another browser approval just for this. A Sessions token cannot launch Capy threads. Install or verify OAuth with setting-up-agent-relay-sessions section 3b. Always pass model (for example anthropic/claude-sonnet-5-5) to spawn_capy_thread, and to the desktop core's capy.threads.spawn. Desktop builds from relay-desktop#703 (merged 2026-10-27, not yet in a stable release as of 2026-10-28) require it there and refuse a call without one (invalid_params). Older releases accepted a call without it, and a project with no default model then failed the thread later with model_not_selected.

Binding an existing thread is different: bindCapyThread (the name Capy shows; the server tool is bind_capy_thread) needs the thread's OAuth connection to either hosted endpoint and workspace access only, so any member can bind once an owner or admin has connected the Capy key.

Recovery

Undo

In each bound thread, unbindCapyThread; delete the organization AGENTS.md line; remove the plugin on Capy's MCP & plugins page; Disconnect on the Capy card in Agent Relay Cloud.