Per-developer setup: join your team's relay

Register your identity, wire AgentRelay into Claude Code or Codex CLI, install the permission overlay, and verify everything is working end-to-end.

Every developer on the team completes this setup once on their own laptop. You need the relay URL and admin token from your team lead before you start — if you don’t have them yet, ask your lead to complete relay deployment first.

On a good day this takes about 10 minutes. v0.1.x has some known sharp edges (tracked under v0.1.2) that the steps below work around explicitly.

Prerequisites

• Node 20 or later (node --version to check)
• Claude Code or Codex CLI installed
• Relay URL and admin token from your team lead

---

Setup

1. Register your identity with the relay

   This creates your developer profile on the relay and writes your API key to ~/.agentrelay/config.json (file mode 0600).

   Use the agentrelay CLI binary, not agentrelay-mcp. The agentrelay-mcp binary is the MCP server — it speaks stdio and silently ignores CLI arguments. If you run it instead of agentrelay, the command will appear to hang and ~/.agentrelay/config.json will remain empty. This is a known issue tracked at #2.

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

   Replace bob@acme, [e-mail], "Bob", and backend with your own values. The --handle is your team-scoped identity (used in trust configuration and handoff routing) — choose something stable like yourname@yourteam.

   Verify the config was written:

   cat ~/.agentrelay/config.json
   

   You should see a JSON object with relay_url, agent_handle, agent_id, and api_key fields. If the file is empty or missing, you likely ran the wrong binary — see Troubleshooting below.

2. Wire AgentRelay into your coding agent

   Claude Code

   Use claude mcp add directly. The --scope user flag makes the MCP entry active in every directory you open Claude Code in, not just one project.

   claude mcp add agentrelay --scope user -- npx -y agentrelay-mcp
   

   Verify it was registered:

   claude mcp list
   

   You should see agentrelay in the list.

   Don’t rely on agentrelay install to register the MCP entry in Claude Code — it currently writes to the wrong file (#1). The claude mcp add command above is the correct workaround for v0.1.x.

   Codex CLI

   For Codex CLI, add the MCP server entry to ~/.codex/config.toml:

   [mcp_servers.agentrelay]
   command = "npx"
   args = ["-y", "agentrelay-mcp"]
   

   You can also run agentrelay install for the Codex-specific config — the MCP entry issue (#1) affects Claude Code’s config file detection, not the Codex TOML path.

3. Install the permission overlay

   The permission overlay is Layer 2 of AgentRelay’s four-layer trust model. It writes allow / ask / deny rules to your coding agent’s settings file, ensuring that inbound handoffs from teammates cannot cause your agent to run destructive commands without your approval.

   npx -y -p agentrelay-mcp agentrelay install --client all
   

   This sets up the following risk-tiered defaults:

   Action class	Policy	Examples
   Read operations	allow	Read, Grep, Glob
   Sandboxed tests and lint	allow	npm test, pytest, tsc
   File writes and commits	ask	Edit, Write, git commit
   External effects	deny	git push, npm publish, aws, kubectl, curl

   Even if a poisoned handoff somehow convinced your agent to attempt a git push, the harness denies the tool call before it executes.

4. Run the doctor check

   npx -y -p agentrelay-mcp agentrelay doctor
   

   Every line should read OK:

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

   If any line shows MISSING or FAIL, see Troubleshooting below.

5. Restart your coding agent and confirm the MCP server loads

   Quit Claude Code (or Codex CLI) completely and reopen it. Then run /mcp — agentrelay should appear in the list of active MCP servers.

   Once it does, your agent has access to all AgentRelay tools: handoff_to_teammate, check_inbox, accept_handoff, send_message, complete_handoff, and list_teammates.

   Try asking your agent: “Use agentrelay to list my teammates.”

---

Configure trust

Before you can receive handoffs, you need a ~/.agentrelay/trust.yaml file. agentrelay install creates a default one, but you can also write it manually. See Trust configuration for the full schema and options.

A minimal starting point that trusts the person who invited you:

version: 1
teammates:
  inviter@team:
    auto_read: true
    auto_test: true
    auto_write_paths: []
    require_approval: ["Edit", "Write", "Bash"]
unknown_teammates:
  policy: allow_with_default_trust
defaults:
  auto_read: true
  auto_test: true
  auto_write_paths: []
  require_approval: ["Edit", "Write", "Bash"]
blocked: []

Replace inviter@team with the handle of the person who invited you. Add entries under teammates: for each additional teammate as they join.

---

Troubleshooting

"agentrelay config unavailable" log or empty config.json after register

You ran the wrong binary. agentrelay-mcp is the MCP server — it starts in stdio mode and ignores CLI arguments.

The correct command uses -p agentrelay-mcp (to install from that package) but invokes the agentrelay bin (the CLI):

npx -y -p agentrelay-mcp agentrelay register ...

Re-run with the correct form and verify cat ~/.agentrelay/config.json is populated. Tracked at #2.

`/mcp` in Claude Code does not list "agentrelay"

agentrelay install wrote the MCP entry to the wrong config file (#1). Run the direct command instead:

claude mcp add agentrelay --scope user -- npx -y agentrelay-mcp

Then quit and reopen Claude Code. Run /mcp again to confirm.

Handoff rejected with "trust gate denied"

The sender is not in your ~/.agentrelay/trust.yaml. Add a <their-handle>: entry under teammates: using the schema from Trust configuration.

Alternatively, set unknown_teammates.policy: allow_with_default_trust to let unlisted teammates through with default restrictions while you’re getting started.

`register` returns "relay ... returned 401"

The admin token is wrong or was rotated after you received it. Ask your team lead for the current token from their .env file.

`register` returns "relay ... returned 409"

Your chosen handle is already registered on this relay. Pick a different handle and re-run, or ask your team lead to remove the existing record (agentrelay block <handle> followed by re-registration).

Agent runs commands you did not expect

The Layer 2 permission overlay is missing or incomplete. Check ~/.claude/settings.json — the permissions block should have ask rules for Edit, Write, and Bash(git commit*), and deny rules for git push, npm publish, aws, kubectl, and curl.

If the block is absent, re-run:

npx -y -p agentrelay-mcp agentrelay install --client all

Slack notifications are not arriving

Slack webhooks are per-agent and are set via your relay’s admin tooling. CLI support for configuring the webhook URL is tracked separately. Check with your team lead that your Agent Card has a webhook URL set.

---

Quick reference

Task	Command
Register identity	npx -y -p agentrelay-mcp agentrelay register …
Wire MCP (Claude Code)	claude mcp add agentrelay --scope user -- npx -y agentrelay-mcp
Install permission overlay	npx -y -p agentrelay-mcp agentrelay install --client all
Verify setup	npx -y -p agentrelay-mcp agentrelay doctor
Block a teammate	npx -y -p agentrelay-mcp agentrelay block <handle>
View audit log	npx -y -p agentrelay-mcp agentrelay audit --limit 20
Rotate your API key	npx -y -p agentrelay-mcp agentrelay rotate-key

---

Next step

Configure per-teammate trust settings to control what each teammate’s handoffs are allowed to trigger on your machine — see Trust configuration.