Agent Relay

Agent Relay is a local-first control plane for your own AI agent fleet.

It does not review code itself. It accepts a task in a web UI, launches configured agents, streams their logs, and stores their final JSON results.

Current Use Case

The main current use case is code review across your own machines and CLI agents.

Simple example:

A teammate sends you a GitHub PR link.
You paste that PR into Agent Relay.
Agent Relay runs your enabled agents, for example:
- Codex on the Mac mini
- Claude on the Mac mini
- Codex on the MacBook Pro
Each agent uses its own tools and credentials to inspect the PR.
You watch the live logs in one place and compare the final outputs.
If one CLI exposes a session id, Agent Relay keeps it so you can continue later in that same session.

So the value today is not “replace GitHub review bots.” It is “give me one place to launch and observe my own agent reviews across local and remote machines.”

Mental Model

Relay The coordinator and the web UI.
Host A machine that can run agents.
Agent One runnable entry on a host, such as Codex, Claude, or Kimi.

The important part:

the relay can launch agents directly on the same machine it runs on
you only need a separate host process for other machines

So your Mac mini can be:

the relay
a local host for local agents

And you can add any number of extra remote hosts later.

URLs and Ports

Default local ports:

4310 The actual Agent Relay app and API.
4311 A small internal proxy used only for serving the app under a Tailscale subpath.
4320 The host API on a remote machine, if you run a separate host.

Normal local usage:

http://127.0.0.1:4310/

Tailscale usage:

Relay: https://YOUR-HOSTNAME.ts.net/agent-relay/
Host: https://YOUR-HOSTNAME.ts.net/agent-host/health

Why two local relay ports exist:

4310 is the real app
4311 is only the subpath shim for /agent-relay/

You normally do not open 4311 directly.

Quick Start

Install dependencies:

npm install

Create your env file:

cp .env.example .env

Start the relay:

npm start

Open:

http://127.0.0.1:4310/

Environment Variables

Current variables in .env.example:

AGENT_RELAY_PORT Relay port. Default 4310.
AGENT_HOST_PORT Host API port. Default 4320.
AGENT_HOST_TOKEN Shared bearer token used when Relay talks to a remote host.

If Relay and the agents live on the same machine, you can still keep the token set, but you do not need to run a separate host process there.

Config Files

Committed examples:

Local machine-specific files:

config/agent-relay.local.json
config/host.local.json

Rule of thumb:

commit the *.example.json files
edit the *.local.json files on your own machines
the local files are ignored by Git

Relay Config

Main relay example config lives in config/agent-relay.example.json.

For your actual machine, edit:

config/agent-relay.local.json

Important fields:

port Relay port.
agents All configured agent entries.
label Name shown in the UI.
hostLabel Which host group the agent appears under in the UI.
launcher How Relay starts this agent.
cwd Working directory before the CLI starts.
command Executable to run for local launchers.
baseUrl Remote host URL for http-json agents.
authToken Shared token for remote hosts.
remoteAgentKey The remote agent id on that host.
timeoutSec Optional hard timeout in seconds. Omit it for no timeout.

Launcher Types

Current launcher values:

codex-local Starts local codex.
claude-local Starts local claude.
shell-json Starts a generic local CLI that returns JSON-like text. Good for tools like kimi.
http-json Sends the task to a remote host over HTTP.

Example: Local Agent

{
  "agents": {
    "codex-mini": {
      "label": "Codex on Mac mini",
      "hostLabel": "Mac mini",
      "launcher": "codex-local",
      "cwd": "${HOME}",
      "command": "codex"
    }
  }
}

Example: Local Kimi Agent

{
  "agents": {
    "kimi-mini": {
      "label": "Kimi on Mac mini",
      "hostLabel": "Mac mini",
      "launcher": "shell-json",
      "cwd": "${HOME}",
      "command": "kimi",
      "args": [
        "--print",
        "--output-format",
        "text",
        "--final-message-only",
        "-p"
      ]
    }
  }
}

Example: Remote Agent On Another Host

{
  "agents": {
    "codex-mbp": {
      "label": "Codex on MacBook Pro",
      "hostLabel": "MacBook Pro",
      "launcher": "http-json",
      "baseUrl": "https://your-macbook-pro.ts.net/agent-host",
      "authToken": "${AGENT_HOST_TOKEN}",
      "remoteAgentKey": "codex"
    }
  }
}

