Run Herdr agents on a remote machine

Set up the VM#

On your computer, create a VM and connect once, which also saves its host key for Herdr. Pick any free name; if you've already clicked Deploy or have a VM, skip the first command and use its name:

ssh exe.dev new --name=my-herdr
ssh my-herdr.exe.xyz

On the VM, connect the agents to the LLM integration. OpenCode gets its latest release first:

exeuntu configure claude
exeuntu configure codex
sudo exeuntu update opencode
mkdir -p ~/.config/opencode
cat > ~/.config/opencode/opencode.json <<'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "providers": {
    "anthropic": { "settings": { "baseURL": "https://llm.int.exe.xyz/anthropic/v1" } },
    "openai": { "settings": { "baseURL": "https://llm.int.exe.xyz/openai/v1" } },
    "fireworks-ai": { "settings": { "baseURL": "https://llm.int.exe.xyz/fireworks/inference/v1" } }
  }
}
EOF

Pi needs nothing: the first time it starts, choose Use exe.dev LLM integration.

Still on the VM, install herdr-core and Herdr TUI with their official installers. Both put a single binary in ~/.local/bin; the links make them work in one-off SSH commands too, whose PATH leaves that folder out. Then install Herdr TUI's status integrations and make a project, a Git repository so you can review and undo what the agents change:

curl -fsSL https://releases.herdr.dev/core/install.sh | sh
curl -fsSL https://herdr.dev/install.sh | sh
sudo ln -sf ~/.local/bin/herdr-core /usr/local/bin/hc
sudo ln -sf ~/.local/bin/herdr /usr/local/bin/herdr
for agent in claude codex pi opencode; do herdr integration install $agent; done
git init ~/project

Check it. Both versions print, the four integrations say current, and Claude Code, run in an hc terminal, answers OK:

hc --version && herdr --version
herdr integration status | grep -E '^(claude|codex|pi|opencode):'
cd ~/project && hc run -- claude -p --model haiku "Reply with exactly: OK"

Add it to Herdr#

On your computer, install the Herdr app if you haven't. Open Add machine from the sidebar (or Settings → Machines), type my-herdr.exe.xyz, and add it. It joins the sidebar as my-herdr. herdr-core is already on the VM, so there is nothing to install; if Herdr asks anyway, let it copy its own build over.

Open a space on my-herdr in ~/project and start an agent from the + menu. The first run of each agent asks a question or two: Claude Code for a theme and whether you trust the folder, Codex whether you trust it, and Pi whether to use exe.dev's LLM integration. Then give it a task, such as:

Write index.html: a one-page site for a very opinionated cat. Keep it short.

The agent runs on the VM, and the sidebar shows when it's working, done, or waiting for you; all four agents report their status to Herdr. Close the window or the laptop, and it carries on.

The same works from a terminal on your computer with hc, which the app installs:

hc machine add my-herdr.exe.xyz
hc run --bg --on my-herdr --cwd project --name cat claude
hc attach my-herdr/cat

Ctrl+\ detaches and leaves the agent running; hc ls lists the VM's terminals beside your own.

Prefer Herdr TUI?#

Herdr TUI, the original terminal app, runs on the same VM. Start it there, like tmux, from any SSH client, including one on your phone:

ssh -t my-herdr.exe.xyz herdr

ctrl+b q detaches; the panes keep running. With Herdr TUI on your computer, you can instead attach with your local keys and theme, or keep the VM in the sidebar beside your local work:

herdr --remote my-herdr.exe.xyz
herdr machine add my-herdr.exe.xyz --label my-herdr

Herdr TUI and the app keep separate agents: what you start in one doesn't show up in the other.

What keeps running#

• Laptop closed, window quit, Wi-Fi gone: everything on the VM keeps running. Herdr reconnects on its own when your computer comes back.
• The VM restarts: running programs stop; your files don't. When Herdr reconnects, herdr-core brings back terminals you marked to keep (hc keep <terminal>, or hc run --keep) as fresh shells in the same folders. Herdr TUI restores its layout when you reattach and resumes the Claude Code, Codex, Pi and OpenCode conversations that were open.
• Updates: hc update and herdr update leave running terminals alone.

Make yourself at home#

• Bring your code: connect a GitHub repo and clone it with git clone https://github.int.exe.xyz/<owner>/<repo>.git. The VM pushes and pulls without a token or SSH key on it.
• Preview what it builds: ask the agent to serve the app on 0.0.0.0:8000, then open https://my-herdr.exe.xyz/. It's private until you share it.
• Shelley is there too: exe.dev's own agent, at https://my-herdr.shelley.exe.xyz/, can start agents with hc (ask it to read hc --skill first), and they appear in your Herdr sidebar.

Back up and restore#

Commit and push your code; that's the copy that matters most. For a copy of the whole VM, agents' histories included, run this on your computer (choose a free backup name):

ssh exe.dev cp my-herdr my-herdr-backup

To use the copy, add my-herdr-backup.exe.xyz to Herdr as another machine.

Update#

On the VM:

hc update
herdr update
sudo exeuntu update claude
sudo exeuntu update codex
sudo exeuntu update opencode
exeuntu update pi

The Herdr app updates itself on your computer. Versions don't have to match: the app and the VM's herdr-core work out what they can do together.

Troubleshooting#

• The machine shows Attention or won't connect. Run ssh my-herdr.exe.xyz on your computer first: Herdr needs a login without a password prompt, and it can't accept a new host key for you. Then hc machine ls shows the state, and hc machine login my-herdr reconnects. For Herdr TUI, use herdr machine status.
• The connection closes at once. Something prints text in a non-interactive login; Herdr's connection carries a byte protocol. Check that ssh my-herdr.exe.xyz true prints nothing.
• An agent doesn't answer. On the VM, claude -p "Reply with exactly: OK" and codex exec "Reply with exactly: OK" show whether the agents work on their own; rerun exeuntu configure claude or exeuntu configure codex, then herdr integration install codex, if not.
• An agent has no status in the sidebar. Update it (see Update); older versions don't report their status. In Herdr TUI, check herdr integration status.
• Logs: herdr-core's are core.log and holder.log in ~/.local/state/herdr-core/default/; Herdr TUI's is ~/.config/herdr/herdr-server.log.

For everything else, see Herdr's machine docs and the Herdr TUI docs.