Skip to main content
RelayCloud separates the control plane from the devices where your assistants run. The control plane manages your organizations, projects, workspaces, servers, assistants, and conversations. The RelayCloud Orchestrator connects each device to RelayCloud and keeps its assistants available.

​
Connection architecture

RelayCloud issues tokens and receives events. A client and connected server use Relay for live traffic, while the Orchestrator connects to two isolated Unix-user OpenCode instances and their assigned workspaces.
The client and Orchestrator request short-lived tokens from RelayCloud, then use them to connect to Relay. The Orchestrator also sends assistant events to RelayCloud’s ingest service for persistence and can connect locally to multiple assistants on the same server or device.

​
Components

​
RelayCloud Control Plane

The RelayCloud Control Plane provides authentication, authorization, the web console, API, MCP server, organization management, server and infrastructure management, and conversation persistence. It issues short-lived tokens and manages the resources that describe your infrastructure and assistant conversations.

​
Client

The client can be your browser running the RelayCloud Web Chat UI or any client connected through the Orchestrator Proxy.

​
Relay

The client and RelayCloud Orchestrator use Relay for assistant connectivity. Relay routes live traffic between them, while RelayCloud issues short-lived tokens that the client uses to establish the Relay session.

​
Orchestrator

The RelayCloud Orchestrator runs on every device that connects to RelayCloud, whether RelayCloud manages the device or it already exists in your environment. It opens an outbound connection to Relay and connects directly to the assistant running on that device.

​
Assistants

Assistants are instances of your harness running on the server. Each assistant can access the workspaces assigned to its Unix user, while the Orchestrator connects each isolated account to RelayCloud. Workspace access can be exposed through Nginx independently of the assistant processes.

​
Request flow

1

Your client selects an Assistant

The client can be the RelayCloud Web Chat UI or an Orchestrator proxy running on your local device. In the Web Chat UI, RelayCloud selects the Assistant when you open a conversation or create a conversation in a workspace. When you start the proxy on a local device, you choose which Assistant to connect to.
2

Your client requests a short-lived token

The client connects to the control plane and requests a short-lived token. The token is scoped to your user and the Assistant you are connecting to. The control plane validates that you can access the Assistant and issues the token if the request is authorized.
3

Your client requests a Relay connection

The client connects to Relay with the short-lived token. Relay validates the token and returns a connection ID and connection token. Relay also sends the connection ID and connection token to the server hosting the Assistant through the Orchestrator’s persistent outbound control WebSocket.
4

Both sides join the connection

The client connects to the WebSocket for the connection ID using the connection token. The Orchestrator on the server hosting the Assistant connects to the same connection ID using the connection token it received.
5

Live traffic flows through Relay

Requests from the client and events from the Assistant travel directly between them through Relay. This hot path does not pass through or depend on the RelayCloud control plane or the ingest service.

​
Workspace and conversation flow

When a new prompt targets a workspace, RelayCloud selects an available assistant for that workspace, creates a conversation record, and sends the prompt through the assistant runner. When a prompt targets an existing conversation, RelayCloud validates that the conversation, workspace, assistant, and organization are still accessible before continuing the session. The browser keeps project and workspace state locally and receives conversation updates in real time when available, with polling as a fallback.

​
Connected device flow

RelayCloud supports both managed and self-managed servers. In both cases, the Orchestrator runs on the server, connects outbound to Relay, and connects directly to its assistants. For a self-managed server, the setup flow connects it to an organization, optionally installs a user-level background service, and can import local assistants. See Connect a self-managed server for the operator steps.