Host Config

Host example config lives in config/host.example.json.

You only need this on a machine that should expose a remote host API.

For your actual machine, edit:

config/host.local.json

Example:

{
  "port": "${AGENT_HOST_PORT}",
  "listenHost": "127.0.0.1",
  "authToken": "${AGENT_HOST_TOKEN}",
  "agents": {
    "codex": {
      "label": "Codex local agent",
      "launcher": "codex-local",
      "cwd": "${HOME}",
      "command": "codex"
    }
  }
}

Recommended Setup

Use one relay, plus:

local agents on the same machine when possible
separate remote hosts only when you need agents on other machines

Example: Mac mini Relay With Local Agents And One Remote MacBook Pro Host

This is the practical mixed setup:

Relay runs on the Mac mini
the Mac mini also runs local agents directly
the MacBook Pro runs one separate host process

Edit these exact files:

On the Mac mini:
- .env.example copied to .env
- config/agent-relay.local.json
On the MacBook Pro:
- .env.example copied to .env
- config/host.local.json

Mac mini `.env`

File:

.env

Example contents:

AGENT_RELAY_PORT=4310
AGENT_HOST_PORT=4320
AGENT_HOST_TOKEN=CHANGE_ME_SHARED_TOKEN

Mac mini `config/agent-relay.local.json`

File:

config/agent-relay.local.json

Example contents:

{
  "agents": {
    "codex-mini": {
      "label": "Codex on Mac mini",
      "hostLabel": "Mac mini",
      "launcher": "codex-local",
      "cwd": "${HOME}",
      "command": "codex"
    },
    "claude-mini": {
      "label": "Claude on Mac mini",
      "hostLabel": "Mac mini",
      "launcher": "claude-local",
      "cwd": "${HOME}",
      "command": "claude"
    },
    "kimi-mini": {
      "label": "Kimi on Mac mini",
      "hostLabel": "Mac mini",
      "launcher": "shell-json",
      "cwd": "${HOME}",
      "command": "kimi",
      "args": [
        "--print",
        "--output-format",
        "text",
        "--final-message-only",
        "-p"
      ]
    },
    "codex-mbp": {
      "label": "Codex on MacBook Pro",
      "hostLabel": "MacBook Pro",
      "launcher": "http-json",
      "baseUrl": "https://your-macbook-pro.ts.net/agent-host",
      "authToken": "${AGENT_HOST_TOKEN}",
      "remoteAgentKey": "codex"
    },
    "kimi-mbp": {
      "label": "Kimi on MacBook Pro",
      "hostLabel": "MacBook Pro",
      "launcher": "http-json",
      "baseUrl": "https://your-macbook-pro.ts.net/agent-host",
      "authToken": "${AGENT_HOST_TOKEN}",
      "remoteAgentKey": "kimi"
    }
  }
}

Notes:

codex-mini, claude-mini, and kimi-mini run directly on the Mac mini
codex-mbp and kimi-mbp call the remote MacBook Pro host over HTTP
if you do not want a local Kimi agent on the Mac mini, leave "enabled": false

MacBook Pro `.env`

File:

.env

Example contents:

AGENT_RELAY_PORT=4310
AGENT_HOST_PORT=4320
AGENT_HOST_TOKEN=CHANGE_ME_SHARED_TOKEN

MacBook Pro `config/host.local.json`

File:

config/host.local.json

Example contents:

{
  "port": "${AGENT_HOST_PORT}",
  "listenHost": "127.0.0.1",
  "authToken": "${AGENT_HOST_TOKEN}",
  "agents": {
    "codex": {
      "label": "Codex local agent",
      "launcher": "codex-local",
      "enabled": true,
      "cwd": "${HOME}",
      "command": "codex"
    },
    "kimi": {
      "label": "Kimi local agent",
      "launcher": "shell-json",
      "enabled": true,
      "cwd": "${HOME}",
      "command": "kimi",
      "args": [
        "--print",
        "--output-format",
        "text",
        "--final-message-only",
        "-p"
      ]
    }
  }
}

Run order in that setup:

you run npm start on the Mac mini
you do not run npm run host on the Mac mini unless you specifically want to expose it as a remote host too
you run npm run host on the MacBook Pro

