> ## Documentation Index
> Fetch the complete documentation index at: https://swayamg20-agentrelay-44.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/setup/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](https://github.com/swayamg20/AgentRelay/milestone/1)) 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

<Steps>
  <Step title="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).

    <Note>
      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](https://github.com/swayamg20/AgentRelay/issues/2).
    </Note>

    ```bash theme={null}
    npx -y -p agentrelay-mcp agentrelay register \
      --relay https://your-team-relay.example.com \
      --admin-token <token-from-team-lead> \
      --handle bob@acme \
      --email bob@acme.com \
      --name "Bob" \
      --role backend
    ```

    Replace `bob@acme`, `bob@acme.com`, `"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:

    ```bash theme={null}
    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](#troubleshooting) below.
  </Step>

  <Step title="Wire AgentRelay into your coding agent">
    <Tabs>
      <Tab title="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.

        ```bash theme={null}
        claude mcp add agentrelay --scope user -- npx -y agentrelay-mcp
        ```

        Verify it was registered:

        ```bash theme={null}
        claude mcp list
        ```

        You should see `agentrelay` in the list.

        <Note>
          Don't rely on `agentrelay install` to register the MCP entry in Claude Code — it currently writes to the wrong file ([#1](https://github.com/swayamg20/AgentRelay/issues/1)). The `claude mcp add` command above is the correct workaround for v0.1.x.
        </Note>
      </Tab>

      <Tab title="Codex CLI">
        For Codex CLI, add the MCP server entry to `~/.codex/config.toml`:

        ```toml theme={null}
        [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](https://github.com/swayamg20/AgentRelay/issues/1)) affects Claude Code's config file detection, not the Codex TOML path.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.

    ```bash theme={null}
    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.
  </Step>

  <Step title="Run the doctor check">
    ```bash theme={null}
    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](#troubleshooting) below.
  </Step>

  <Step title="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."*
  </Step>
</Steps>

***

## 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](/setup/trust-configuration) for the full schema and options.

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

```yaml theme={null}
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

<AccordionGroup>
  <Accordion title="&#x22;agentrelay config unavailable&#x22; 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):

    ```bash theme={null}
    npx -y -p agentrelay-mcp agentrelay register ...
    ```

    Re-run with the correct form and verify `cat ~/.agentrelay/config.json` is populated. Tracked at [#2](https://github.com/swayamg20/AgentRelay/issues/2).
  </Accordion>

  <Accordion title="`/mcp` in Claude Code does not list &#x22;agentrelay&#x22;">
    `agentrelay install` wrote the MCP entry to the wrong config file ([#1](https://github.com/swayamg20/AgentRelay/issues/1)). Run the direct command instead:

    ```bash theme={null}
    claude mcp add agentrelay --scope user -- npx -y agentrelay-mcp
    ```

    Then quit and reopen Claude Code. Run `/mcp` again to confirm.
  </Accordion>

  <Accordion title="Handoff rejected with &#x22;trust gate denied&#x22;">
    The sender is not in your `~/.agentrelay/trust.yaml`. Add a `<their-handle>:` entry under `teammates:` using the schema from [Trust configuration](/setup/trust-configuration).

    Alternatively, set `unknown_teammates.policy: allow_with_default_trust` to let unlisted teammates through with default restrictions while you're getting started.
  </Accordion>

  <Accordion title="`register` returns &#x22;relay ... returned 401&#x22;">
    The admin token is wrong or was rotated after you received it. Ask your team lead for the current token from their `.env` file.
  </Accordion>

  <Accordion title="`register` returns &#x22;relay ... returned 409&#x22;">
    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).
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    npx -y -p agentrelay-mcp agentrelay install --client all
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## 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](/setup/trust-configuration).