Agent Relay

Installation

Agent Relay ships as a Python package on PyPI as agent-relay-tool and requires Python 3.11 or newer. Pick the path that matches your setup below — each one is a complete walkthrough from a fresh shell to a working agent-relay binary.

macOS

Tested on macOS 12 Monterey and newer, both Intel and Apple Silicon.

  1. Check your Python version

    macOS ships with an older system Python. Confirm you have 3.11+ available (install via brew install python@3.12 if not).

    terminal
    python3 --version

    You should see Python 3.11.x or higher. If the system Python is older, install a newer one with Homebrew before continuing.

  2. Run the installer

    The installer bootstraps uv if it's missing, then installs Agent Relay into its own isolated environment and drops agent-relay on your PATH.

    terminal
    curl -fsSL https://agent-relay.dev/install.sh | sh

    No sudo is required — everything lands under ~/.local/.

  3. Reload your shell

    The installer appends ~/.local/bin to your PATH in ~/.zshrc. Either start a new terminal tab or source it manually:

    terminal
    source ~/.zshrc

  4. Verify the install

    terminal
    agent-relay --version

    Expected output: a version line like agent-relay 0.5.5.

    If `agent-relay: command not found`

    The installer couldn't write to your shell config, or you're using a non-default shell (fish, nu, etc). Add the install directory to your PATH manually:

    terminal
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Upgrading

Each install path has its own upgrade command. Run whichever matches the path you used above.

terminal
# macOS / Linux
curl -fsSL https://agent-relay.dev/install.sh | sh
terminal
# Windows
irm https://agent-relay.dev/install.ps1 | iex

The installer is idempotent — re-running it upgrades in place.

Uninstalling

Remove the binary and (optionally) the install directory:

terminal
# macOS / Linux
rm ~/.local/bin/agent-relay
terminal
# Windows
Remove-Item "$env:USERPROFILE\.local\bin\agent-relay.exe"

What's next

Quickstart

Run your first agent handoff in five steps.

Sessions

Understand what gets captured under .agent-relay/.