--- title: "Run Herdr agents on a remote machine" description: "Add an exe.dev VM to Herdr as an SSH machine: Claude Code, Codex, Pi and OpenCode keep running there after your laptop closes, with no API keys." url: https://exe.dev/deploy/herdr category: "AI agents" updated: 2026-10-31 --- # Run Herdr agents on a remote machine An always-on SSH machine for Herdr, with agents ready and no API keys. - **Software:** Herdr (https://herdr.dev) - **Source:** https://github.com/herdrdev/herdr-app - **License:** Apache-2.0 - **Time:** 5 minutes - **Example VM name:** `my-herdr` (yours will differ; on the VM, `hostname` prints it) - **Machine-readable:** https://exe.dev/deploy/herdr/manifest.json ## What you get - herdr-core (`hc`) and Herdr TUI installed on the VM, so Herdr on your computer can add it as a machine - Claude Code, Codex, Pi and OpenCode using exe.dev's LLM integration, with no API key to paste - Herdr's status integrations for those four agents - A Git project at `~/project` - A Claude Code run through `hc` that answers `OK` Running on the VM: - **herdr-core (hc)**: the runtime the Herdr app uses on each machine; a systemd user service, data in `~/.local/state/herdr-core` - **Herdr TUI**: the original terminal app, with its own server, data in `~/.config/herdr` - **Claude Code, Codex, Pi and OpenCode**: preinstalled; connected to exe.dev's LLM integration, data in `~/.claude, ~/.codex, ~/.pi, ~/.config/opencode` - **Your project**, data in `~/project` How it is reached: - ssh my-herdr.exe.xyz (private): how Herdr reaches the VM, and your terminal ## Deploy with Shelley Open https://exe.dev/new?prompt=Set%20up%20Herdr%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe.dev%2Fdeploy%2Fherdr.md%20from%20top%20to%20bottom.%0A%0AThe%20recipe%27s%20example%20VM%20name%20is%20my-herdr.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-herdr.%20Skip%20the%20step%20that%20creates%20the%20VM%3B%20you%20are%20on%20it.%0A%0AYou%20are%20done%20when%20all%20of%20these%20are%20true.%20Check%20each%20one%20yourself%3A%0A-%20herdr-core%20%28%60hc%60%29%20and%20Herdr%20TUI%20installed%20on%20the%20VM%2C%20so%20Herdr%20on%20your%20computer%20can%20add%20it%20as%20a%20machine%0A-%20Claude%20Code%2C%20Codex%2C%20Pi%20and%20OpenCode%20using%20exe.dev%27s%20LLM%20integration%2C%20with%20no%20API%20key%20to%20paste%0A-%20Herdr%27s%20status%20integrations%20for%20those%20four%20agents%0A-%20A%20Git%20project%20at%20%60~%2Fproject%60%0A-%20A%20Claude%20Code%20run%20through%20%60hc%60%20that%20answers%20%60OK%60%0A%0ARun%20the%20VM-side%20commands%20in%20%22Set%20up%20the%20VM%22%20only%3B%20skip%20creating%20the%20VM.%0AIf%20%60exeuntu%20configure%60%20reports%20an%20existing%20user%20config%2C%20leave%20it%20alone.%0AIf%20%60~%2F.config%2Fopencode%2Fopencode.json%60%20already%20exists%2C%20add%20the%20%60model%60%0Aand%20%60providers%60%20settings%20to%20it%20instead%20of%20replacing%20it.%20Do%20not%20start%0Ainteractive%20agents%20or%20%60herdr%60.%20Verify%20with%20the%20checks%20at%20the%20end%20of%20that%0Asection%3A%20both%20versions%20print%2C%20%60herdr%20integration%20status%60%20lists%20claude%2C%0Acodex%2C%20pi%20and%20opencode%20as%20%60current%60%2C%20and%20the%20%60hc%20run%60%20check%20prints%20%60OK%60.%0ASkip%20the%20later%20sections%20and%20the%20FAQ.%20Finish%20by%20telling%20the%20owner%20to%20add%0A%60%3Cthis%20VM%27s%20name%3E.exe.xyz%60%20in%20the%20Herdr%20app%20%28%22Add%20it%20to%20Herdr%22%29%2C%20or%20to%20run%0A%60ssh%20-t%20%3Cthis%20VM%27s%20name%3E.exe.xyz%20herdr%60%20for%20Herdr%20TUI.%0A%0AFinish%20with%20the%20URLs%20I%20should%20open.%0A to create a VM whose agent, Shelley, follows this recipe. From a terminal: ```sh curl -fsSL https://exe.dev/deploy/herdr/prompt.txt | ssh exe.dev new --prompt=/dev/stdin ``` Or follow the steps below by hand. [Herdr](https://herdr.dev) puts your coding agents in one window and tells you which one needs you. Its terminals live in a small runtime, [herdr-core](https://github.com/herdrdev/herdr-core), not in the window, and any machine you can reach over SSH can join the sidebar. Make that machine an exe.dev VM and the agents keep working when your laptop sleeps: the VM is always on, its disk is persistent, and SSH works from the moment it exists. The VM comes with Claude Code, Codex, Pi and OpenCode. Here they use exe.dev's [LLM integration](/docs/integrations-llm): no API keys on the VM, and model usage billed to your exe.dev account. ## 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: ```bash 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: ```bash 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: ```bash 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`: ```bash 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](https://herdr.dev) 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: ```bash 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: ```bash 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: ```bash 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 `, 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](/docs/integrations-github) and clone it with `git clone https://github.int.exe.xyz//.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](/docs/sharing). - **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): ```bash 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: ```bash 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](https://github.com/herdrdev/herdr-core/blob/main/docs/machines.md) and the [Herdr TUI docs](https://herdr.dev/tui/docs/connecting-machines/). ## Frequently asked questions ### Does the Herdr app run on the VM? No. The app is a desktop program for macOS, Linux and Windows; it runs on your computer and adds the VM as a machine over SSH. The VM runs herdr-core, which owns the terminals, so it needs no desktop. ### Herdr app or Herdr TUI? Either; this VM has both. The app is built on herdr-core; Herdr TUI is the original terminal app, with its own server. They don't share agents: what you start in one doesn't show up in the other. Herdr TUI also works from a phone's SSH app. ### Can I use my own Claude or ChatGPT subscription? Yes. On the VM, run `claude auth login` or `codex login` after removing what `exeuntu configure` added: `apiKeyHelper` and `env.ANTHROPIC_BASE_URL` in `~/.claude/settings.json`, and the `exe-llm` provider in `~/.codex/config.toml`. Keep the `hooks` entries Herdr added. ### How much does it cost? Herdr is free and open source (Apache-2.0). You pay for the VM as part of your exe.dev plan, and model usage through the [LLM integration](/docs/integrations-llm) is billed to your exe.dev account. exe.dev keeps a [list of models and prices](/llm-gateway-models). ### Does anything listen on the internet? No. herdr-core and Herdr TUI listen on Unix sockets on the VM, and Herdr reaches them through SSH with your exe.dev key. Adding the VM to Herdr gives that computer the same access as a shell on the VM. ## Related - [Run T3 Code on a remote server](https://exe.dev/deploy/t3code.md): Your coding agents on an always-on VM, steered from your phone. - [Run Claude Code on a remote server](https://exe.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop. - [Run Codex on a remote server](https://exe.dev/deploy/codex.md): A computer for Codex. An early night for your laptop. - [Run OpenCode on a remote server](https://exe.dev/deploy/opencode.md): Every model, one VM, and an agent that works while your laptop sleeps. - [Run the Pi coding agent on a remote server](https://exe.dev/deploy/pi.md): An agent that doesn't ask first, on a computer that can take it. - [Host OpenClaw](https://exe.dev/deploy/openclaw.md): An AI sidekick with its own computer. Your laptop can take a nap.