agent-bridge
A small HTTP service on the machine where your Claude Code agents run (the agent
host). mcp-gateway calls it over the LAN. It turns each request
into herdr CLI calls and returns trimmed results. herdr owns the agents, which are
addressed by their herdr pane id (e.g. w1:p1); agent-bridge's own state is only its id
and the gateway it enrolled with.
mcp-gateway ──LAN, bearer token──> agent-bridge :8765 ──> herdr CLI ──> Claude Code agents
It sees every herdr agent of its user, including ones started by hand, and controls those whose folder is under the allowed roots.
System requirements
| OS | macOS, Linux or Windows (natively), wherever herdr runs. Tested on macOS 27.2 (Apple silicon), Ubuntu 26.04 LTS (x86_64, systemd 259) and Windows 11 25H2 (Windows PowerShell 5.1). The service setup needs launchd on macOS, systemd user units on Linux, and Windows 10 version 1809 or later. |
| herdr | 0.8.0 or newer (tested with 0.8.0 and 0.9.5); its server must be running for the same user (it is whenever herdr is open, and keeps running after you detach) |
| Claude Code | the claude CLI, installed and logged in for that user |
| Python | 3.11+, via uv (uv installs it if needed); on Windows, uv 0.12.4 or newer, as older ones install a windowless agent-bridge that opens a console window |
| Network | reachable from the gateway host on one TCP port (default 8765), and able to reach the gateway on its port (8766) to enroll. Give the host a fixed LAN address, e.g. a DHCP reservation. Nothing is exposed to the internet. |
| Always on | the agents and agent-bridge only answer while the host is awake and, on macOS and Windows, the user is logged in; see Keeping the agent host available |
Keeping the agent host available
While you're away from the agent host, it has to stay awake, logged in and running herdr. If it sleeps, agent-bridge and the agents pause, and every tool call answers "The agent host is not reachable". The gateway host can't wake it: macOS's "Wake for network access" doesn't reliably wake for a plain TCP connection.
macOS
- Keep it awake on power:
sudo pmset -c sleep 0(the display can still sleep), or System Settings → Energy (on a laptop: Battery → Options) → turn on "Prevent automatic sleeping when the display is off". For a single trip,caffeinate -sin a terminal does the same until you stop it. - A laptop with the lid closed sleeps anyway, unless it's on power with an external
display.
sudo pmset -c disablesleep 1keeps it awake with the lid closed too (an undocumented setting; undo with0; mind the heat). - Stay logged in. agent-bridge is a launchd agent, which only runs in a logged-in session; a locked screen is fine. After a restart (for example an overnight macOS update) FileVault waits for your password, so nothing runs until you log in again. Consider turning off automatic installation of macOS updates.
- Keep herdr open, or detached; its server must be running.
Linux
- Turn off suspend:
sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target. On a laptop, also setHandleLidSwitch=ignoreandHandleLidSwitchExternalPower=ignorein/etc/systemd/logind.conf. agent-bridge setupturns on lingering, so agent-bridge and herdr's server start at boot and keep running after you log out.
Windows
- Turn off sleep on power (Settings → System → Power).
- Stay logged on. The scheduled task starts at logon and only runs in your session; a locked screen is fine.
Before you leave, ask Claude to list your agents. If it answers that the agent host is not reachable, the host is asleep, logged out, or agent-bridge isn't running.
API
All routes require Authorization: Bearer $AGENT_BRIDGE_TOKEN.
| Route | herdr | Notes |
|---|---|---|
GET /info |
--version |
the host: api_version (2; a bridge without /info is 1), bridge_id (from the state file), name (AGENT_BRIDGE_NAME, or the hostname as a slug), platform (darwin, linux or windows), bridge_version, herdr_version (null if herdr can't be run), roots, projects_root (the first root), the accounts' names and max_agents |
GET /projects/{name} |
{"cwd": …} of the folder name under the first allowed root that has one; 404 project_not_found otherwise, also for anything but one folder name (.., ., ~, /, \, :) |
|
GET /agents |
agent list |
every herdr agent, in any folder. project is the agent's folder under the closest allowed root, joined with / on every platform (grafik/api for <root>/grafik/api), null at a root or outside them. An idle or done agent whose last message ends with a question has it in question (read from its screen with agent read, so it is a guess; herdr itself can't tell that agent from one that simply finished). account is the account its Claude Code runs on (see Claude accounts) |
GET /agents/{id} |
agent get |
the same, including question and account |
GET /agents/{id}/output?lines=40&source=recent |
agent read |
last N (1-500) meaningful lines: padding, input box (also when it shows the session's name) and status bar dropped; the visible screen only while the agent is working or blocked (herdr can't scroll its history then). source=visible reads only the screen; recent-unwrapped reads herdr's history of that name |
POST /agents/{id}/prompt {text, timeout_s?, lines?} |
agent prompt --wait |
waits until idle/done/blocked (the agent includes question); on timeout returns timed_out: true with current status, and unconfirmed: true if the text was typed but the agent didn't react within 5 s (don't resend). Refused with 409 agent_blocked while the agent is blocked (the Enter would answer its question), and with 409 agent_busy while it is working or another prompt to it is running |
POST /agents/{id}/wait {timeout_s?, lines?, expect_change?} |
agent wait |
same result as /prompt, without sending anything; expect_change (after /keys) first gives the agent 5 s to leave its old blocked state |
POST /agents/{id}/keys {keys} |
agent send-keys |
answer a blocked agent's question |
POST /agents {project, name?, account?} |
workspace create + agent start --kind claude |
start an agent in a project: a folder name, looked up as GET /projects/{name} does, or an absolute path. {cwd} (an absolute path) is still taken instead of project, for gateways from before it. On the folder's Claude account or the one named (see below); the reply adds the account used. name (by default the folder's) may be any words: it becomes a name herdr accepts (lower-case ASCII, starting with a letter, at most 32 characters, e.g. Grafik fix! → grafik-fix), with -2, -3, … if a live agent already has it |
PATCH /agents/{id} {name} |
agent rename + workspace rename |
give the agent and its workspace the same new name, made the way POST /agents makes one (-2, -3, … only if another live agent has it); returns the agent |
DELETE /agents/{id} |
agent get + pane close |
close the agent's pane; 404 if the id isn't an agent (a shell or dev-server pane) |
Every error comes back as {"error": {"code", "message"}} with a matching status
(unauthorized → 401, path_not_allowed → 403, agent_not_found → 404,
agent_limit_reached → 409, timeout → 504, …); the message is written to be read
aloud. Only request validation failures keep FastAPI's {"detail": [...]} shape (422).
Reading (list, details, output, wait) works for every agent. Changing one (/prompt,
/keys, PATCH, DELETE) only works for agents whose folder is under
AGENT_BRIDGE_ALLOWED_ROOTS; any other agent gets 403 agent_not_allowed, so a
misheard id can't prompt, answer, rename or close an agent you started by hand
elsewhere. To keep agents in some folders off limits, leave those folders out of the
allowed roots.
Starting agents
POST /agents refuses, in this order:
422 bad_projectifprojectis neither one folder name nor an absolute path, and404 project_not_foundif no allowed root has a folder of that name.403if an absolute path is outsideAGENT_BRIDGE_ALLOWED_ROOTS(symlinks and..are resolved first).404if the folder doesn't exist.422 unknown_accountif the named account isn't inAGENT_BRIDGE_ACCOUNTS.409 agent_limit_reachedifAGENT_BRIDGE_MAX_AGENTS(10) or more herdr agents already exist: "Refusing to start a new agent: 10 agents are already running and the limit is 10. Stop an agent first." The count and the start are serialized, so parallel requests can't slip past the limit.409 trust_refusedor409 folder_not_trusted(see Folder trust), or502 agent_not_detectedif Claude Code didn't come up, twice.
Agents start with AGENT_BRIDGE_CLAUDE_ARGS (default --permission-mode auto) and with
CLAUDE_CONFIG_DIR set to their account's config (see Claude accounts),
or else to AGENT_BRIDGE_CLAUDE_CONFIG_DIR if set. Each
one gets its own herdr workspace, labelled with the name.
With "remote_control": true in the request (the gateway sends it unless the user asks
otherwise), the agent also gets --remote-control <name>, so the session shows up in the
Claude app under the agent's name (renaming the agent later doesn't rename the session);
left out, it is off. If AGENT_BRIDGE_CLAUDE_ARGS already has --remote-control, it
isn't passed again, and every agent has it. The answer says which in remote_control:
on, off, or blocked when Claude Code showed "Remote Control is disabled by your
organization's policy" within the 5 s the start looks for the trust dialog (e.g. on a
Claude Team account); the agent then runs without it.
Claude accounts
agent-bridge can start agents on more than one Claude login, e.g. a work subscription for
work projects and a personal one for the rest, picking the login from the project's
folder. Claude Code keeps each login in a config folder: its default one (~/.claude,
what a plain claude uses), or another named by CLAUDE_CONFIG_DIR.
-
Log in once in each config. The default one is likely logged in already. For another, run
CLAUDE_CONFIG_DIR=~/.claude-personal claude, log in, and quit. An alias such asalias claude-personal='CLAUDE_CONFIG_DIR=$HOME/.claude-personal claude'keeps using that login by hand easy. -
Name the accounts in
AGENT_BRIDGE_ACCOUNTS, as JSON: each with its config folder and the project folders it's for. Names are lower-case; paths are full paths."config_dir": nullmeans Claude Code's default config.{ "work": {"config_dir": null, "folders": ["/Users/me/projects/work"]}, "personal": {"config_dir": "/Users/me/.claude-personal", "folders": ["/Users/me/projects/own"]} }
-
Apply it. With
agent-bridge setup, pass it in once as--accounts; re-runs keep it, and an empty value removes it:agent-bridge setup --accounts '{"work": {"config_dir": null, "folders": ["/Users/me/projects/work"]}}'
In Windows PowerShell 5.1, write each
"inside it as\": it drops them otherwise when it passes the value on. Remove it there with--accounts=, as it drops''too:agent-bridge setup --accounts '{\"work\": {\"config_dir\": null, \"folders\": [\"C:\\Users\\me\\work\"]}}'
By hand, add it to the env file in single quotes, and restart agent-bridge. A mistake stops startup with a line naming it, e.g.
AGENT_BRIDGE_ACCOUNTS (work.config): Extra inputs are not permitted. -
Trust the default config's folders by hand. agent-bridge never edits Claude Code's default config, so it can't mark folders trusted for an account with
"config_dir": null. Openclaudeonce in each of those projects and accept (see folder trust for why a folder above them isn't enough). Until then, starts there stop with409 folder_not_trusted.
A new agent gets the account named in the request ("account" in POST /agents, any
case; in the Claude app, e.g. "start grafik on my personal account"), else the account
whose folder holds its folder most closely, else AGENT_BRIDGE_CLAUDE_CONFIG_DIR, which
counts as the account with the same config_dir if there is one. The reply names the
account. An unknown name is refused with 422 unknown_account, listing the accounts.
A listed agent's account, also for one started by hand, is the account whose
config_dir is the CLAUDE_CONFIG_DIR of its claude process (found with herdr pane process-info; none set is the default config). It is null when no account or several
have that config, when the process can't be read, or without AGENT_BRIDGE_ACCOUNTS.
Folder trust (below) is written to the account's own config, and never to the default
one.
Folder trust
Claude's "Do you trust this folder?" dialog defaults to "No, exit", so a prompt sent
into it would quit Claude. If the dialog shows after a start, the start fails with
409 folder_not_trusted and the new workspace is closed.
So either trust each project folder once by hand (open claude in it and accept), or
let agent-bridge do it. In a git repository Claude Code checks the repository's own
folder: trusting a folder above it, such as the one holding all your projects, doesn't
count, so the dialog still shows. To let agent-bridge do it, set both:
AGENT_BRIDGE_CLAUDE_CONFIG_DIR: a separate Claude config for the agents, e.g.~/.claude-agents(runCLAUDE_CONFIG_DIR=~/.claude-agents claudeonce to log in; until then starts fail with409 trust_refusedsaying so);AGENT_BRIDGE_TRUST_ROOT: the folder under which new agents' folders are marked trusted in the agent's Claude config (<config dir>/.claude.json).
Hard limits:
- only folders under the trust root are ever trusted automatically;
- never in the default config (
~/.claude.json,~/.claude/): agent-bridge refuses to start with a trust root but no separate config dir, or with a config dir that is the default one, and refuses each start with409 trust_refusedif it is anyway. An account with"config_dir": null(the default config) gets nothing trusted: its folders must be trusted by hand, or its starts stop at the dialog. Folders are compared on disk, not by spelling, so another letter case (macOS disks ignore case), a symlink, or a.claude.jsonlinked to~/.claude.jsonis caught too.
The file is written atomically and left alone if the folder itself is already trusted.
Configuration
Read from the environment, or from the env file (the environment wins), one
AGENT_BRIDGE_…=value per line. An invalid setting stops startup with one line per
problem, naming the variable. Enrolling adds a state file. Both must be readable only by
you (chmod 600):
| Platform | Settings (env file) | State |
|---|---|---|
| macOS | ~/Library/Application Support/agent-bridge/env |
~/Library/Application Support/agent-bridge/state.json |
| Linux | ~/.config/agent-bridge/env |
~/.local/state/agent-bridge/state.json |
| Windows | %APPDATA%\agent-bridge\env |
%LOCALAPPDATA%\agent-bridge\state.json |
AGENT_BRIDGE_ENV_FILE and AGENT_BRIDGE_STATE_FILE point elsewhere. A .env file in
the working folder is read too, under the env file, with a warning.
| Variable | Default | |
|---|---|---|
AGENT_BRIDGE_TOKEN |
— | required, at least 32 characters: letters, digits, . _ ~ + / - and trailing = |
AGENT_BRIDGE_ALLOWED_ROOTS |
— | required, absolute folders agents may start in, separated by : (; on Windows); /, the home folder or anything above it, and on Windows \\ paths, are refused |
AGENT_BRIDGE_HOST |
— | the LAN address to listen on, given to the gateway too; an IP address, not 0.0.0.0 (127.0.0.1 when mcp-gateway runs on the same machine). serve, enroll, rename and check need it |
AGENT_BRIDGE_PORT |
8765 |
|
AGENT_BRIDGE_NAME |
— | this host's name in agent ids (mac/w1:p1): a lowercase letter, then up to 31 lowercase letters, digits or -. serve, enroll, rename and check need it |
AGENT_BRIDGE_CLAUDE_CONFIG_DIR |
unset | CLAUDE_CONFIG_DIR for new agents whose folder has no account; unset uses Claude Code's default config |
AGENT_BRIDGE_ACCOUNTS |
none | named Claude logins and the folders they're for, as JSON (see Claude accounts); names are lower-case, e.g. work |
AGENT_BRIDGE_CLAUDE_ARGS |
--permission-mode auto |
extra claude arguments, shell-quoted; set it empty for none |
AGENT_BRIDGE_HERDR_BIN |
herdr |
the full path, e.g. ~/.local/bin/herdr; serve, enroll, rename and check need it set |
AGENT_BRIDGE_TRUST_ROOT |
unset | auto-trust folders under it; needs AGENT_BRIDGE_CLAUDE_CONFIG_DIR; absolute, and like the allowed roots never / or the home folder |
AGENT_BRIDGE_MAX_AGENTS |
10 |
no new agents while this many or more exist (all herdr agents count) |
AGENT_BRIDGE_MAX_OUTPUT_CHARS |
8000 |
terminal output beyond this is cut from the front (truncated: true) |
AGENT_BRIDGE_PROMPT_TIMEOUT_MS |
600000 |
how long prompt and wait block when the request gives no timeout_s |
Run
The herdr server must be running in the same user session. To try it in the foreground, write the env file and start it from the checkout. To keep it running, set it up as a service instead (below).
uv sync --all-packages
uv run --package claude-remote-mcp-agent-bridge agent-bridge serve
Commands
| Command | Does | Exit codes |
|---|---|---|
agent-bridge serve |
runs the service from the env and state files, and tells the gateway its address | |
agent-bridge enroll <string> |
joins the gateway that printed the string (below) | 0 enrolled, 3 name taken, 4 gateway unreachable (prints the command to retry), 5 enrolled but the state file couldn't be saved, 1 otherwise |
agent-bridge rename <name> |
renames this host on that gateway | 0 renamed, 2 name won't do, 3 name taken, 4 gateway unreachable, 5 renamed but the state file couldn't be saved, 6 gateway too old to rename hosts, 1 otherwise (e.g. not enrolled); 4, 6 and a refusal from the gateway print the gateway's command, but a gateway without this host says to enroll again |
agent-bridge unenroll |
leaves that gateway | 0, also when the gateway can't be reached or refuses (prints the gateway's command); 1 if the state file can't be read or written |
agent-bridge check |
checks the settings, the files' modes, herdr, the running service and the gateway, one line each | 0 all passed, 1 one failed |
agent-bridge check --token-format <token>, --name-format <name> |
checks a value before it goes in the env file | 0 fine, 2 not (why, on stderr) |
agent-bridge setup |
installs or updates the service and enrolls it (macOS, Linux, Windows) | 0 installed (enrolled or not), 1 refused or failed |
agent-bridge uninstall |
leaves the gateway, then removes the service, its settings, state and log (on Windows, also the firewall rule) | 0 removed, also when leaving the gateway failed (prints the gateway's command); 1 run with sudo, or the service couldn't be removed (Linux: also no systemd user manager; Windows: also run as another account than the desktop's; nothing is removed then) |
agent-bridge --version |
prints the installed version | 0 |
Enroll with the gateway
With agent-bridge running, run sudo mcp-gateway enroll on the gateway host, then here:
uv run --package claude-remote-mcp-agent-bridge agent-bridge enroll 'crm1@192.168.1.10:8766#…'
The gateway checks that the address in AGENT_BRIDGE_HOST and AGENT_BRIDGE_PORT
answers as this bridge, and adds it under AGENT_BRIDGE_NAME. From then on, every start
tells the gateway the current address; if it can't be reached, agent-bridge logs how to
enroll again and serves on. A bridge can also be added by hand on the gateway host with
sudo mcp-gateway bridges add <url>, which asks for the token.
The examples below use /path/to/claude-remote-mcp for the checkout, 192.168.1.20 for
the LAN address and ~/projects for the projects folder; replace them with yours.
As a service on macOS (launchd)
launchd, macOS's service manager, starts agent-bridge at login and restarts it if it
stops. It is configured by a plist file in ~/Library/LaunchAgents, which runs
agent-bridge serve; the settings are in the env file.
agent-bridge setup writes both and enrolls the bridge.
With agent-bridge setup
Run sudo mcp-gateway enroll on the gateway host for an enrollment string. Then, as your
own user, not with sudo:
uv tool install claude-remote-mcp-agent-bridge
agent-bridge setup
It asks only for what isn't installed yet:
- the folders agents may start in (
AGENT_BRIDGE_ALLOWED_ROOTS, default~/Projects); - this host's name in agent ids (
AGENT_BRIDGE_NAME, default: the hostname); - once, a separate Claude config (default
~/.claude-agents) and a trust root (default: the first folder agents may start in), for folder trust. Answer-at the config question to skip both. If the config is new, log in to it once, as setup reminds you at the end; - the enrollment string, until the host is enrolled. Enter installs without enrolling.
It finds the LAN address and herdr itself, and generates the token on the first run.
Then it:
- checks the port (8765). If another program holds it, it names the program and offers a free port;
- writes the env file, readable only by you. Other settings in it are kept, but not its comments;
- writes the plist and (re)starts the service;
- runs
agent-bridge check; - enrolls with the gateway. If the gateway has another host by that name, it asks for another one.
The last lines name the host as the gateway knows it. Nothing needs copying to the
gateway host. The plist runs ~/.local/bin/agent-bridge, which uv tool upgrade claude-remote-mcp-agent-bridge keeps; re-run agent-bridge setup after upgrading, which
restarts the service. Re-running asks nothing on an installed Mac, and keeps the token
and the enrollment. If setup stops partway, run it again: it picks up from there.
To skip the questions or change an installed value, pass it: --roots, --name,
--host, --port, --herdr-bin, --claude-config-dir and --trust-root ('' for no
folder trust), --enrollment ('' to enroll later), and --accounts (never asked for;
'' removes it). --rotate-token replaces the token and needs --enrollment (if
enrolling fails, the old token is put back). A new --name on an enrolled host renames
it on the gateway (agent-bridge rename); a gateway too old for that, or one that can't
be reached, is asked for an enrollment string instead, as enrolling again renames it too.
For any other setting, edit the env file and re-run setup. See agent-bridge setup --help.
On a Mac set up from a checkout with the setup script of earlier versions, agent-bridge setup takes the install over: it keeps the env file, the token and the enrollment, and
points the plist at the package. An older install whose settings are still in the plist
has them moved to the env file; setup then asks for the name and an enrollment string.
Give the name the host has on the gateway: the gateway replaces its record at the same
address. If the Mac's address has changed since, the old record holds the name; remove it
first with sudo mcp-gateway bridges remove <name> on the gateway host.
Setup refuses to run from a checkout's .venv or under uvx, as the plist must run an
installed agent-bridge. From a checkout, install it with
uv tool install --editable ./agent-bridge and run that one's agent-bridge setup.
By hand
What setup does, step by step:
-
Write the env file, with at least
AGENT_BRIDGE_TOKEN(generate it withopenssl rand -hex 32),AGENT_BRIDGE_ALLOWED_ROOTS,AGENT_BRIDGE_HOST(the LAN address,ipconfig getifaddr en0on Wi-Fi),AGENT_BRIDGE_NAMEandAGENT_BRIDGE_HERDR_BIN(command -v herdr), andchmod 600it. -
Write
~/Library/LaunchAgents/dev.claude-remote.agent-bridge.plist, with the full path ofagent-bridge(command -v agent-bridge) and of the log. Write paths in full: launchd doesn't expand~or$HOME. Make the log's folder,~/Library/Logs, if it isn't there.<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key><string>dev.claude-remote.agent-bridge</string> <key>ProgramArguments</key> <array> <string>/Users/me/.local/bin/agent-bridge</string> <string>serve</string> </array> <key>RunAtLoad</key><true/> <key>KeepAlive</key><true/> <key>ThrottleInterval</key><integer>10</integer> <key>StandardOutPath</key><string>/Users/me/Library/Logs/agent-bridge.log</string> <key>StandardErrorPath</key><string>/Users/me/Library/Logs/agent-bridge.log</string> </dict> </plist>
-
Check it and load it. It starts right away and at every login:
plutil -lint ~/Library/LaunchAgents/dev.claude-remote.agent-bridge.plist launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.claude-remote.agent-bridge.plist
-
Run
agent-bridge check, then enroll it.
If the macOS firewall is on, allow incoming connections for Python when asked.
Restart, stop, uninstall
These work however you installed it:
# Status: a PID and "state = running" when it's up; "last exit code" after a crash
launchctl print gui/$(id -u)/dev.claude-remote.agent-bridge | grep -E 'state|pid|last exit'
# Log: errors, plus one line per request. Nothing rotates it; it grows slowly, and
# emptying it is safe while agent-bridge runs (launchd appends to it).
tail -f ~/Library/Logs/agent-bridge.log
: > ~/Library/Logs/agent-bridge.log
# Restart, e.g. after editing the env file. Re-running agent-bridge setup does that too.
launchctl kickstart -k gui/$(id -u)/dev.claude-remote.agent-bridge
# Stop. `launchctl stop` is not enough: KeepAlive would start it again at once.
# Unloading stops it until you start it again or log in next time.
launchctl bootout gui/$(id -u)/dev.claude-remote.agent-bridge
# Start again (after `disable` below, `enable` it first)
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.claude-remote.agent-bridge.plist
# Keep it from starting at login without deleting the plist. This doesn't stop it if
# it's running (bootout does), and bootstrap fails with "5: Input/output error" until
# you enable it again. Re-running agent-bridge setup enables it too.
launchctl disable gui/$(id -u)/dev.claude-remote.agent-bridge
launchctl enable gui/$(id -u)/dev.claude-remote.agent-bridge # undo
# Uninstall: leaves the gateway, then removes the service, the env and state files and
# the log. Then `uv tool uninstall claude-remote-mcp-agent-bridge` removes the package.
agent-bridge uninstall
By hand, uninstalling is agent-bridge unenroll, launchctl bootout as above, then
removing the plist, ~/Library/Application Support/agent-bridge and the log.
As a service on Linux (systemd user unit)
A systemd user service runs agent-bridge as you, next to your herdr server. It starts at
boot without anyone logging in (lingering), and restarts if it stops. A second user
service runs herdr's server headless, so agents can start after a reboot too; you can
still attach to it with herdr.
With agent-bridge setup
Run sudo mcp-gateway enroll on the gateway host for an enrollment string. Then, as your
own user, not with sudo, in your own login (SSH or a console; not through su or
sudo -u, which have no user manager):
uv tool install claude-remote-mcp-agent-bridge
agent-bridge setup
It asks the same questions as on macOS, only for what isn't installed yet, and takes the same flags. Then it:
- checks the port (8765). If another program holds it, it names the program and offers a free port;
- writes the settings to
~/.config/agent-bridge/env, readable only by you. Other settings in it are kept, but not its comments; - installs
agent-bridge.serviceandagent-bridge-herdr.servicein~/.config/systemd/user/. It starts herdr's service only when no herdr server is running, and never restarts it, so running agents stay; - turns on lingering (
loginctl enable-linger). If that is refused, it prints thesudocommand to run; - (re)starts agent-bridge, runs
agent-bridge check, and enrolls. If the gateway has another host by that name, it asks for another one.
--no-herdr-service installs no service for herdr's server, if you start it yourself,
and removes one installed before without stopping its server; --herdr-service brings it
back. Re-runs keep what is installed.
The unit runs ~/.local/bin/agent-bridge, which uv tool upgrade claude-remote-mcp-agent-bridge keeps; re-run agent-bridge setup after upgrading, which
restarts agent-bridge but not herdr's server. Re-running asks nothing on an installed
host, and keeps the token and the enrollment. If setup stops partway, run it again.
A host set up from a checkout with agent-bridge/deploy/linux/setup.sh (earlier
versions) is taken over with no questions: setup keeps its env file, token and
enrollment, keeps herdr's service as it was (none, if it was installed with
HERDR_SERVICE=0), and points the unit at the package. The checkout isn't used after
that.
Setup refuses to run from a checkout's .venv or under uvx, as the unit must run an
installed agent-bridge. From a checkout, install it with
uv tool install --editable ./agent-bridge and run that one's agent-bridge setup.
Restart, stop, uninstall
systemctl --user status agent-bridge
journalctl --user -u agent-bridge -f
systemctl --user restart agent-bridge # after editing the env file
systemctl --user stop agent-bridge # until the next start or boot
systemctl --user disable --now agent-bridge # and don't start at boot
agent-bridge uninstall
uv tool uninstall claude-remote-mcp-agent-bridge
agent-bridge uninstall leaves the gateway (agent-bridge unenroll), then removes both
services, the env file and the state file. Its log is in the journal, which systemd ages
out. herdr's server keeps running with its agents until you stop it (herdr server stop)
or reboot. Lingering stays on; loginctl disable-linger turns it off.
As a service on Windows (Task Scheduler)
A scheduled task starts agent-bridge when you log on. It runs as you, in your session (where the herdr server runs), with no window.
With agent-bridge setup
Run sudo mcp-gateway enroll on the gateway host for an enrollment string. Then, in an
ordinary PowerShell window (not one run as administrator, and not as another account):
uv tool install claude-remote-mcp-agent-bridge
agent-bridge setup
It asks the same questions as on macOS, only for what isn't
installed yet, and takes the same flags; --roots takes folders separated by ;, in
quotes (--roots 'C:\Projects;D:\Work'), as PowerShell ends a command at an unquoted ;.
Windows PowerShell 5.1 drops an empty '' argument, so write an empty value with =, as
in --enrollment= or --trust-root=. The default name is the computer name, e.g.
win-pc. It finds the LAN address and
herdr.exe itself, including herdr's %LOCALAPPDATA%\Programs\Herdr\bin\herdr.exe,
which isn't on PATH. Then it:
- checks the port (8765). If another program holds it, or Windows keeps it for Hyper-V or WSL, it names that and offers a free port. A port held by agent-bridge itself is fine; it is restarted;
- writes the settings to
%APPDATA%\agent-bridge\env. Other settings in it are kept, but not its comments.AGENT_BRIDGE_*variables set in your user or machine environment would win over it for the task, so setup refuses them and prints how to remove them; - adds an inbound firewall rule for the port on Private networks only. This is the
only step that asks for admin rights (one UAC prompt). If Windows treats your network
as Public, it asks whether to make it Private (answer
y): the gateway can't reach agent-bridge otherwise. If you decline the prompt, it prints the commands to run as administrator; - stops the running agent-bridge, if any, and registers the
agent-bridgetask, which starts it. The task runsagent-bridgew.exe serve --log-file …:agent-bridgewis agent-bridge without a console window, aspythonwis topython. Nothing runs in between, so ending the task ends agent-bridge. It is tried every minute while you're logged on, which does nothing while it runs. That way it starts once Wi-Fi brings up the LAN address, and starts again if it stops; - runs
agent-bridge check, and enrolls with the gateway (asking for another name if the gateway already has a host by that name).
Its log is %LOCALAPPDATA%\agent-bridge\agent-bridge.log, with a line for each start and one
per request. Once it passes 1 MB it is moved to agent-bridge.log.1, replacing the one
before, also while agent-bridge runs (while another program has it open, such as
Get-Content -Wait, that waits until it lets go). It holds only what agent-bridge logs, not
what it prints; an exception is logged by its type alone, without its message or traceback,
which could include a setting.
The task runs %USERPROFILE%\.local\bin\agent-bridgew.exe, which upgrades keep. Re-running
setup asks nothing on an installed host, and keeps the token and the enrollment. If setup
stops partway, run it again; a setup that stops after stopping agent-bridge puts the task
back as it was.
Windows can't replace files a running program has open, so stop agent-bridge before
upgrading: uv tool upgrade fails while it runs, and leaves the package half removed.
Setup starts it again:
schtasks /Change /TN agent-bridge /DISABLE; schtasks /End /TN agent-bridge
uv tool upgrade claude-remote-mcp-agent-bridge
agent-bridge setup
If an upgrade failed that way, agent-bridge is gone too: run
uv tool install --reinstall claude-remote-mcp-agent-bridge (with agent-bridge stopped,
as above), then agent-bridge setup.
A host set up from a checkout with agent-bridge\deploy\windows\setup.ps1 (earlier
versions) is taken over with no questions: setup keeps its env file, token and
enrollment, and no folder trust if none was set up. It stops the checkout's agent-bridge
and points the task at the package. The checkout isn't used after that.
Setup refuses to run from a checkout's .venv or under uvx, as the task must run an
installed agent-bridge. From a checkout, install it with
uv tool install --editable ./agent-bridge and run that one's agent-bridge setup.
Restart, stop, uninstall
# Restart it, e.g. after editing the env file. The log gets a new "starting agent-bridge"
# line. Re-running agent-bridge setup does that too.
schtasks /End /TN agent-bridge; schtasks /Run /TN agent-bridge
# Stop it. Disabled first, or the task starts it again within a minute.
schtasks /Change /TN agent-bridge /DISABLE; schtasks /End /TN agent-bridge
# Start again: re-run agent-bridge setup, which registers the task again. Only enabling and
# starting it (schtasks /Change /ENABLE, then /Run) leaves out the every-minute retry,
# which disabling ended, until your next logon.
agent-bridge setup
# Uninstall: leaves the gateway, then removes the task, the firewall rule (one UAC
# prompt), the env file, the state file and the log.
agent-bridge uninstall
uv tool uninstall claude-remote-mcp-agent-bridge
When it's stopped or removed
While agent-bridge is stopped, mcp-gateway answers every tool call with "The agent host
is not reachable", and the agents in herdr keep running untouched. Uninstalling leaves
behind any folder-trust entries agent-bridge added to the agents' Claude configs
(<config dir>/.claude.json); they're ordinary trust entries and can
stay. To retire the whole setup, also
uninstall mcp-gateway and remove the
connector in claude.ai.
Tests
uv run --package claude-remote-mcp-agent-bridge pytest agent-bridge
The tests replace the herdr CLI with a fake runner, so they never touch real agents or the real Claude config. They include negative cases: starts outside the allowed roots, in missing folders, at the agent limit, and trust attempts on the default config, each checked to leave no workspace and no config change behind.
Metadata
Release files for claude-remote-mcp-agent-bridge 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| claude_remote_mcp_agent_bridge-0.2.0.tar.gz | 145.6 kB | With provenance | Details for claude_remote_mcp_agent_bridge-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| claude_remote_mcp_agent_bridge-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for claude_remote_mcp_agent_bridge-0.2.0-py3-none-any.whl |
Total release size: 235.0 kB
Release files / claude_remote_mcp_agent_bridge-0.2.0.tar.gz
| Download URL | claude_remote_mcp_agent_bridge-0.2.0.tar.gz |
|---|---|
| Size | 145.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
df10dac8e6a67e8bc84aabba0b0b2f434801e0f9db7bb07d25cac0cc95784547
|
|
BLAKE2b-256 checksum How to use checksums |
43a7daf0f3ece99433ac18decf8af8efa9ec5f6bcdbe560ab99a2e13d24602f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / claude_remote_mcp_agent_bridge-0.2.0-py3-none-any.whl
| Download URL | claude_remote_mcp_agent_bridge-0.2.0-py3-none-any.whl |
|---|---|
| Size | 89.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cd5f86356760f1eb28087abf0f7efaa7757d41fca67538b8309f43907c7d0a89
|
|
BLAKE2b-256 checksum How to use checksums |
18908e43436ed557395eebc2ada0d3f63e4e9e0a144bddf7057561dede9d963d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for claude-remote-mcp-agent-bridge 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for claude_remote_mcp_agent_bridge-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.