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..4b30550d0
--- /dev/null
+++ b/docs/self-hosting/README.md
@@ -0,0 +1,76 @@
+# 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. 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
+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
+set -a; . ~/.config/agent-relay/self-host.env; set +a
+agent-relay node up
+```
+
+`node up` reports `Workspace: joined <id>` 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`. 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.
+
+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 node 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.