> ## 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.

# 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

<Tabs>
  <Tab title="Team lead">
    You run the relay once for the whole team. Your teammates will connect to the URL you expose.

    <Steps>
      <Step title="Clone and configure">
        Clone the repository and copy the example environment file:

        ```bash theme={null}
        git clone https://github.com/swayamg20/AgentRelay
        cd AgentRelay
        cp .env.example .env
        ```

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

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

      <Step title="Start the relay">
        Bring up Postgres and the relay together. Migrations run automatically on boot.

        ```bash theme={null}
        docker compose --profile selfhost up -d
        ```

        Verify the relay is healthy:

        ```bash theme={null}
        curl http://localhost:8080/healthz
        # → {"status":"ok"}
        ```
      </Step>

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

        ```bash theme={null}
        docker compose --profile selfhost up -d
        ```

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

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

      <Step title="Register yourself">
        You're a teammate too. Follow the **Teammate** tab to connect your own machine to the relay you just deployed.
      </Step>
    </Steps>
  </Tab>

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

    <Steps>
      <Step title="Register your identity">
        Run the `agentrelay` CLI to create your identity on the relay. The admin token comes from your team lead.

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

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

        ```bash theme={null}
        cat ~/.agentrelay/config.json
        ```
      </Step>

      <Step title="Wire AgentRelay into Claude Code">
        Add the MCP server at user scope so it works in every directory:

        ```bash theme={null}
        claude mcp add agentrelay --scope user -- npx -y agentrelay-mcp
        claude mcp list   # should show 'agentrelay'
        ```

        <Note>
          In v0.1.x, `agentrelay install` writes the MCP entry to the wrong file ([#1](https://github.com/swayamg20/AgentRelay/issues/1)). Use `claude mcp add` directly as shown above. The permission overlay part of `install` still works correctly — run it in the next step.
        </Note>
      </Step>

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

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

      <Step title="Verify your setup">
        Run `doctor` to confirm every component is wired:

        ```bash theme={null}
        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](/setup/developer-onboarding) for troubleshooting steps.
      </Step>

      <Step title="Restart Claude Code">
        Quit Claude Code and reopen it. Run `/mcp` — `agentrelay` should appear in the list of active MCP servers.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Send your first handoff

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

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

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

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

## Next steps

<CardGroup cols={2}>
  <Card title="How it works" icon="diagram-project" href="/how-it-works">
    Understand the relay, MCP server, and A2A protocol under the hood
  </Card>

  <Card title="Trust configuration" icon="shield-halved" href="/setup/trust-configuration">
    Configure per-teammate trust levels in `~/.agentrelay/trust.yaml`
  </Card>

  <Card title="MCP tools" icon="wrench" href="/tools/overview">
    Explore all seven tools your agent uses to send and receive handoffs
  </Card>

  <Card title="CLI reference" icon="terminal" href="/cli/overview">
    Full reference for `register`, `doctor`, `block`, `audit`, and more
  </Card>
</CardGroup>