Verification:

on Mac mini:
- open http://127.0.0.1:4310/
on MacBook Pro:
- open http://127.0.0.1:4320/health

Example: Mac mini only

This is the easiest setup.

Relay runs on Mac mini
Codex/Claude/Kimi are installed on Mac mini
Relay launches them directly

Steps:

Add local agents to config/agent-relay.local.json
Start Relay:

npm start

That is all.

You do not need to run npm run host on that same machine.

Example: Mac mini relay + MacBook Pro host

Relay runs on Mac mini
Mac mini can still run its own local agents directly
MacBook Pro runs a separate host process for its own local agents

On the relay machine

Edit config/agent-relay.local.json
Add remote agents with launcher: "http-json" and the MacBook Pro host URL
Set .env:

cp .env.example .env

At minimum:

AGENT_RELAY_PORT=4310
AGENT_HOST_TOKEN=CHANGE_ME

Start Relay:

npm start

On the MacBook Pro

Clone the repo
Install dependencies:

npm install

Create .env:

cp .env.example .env

At minimum:

AGENT_HOST_PORT=4320
AGENT_HOST_TOKEN=THE_SAME_TOKEN_AS_THE_RELAY

Edit config/host.local.json so the local agents match what is installed on that MacBook Pro
Start the host:

npm run host

Verify:

http://127.0.0.1:4320/health

Tailscale

Relay under `/agent-relay/`

Relay itself runs on:

http://127.0.0.1:4310/

The local proxy on 4311 exists only to make this subpath work:

/agent-relay/

The helper script:

./configure-tailscale-serve.sh

sets Tailscale Serve to:

/agent-relay/ -> http://127.0.0.1:4311/agent-relay/

Remote host over Tailscale

On the remote machine:

./host-configure-tailscale-serve.sh

This exposes the host under:

https://YOUR-HOSTNAME.ts.net/agent-host/

Session IDs

If a CLI prints a recognizable session id, Relay stores it and shows it on past jobs.

That makes it possible to continue work later in the original agent session.

Scripts

npm start Start Relay.
npm run host Start the host API on a machine that should expose remote agents.
npm run build Build the frontend into public/.

Skill And Prompt Presets

This repo includes separate drafts for three integration paths:

OpenClaw skill:
- skills/agent-relay-review/SKILL.md
Claude Project / system prompt draft:
- integrations/claude/AGENT_RELAY_PROJECT.md
OpenAI Custom GPT / hosted agent draft:
- integrations/openai/AGENT_RELAY_CUSTOM_GPT.md

They are intended as practical starting points for running Agent Relay from other AI control surfaces.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
config		config
frontend		frontend
integrations		integrations
lib		lib
public		public
schemas		schemas
skills/agent-relay-review		skills/agent-relay-review
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
agent-relay-subpath-proxy.mjs		agent-relay-subpath-proxy.mjs
configure-tailscale-serve.sh		configure-tailscale-serve.sh
host-configure-tailscale-serve.sh		host-configure-tailscale-serve.sh
host.js		host.js
install-tailnet.sh		install-tailnet.sh
package-lock.json		package-lock.json
package.json		package.json
run-agent-relay-server.sh		run-agent-relay-server.sh
server.js		server.js
vite.config.mjs		vite.config.mjs

Folders and files

Latest commit

History

Repository files navigation

Agent Relay

Current Use Case

Mental Model

URLs and Ports

Quick Start

Environment Variables

Config Files

Relay Config

Launcher Types

Example: Local Agent

Example: Local Kimi Agent

Example: Remote Agent On Another Host

Host Config

Recommended Setup

Example: Mac mini Relay With Local Agents And One Remote MacBook Pro Host

Mac mini .env

Mac mini config/agent-relay.local.json

MacBook Pro .env

MacBook Pro config/host.local.json

Example: Mac mini only

Example: Mac mini relay + MacBook Pro host

On the relay machine

On the MacBook Pro

Tailscale

Relay under /agent-relay/

Remote host over Tailscale

Session IDs

Scripts

Skill And Prompt Presets

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Mac mini `.env`

Mac mini `config/agent-relay.local.json`

MacBook Pro `.env`

MacBook Pro `config/host.local.json`

Relay under `/agent-relay/`

Packages