Provides a native Hermes Agent plugin with tools and slash commands for listing machines and agents, spawning background agents, prompting active agents, reading agent output, and checking Herdr node status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@herdr-mcp-server Start a background Herdr session to run npm test."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Multi-machine fleet orchestration CLI and universal agent skill for the Herdr terminal multiplexer.
When coordinating AI coding agents (Pi, Claude Code, OpenCode, Codex, Cursor, Hermes, Antigravity) across multiple machines—local laptops, workstations, GPU boxes, and server instances—knowing which agent is running where, what project directory it occupies, and its execution state is critical.
Herdr Agent Gateway provides a unified command-line executable (herdr-agent-gateway) and a universal Agent Skill:
Native OpenSSH Multiplexing: Built directly upon Herdr's native SSH coordination engine (herdr --machine <target>). No custom HTTP daemons, no custom listening ports, and no extra tokens to manage.
Cluster-Wide Agent Overview: Displays all active agents across local and saved SSH machines with agent kind, lifecycle status, workspace label, terminal title, working directory (cwd), and task description.
Multi-Machine Agent Spawning & Prompting: Split panes and launch agents (local or remote) with initial tasks, prompt injection, and screen output reading.
Universal Agent Skill: A single skill readable by any LLM agent harness (Pi, Hermes, Claude, OpenCode, Antigravity) without needing custom agent-specific plugins.
Related MCP server: pty-mcp
flowchart TD
subgraph Agents["AI Coding Agents"]
PiAgent["Pi Coding Agent (pi)"]
HermesAgent["Hermes (in Podman)"]
ClaudeAgent["Claude Code / OpenCode"]
end
subgraph Skill["Universal Skill"]
SkillDef["skill:herdr-agent-gateway"]
end
subgraph CLI["Gateway CLI Tool"]
GatewayCLI["herdr-agent-gateway<br/>(machines | overview | spawn | prompt | read | status)"]
end
subgraph LocalHerdr["Local Machine (Herdr Multiplexer)"]
LocalDaemon["Herdr Daemon API<br/>(~/.config/herdr/herdr.sock)"]
LocalPanes["Local Panes & Agents<br/>(pi, claude, opencode)"]
end
subgraph RemoteMachines["Remote SSH Machines (Herdr)"]
Server1["server1<br/>(herdr --machine server1)"]
Predator["pikujs-predator<br/>(herdr --machine pikujs-predator)"]
end
Agents -->|"loads"| SkillDef
SkillDef -->|"executes"| GatewayCLI
GatewayCLI -->|"calls"| LocalDaemon
LocalDaemon --> LocalPanes
LocalDaemon -->|"Multiplexed OpenSSH<br/>(ControlPersist 600)"| Server1
LocalDaemon -->|"Multiplexed OpenSSH<br/>(ControlPersist 600)"| Predatorherdr-agent-gateway)machines)# Formatted table
herdr-agent-gateway machines
# Structured JSON
herdr-agent-gateway machines --json
# Probe live connection status of each node
herdr-agent-gateway machines --probeoverview)# Pretty terminal overview table
herdr-agent-gateway overview
# Detailed view (includes task description and pane ID)
herdr-agent-gateway overview -d
# Filter by machine
herdr-agent-gateway overview --machine pikujs-server-1
# Structured JSON output
herdr-agent-gateway overview --jsonspawn)Split a pane and start a coding agent on local or any remote machine:
# Spawn Pi agent locally
herdr-agent-gateway spawn --kind pi --name my-agent --cwd /home/pikujs/Projects/app
# Spawn Claude Code on remote machine with initial prompt and wait:
herdr-agent-gateway spawn \
--kind claude \
--name refactor-agent \
--machine pikujs-server-1 \
--cwd /srv/projects/api \
--prompt "Refactor user authentication module" \
--waitprompt)herdr-agent-gateway prompt my-agent "Run unit tests and fix errors" --waitread)herdr-agent-gateway read my-agent --lines 50status)herdr-agent-gateway status
herdr-agent-gateway status --machine pikujs-server-1The repository includes a ready-to-use skill at skills/herdr-agent-gateway/SKILL.md.
For Pi Coding Agent: Discovered automatically if placed or linked into ~/.agents/skills/herdr-agent-gateway or ~/.pi/agent/skills/.
For Hermes Agent: Bind-mount into /home/hermes/.hermes/skills/herdr-agent-gateway.
For Claude Code / OpenCode / Antigravity: Standard ~/.agents/skills/ directory.
Add herdr-agent-gateway to your flake inputs and import the module:
{
imports = [ herdr-agent-gateway.homeManagerModules.default ];
services.herdr-agent-gateway = {
enable = true;
skill.enable = true; # Links skill into ~/.agents/skills/herdr-agent-gateway
};
}Herdr manages saved remote machines via ~/.local/state/herdr/client/endpoints.json. In your NixOS/Home Manager herdr module (modules/home/herdr.nix), you can declaratively provision these endpoints:
{ pkgs, herdr, herdr-agent-gateway, host, ... }:
let
clusterNodes = [
{ name = "server1"; label = "pikujs-server-1"; target = "pikujs@pikujs-server-1.local"; }
{ name = "pikujs-mini"; label = "pikujs-mini"; target = "pikujs@pikujs-mini.local"; }
{ name = "pikujs-predator"; label = "pikujs-predator"; target = "pikujs@pikujs-predator.local"; }
];
remoteMachines = builtins.filter (n: n.name != host) clusterNodes;
in
{
imports = [ herdr-agent-gateway.homeManagerModules.default ];
home.packages = [ herdr.packages.${pkgs.system}.default ];
services.herdr-agent-gateway.enable = true;
xdg.stateFile."herdr/client/endpoints.json".text = builtins.toJSON {
version = 1;
ssh = map (m: {
id = builtins.hashString "md5" "${m.target}-default";
label = m.label;
target = m.target;
session = "default";
enabled = true;
}) remoteMachines;
};
}To allow Hermes in a Podman container to control the fleet via the host's Herdr socket:
container.extraVolumes = [
# Bind mount host Herdr config & socket dir:
"/home/pikujs/.config/herdr:/home/hermes/.config/herdr"
# Bind mount CLI tools:
"${herdr.packages.${pkgs.system}.default}/bin/herdr:/usr/local/bin/herdr:ro"
"${herdr-agent-gateway.packages.${pkgs.system}.default}/bin/herdr-agent-gateway:/usr/local/bin/herdr-agent-gateway:ro"
# Bind mount skill:
"${herdr-agent-gateway.packages.${pkgs.system}.default}/share/agents/skills/herdr-agent-gateway:/home/hermes/.hermes/skills/herdr-agent-gateway:ro"
];~/.config/herdr/config.toml)To open the multi-machine agent overview in a temporary Herdr pane with a single keybinding, add to ~/.config/herdr/config.toml:
[[keys.command]]
key = "prefix+alt+o"
type = "pane"
command = "herdr-agent-gateway overview -d"
description = "fleet agent overview"MIT © 2026 PikuJS & contributors
This server cannot be deployed
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
On-demand GPU nodes for agents: create nodes, run commands, and submit jobs, billed by the minute.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
