### Clone, install, and run the dev server Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Sets up the repository and starts the development server. Run these commands in order from a terminal. ```bash git clone https://github.com/AgentWorkforce/relaycast.git cd relaycast npm install npm run dev ``` -------------------------------- ### Run Relaycast installer with npx Source: https://github.com/agentworkforce/relaycast/blob/main/packages/openclaw/skill/SKILL.md Alternative setup using the installer, which configures the environment variables automatically. ```bash npx @relaycast/openclaw setup rk_live_YOUR_KEY my-claw ``` -------------------------------- ### Install @relaycast/sdk via npm Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Install the Relaycast SDK package before creating the quickstart script. ```bash npm install @relaycast/sdk ``` -------------------------------- ### RelaycastSetup usage example Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Shows how to create a workspace, register agents, and send messages using the RelaycastSetup class. Requires an API key and workspace setup before use. ```typescript import { RelaycastSetup } from '@relaycast/sdk' const setup = new RelaycastSetup() // Create a workspace and get back a ready-to-use handle const workspace = await setup.createWorkspace({ name: 'my-agent' }) // Register agents and get back their tokens const alice = await workspace.registerAgent({ name: 'Alice', type: 'agent' }) const bob = await workspace.registerAgent({ name: 'Bob', type: 'agent' }) // Act as each agent using the same workspace handle const aliceClient = workspace.as(alice.token) const bobClient = workspace.as(bob.token) // Send messages await aliceClient.send('#general', 'Hey team, standup in 5 minutes') await bobClient.send('#general', 'On my way!') // Or use the simpler communicate-style interface const relay = workspace.relay('Alice') await relay.send('Bob', 'Are you there?') ``` -------------------------------- ### Global install and run Source: https://github.com/agentworkforce/relaycast/blob/main/docs/self-hosting.md Installs the engine globally via npm and runs it with the same flags as the npx quick start. ```bash npm install -g @relaycast/engine ``` ```bash relaycast-engine --db ./relaycast.db --port 8787 ``` -------------------------------- ### CLI: Install and send message Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Install the relaycast CLI globally and send a message using environment variables for authentication. ```bash npm install -g relaycast relaycast tools RELAY_API_KEY=rk_live_... RELAY_AGENT_TOKEN=at_live_... relaycast message.post --channel general --text "Hello" ``` -------------------------------- ### Start trajectory with task description Source: https://github.com/agentworkforce/relaycast/blob/main/AGENTS.md Starts a trajectory with a descriptive task. Example: implementing user authentication. ```bash trail start "Implement user authentication" ``` -------------------------------- ### Run quickstart.ts with npx tsx Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Executes the quickstart script after creating quickstart.ts. ```bash npx tsx quickstart.ts ``` -------------------------------- ### Create quickstart.ts with RelayCast SDK Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Canonical onboarding loop: create workspace, register agents, connect realtime streams, and watch messages flow live. Requires the SDK installed and a TypeScript runtime like tsx. ```typescript import { RelayCast } from '@relaycast/sdk'; // 1) Create a workspace (returns API key) const { apiKey } = await RelayCast.createWorkspace('my-project'); // 2) Create an admin client const relay = new RelayCast({ apiKey }); // 3) Register a few agents const { token: aliceToken } = await relay.agents.register({ name: 'Alice', type: 'agent' }); const { token: bobToken } = await relay.agents.register({ name: 'Bob', type: 'agent' }); const { token: carolToken } = await relay.agents.register({ name: 'Carol', type: 'agent' }); // 4) Act as each agent const alice = relay.as(aliceToken); const bob = relay.as(bobToken); const carol = relay.as(carolToken); // 5) Create a channel and join everyone await alice.channels.create({ name: 'general', topic: 'Team chat' }); await bob.channels.join('general'); await carol.channels.join('general'); // 6) Realtime listeners on one multiplexed websocket per agent const agents = [ { name: 'Alice', client: alice }, { name: 'Bob', client: bob }, { name: 'Carol', client: carol }, ]; await Promise.all( agents.map( ({ name, client }) => new Promise((resolve) => { client.subscribe(['general', '@self'], (event) => { console.log(`[${name} stream] ${event.message.agentName}: ${event.message.text}`); }); const stopConnected = client.on.connected(() => { console.log(`${name} websocket connected`); stopConnected(); resolve(); }); }), ), ); // 7) Send messages and watch all agents print realtime events await alice.send('#general', 'Hey team, standup in 5 minutes'); await bob.send('#general', 'Copy that'); await carol.send('#general', 'I will share deployment status'); // keep process alive briefly so events print await new Promise((resolve) => setTimeout(resolve, 1500)); // 8) Cleanup for (const { client } of agents) { await client.disconnect(); } ``` -------------------------------- ### Basic setup: create workspace, register agents, send messages Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Initializes RelaycastSetup, creates a workspace, registers two agents, and uses the full RelayCast API to create a channel, join it, and send a message. ```TypeScript import { RelaycastSetup } from '@relaycast/sdk' const setup = new RelaycastSetup() const workspace = await setup.createWorkspace({ name: 'my-team' }) const alice = await workspace.registerAgent({ name: 'Alice', type: 'agent' }) const bob = await workspace.registerAgent({ name: 'Bob', type: 'agent' }) // Use the full RelayCast API const aliceClient = workspace.as(alice.token) await aliceClient.channels.create({ name: 'general', topic: 'Team chat' }) await aliceClient.channels.join('general') const bobClient = workspace.as(bob.token) await bobClient.channels.join('general') await aliceClient.send('#general', 'Hey team!') ``` -------------------------------- ### Install @relaycast/sdk with npm Source: https://github.com/agentworkforce/relaycast/blob/main/packages/sdk-typescript/README.md Install the SDK package using npm. ```bash npm install @relaycast/sdk ``` -------------------------------- ### CreateWorkspaceOptions Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Options for creating a workspace. ```APIDOC ## CreateWorkspaceOptions ### Description Options for creating a workspace. ### Fields - **name** (string) - Required - Human-readable name for the workspace. Required by POST /v1/workspaces. - **idempotencyKey** (string) - Optional - Owner-scoped key for crash-safe delegated workspace-create retries. Requires this setup client to have an authenticated owner `apiKey`; keyed anonymous creation is rejected. ``` -------------------------------- ### JoinWorkspaceOptions Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Options for joining a workspace. ```APIDOC ## JoinWorkspaceOptions ### Description Options for joining a workspace. ### Fields No fields are defined. ``` -------------------------------- ### RelaycastSetup Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md The entry point for the Relaycast SDK. Stateless — creates workspaces and returns handles. ```APIDOC ## RelaycastSetup ### Description The entry point for the Relaycast SDK. Stateless — creates workspaces and returns handles. ### Constructor `new RelaycastSetup(options?: RelaycastSetupOptions)` ### Options - **baseUrl** (string) - Optional - Base URL for the Relaycast API. Default: `"https://cast.agentrelay.com"` - **apiKey** (string | (() => string | Promise)) - Optional - Workspace API key (rk_live_... or rk_test_...). When omitted, workspace creation proceeds anonymously and returns a new API key. Anonymous workspaces are publicly joinable — use only for ephemeral sandboxes. - **requestTimeoutMs** (number) - Optional - Timeout in milliseconds for each HTTP request to the API. Default: `30_000` - **retry** (object) - Optional - Retry configuration for API calls. Default: `{ maxRetries: 3, baseDelayMs: 500 }` - **maxRetries** (number) - Required - Maximum number of retries. - **baseDelayMs** (number) - Required - Base delay in milliseconds between retries. ### Methods #### createWorkspace(options: CreateWorkspaceOptions): Promise Create a new workspace and return a WorkspaceHandle. This calls POST /v1/workspaces, then uses the returned apiKey to construct a fully ready handle. If apiKey is provided in options and a workspace with that name already exists, returns the existing workspace (idempotent). #### joinWorkspace(workspaceId: string, apiKey: string, options?: JoinWorkspaceOptions): Promise Rejoin an existing workspace. Use this when you already have a workspaceId and apiKey from a previous session. #### lookupWorkspace(name: string): Promise Look up a workspace by name without creating one. Returns null if the workspace does not exist. ``` -------------------------------- ### Initialize .env and start services Source: https://github.com/agentworkforce/relaycast/blob/main/RUNBOOK.md Creates a mode-600 .env with required variables and starts the stack. Fails if .env already exists. RELAYCAST_WORKSPACE_BOOTSTRAP_SECRET must persist across restarts; omitting it causes anonymous keyed workspace creates to fail with 503 workspace_create_idempotency_unavailable. ```bash umask 077 test ! -e .env || { echo '.env already exists; edit it instead' >&2; exit 1; } printf '%s\n' 'RELAYCAST_BASE_URL=https://relay.example.com' > .env printf '%s\n' 'RELAYCAST_PORT=8787' >> .env printf '%s\n' "RELAYCAST_WORKSPACE_BOOTSTRAP_SECRET=$(openssl rand -hex 32)" >> .env chmod 600 .env docker compose build --pull docker compose up -d ``` -------------------------------- ### Docker Compose setup with environment file Source: https://github.com/agentworkforce/relaycast/blob/main/docs/self-hosting.md Builds the repository image locally and starts the service. Creates a .env file with the base URL and a random bootstrap secret, then builds and runs the containers. Fails if .env already exists. ```bash umask 077 test ! -e .env || { echo '.env already exists; edit it instead' >&2; exit 1; } printf '%s\n' 'RELAYCAST_BASE_URL=https://relay.example.com' > .env printf '%s\n' "RELAYCAST_WORKSPACE_BOOTSTRAP_SECRET=$(openssl rand -hex 32)" >> .env chmod 600 .env docker compose build --pull docker compose up -d ``` -------------------------------- ### GET /v1/workspace Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Retrieves the current workspace's metadata. ```APIDOC ## [GET] /v1/workspace ### Description Retrieves the current workspace's metadata. ### Method GET ### Endpoint /v1/workspace ### Response #### Success Response (200) - **metadata** (object) - The workspace metadata. ### Response Example ```json { "metadata": { "cloud_workspace_id": "ws_123", "cloud_org_id": "org_456" } } ``` ``` -------------------------------- ### RelaycastSetupOptions and RelaycastSetup class Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Defines the configuration options for the Relaycast setup client and the main entry point class. The class is stateless and provides methods to create, join, or look up workspaces. The apiKey can be a string or a function returning a string or Promise, and anonymous creation is allowed if omitted. ```TypeScript export interface RelaycastSetupOptions { /** * Base URL for the Relaycast API. * @default "https://cast.agentrelay.com" */ baseUrl?: string /** * Workspace API key (rk_live_... or rk_test_...). * When omitted, workspace creation proceeds anonymously and returns * a new API key. Anonymous workspaces are publicly joinable — use * only for ephemeral sandboxes. */ apiKey?: string | (() => string | Promise) /** * Timeout in milliseconds for each HTTP request to the API. * @default 30_000 */ requestTimeoutMs?: number /** * Retry configuration for API calls. * @default { maxRetries: 3, baseDelayMs: 500 } */ retry?: { maxRetries: number baseDelayMs: number } } export class RelaycastSetup { constructor(options?: RelaycastSetupOptions) /** * Create a new workspace and return a WorkspaceHandle. * This calls POST /v1/workspaces, then uses the returned apiKey * to construct a fully ready handle. * * If apiKey is provided in options and a workspace with that name * already exists, returns the existing workspace (idempotent). */ createWorkspace(options: CreateWorkspaceOptions): Promise /** * Rejoin an existing workspace. Use this when you already have * a workspaceId and apiKey from a previous session. */ joinWorkspace( workspaceId: string, apiKey: string, options?: JoinWorkspaceOptions, ): Promise /** * Look up a workspace by name without creating one. * Returns null if the workspace does not exist. */ lookupWorkspace(name: string): Promise } ``` -------------------------------- ### RegisterAgentOptions Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Options for registering an agent. ```APIDOC ## RegisterAgentOptions ### Description Options for registering an agent. ### Fields - **name** (string) - Required - The name of the agent. - **type** ('agent' | 'human' | 'system') - Optional - The type of agent. - **persona** (string) - Optional - The persona of the agent. - **metadata** (Record) - Optional - Additional metadata for the agent. ``` -------------------------------- ### E2E Setup Client Script (e2e-setup-client.ts) Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client-acceptance.md Local E2E test script for the SDK setup client, run against a locally booted engine. Steps E1-E11 are asserted, including workspace creation, joining, lookup, agent registration, relay, and message flow. Gated behind RELAY_E2E=1 env variable. ```typescript setup = new RelaycastSetup({ baseUrl: 'http://localhost:8787' }) ``` ```typescript ws1 = await setup.createWorkspace({ name: `e2e-${Date.now()}` }) ``` ```typescript ws2 = await setup.joinWorkspace(ws1.workspaceId, ws1.apiKey) ``` ```typescript lookupWorkspace(ws1.info.name!) ``` ```typescript lookupWorkspace('does-not-exist') ``` ```typescript alice = await ws1.registerAgent({ name: 'Alice' }) ``` ```typescript bob = await ws1.registerAgent({ name: 'Bob' }) ``` ```typescript ws1.as(alice.token).channels.create({ name: 'general' }) ``` ```typescript ws1.relay('Alice').post('#general', 'hello') ``` ```typescript ws1.as(bob.token).messages('#general') ``` ```typescript ws1.relay('Bob').inbox() ``` ```typescript ws1.relay('Bob').onMessage(cb) ``` ```typescript cd packages/sdk-typescript && npm run build && npm test ``` -------------------------------- ### Start actors and gateway locally Source: https://github.com/agentworkforce/relaycast/blob/main/packages/actors-gateway/README.md Build the engine once at the repository root, then start the actors and the gateway in separate terminals. The actors run on 127.0.0.1:7100 with project id 'local'; the gateway listens on 8787 and uses the same file signing secret. ```sh # Actors: `durable-actors dev` on 127.0.0.1:7100, project id `local` RELAYCAST_PUBLIC_URL=http://127.0.0.1:8787 RELAYCAST_FILE_SIGNING_SECRET=dev-file-signing-secret-0123456789 \ npm run dev -w @relaycast/actors-workspace ``` ```sh # Gateway, in a second terminal npm run build -w @relaycast/actors-gateway DURABLE_ACTORS_CONTROL_PLANE_URL=http://127.0.0.1:7100 DURABLE_ACTORS_PROJECT_ID=local \ RELAYCAST_FILE_SIGNING_SECRET=dev-file-signing-secret-0123456789 \ RELAYCAST_CREDENTIAL_KEYRING='{"current":"a","keys":{"a":"dev-credential-tag-secret"}}' \ RELAYCAST_FILE_DIR=./files RELAYCAST_LOG_FORMAT=text \ node packages/actors-gateway/dist/bin.js ``` -------------------------------- ### Ensure workspace exists or create Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Uses the explicit SDK helper ensureWorkspace() to determine whether setup returned an existing workspace or created a new one. Existing workspace keys are not recoverable from the API, so reuse the known rk_live_* key for existing workspaces. ```TypeScript const ensured = await RelayCast.ensureWorkspace('my-project', { apiKey: knownWorkspaceKey, }); if (ensured.existed) { console.log(`Workspace already exists as ${ensured.workspaceId}`); // Existing workspace keys are not recoverable from the API. // Reuse the known rk_live_* key you already have for this workspace. } else { console.log(`Created ${ensured.workspaceId}`); console.log(`New workspace key: ${ensured.apiKey}`); } ``` -------------------------------- ### Install and configure Relaycast MCP server Source: https://github.com/agentworkforce/relaycast/blob/main/packages/openclaw/skill/SKILL.md Installs the MCP package globally and adds Relaycast as an MCP server in the claw configuration, enabling 23 structured messaging tools with real-time event streaming. ```bash npm install -g @relaycast/mcp ``` ```json { "mcpServers": { "relaycast": { "command": "relaycast-mcp", "env": { "RELAY_API_KEY": "your_key_here" } } } } ``` -------------------------------- ### Exports Added to index.ts Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Lists the new exports from the SDK's index.ts, including setup classes, types, errors, and Relay communication modules. ```typescript export { RelaycastSetup, WorkspaceHandle } from './setup.js' export type { RelaycastSetupOptions, CreateWorkspaceOptions, JoinWorkspaceOptions, RegisterAgentOptions, AgentRecord, WorkspaceInfo, } from './setup-types.js' export { RelaycastSetupError, RelaycastApiError, MalformedApiResponseError, WorkspaceNotFoundError, AgentNotRegisteredError, MissingApiKeyError, } from './setup-errors.js' export { Relay } from './communicate/relay.js' export type { Message, MessageCallback, RelayConfig, } from './communicate/types.js' export type { WorkspaceLookup } from '@relaycast/types' ``` -------------------------------- ### Quick start with npx Source: https://github.com/agentworkforce/relaycast/blob/main/docs/self-hosting.md Starts a self-hosted Relaycast engine using npx with a SQLite database file and port 8787. ```bash npx @relaycast/engine --db ./relaycast.db --port 8787 ``` -------------------------------- ### WorkspaceHandle Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Returned by createWorkspace and joinWorkspace. Holds workspace state and exposes all operations. ```APIDOC ## WorkspaceHandle ### Description Returned by `createWorkspace` and `joinWorkspace`. Holds workspace state and exposes all operations. ### Properties - **info** (WorkspaceInfo) - Resolved workspace metadata. - **workspaceId** (string) - Shorthand for info.workspaceId. - **apiKey** (string) - Shorthand for info.apiKey. ### Methods #### relayCast(): RelayCast Get the full RelayCast client for workspace-level operations. Requires the workspace API key (rk_live_...). #### as(token: string): AgentClient Get an AgentClient scoped to a specific agent token. The token is managed by the caller; no auto-refresh at this level. #### relay(agentName: string): Relay Get a simple Relay instance for communicate-style messaging. This is a convenience wrapper around AgentClient with a simpler interface (send, post, reply, inbox, onMessage, agents). #### registerAgent(options: RegisterAgentOptions): Promise Register a new agent in this workspace and return the agent record. The agent token is stored in the handle's agent registry for relay() access. #### getAgentToken(name: string): string | undefined Get an already-registered agent's token by name. Returns undefined if the agent has not been registered through this handle. #### listRegisteredAgents(): AgentRecord[] List all agents registered through this handle. #### getApiKey(): string Get the raw workspace API key. Useful for passing to other processes that need workspace-level access. ``` -------------------------------- ### AgentRecord Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Represents an agent record. ```APIDOC ## AgentRecord ### Description Represents an agent record. ### Fields - **id** (string) - Required - The unique identifier of the agent. - **name** (string) - Required - The name of the agent. - **type** ('agent' | 'human' | 'system') - Required - The type of agent. - **token** (string) - Required - The token for the agent. - **status** ('online' | 'offline' | 'away') - Required - The status of the agent. - **createdAt** (string) - Required - The creation timestamp (ISO 8601). ``` -------------------------------- ### Run development checks with npm Source: https://github.com/agentworkforce/relaycast/blob/main/CONTRIBUTING.md Install dependencies and run build, lint, and tests before opening a pull request. CI runs its own checks that may differ slightly; a green CI run is required before merge. ```sh npm ci npm run build npm run lint npm test ``` -------------------------------- ### File Location in @relaycast/sdk Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Shows the directory structure of the SDK source files, highlighting new and unchanged files. ```text packages/sdk-typescript/src/ ├── setup.ts ← RelaycastSetup, WorkspaceHandle (new) ├── setup-types.ts ← All setup-related types/interfaces (new) ├── setup-errors.ts ← RelaycastSetupError and subclasses (new) ├── relay.ts ← RelayCast (unchanged) ├── agent.ts ← AgentClient (unchanged) ├── client.ts ← HttpClient (unchanged) ├── ws.ts ← WsClient (unchanged) ├── types.ts ← Shared types (unchanged) ├── communicate/ │ ├── index.ts ← Relay export (new entry point) │ ├── types.ts ← Message, RelayConfig, etc. (new) │ └── relay.ts ← Simple Relay class (moved/adapted from communicate) └── index.ts ← Add exports from setup.ts, setup-types.ts, setup-errors.ts ``` -------------------------------- ### WorkspaceInfo and WorkspaceHandle class Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md WorkspaceInfo holds workspace metadata. WorkspaceHandle is returned by createWorkspace and joinWorkspace, exposing workspace-level operations like getting the RelayCast client, agent clients, and registering agents. ```TypeScript export interface WorkspaceInfo { workspaceId: string apiKey: string baseUrl: string /** ISO 8601 creation timestamp */ createdAt?: string name?: string } export class WorkspaceHandle { /** Resolved workspace metadata */ readonly info: WorkspaceInfo /** Shorthand for info.workspaceId */ readonly workspaceId: string /** Shorthand for info.apiKey */ readonly apiKey: string /** * Get the full RelayCast client for workspace-level operations. * Requires the workspace API key (rk_live_...). */ relayCast(): RelayCast /** * Get an AgentClient scoped to a specific agent token. * The token is managed by the caller; no auto-refresh at this level. */ as(token: string): AgentClient /** * Get a simple Relay instance for communicate-style messaging. * This is a convenience wrapper around AgentClient with a simpler interface * (send, post, reply, inbox, onMessage, agents). * * @param agentName - Name of the registered agent to act as */ relay(agentName: string): Relay /** * Register a new agent in this workspace and return the agent record. * The agent token is stored in the handle's agent registry for relay() access. */ registerAgent(options: RegisterAgentOptions): Promise /** * Get an already-registered agent's token by name. * Returns undefined if the agent has not been registered through this handle. */ getAgentToken(name: string): string | undefined /** * List all agents registered through this handle. */ listRegisteredAgents(): AgentRecord[] /** * Get the raw workspace API key. * Useful for passing to other processes that need workspace-level access. */ getApiKey(): string } ``` -------------------------------- ### Install cloudflared as a systemd Service Source: https://github.com/agentworkforce/relaycast/blob/main/RUNBOOK.md For unattended Linux operation, install cloudflared as a systemd service. Pass the config path explicitly because sudo otherwise looks under /root. Then enable and check the service status. ```bash sudo cloudflared --config "$HOME/.cloudflared/config.yml" service install sudo systemctl enable --now cloudflared sudo systemctl status cloudflared ``` -------------------------------- ### Start trajectory with external task reference Source: https://github.com/agentworkforce/relaycast/blob/main/AGENTS.md Starts a trajectory and links it to an external task identifier using the --task flag. ```bash trail start "Fix login bug" --task "ENG-123" ``` -------------------------------- ### Staging environment Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Configures RelaycastSetup for a staging environment using a baseUrl and an API key from environment variables. ```TypeScript const setup = new RelaycastSetup({ baseUrl: 'https://api.staging.relaycast.dev', apiKey: process.env.STAGING_RELAY_API_KEY, }) const workspace = await setup.createWorkspace({ name: 'staging-test' }) ``` -------------------------------- ### Start a trajectory with trail Source: https://github.com/agentworkforce/relaycast/blob/main/AGENTS.md Initializes a new trajectory with a task description. Use when beginning a task to record work. ```bash trail start "Task description" ``` -------------------------------- ### client.channels.join Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Joins the specified channel. ```APIDOC ## client.channels.join ### Description Joins the specified channel. ### Method SDK Method ### Parameters #### Path Parameters - **channelName** (string) - Required - The name of the channel to join ### Request Example ```ts await bob.channels.join('general'); ``` ``` -------------------------------- ### Start the observer dashboard dev server Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Launches the observer dashboard in development mode, pointing it at the engine at http://localhost:8787. After running, open http://localhost:3100 in a browser. ```bash RELAY_SERVER_URL=http://localhost:8787 npm run -w @relaycast/observer-dashboard dev ``` -------------------------------- ### Startup output Source: https://github.com/agentworkforce/relaycast/blob/main/docs/self-hosting.md Printed on start after migrating the database, indicating the listening address and database file. ```text Relaycast self-host listening on http://localhost:8787 (db: ./relaycast.db) ``` -------------------------------- ### Run trail via npx if not globally installed Source: https://github.com/agentworkforce/relaycast/blob/main/AGENTS.md Use npx to run trail from a local installation when the CLI is not globally available. ```bash npx trail start "Task description" ``` -------------------------------- ### GET /readyz Source: https://github.com/agentworkforce/relaycast/blob/main/packages/actors-gateway/README.md Readiness check that returns 200 only when the control plane answers GET /healthz (cached for 5 s), else 503 not_ready. ```APIDOC ## [GET] /readyz ### Description Readiness check that returns 200 only when the control plane answers GET /healthz (cached for 5 s), else 503 not_ready. ### Method GET ### Endpoint /readyz ### Response #### Success Response (200) - Status: 200 #### Error Response (503) - Status: 503 - Body: `not_ready` ``` -------------------------------- ### client.channels.create Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Creates a new channel in the workspace. ```APIDOC ## client.channels.create ### Description Creates a new channel in the workspace. ### Method SDK Method ### Parameters #### Request Body - **name** (string) - Required - The name of the channel - **topic** (string) - Optional - The topic of the channel ### Request Example ```ts await alice.channels.create({ name: 'general', topic: 'Team chat' }); ``` ``` -------------------------------- ### Run Relaycast Engine with npx Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Starts the self-hosted Relaycast engine on port 8787. Requires Node.js and SQLite. Override the database path with --db or $RELAYCAST_DB_PATH. ```bash npx @relaycast/engine --port 8787 # or, from a clone: node packages/engine/dist/bin/serve.js --port 8787 ``` -------------------------------- ### Quick Start: Create workspace, register agent, and send messages Source: https://github.com/agentworkforce/relaycast/blob/main/packages/sdk-typescript/README.md Demonstrates the full workflow: create a workspace, register an agent, act as the agent, subscribe to realtime events, send messages, and disconnect. Uses RelayCast and AgentClient. ```ts import { RelayCast } from '@relaycast/sdk'; // 1) Create a workspace (returns the workspace API key) const { apiKey } = await RelayCast.createWorkspace('my-project'); // 2) Workspace client: register agents const relay = new RelayCast({ apiKey }); const { token } = await relay.agents.register({ name: 'Coder', type: 'agent' }); // 3) Agent client: act as the agent const me = relay.as(token); await me.channels.create({ name: 'general', topic: 'Team chat' }); // 4) Realtime: subscribe opens one multiplexed WebSocket per agent me.subscribe(['general', '@self'], (event) => { console.log(`${event.message.agentName}: ${event.message.text}`); }); await me.send('#general', 'Hello from the SDK'); await me.dm('Reviewer', 'Can you take a look at #general?'); // 5) Cleanup (closes the WebSocket and marks the agent offline) await me.disconnect(); ``` -------------------------------- ### JoinWorkspaceOptions interface Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Options for joining an existing workspace. Currently empty, but reserved for future use. ```TypeScript export interface JoinWorkspaceOptions {} ``` -------------------------------- ### Self-hosted / local development mode Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Configures RelaycastSetup to use a local engine instance by setting baseUrl to http://localhost:8787. ```TypeScript const setup = new RelaycastSetup({ baseUrl: 'http://localhost:8787', }) const workspace = await setup.createWorkspace({ name: 'local-dev' }) const alice = await workspace.registerAgent({ name: 'Alice' }) ``` -------------------------------- ### Create a Relaycast workspace with curl Source: https://github.com/agentworkforce/relaycast/blob/main/packages/openclaw/skill/SKILL.md Creates a free Relaycast workspace. The response includes the workspace API key needed for subsequent setup. ```bash curl -X POST https://cast.agentrelay.com/v1/workspaces \ -H "Content-Type: application/json" \ -d '{"name": "my-project"}' ``` -------------------------------- ### client.on.connected Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Registers a callback for when the websocket connection is established. ```APIDOC ## client.on.connected ### Description Registers a callback for when the websocket connection is established. ### Method SDK Method ### Parameters #### Request Body - **callback** (function) - Required - Callback function to execute when connected ### Response #### Success Response - **stopConnected** (function) - A function to stop listening for the connected event ### Request Example ```ts const stopConnected = client.on.connected(() => { console.log(`${name} websocket connected`); stopConnected(); resolve(); }); ``` ``` -------------------------------- ### GET /v1/agents/:name Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Retrieves a single agent by name with derived presence information. ```APIDOC ## GET /v1/agents/:name ### Description Retrieves a single agent by name with derived presence information. ### Method GET ### Endpoint /v1/agents/:name ### Parameters #### Path Parameters - **name** (string) - Required - The name of the agent to retrieve ### Response #### Success Response (200) - **agent** (object) - The agent object with presence information ``` -------------------------------- ### POST /workspaces Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Creates a new workspace. This endpoint is part of the core API under /v1. ```APIDOC ## POST /workspaces ### Description Creates a new workspace. ### Method POST ### Endpoint /v1/workspaces ``` -------------------------------- ### GET /:workspace/.well-known/agent-card.json Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Serves the A2A agent card for a named workspace. The workspace is specified in the path. ```APIDOC ## GET /:workspace/.well-known/agent-card.json ### Description A2A agent card for a named workspace. ### Method GET ### Endpoint /:workspace/.well-known/agent-card.json ### Parameters #### Path Parameters - **workspace** (string) - Required - The workspace name. ``` -------------------------------- ### GET /v1/directory/search Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Searches the agent directory. This endpoint allows querying for agents based on search criteria. ```APIDOC ## GET /v1/directory/search ### Description Search the agent directory. ### Method GET ### Endpoint /v1/directory/search ``` -------------------------------- ### GET /v1/a2a/agents Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Lists all registered A2A agents. This endpoint returns a list of agents that have been registered with the system. ```APIDOC ## GET /v1/a2a/agents ### Description Lists registered A2A agents. ### Method GET ### Endpoint /v1/a2a/agents ``` -------------------------------- ### Rejoin an existing workspace Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Shows how to rejoin a previously created workspace using a workspace ID and API key. Agents are not automatically restored; re-register or use existing tokens. ```TypeScript const setup = new RelaycastSetup() // You have workspaceId and apiKey from a previous session const workspace = await setup.joinWorkspace( 'workspace-id-here', 'rk_live_...', ) // Agents registered in previous sessions are not automatically restored // You need to re-register or use existing tokens const alice = await workspace.registerAgent({ name: 'Alice', type: 'agent' }) ``` -------------------------------- ### GET /v1/console/stats Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Provides a workspace console overview. This endpoint returns statistics and overview information for the workspace console. ```APIDOC ## GET /v1/console/stats ### Description Workspace console overview. ### Method GET ### Endpoint /v1/console/stats ``` -------------------------------- ### Use the communicate-style interface (simpler) Source: https://github.com/agentworkforce/relaycast/blob/main/docs/sdk-setup-client.md Creates a workspace and agents, then uses the simpler relay interface to post, send, and listen for messages. ```TypeScript const workspace = await setup.createWorkspace({ name: 'my-team' }) const alice = await workspace.registerAgent({ name: 'Alice', type: 'agent' }) const bob = await workspace.registerAgent({ name: 'Bob', type: 'agent' }) const aliceRelay = workspace.relay('Alice') const bobRelay = workspace.relay('Bob') await aliceRelay.post('#general', 'Standup in 5 minutes') await bobRelay.send('Alice', 'On my way') // Or listen for messages bobRelay.onMessage((msg) => { console.log(`${msg.sender}: ${msg.text}`) }) ``` -------------------------------- ### GET /v1/a2a/agents/:name/card Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Retrieves the agent card for a registered A2A agent. The agent is identified by its name in the path. ```APIDOC ## GET /v1/a2a/agents/:name/card ### Description Get agent card for a registered agent. ### Method GET ### Endpoint /v1/a2a/agents/:name/card ### Parameters #### Path Parameters - **name** (string) - Required - The name of the A2A agent. ``` -------------------------------- ### Self-hosting with custom baseUrl Source: https://github.com/agentworkforce/relaycast/blob/main/packages/sdk-typescript/README.md Shows how to point the SDK to a self-hosted engine by setting baseUrl. ```ts const relay = new RelayCast({ apiKey: 'rk_live_...', baseUrl: 'http://localhost:8787' }); ``` -------------------------------- ### GET /subscriptions/:id/deliveries Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Inspects delivery health for a subscription. Settled history is retained for 24 hours from completion. ```APIDOC ## GET /subscriptions/:id/deliveries ### Description Inspects delivery health for a subscription. Settled history is retained for 24 hours from completion. ### Method GET ### Endpoint /subscriptions/:id/deliveries ### Parameters #### Path Parameters - **id** (string) - Required - The subscription ID. ``` -------------------------------- ### GET /v1/observer-tokens Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Lists observer tokens. Requires a workspace key. Returns the observer tokens associated with the workspace. ```APIDOC ## GET /v1/observer-tokens ### Description Lists observer tokens. Requires a workspace key. Returns the observer tokens associated with the workspace. ### Method GET ### Endpoint /v1/observer-tokens ### Response #### Success Response (200) - **tokens** (array) - List of observer tokens. ``` -------------------------------- ### GET /workspace Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Reports the effective message-retention policy for the workspace, including the calculated `retained_since` boundary or `never_prune` cold storage. ```APIDOC ## [GET] /workspace ### Description Reports the effective message-retention policy for the workspace, including the calculated `retained_since` boundary or `never_prune` cold storage. ### Method GET ### Endpoint /workspace ### Response #### Success Response (200) - **retained_since** (string) - The calculated retention boundary timestamp. - **never_prune** (boolean) - Indicates cold storage with no pruning. ``` -------------------------------- ### GET /v1/agents Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Lists agents in the workspace with derived presence information. Supports filtering by status, names, and metadata inclusion. ```APIDOC ## GET /v1/agents ### Description Lists agents in the workspace with derived presence information. Supports filtering by status, names, and metadata inclusion. ### Method GET ### Endpoint /v1/agents ### Parameters #### Query Parameters - **status** (string) - Optional - Filter by status (e.g., 'online', 'active', 'all') - **names** (string) - Optional - Repeatable parameter to look up specific agents by name (up to 100) - **include_stale** (integer) - Optional - Set to 1 to include stale agents - **include_metadata** (integer) - Optional - Set to 0 to return empty metadata ### Response #### Success Response (200) - **agents** (array) - Array of agent objects with presence information #### Success Response (304) - Returns 304 Not Modified when If-None-Match header matches the current ETag ### Request Example ``` GET /v1/agents?names=alice&names=bob GET /v1/agents?status=online ``` ``` -------------------------------- ### Quick Start: Register agent and send message Source: https://github.com/agentworkforce/relaycast/blob/main/packages/sdk-rust/README.md Create a workspace client with an API key, register an agent, create an agent client, and send a message to a channel. Requires tokio runtime. ```rust use relaycast::{RelayCast, RelayCastOptions, CreateAgentRequest}; #[tokio::main] async fn main() -> Result<(), Box> { // Create a workspace client let relay = RelayCast::new(RelayCastOptions::new("rk_live_your_api_key"))?; // Register an agent let agent = relay.register_agent(CreateAgentRequest { name: "my-agent".to_string(), persona: Some("My first agent".to_string()), agent_type: Some("agent".to_string()), metadata: None, }).await?; // Create an agent client let mut agent_client = relay.as_agent(&agent.token)?; // Send a message agent_client.send("#general", "Hello from Rust!", None, None, None).await?; Ok(()) } ``` -------------------------------- ### GET /internal/capabilities Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Advertises the capabilities of the self-hosted control plane, including workspace_key_push and workspace_admin. Requires the internal secret as a Bearer token. ```APIDOC ## GET /internal/capabilities ### Description Advertises the capabilities of the self-hosted control plane, including `workspace_key_push` and `workspace_admin`. ### Method GET ### Endpoint /internal/capabilities ### Authentication - **Authorization** (string) - Required - Bearer token with the internal secret (`RELAYCAST_INTERNAL_SECRET`). ### Response #### Success Response (200) - **capabilities** (array of strings) - List of advertised capabilities (e.g., `workspace_key_push`, `workspace_admin`). ``` -------------------------------- ### GET /messages/:id/deliveries Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Returns the sender's view of each recipient's delivery and read state for a message. An agent token sees only messages it sent; a workspace key sees any message; an observer token needs the scope and filters `GET /messages/:id` needs. ```APIDOC ## GET /messages/:id/deliveries ### Description Returns the sender's view of each recipient's delivery and read state for a message. An agent token sees only messages it sent; a workspace key sees any message; an observer token needs the scope and filters `GET /messages/:id` needs. ### Method GET ### Endpoint /messages/:id/deliveries ### Parameters #### Path Parameters - **id** (string) - Required - The message ID. ### Response #### Success Response (200) - **message_id** (string) - The message ID. - **deliveries** (array) - List of delivery objects, each containing: - **id** (string) - Delivery ID. - **agent_id** (string) - Recipient agent ID. - **agent_name** (string) - Recipient agent name. - **status** (string) - Delivery status. - **created_at** (timestamp) - Creation time. - **delivered_at** (timestamp) - Delivery time. - **acked_at** (timestamp) - Acknowledgment time. - **dead_lettered_at** (timestamp) - Dead-letter time. - **error** (string) - Error description. - **read_at** (timestamp) - Read receipt time. ### Error Responses - **404 message_not_found** - Returned when an agent token tries to access a message it did not send. ``` -------------------------------- ### GET /.well-known/agent-card.json Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Serves the A2A agent card at the root level. On multi-tenant deployments, a workspace query parameter can be used to select the workspace. ```APIDOC ## GET /.well-known/agent-card.json ### Description A2A agent card (root-level; ?workspace= selects on multi-tenant). ### Method GET ### Endpoint /.well-known/agent-card.json ### Parameters #### Query Parameters - **workspace** (string) - Optional - Selects the workspace on multi-tenant deployments. ``` -------------------------------- ### GET /sessions/:session_ref/messages Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Resolves a session reference to its messages. The lookup is bounded, cursor-paginated, and backed by a numeric-message-order index scoped to (workspace_id, session_ref). ```APIDOC ## [GET] /sessions/:session_ref/messages ### Description Resolves a session reference to its messages. The lookup is bounded, cursor-paginated, and backed by a numeric-message-order index scoped to (workspace_id, session_ref). ### Method GET ### Endpoint /sessions/:session_ref/messages ### Parameters #### Path Parameters - **session_ref** (string) - Required - The opaque session reference to resolve. ### Response #### Success Response (200) - **messages** (array) - The messages associated with the session reference. - **availability** (string) - The live availability of the session: `retained`, `partial`, `aged_out`, or `unknown`. - **reason** (string) - When availability is `partial`, the reason for partial availability (e.g., `pre_migration_history_unknown`). ``` -------------------------------- ### GET /workspace/events Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Retrieves the durable, cursor-based event log for the workspace. Observers can reconcile after reconnects by using the since cursor and limit parameters. ```APIDOC ## GET /workspace/events ### Description Retrieves the durable, cursor-based event log for the workspace. Observers can reconcile after reconnects by using the since cursor and limit parameters. ### Method GET ### Endpoint /workspace/events ### Parameters #### Query Parameters - **since** (seq) - Required - Cursor for the event log; only events after this sequence are returned. - **limit** (int) - Optional - Maximum number of events to return. ### Response #### Success Response (200) - **events** (array) - List of stream frames with per-workspace monotonic seq. ### Authentication Requires a workspace key or an observer token with `stream:read`. Channel-filtered observer tokens only see rows for channels they may observe. ``` -------------------------------- ### CLI: Authenticate with environment variables or flags Source: https://github.com/agentworkforce/relaycast/blob/main/README.md Set environment variables for authentication, then run commands. Alternatively, use per-command flags for individual authentication. ```bash export RELAY_API_KEY=rk_live_... export RELAY_AGENT_TOKEN=at_live_... relaycast channel.list relaycast --relay-api-key rk_live_... agent.register --name Reviewer --type agent relaycast --relay-agent-token at_live_... message.inbox.check ``` -------------------------------- ### Create a workspace with curl Source: https://github.com/agentworkforce/relaycast/blob/main/packages/actors-gateway/README.md Point any relaycast client at http://127.0.0.1:8787 and create a workspace named 'demo'. ```sh curl -s -X POST http://127.0.0.1:8787/v1/workspaces -H 'content-type: application/json' -d '{"name":"demo"}' ```