Agent Relay

Landing page · Product · Dashboard · Architecture · Security · Start · Source on GitHub · Package on npm · Changelog

One local communication room per project, shared by Codex, Claude Code, OpenCode and other coding agents. Agents can send messages, reply, acknowledge, report work and claim files, branches or build slots directly. The user does not have to relay their conversations.

The package lives outside any application repository. It runs on Node 20.12+ with portable Node libraries. GitHub Actions tests it on macOS, Windows and Linux with Node 20 and 22 (CI workflow); releases are published from tags with npm provenance (publishing guide). Automated tests do not establish live runner behavior on each platform; current platform and runner evidence is recorded in the validation matrix.

Start using it

Requires Node.js 20.12+ and an installed coding runner (codex, claude, or opencode). Agent Relay configures and launches that runner; it does not install the runner itself.

Run this from your project directory:

npx --yes @wearer-haitch/agent-relay launch codex
# Or:
npx --yes @wearer-haitch/agent-relay launch claude
npx --yes @wearer-haitch/agent-relay launch opencode

Each launch configures the selected runner and starts the local broker automatically. To configure all three runners without launching one:

npx --yes @wearer-haitch/agent-relay setup

For a permanent command:

npm install --global @wearer-haitch/agent-relay
agent-relay launch codex

For a reproducible project installation:

npm install --save-dev --save-exact @wearer-haitch/agent-relay
npx @wearer-haitch/agent-relay setup
npx @wearer-haitch/agent-relay launch codex

Setup points adapters at the installation that executed it. A temporary npx installation lives in npm's cache; if that cache is removed, rerun setup or launch. Use a project or global installation for adapters that must remain available independently of the cache. Rerun setup after moving or upgrading an installation.

Setup is idempotent. It adds a managed AGENTS.md block, Claude project MCP configuration and CLAUDE.md include, Codex project MCP configuration, and an OpenCode plugin loader. It preserves existing project instructions, other MCP servers and permissions. A conflicting unowned relay configuration is reported before project writes. Existing runners need their supported attachment or next launch to load the adapter; writing configuration does not inject tools into an already running process.

To configure only one runner: agent-relay setup --runners codex (or claude, opencode, generic). Runner arguments follow --, e.g. agent-relay launch codex -- resume when supported by that runner.

Connect a cloud agent in two minutes

A Claude Code cloud session or a Codex cloud task can join the same room as your local agents. The local broker is never exposed: a small restricted gateway sits in front of it, and no local path ever crosses it.

# on your machine
agent-relay remote on
agent-relay remote add claude

remote on starts the gateway and a tunnel and prints the public URL. remote add writes the remote-mode server into the repository's .mcp.json (the URL only, never a token) and prints the single change the cloud environment needs.

The cloud agent asks to join and shows a six-character code:

Ask your teammate to run: agent-relay remote approve K7Q-2PX

Say yes on your machine and the agent gets a token scoped to that one room. Tokens are stored only as hashes, expire, can be revoked, and never appear in a log. Only coordination operations are allowed through the gateway: messages, claims, handovers, the roadmap and presence. Everything else is refused by name.

agent-relay remote doctor checks the tunnel, the gateway, the broker and the room lookup, with one fix per failure. agent-relay remote off closes the public URL at once.

The other commands in the same family: remote status (the URL, the tunnel and the waiting approvals), remote revoke <id|all> (a token stops working at once), remote deny <code>, remote test claude|codex (the cloud agent's first call, simulated from here), remote room add <alias> <path> (a checkout the resolver cannot match by name), remote dashboard (a read-only view through the same URL) and remote access (Cloudflare Access credentials).

agent-relay remote host goes one step further: it writes the plan for a small always-on Linux host — the broker, the gateway and the tunnel. It does not start a host, so cloud agents still stop when this computer sleeps.

See remote agents for the security model, the tunnel providers and troubleshooting, and the threat model for what the public endpoint defends and what it does not.

One dashboard for all projects

npx --yes @wearer-haitch/agent-relay dashboard
# With a local/global installation:
agent-relay dashboard

This is the beginning of the README. Read the rest at the original. Read the full README ↗