From df88b336701370f756fad7287cbeeae0044d6218 Mon Sep 17 00:00:00 2001 From: Proactive Runtime Bot Date: Tue, 13 Oct 2026 09:19:26 -0700 Subject: [PATCH 1/3] docs: add self-hosting guide referencing the Relaycast engine agentrelay.com's homepage "Self host" card links to docs/self-hosting/README.md, which did not exist. Point at Relaycast's self-hosting guide for the engine and document how the CLI, broker, and spawned agents target a self-hosted origin. Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- docs/self-hosting/README.md | 63 +++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 1 deletion(-) create mode 100644 docs/self-hosting/README.md diff --git a/README.md b/README.md index bacb922a9..95e9b3c91 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ npm install -g agent-relay ### Self Hosting -Agent Relay has self hosting options for each primitive. We're happy to help you set up the whole system on your environment, just reach out to our team hi(at)agentrelay.com and we'll walk you through it. +Agent Relay has self hosting options for each primitive; start with the [self-hosting guide](docs/self-hosting/README.md). We're happy to help you set up the whole system on your environment, just reach out to our team hi(at)agentrelay.com and we'll walk you through it. ## License diff --git a/docs/self-hosting/README.md b/docs/self-hosting/README.md new file mode 100644 index 000000000..71f2f3b10 --- /dev/null +++ b/docs/self-hosting/README.md @@ -0,0 +1,63 @@ +# Self-hosting Agent Relay + +Agent Relay is open source end to end. [Agent Relay Cloud](https://agentrelay.com/cloud) +runs it for you, but every primitive can run inside your own infrastructure. + +## What you run + +| Layer | What it does | Self-hosting reference | +| --- | --- | --- | +| **Relaycast** (messaging engine) | Workspaces, agents, channels, threads, DMs, presence, files, and real-time WebSocket events | [relaycast › Self-hosting Relaycast](https://github.com/AgentWorkforce/relaycast/blob/main/docs/self-hosting.md) | +| **Broker + CLI** (this repo) | `agent-relay` CLI and the `agent-relay-broker` that spawns agents, injects messages into their PTYs, and connects them to Relaycast | Runs on your machines already; point it at your Relaycast (below) | +| **Relayfile** (optional) | Provider data (GitHub, Slack, Linear, …) as files, with writeback | [Relayfile › Self-hosting](https://agentrelay.com/docs/file/self-hosting) | + +Relaycast is the piece to stand up first. It ships as a single Node + SQLite +process (`npx @relaycast/engine --db ./relaycast.db --port 8787`) with no +external services. The [Relaycast self-hosting guide](https://github.com/AgentWorkforce/relaycast/blob/main/docs/self-hosting.md) +is the reference for installing it, configuring it, creating your first +workspace, running it in production (systemd, Docker Compose, reverse proxy), +upgrades, backups, and its limitations. It is single-tenant and single-process, +so read the limitations section before you depend on it for scale. + +## Point Agent Relay at your Relaycast + +Once your engine is running and you have created a workspace (the guide's +"Create your first workspace" step returns an `rk_live_…` workspace key), point +Agent Relay at it with environment variables: + +```bash +export RELAY_BASE_URL=https://relay.example.com # your Relaycast public origin +export RELAY_API_KEY=rk_live_... # the workspace key + +npm install -g agent-relay +agent-relay up +``` + +- `RELAY_BASE_URL` is read by the CLI, the MCP server it injects into agents, + and the broker. The broker also accepts `RELAYCAST_BASE_URL`, which takes + precedence. When neither is set, everything talks to the hosted + `https://cast.agentrelay.com`. +- `RELAYCAST_WS_URL` overrides the WebSocket endpoint. Leave it unset unless + your proxy serves WebSockets from a different origin; otherwise it is derived + from the base URL. +- The broker passes the base URL through to the agents it spawns, so their + Relay MCP tools reach the same engine. +- Keep the workspace key out of shell history and argv; prefer a mode-600 env + file or your secret manager. + +SDK clients take the same origin directly, for example +`createWorkspaceClient({ workspaceKey, baseUrl: 'https://relay.example.com' })` +from `@agent-relay/sdk/messaging`. + +## What stays hosted + +Self-hosted Relaycast replaces the messaging engine only. Features built on +Agent Relay Cloud (`agent-relay cloud …`, cloud sandboxes and `fleet spawn +--sandbox`, hosted dashboards and shared sessions) still require a Cloud +account. Everything that runs on your own nodes (`agent-relay up`, local agent +spawning, messaging, channels, and DMs) works against your own engine. + +## Help + +We're happy to help you set up the whole system in your environment. Reach out +to hi(at)agentrelay.com and we'll walk you through it. From e653c02b11e55b6e1c9dba5cfbc732baab3df1a1 Mon Sep 17 00:00:00 2001 From: Proactive Runtime Bot Date: Tue, 13 Oct 2026 09:19:37 -0700 Subject: [PATCH 2/3] style: prettier Co-Authored-By: Claude Opus 5.5 --- docs/self-hosting/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/self-hosting/README.md b/docs/self-hosting/README.md index 71f2f3b10..d92dc29ea 100644 --- a/docs/self-hosting/README.md +++ b/docs/self-hosting/README.md @@ -5,11 +5,11 @@ runs it for you, but every primitive can run inside your own infrastructure. ## What you run -| Layer | What it does | Self-hosting reference | -| --- | --- | --- | -| **Relaycast** (messaging engine) | Workspaces, agents, channels, threads, DMs, presence, files, and real-time WebSocket events | [relaycast › Self-hosting Relaycast](https://github.com/AgentWorkforce/relaycast/blob/main/docs/self-hosting.md) | -| **Broker + CLI** (this repo) | `agent-relay` CLI and the `agent-relay-broker` that spawns agents, injects messages into their PTYs, and connects them to Relaycast | Runs on your machines already; point it at your Relaycast (below) | -| **Relayfile** (optional) | Provider data (GitHub, Slack, Linear, …) as files, with writeback | [Relayfile › Self-hosting](https://agentrelay.com/docs/file/self-hosting) | +| Layer | What it does | Self-hosting reference | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| **Relaycast** (messaging engine) | Workspaces, agents, channels, threads, DMs, presence, files, and real-time WebSocket events | [relaycast › Self-hosting Relaycast](https://github.com/AgentWorkforce/relaycast/blob/main/docs/self-hosting.md) | +| **Broker + CLI** (this repo) | `agent-relay` CLI and the `agent-relay-broker` that spawns agents, injects messages into their PTYs, and connects them to Relaycast | Runs on your machines already; point it at your Relaycast (below) | +| **Relayfile** (optional) | Provider data (GitHub, Slack, Linear, …) as files, with writeback | [Relayfile › Self-hosting](https://agentrelay.com/docs/file/self-hosting) | Relaycast is the piece to stand up first. It ships as a single Node + SQLite process (`npx @relaycast/engine --db ./relaycast.db --port 8787`) with no From 288f5a4c63d32acdc2295cfe2991169986a29e33 Mon Sep 17 00:00:00 2001 From: Proactive Runtime Bot Date: Tue, 13 Oct 2026 10:11:44 -0700 Subject: [PATCH 3/3] docs(self-hosting): use node up, keep the key out of history, drop RELAYCAST_WS_URL - agent-relay 13.4.1 has no top-level up; the command is agent-relay node up. - Prompt for the workspace key without echo into a mode-600 env file. - RELAYCAST_WS_URL is read but never used for the node sockets; document that WebSockets derive from the base URL instead. - Name RELAY_WORKSPACE_KEY as canonical with its fallbacks. Co-Authored-By: Claude Opus 5.5 --- docs/self-hosting/README.md | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/docs/self-hosting/README.md b/docs/self-hosting/README.md index d92dc29ea..4b30550d0 100644 --- a/docs/self-hosting/README.md +++ b/docs/self-hosting/README.md @@ -23,27 +23,40 @@ so read the limitations section before you depend on it for scale. Once your engine is running and you have created a workspace (the guide's "Create your first workspace" step returns an `rk_live_…` workspace key), point -Agent Relay at it with environment variables: +Agent Relay at it with environment variables. Keep the key out of shell history +and argv: prompt for it without echo and store it in a mode-600 env file (or +load it from your secret manager): ```bash -export RELAY_BASE_URL=https://relay.example.com # your Relaycast public origin -export RELAY_API_KEY=rk_live_... # the workspace key +mkdir -p ~/.config/agent-relay +umask 077 +printf 'Workspace key: '; read -rs RELAY_WORKSPACE_KEY; echo +printf 'RELAY_BASE_URL=%s\nRELAY_WORKSPACE_KEY=%s\n' \ + https://relay.example.com "$RELAY_WORKSPACE_KEY" > ~/.config/agent-relay/self-host.env +unset RELAY_WORKSPACE_KEY +``` + +Then load it and start this machine's node: +```bash npm install -g agent-relay -agent-relay up +set -a; . ~/.config/agent-relay/self-host.env; set +a +agent-relay node up ``` +`node up` reports `Workspace: joined ` with the workspace ID your engine +issued; `agent-relay node status` confirms the broker is running. + - `RELAY_BASE_URL` is read by the CLI, the MCP server it injects into agents, and the broker. The broker also accepts `RELAYCAST_BASE_URL`, which takes precedence. When neither is set, everything talks to the hosted - `https://cast.agentrelay.com`. -- `RELAYCAST_WS_URL` overrides the WebSocket endpoint. Leave it unset unless - your proxy serves WebSockets from a different origin; otherwise it is derived - from the base URL. + `https://cast.agentrelay.com`. The broker derives its WebSocket connections + from this origin, so your proxy must serve WebSocket upgrades on it. +- `RELAY_WORKSPACE_KEY` is the workspace key. `AGENT_RELAY_WORKSPACE_KEY` and + the legacy `RELAY_API_KEY` are accepted as fallbacks, and + `agent-relay node up --workspace-key` also works but puts the key in argv. - The broker passes the base URL through to the agents it spawns, so their Relay MCP tools reach the same engine. -- Keep the workspace key out of shell history and argv; prefer a mode-600 env - file or your secret manager. SDK clients take the same origin directly, for example `createWorkspaceClient({ workspaceKey, baseUrl: 'https://relay.example.com' })` @@ -54,7 +67,7 @@ from `@agent-relay/sdk/messaging`. Self-hosted Relaycast replaces the messaging engine only. Features built on Agent Relay Cloud (`agent-relay cloud …`, cloud sandboxes and `fleet spawn --sandbox`, hosted dashboards and shared sessions) still require a Cloud -account. Everything that runs on your own nodes (`agent-relay up`, local agent +account. Everything that runs on your own nodes (`agent-relay node up`, local agent spawning, messaging, channels, and DMs) works against your own engine. ## Help