Quickstart: Get two agents talking in minutes

Set up AgentRelay for your team — deploy the relay with Docker, register each developer, and send your first cross-machine agent handoff.

AgentRelay has two roles: the team lead deploys a single relay once, and each teammate connects to it. This guide walks through both paths and ends with a live handoff round-trip to confirm everything is wired.

Prerequisites

• Node 20+ on every developer’s machine (check with node --version)
• Docker on the machine that will host the relay
• Claude Code or Codex CLI on every developer’s machine

Team lead

You run the relay once for the whole team. Your teammates will connect to the URL you expose.

1. Clone and configure

   Clone the repository and copy the example environment file:

   git clone https://github.com/swayamg20/AgentRelay
   cd AgentRelay
   cp .env.example .env
   

   Before exposing the relay publicly, rotate the generated secrets in .env:

   sed -i '' "s|^RELAY_PEPPER=.*|RELAY_PEPPER=$(openssl rand -hex 32)|" .env
   sed -i '' "s|^RELAY_ADMIN_TOKEN=.*|RELAY_ADMIN_TOKEN=$(openssl rand -hex 16)|" .env
   sed -i '' "s|^RELAY_ENCRYPTION_KEY=.*|RELAY_ENCRYPTION_KEY=$(openssl rand -hex 32)|" .env
   
2. Start the relay

   Bring up Postgres and the relay together. Migrations run automatically on boot.

   docker compose --profile selfhost up -d
   

   Verify the relay is healthy:

   curl http://localhost:8080/healthz
   # → {"status":"ok"}
   
3. Expose to the internet

   Teammates on other laptops need a public URL. Point a reverse proxy (nginx, Caddy, or Cloudflare Tunnel) at port 8080, then set RELAY_PUBLIC_URL in .env to the public URL and restart:

   docker compose --profile selfhost up -d
   

   For testing, an SSH tunnel or cloudflared tunnel --url http://localhost:8080 works.

4. Share the admin token

   RELAY_ADMIN_TOKEN from your .env is what each teammate needs to register. Store it in your team vault (1Password, Vault, etc.) and share it over a secure channel — not a public Slack channel.

5. Register yourself

   You’re a teammate too. Follow the Teammate tab to connect your own machine to the relay you just deployed.

Teammate

Your team lead has already deployed a relay and shared the relay URL and admin token with you. The steps below get your coding agent connected.

1. Register your identity

   Run the agentrelay CLI to create your identity on the relay. The admin token comes from your team lead.

   npx -y -p agentrelay-mcp agentrelay register \
     --relay https://your-team-relay.example.com \
     --admin-token <token-from-team-lead> \
     --handle yourname@team \
     --email [e-mail] \
     --name "Your Name" \
     --role backend
   

   This writes your credentials to ~/.agentrelay/config.json. Verify it was written:

   cat ~/.agentrelay/config.json
   
2. Wire AgentRelay into Claude Code

   Add the MCP server at user scope so it works in every directory:

   claude mcp add agentrelay --scope user -- npx -y agentrelay-mcp
   claude mcp list   # should show 'agentrelay'
   

   In v0.1.x, agentrelay install writes the MCP entry to the wrong file (#1). Use claude mcp add directly as shown above. The permission overlay part of install still works correctly — run it in the next step.

3. Install the permission overlay

   Write the recommended allow/ask/deny rules to your Claude Code or Codex settings. This is the Layer 2 trust enforcement — reads auto-approve, writes require your confirmation, and destructive commands like git push and npm publish are denied entirely.

   npx -y -p agentrelay-mcp agentrelay install --client all
   
4. Verify your setup

   Run doctor to confirm every component is wired:

   npx -y -p agentrelay-mcp agentrelay doctor
   

   You want all lines to show OK:

   config:           OK
   relay reachable:  OK
   api key valid:    OK
   mcp[claude-code]: OK
   trust.yaml:       OK
   

   If any line shows MISSING, see the developer onboarding guide for troubleshooting steps.

5. Restart Claude Code

   Quit Claude Code and reopen it. Run /mcp — agentrelay should appear in the list of active MCP servers.

Send your first handoff

Once both sides are set up, verify the full round-trip.

1. Send a handoff (sender)

   In Claude Code, ask your agent to send a test handoff:

   “Use agentrelay to send a handoff to teammate@team. Intent: ask_question. Summary: ‘Cross-machine setup test’. Body: ‘If you can read this with the inbound preamble wrapper, the trust model is working end-to-end. Reply with accept_handoff then send_message to confirm.’”

   Your agent calls the handoff_to_teammate MCP tool and returns a thread_id. If the recipient has a Slack webhook configured, they receive a DM.

2. Check the inbox (receiver)

   On the receiving machine, ask Claude Code:

   “Check my agentrelay inbox.”

   The handoff appears wrapped with the Layer 1 provenance preamble:

   [INBOUND HANDOFF FROM sender@team via AgentRelay]
   <message body>
   [END OF HANDOFF]
   

   That wrapper tells the receiving agent to treat the content as data, not instructions — it’s the load-bearing security primitive in AgentRelay’s trust model.

3. Accept and reply (receiver)

   Ask the receiving agent:

   “Accept the handoff and send a message back saying confirmed.”

   When the reply arrives in the sender’s inbox (also preamble-wrapped), the round-trip is complete and both agents are talking.

Next steps

How it works

Understand the relay, MCP server, and A2A protocol under the hood

Trust configuration

Configure per-teammate trust levels in ~/.agentrelay/trust.yaml

MCP tools

Explore all seven tools your agent uses to send and receive handoffs

CLI reference

Full reference for register, doctor, block, audit, and more