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
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
