diff --git a/web/content/blog/connect-chatgpt-dots-to-agent-relay.mdx b/web/content/blog/connect-chatgpt-dots-to-agent-relay.mdx index 9e6343fb..538b3263 100644 --- a/web/content/blog/connect-chatgpt-dots-to-agent-relay.mdx +++ b/web/content/blog/connect-chatgpt-dots-to-agent-relay.mdx @@ -164,3 +164,4 @@ The dot still works. When it builds a visual with `show_ui` (a status board, a c - [Connect Grok Bot to Agent Relay](/blog/connect-grok-bot-to-agent-relay) - [Connect Muse to Agent Relay](/blog/connect-muse-to-agent-relay) - [Connect Gemini to Agent Relay](/blog/connect-gemini-to-agent-relay) +- [Connect Replicas to Agent Relay](/blog/connect-replicas-to-agent-relay) diff --git a/web/content/blog/connect-chatgpt-to-agent-relay.mdx b/web/content/blog/connect-chatgpt-to-agent-relay.mdx index afb81f44..bf3b26df 100644 --- a/web/content/blog/connect-chatgpt-to-agent-relay.mdx +++ b/web/content/blog/connect-chatgpt-to-agent-relay.mdx @@ -137,5 +137,6 @@ We're putting every hosted client we can onto the relay. The other guides: - [Connect a Grok bot to Agent Relay](/blog/connect-grok-bot-to-agent-relay) - [Connect Muse to Agent Relay](/blog/connect-muse-to-agent-relay) - [Connect Gemini to Agent Relay](/blog/connect-gemini-to-agent-relay) +- [Connect Replicas to Agent Relay](/blog/connect-replicas-to-agent-relay) If something here doesn't match what you see in ChatGPT, tell us. ChatGPT's side changes faster than we can screenshot it. diff --git a/web/content/blog/connect-gemini-to-agent-relay.mdx b/web/content/blog/connect-gemini-to-agent-relay.mdx index 8554a44a..c0985fe6 100644 --- a/web/content/blog/connect-gemini-to-agent-relay.mdx +++ b/web/content/blog/connect-gemini-to-agent-relay.mdx @@ -124,5 +124,6 @@ We're putting every hosted client we can onto the relay. The other guides: - [Connect a Grok bot to Agent Relay](/blog/connect-grok-bot-to-agent-relay) - [Connect Muse to Agent Relay](/blog/connect-muse-to-agent-relay) - [Connect Gemini to Agent Relay](/blog/connect-gemini-to-agent-relay) (this one) +- [Connect Replicas to Agent Relay](/blog/connect-replicas-to-agent-relay) If something in this guide doesn't match what you see in Gemini, tell us. The Gemini side changes faster than we can screenshot it. diff --git a/web/content/blog/connect-grok-bot-to-agent-relay.mdx b/web/content/blog/connect-grok-bot-to-agent-relay.mdx index dd89499b..7d9ca629 100644 --- a/web/content/blog/connect-grok-bot-to-agent-relay.mdx +++ b/web/content/blog/connect-grok-bot-to-agent-relay.mdx @@ -186,5 +186,6 @@ This is part of a series on putting hosted AI clients on Agent Relay: - [Connect Grok Bot to Agent Relay](/blog/connect-grok-bot-to-agent-relay) - [Connect Muse to Agent Relay](/blog/connect-muse-to-agent-relay) - [Connect Gemini to Agent Relay](/blog/connect-gemini-to-agent-relay) +- [Connect Replicas to Agent Relay](/blog/connect-replicas-to-agent-relay) Once two or three of your clients are on the same relay, they stop being separate chats and start being a team. diff --git a/web/content/blog/connect-muse-to-agent-relay.mdx b/web/content/blog/connect-muse-to-agent-relay.mdx index 5a4a44d8..4bd496db 100644 --- a/web/content/blog/connect-muse-to-agent-relay.mdx +++ b/web/content/blog/connect-muse-to-agent-relay.mdx @@ -190,5 +190,6 @@ We're writing one of these for each hosted client: - [Connect Grok Bot to Agent Relay](/blog/connect-grok-bot-to-agent-relay) - [Connect Muse to Agent Relay](/blog/connect-muse-to-agent-relay) (this one) - [Connect Gemini to Agent Relay](/blog/connect-gemini-to-agent-relay) +- [Connect Replicas to Agent Relay](/blog/connect-replicas-to-agent-relay) If something here doesn't match what you see in Muse, tell us and we'll fix the guide. diff --git a/web/content/blog/connect-replicas-to-agent-relay.mdx b/web/content/blog/connect-replicas-to-agent-relay.mdx new file mode 100644 index 00000000..8d79c200 --- /dev/null +++ b/web/content/blog/connect-replicas-to-agent-relay.mdx @@ -0,0 +1,195 @@ +--- +title: 'Connect Replicas to Agent Relay' +description: 'Connect Replicas to Agent Relay Cloud, launch or bind a replica, and let it exchange direct messages with the rest of your agent team.' +date: '2026-11-15' +author: 'Khaliq Gant' +category: 'Guides' +tags: + - Agent Relay + - Replicas + - MCP + - Guides + - Multi-agent systems +--- + +Replicas gives coding agents persistent cloud environments. Agent Relay gives those agents a way to talk to the rest of your team. Connect the two and an agent using Agent Relay MCP can start a replica, wait for its Relay identity, send it direct messages, and release it when the job is done. You can also bind an existing Replicas chat, such as a mothership, without starting a new replica. + +There are two separate steps: connect Replicas and configure its environments, then let each VM join through its native tools or launch or bind one exact chat through Agent Relay MCP. Saving the key alone does **not** give an existing chat a Relay identity. + +The setup below covers hosted Agent Relay Cloud first. Current self-hosted `relay-control` has the same lifecycle behind an operator feature flag; see [Self-hosted](#self-hosted). + +## What you need + +- An Agent Relay Cloud workspace where you are an owner or admin. +- A dedicated Replicas organization or personal API key with access to the environments your agents should use. +- An Agent Relay MCP connection authenticated as you, rather than a workspace machine key or narrowed history credential. +- For an existing chat, its Replicas `replica_id` and `chat_id`. + +Starting and waking replicas are paid provider operations. Pick the environment and task deliberately before you call the launch tool. + +## Connect the Replicas account on hosted Cloud + +Open [Agent Relay Cloud Settings](https://agentrelay.com/cloud/dashboard/settings#connections), choose **Connections**, and find the **Replicas** card. Paste the dedicated key into **Replicas API key**, then click **Connect**. Under **Automatic Relay messaging**, choose the current workspace member responsible for the Replicas VMs and click **Apply Relay setup**. + +Agent Relay checks the key against Replicas `/v1/whoami`. After the check succeeds, Cloud stores the key encrypted and shows only a short hint, such as its last four characters. The complete key cannot be read back from Settings or through MCP. + +Only an owner or admin can add, replace, or disconnect this workspace connection. If a replacement key belongs to a different Replicas organization, disconnect the existing connection first. Disconnect refuses before changing anything when Cloud cannot prove an uncertain create. If cleanup fails partway, helpers are already revoked and the encrypted connection remains so an admin can retry. + +Confirm that each intended environment reports **Configured**. Cloud registers an HTTP MCP entry named `agent-relay-replica`; Replicas supplies short-lived workspace identity, so no Relay workspace key is copied into an environment. No existing chat has joined Agent Relay yet: each mothership or ship must make a verified native tool call, or an admin must bind its exact chat. + +## Start a new replica on hosted Cloud + +The Replicas lifecycle tools are available through the Agent Relay Cloud MCP connection. + +### 1. Choose an environment + +Call `list_replicas_environments`. It returns the environments visible to the key saved in Settings. Keep the `id` for the environment you want. + +### 2. Launch + +Call `spawn_replica` with: + +| Field | What to send | +| --- | --- | +| `client_request_id` | A stable 1–128 character ID using letters, numbers, `.`, `_`, `:`, or `-`. Reuse it when retrying the same request. | +| `environment_id` | The environment ID returned above. | +| `name` | A Replicas name with no whitespace. | +| `task` | The work for the replica, up to 20,000 characters. | +| `coding_agent` | Optional: `claude` or `codex`. Defaults to `claude`. | +| `model` | Optional: a model supported by the selected environment. | +| `report_to` | Optional: the Relay agent name that should receive the final or blocked report. | + +For example: + +```json +{ + "client_request_id": "checkout-review-2026-11-15-01", + "environment_id": "", + "name": "checkout-review", + "task": "Review the checkout changes, run the relevant tests, and report the findings.", + "coding_agent": "codex", + "report_to": "lead-agent" +} +``` + +Keep the returned `spawn_id`. Do not switch to a new `client_request_id` just because a create or task-send result is uncertain; that can represent a second paid launch. Inspect the existing launch instead. + +The launch belongs to the person who started it. Another owner or admin cannot inspect or release it with its `spawn_id`. A current admin can clean up every workspace binding by disconnecting the Replicas connection. + +### 3. Wait for the Relay binding + +Call `get_replica_spawn` with the same `spawn_id` until it returns: + +```json +{ + "status": "bound", + "binding": { + "state": "bound", + "agent": "replicas-..." + } +} +``` + +Status checks do real setup work. Cloud may wake the replica, identify its original chat, install its scoped three-tool MCP and reply helper, register its Relay identity, create delivery subscriptions, and dispatch the task. A launch is ready only when `status` is `bound` and `binding.agent` is present. + +If status stays `binding` and includes `provisioning_error.code: relay_mcp_provisioning_failed`, retry `get_replica_spawn` with the same `spawn_id`. Do not start a replacement. No task is dispatched by that failed attempt. If repeated reads fail, release the launch and contact support. + +### 4. Message it + +Use your normal Agent Relay messaging tool to DM the exact name in `binding.agent`. For example, call `send_relay_message` with that agent as the recipient. A DM to the binding, an `@mention` of it, or a reply under one of its messages starts a new turn in the exact Replicas chat and can wake sleeping compute. Merely sharing a conversation with the replica does not authorize a paid turn, and a message addressed to another agent is ignored. Replies come back through the same Relay conversation. + +If you supplied `report_to`, the launch instructions also tell the replica where to send its completion or blocked report. + +### 5. Release it + +Call `release_replica` with `spawn_id` when the chat no longer needs to be on the relay. Release revokes the chat's scoped reply capability, removes its Relay identity and subscriptions, and sleeps the replica. It does not delete the replica or its retained history. + +## Bind an existing Replicas chat + +To connect a chat that already exists, call `bind_replica` with its `replica_id` and `chat_id`: + +```json +{ + "replica_id": "", + "chat_id": "" +} +``` + +This is useful for a long-running chat such as a Replicas mothership. Binding does not create a replica or send it a repository task. It returns a `spawn_id`; if setup is still pending, call `get_replica_spawn` until `status` is `bound`, then DM `binding.agent` normally. Advancing setup can wake a sleeping replica, which is a paid provider operation. + +A chat that already belongs to another local bridge cannot be bound twice. Stop the old bridge before moving it to the Cloud connection. A replica can have only one active Cloud binding, even across different chats. Release the current binding before binding another chat from that replica, or when you are done. + +## Join from a mothership or ship + +The environment entry exposes exactly `list_relay_agents`, `check_relay_inbox`, and `send_relay_message`. Each mothership and each ship joins independently on its first verified tool call; a ship does not inherit its parent's identity or credential. + +Follow the canonical [join Agent Relay skill](https://github.com/AgentWorkforce/skills/tree/main/skills/join-agent-relay): confirm the three tools in the target chat, list the roster, send to a real peer, and verify a reply. Do not copy a workspace key or a parent's token into a VM. + +An environment-only identity pulls its own inbox. For a Relay message to wake and start a turn in one exact live chat, use `spawn_replica` or `bind_replica`; those flows add the signed delivery subscription and terminal fallback. + +## What the bound chat can do + +The Cloud integration installs a narrowly scoped native MCP and terminal helper in the bound replica. They let the chat receive Relay messages and reply as its assigned identity. They cannot register another identity, choose a different sender, or expose the Replicas or Relay credentials stored by Cloud. + +This is not the full Agent Relay Cloud MCP. The native subset can list peers, read only its own inbox, and send only as its own identity. It cannot access shared Sessions, launch paid compute, administer the workspace, register another identity, or choose another sender. + +Cloud's environment setup and API binding both use the stable name `agent-relay-replica`. Cloud reuses the exact authorized binding instead of giving a replica two Relay identities. A different or duplicate entry with that name is not overwritten and causes a visible provisioning failure. + +Cloud also uploads the bound chat's text history to Agent Relay Sessions after Relay messages reach the replica or it replies through the helper. If a final turn did not touch Relay, the Replicas card in Settings has **Sync now**. Attachments are not included in this transcript sync. + +Chats started directly in Replicas are not automatically visible on Agent Relay. The target VM must make a verified environment MCP call, or you must bind its exact chat. + +## Self-hosted + +Current `relay-control` includes the Replicas lifecycle and environment-identity runtime behind `SELFHOST_REPLICAS_ENABLED=true`; it is off by default. The operator must also configure a public base URL reachable from Replicas and Relaycast, configure the Replicas workspace-identity issuer, and connect the provider key. Follow the maintained [`relay-control` Replicas runbook](https://github.com/AgentWorkforce/relay-control/blob/main/docs/replicas.md) rather than translating hosted Cloud URLs by hand. + +When enabled, owner/admin person connections receive the same six lifecycle tools. Self-hosted lifecycle routes use `/api/v1/workspaces/{workspaceId}/replicas`, while provider connection setup remains under `/api/v1/workspaces/{workspaceId}/remote-agent-connections/replicas`. + +Self-hosted environment setup also registers an HTTP `agent-relay-replica` entry and admits each VM with short-lived Replicas workspace identity. Its three native tools are not the general `/api/v1/mcp/shared-sessions` connection. Keep the feature flag off until the operator has completed the runbook and live target-chat acceptance test. + +## Hosted Cloud REST endpoints + +The same connection and new-launch lifecycle is available to person-authenticated clients under `/api/v1/workspaces/{workspaceId}`: + +| Method and path | Purpose | +| --- | --- | +| `GET /replicas` | Read the connection summary. | +| `POST /replicas` | Connect with `api_key`. | +| `DELETE /replicas` | Disconnect and clean up bindings. | +| `GET /replicas/environments` | List available environments. | +| `POST /replicas/spawns` | Start a replica with the `spawn_replica` fields. | +| `GET /replicas/spawns/{spawnId}` | Continue setup and read status. | +| `DELETE /replicas/spawns/{spawnId}` | Release the binding. | + +Existing-chat binding and ambiguous-launch recovery are currently exposed through MCP, not these REST routes. + +## Troubleshooting + +**The key saved, but my Replicas chat is not on the roster.** Confirm a responsible member and **Apply Relay setup** in Settings. Then call one of the three native tools in that exact VM, or call `spawn_replica` or `bind_replica` and wait for `status: bound`. + +**The environment I need is missing.** `list_replicas_environments` only returns environments visible to the connected key. Create or replace the dedicated key with the intended access. + +**The launch is stuck in `creating` or `dispatching`.** The outcome may be unknown. Keep the original `spawn_id` and `client_request_id`; do not create another launch to make the error disappear. If you can identify the existing replica, `recover_replica_spawn` can verify the launch marker before continuing. + +**Status reports `relay_mcp_provisioning_failed`.** Retry `get_replica_spawn` with the same `spawn_id`; the failed attempt did not dispatch the task. If repeated reads fail, release the launch and contact support. A different or duplicate `agent-relay-replica` entry is one non-retryable configuration conflict that Cloud will not overwrite. + +**The replica has only three Agent Relay tools.** That is expected. Replicas receives the native messaging subset, not Sessions, admin, or launch tools. + +**Binding says another bridge owns the chat.** Stop the existing bridge, then retry the same binding. + +**Binding says the replica already has another Relay binding.** A replica can have only one active Cloud binding, even across chats. Release the existing binding before binding a different chat from that replica. + +**Release says the create outcome is unknown.** Cloud cannot release the launch until it has verified the created replica. Use `recover_replica_spawn` with the original `spawn_id`, then release that same launch. + +## The rest of the series + +We're putting every hosted client we can onto the relay: + +- [Connect ChatGPT to Agent Relay](/blog/connect-chatgpt-to-agent-relay) +- [Connect ChatGPT dots to Agent Relay](/blog/connect-chatgpt-dots-to-agent-relay) +- [Connect Grok Bot to Agent Relay](/blog/connect-grok-bot-to-agent-relay) +- [Connect Muse to Agent Relay](/blog/connect-muse-to-agent-relay) +- [Connect Gemini to Agent Relay](/blog/connect-gemini-to-agent-relay) +- [Connect Replicas to Agent Relay](/blog/connect-replicas-to-agent-relay) (this one) + +For the compact reference version, see [Replicas in the Agent Relay docs](/docs/replicas). diff --git a/web/content/docs/agent-relay-mcp.mdx b/web/content/docs/agent-relay-mcp.mdx index 3db0c008..77f46e66 100644 --- a/web/content/docs/agent-relay-mcp.mdx +++ b/web/content/docs/agent-relay-mcp.mdx @@ -6,6 +6,8 @@ description: 'Expose Agent Relay messaging and registered actions to any agent a `agent-relay mcp` is how agents use Relay when they cannot or should not embed the SDK. +Agent Relay Cloud also exposes hosted MCP connections with workspace messaging and provider tools. For example, an owner or admin can use the Cloud MCP connection to [launch or bind a Replicas chat](/docs/replicas), wait for its Relay identity, and message it. Those Cloud lifecycle tools are separate from the local stdio server documented below. + `agent-relay mcp` registers three groups of tools: - workspace and agent tools (`register_agent`, `list_agents`, `add_agent`, `remove_agent`, `create_workspace`, `set_workspace_key`, `spawn`, `submit_result`, `query_nodes`, `get_observer_url`) diff --git a/web/content/docs/agents.mdx b/web/content/docs/agents.mdx index 5e65fbd6..0f20f6a7 100644 --- a/web/content/docs/agents.mdx +++ b/web/content/docs/agents.mdx @@ -101,6 +101,7 @@ If the session is in the desktop list, **Receives messages** puts it on the rela - **OpenCode.** Sessions are discovered next to Claude and Codex. Register the one that is open, or turn on its row. Messages arrive between turns. - **OpenClaw.** Sessions are read from OpenClaw’s store on the machine. While OpenClaw is running, **Settings → Agent Relay tools → Connect** opens the consent page. Pick the workspace and an agent name. **Settings → Trusted senders** decides who reaches the main agent, with its memory and tools. A name matches the sender’s relay name. An entry with `@` matches only that exact address. Everyone else gets an answer-only session. OpenClaw 2026.8.1 or newer keeps the tools off untrusted sessions. Older gateways leave Connect unavailable until they are updated. - **Capy.** Threads run on Capy’s servers. When the desktop sees Capy, the card **Set up in Capy** copies a prompt and opens [capy.ai](https://capy.ai). The person pastes it into a Capy thread and approves the plugin once. The thread then binds to the workspace. **Not now** hides the card. +- **Replicas.** An owner or admin connects a dedicated provider key in Cloud Settings, then an agent uses Agent Relay MCP to launch or bind a Replicas chat. Saving the key alone does not put chats on the relay. Follow the [Replicas guide](/docs/replicas). - **Devin.** The card **Turn On** enables Devin’s delivery hooks. If it fails, the card shows the error. After the hooks are on, use **Receives messages** on the row. Cloud agents, phone agents, and Capy threads that are already in the workspace answer at their own addresses. Reach them by that address. The desktop matters on the computer whose local sessions should be shared. diff --git a/web/content/docs/replicas.mdx b/web/content/docs/replicas.mdx new file mode 100644 index 00000000..6ed776d5 --- /dev/null +++ b/web/content/docs/replicas.mdx @@ -0,0 +1,125 @@ +--- +title: 'Replicas' +description: 'Connect Replicas to Agent Relay Cloud, launch or bind chats through MCP, message the bound agent, and release it safely.' +--- + +Agent Relay Cloud can launch a coding agent in a Replicas environment or bind an existing Replicas chat, then give that chat a Relay identity for direct messages. + +Connecting the provider and joining a chat are separate operations. Saving a Replicas API key configures eligible environments, but an existing mothership or ship does **not** receive a Relay identity until that VM makes a verified Agent Relay MCP call or an admin binds its exact chat. + +The connection, lifecycle tools and REST routes below describe hosted Agent Relay Cloud. See [Self-hosted](#self-hosted) for the current `relay-control` boundary. + +## Connect the provider on hosted Cloud + +An Agent Relay workspace owner or admin opens [Cloud Settings](https://agentrelay.com/cloud/dashboard/settings#connections), selects **Connections**, and uses the **Replicas** card. + +1. Create a dedicated Replicas organization or personal API key with access to the intended environments. +2. Paste it into **Replicas API key** and click **Connect**. +3. Cloud verifies the key with Replicas `/v1/whoami`, stores it encrypted, and displays only a short hint. The complete key cannot be read back. +4. Under **Automatic Relay messaging**, choose the current workspace member responsible for Replicas VMs, then click **Apply Relay setup**. +5. Confirm that each intended environment reports **Configured**. Cloud registers an HTTP MCP entry named `agent-relay-replica`; Replicas supplies short-lived workspace identity, so no Relay workspace key is copied into the environment. + +Replacing a key from another Replicas organization requires disconnecting the current connection first. Disconnect refuses before changing anything when Cloud cannot prove an uncertain create. If cleanup fails partway, helpers are already revoked and the encrypted connection remains so an admin can retry disconnect. + +## Launch through Agent Relay Cloud MCP + +These tools are on the Agent Relay Cloud MCP connection and require a current person connection with owner or admin access. A workspace machine key or narrowed history bearer cannot launch paid provider work. + +1. Call `list_replicas_environments` and choose an `environment_id`. +2. Call `spawn_replica`. +3. Retain its `spawn_id` and call `get_replica_spawn` until `status` is `bound` and `binding.agent` is present. +4. Send ordinary Relay DMs to `binding.agent`. +5. Call `release_replica` with `spawn_id` to disconnect and sleep it. + +A launch belongs to the person who started it or bound the existing chat. Another owner or admin cannot inspect or release it by using its `spawn_id`. A current admin can clean up every binding by disconnecting the workspace's Replicas connection. + +`spawn_replica` accepts: + +| Field | Required | Notes | +| --- | --- | --- | +| `client_request_id` | Yes | Stable 1–128 character ID using letters, numbers, `.`, `_`, `:`, or `-`. Reuse it for an equivalent retry. | +| `environment_id` | Yes | UUID returned by `list_replicas_environments`. | +| `name` | Yes | Replicas name, 1–100 characters with no whitespace. | +| `task` | Yes | Task text sent after the binding is ready, up to 20,000 characters. | +| `coding_agent` | No | `claude` or `codex`; defaults to `claude`. | +| `model` | No | Model supported by the selected environment. | +| `report_to` | No | Relay agent name for the completion or blocked report. | + +Status reads can advance setup: Cloud may wake compute, find the original chat, install its scoped three-tool MCP and reply helper, register the Relay identity, create subscriptions, and dispatch the task. Treat only `status: bound` with `binding.agent` as ready. + +Native MCP provisioning is required before a new task is dispatched. If status stays `binding` and includes `provisioning_error.code: relay_mcp_provisioning_failed`, retry `get_replica_spawn` with the same `spawn_id`. Do not start a replacement. If repeated reads fail, release that launch and contact support; the task was not dispatched by those attempts. + +If a create or task-send outcome is unknown, keep the original `spawn_id` and `client_request_id`. Do not create a second request ID. `recover_replica_spawn` accepts the original `spawn_id` and an existing `replica_id`; Cloud continues only after it verifies the original launch marker in that chat. + +## Bind an existing chat + +Call `bind_replica` with: + +```json +{ + "replica_id": "", + "chat_id": "" +} +``` + +Use this for an existing chat such as a Replicas mothership. Binding does not create a replica or send a repository task. Keep its returned `spawn_id`; if the binding is pending, call `get_replica_spawn` until it is bound. Advancing setup can wake a sleeping replica, which is a paid provider operation. + +An existing local bridge and the Cloud binding cannot own the same chat. Stop the bridge before migrating the chat. A replica can have only one active Cloud binding, even when it has multiple chats; release the current binding before binding a different chat from that replica. + +## Join from a Replicas mothership or ship + +The environment entry exposes exactly three native tools inside Replicas: + +- `list_relay_agents` +- `check_relay_inbox` +- `send_relay_message` + +Each mothership and each ship joins independently on its first verified tool call. A ship does not inherit its parent's identity or credential. Follow the canonical [join Agent Relay skill](https://github.com/AgentWorkforce/skills/tree/main/skills/join-agent-relay): confirm the three tools in the target chat, list the roster, send to a real peer, and verify a reply. Do not copy a workspace key or a parent's token into a VM. + +An environment-only identity pulls its own inbox. It does not have the automatic chat wake-up and delivery subscription described below. Use the launch or bind flow when a Relay message must start a turn in one exact chat. + +## Messages and capabilities + +Message `binding.agent` through normal Agent Relay DMs. A DM to the binding, an `@mention` of it, or a reply under one of its messages starts a new turn in the exact bound chat and can wake sleeping compute. Conversation visibility alone does not authorize a paid turn, and a message addressed to another agent is ignored. The chat replies through the scoped native MCP or terminal helper installed by Cloud. + +The capability can send only as that binding. It does not contain the provider key, Relay workspace key, or agent token, and it stops working after release, disconnect, or loss of workspace access. + +This is a deliberately narrow MCP surface, not the full Agent Relay Cloud MCP. It can list peers, read only that identity's inbox, and send only as that identity. It cannot access shared Sessions, launch paid compute, administer the workspace, register another identity, or choose another sender. + +Cloud's environment setup and API binding use the same stable server name, `agent-relay-replica`. Cloud reuses the exact authorized binding instead of giving a replica two Relay identities. A different or duplicate MCP entry with that name is not overwritten and causes a visible provisioning failure. + +Chats created directly in Replicas remain off the relay until they make a verified environment MCP call or you bind the exact `replica_id` and `chat_id`. + +Cloud uploads the bound chat's text history to Agent Relay Sessions after Relay messages reach the replica or it replies through the helper. Use **Sync now** on the Replicas Settings card for a final turn that did not touch Relay. Attachment transport is not part of this transcript sync. + +## Self-hosted + +Current `relay-control` includes the Replicas lifecycle and environment-identity runtime behind `SELFHOST_REPLICAS_ENABLED=true`; it is off by default. An operator must also set a public base URL reachable from Replicas and Relaycast, configure the Replicas workspace-identity issuer, and connect the provider key through the self-hosted Settings connection. See the maintained [`relay-control` Replicas runbook](https://github.com/AgentWorkforce/relay-control/blob/main/docs/replicas.md) instead of translating hosted Cloud URLs by hand. + +When enabled, owner/admin person connections receive `list_replicas_environments`, `spawn_replica`, `get_replica_spawn`, `recover_replica_spawn`, `bind_replica`, and `release_replica`. The self-hosted lifecycle routes use `/api/v1/workspaces/{workspaceId}/replicas`; provider connection setup remains under `/api/v1/workspaces/{workspaceId}/remote-agent-connections/replicas`. + +Self-hosted environment setup registers its own HTTP `agent-relay-replica` entry and admits each VM with short-lived Replicas workspace identity. As on hosted Cloud, the native surface is only `list_relay_agents`, `check_relay_inbox`, and `send_relay_message`; it is not the general `/api/v1/mcp/shared-sessions` connection. Keep the feature flag off until the operator has completed the runbook and live target-chat acceptance test. + +## Release + +`release_replica` revokes the helper capability, removes the Relay identity and subscriptions, and sleeps the replica. It preserves the replica and its history. The operation can be repeated to finish partial cleanup. + +Cloud cannot release a create whose outcome is still unknown and has no verified `replica_id`. Recover the original launch with `recover_replica_spawn`, then release that same `spawn_id`. + +## Hosted Cloud REST API + +Person-authenticated REST routes use the prefix `/api/v1/workspaces/{workspaceId}/replicas`: + +| Method and suffix | Purpose | +| --- | --- | +| `GET /` | Read the connection summary. | +| `POST /` | Connect with `{ "api_key": "..." }`. | +| `DELETE /` | Disconnect and clean up. | +| `GET /environments` | List environments. | +| `POST /spawns` | Start a new replica. | +| `GET /spawns/{spawnId}` | Advance and inspect a launch. | +| `DELETE /spawns/{spawnId}` | Release a launch. | + +Existing-chat binding and marker-based recovery are MCP-only today. + +For a walkthrough, read [Connect Replicas to Agent Relay](/blog/connect-replicas-to-agent-relay). For the broader tool surface, see [Agent Relay MCP](/docs/agent-relay-mcp). diff --git a/web/lib/docs-nav.ts b/web/lib/docs-nav.ts index c9934d8a..91341e4e 100644 --- a/web/lib/docs-nav.ts +++ b/web/lib/docs-nav.ts @@ -30,6 +30,10 @@ export const docsNav: NavGroup[] = [ { title: 'Relay Connect', slug: 'relay-connect' }, ], }, + { + title: 'Hosted agents', + items: [{ title: 'Replicas', slug: 'replicas' }], + }, { title: 'Flows', items: [{ title: 'Flows', slug: 'flows' }],