Herdr sandbox: run each coding agent pane in a CreateOS microVM

Herdr sandbox: run each coding agent pane in a CreateOS microVM

To run a Herdr sandbox on CreateOS, sign in with createos login, run createos sandbox setup herdr, then open Herdr in a git worktree and press prefix+shift+s. The plugin creates a sandbox, uploads your worktree, installs the coding agent inside it and attaches the agent's terminal to a new Herdr pane. One pane maps to one sandbox.

This is for developers who run Claude Code, Codex, OpenCode, Pi or Cursor in Herdr and want each agent's commands and edits to run in a CreateOS Sandbox instead of on their own machine. Each sandbox is a Firecracker microVM with its own guest kernel, filesystem and network identity.

Herdr is a separate project. The CreateOS Sandbox plugin for Herdr is maintained by CreateOS and is not a Herdr product.

Key takeaways

• You need the createos CLI v0.0.26 or newer, Herdr 0.7.5 or newer, Bun and a git worktree.
• The agent runs inside the sandbox, VM-isolated from your laptop, and Herdr still shows each pane as working, waiting or idle.
• Outbound network access is open until you add an egress list to the plugin config.
• An idle sandbox pauses itself after 30 minutes by default.

What does the CreateOS plugin change in Herdr?

It moves the coding agent itself into a sandbox, while Herdr stays on your machine as the control room. The usual arrangement runs the agent locally and sends work to a sandbox. This plugin does the reverse (Herdr integration docs).

Your keystrokes go into the microVM and the agent's output comes back. To bring the agent's work home, the apply action exports a Git patch from the sandbox and applies it locally.

For background, read what an AI agent sandbox is.

How do I set up a Herdr sandbox with CreateOS?

Four steps take you from no CLI to an agent running in a sandbox pane. You need macOS or Linux and a CreateOS account, plus the tools listed above.

Step 1: How do I install the createos CLI?

Copy the installer command from the Prerequisites section of our docs. You need createos CLI v0.0.26 or newer, because createos sandbox setup herdr first shipped in that release.

If createos sandbox --help does not list setup, run the installer again to upgrade in place.

Step 2: How do I sign in to CreateOS?

Run this at a terminal:

createos login

For CI or headless use, set an API key instead with export CREATEOS_API_KEY=<key>.

Step 3: How do I install the Herdr plugin?

Run one command:

createos sandbox setup herdr

It checks that you are signed in and that Herdr, Bun and git are present. Then it installs the plugin, writes config.json and adds keybindings to Herdr's config.toml, after backing that file up. Add --doctor to check without changing anything, or --agent codex to pick a different agent.

Step 4: How do I start an agent in a sandbox?

Open Herdr in a git worktree and press prefix+shift+s. The plugin opens a new pane, creates a sandbox, uploads your worktree, makes a baseline git commit inside the box, installs the agent and attaches the agent's terminal to the pane.

Sign the agent in within that pane the first time it opens. If anything fails after the sandbox exists, the plugin deletes it. Two other keys matter: prefix+shift+a applies the sandbox's changes locally, and prefix+shift+x deletes the pane's sandbox (press it twice to confirm).

Which credentials go where?

Your CreateOS credentials stay on your machine, and the agent's own provider key goes inside the sandbox. Mixing them up is the most common setup mistake (Two sets of credentials).

Do not put the agent's key in the plugin's config.json, and do not export it expecting it to reach the box.

What does the plugin upload from my worktree?

It uploads the files git knows about, minus submodules, your excludes, a credential deny-list and anything git ignores. The deny-list covers .env files, SSH and GPG directories, cloud and Kubernetes credentials, .npmrc, .git-credentials, private keys and Terraform state.

It matches file names, not contents, so a secret inside an ordinary source file will be uploaded. Treat the sandbox as holding a copy of your working tree (What gets uploaded).

How do I stop the agent's sandbox from reaching the internet?

Add an egress list to the plugin's config.json, because outbound traffic is open until you do. Once any rule is set, only listed destinations pass. Everything else is dropped in-kernel on the host, outside the VM, and code inside the sandbox cannot change that (Limits and defaults).

Print the config directory with herdr plugin config-dir createos.sandbox, then edit config.json there:

{
  "agent": "claude-code",
  "autoPause": "30m",
  "egress": ["registry.npmjs.org", "github.com"]
}

The plugin installs the agent inside the box with the agent's own installer, so your allowlist has to let that installer through. In the live checks recorded in the plugin's README, a start whose agent install failed under a restrictive egress list deleted its own sandbox.

The Egress API docs list every rule format. For why the kernel boundary matters, read when a coding agent needs a microVM.

What are the limits of the Herdr plugin?

The main limits are the account box cap, the default shape and pane mappings that do not survive every move.

• Box cap. Each pane is one sandbox. Your account caps how many sandboxes exist at once, paused ones included. A create over the cap fails rather than queueing, and only deleting a sandbox frees a slot (concurrency limits).
• Default shape. The plugin defaults to s-2vcpu-4gb (2 vCPU, 4 GiB). If your account's largest shape is smaller, pass a smaller --shape.
• Auto-pause. An idle sandbox pauses after 30 minutes by default and keeps its disk. The attach action resumes it.
• Pane mapping. Herdr restores panes after a restart but not their processes, so use attach to reconnect. The mapping is keyed by pane ID, so moving a pane to another workspace loses it.

For the isolation model underneath, see microVM isolation for AI agents.

When do I not need this?

If you want the agent to keep running on your own machine, the Claude Code, Codex, OpenCode and Pi integrations run the same agents locally instead. They are listed in the Sandbox integrations docs. If you do not use Herdr, this plugin adds nothing.

Common questions

How do I run Claude Code in a Herdr sandbox?

Install the createos CLI, run createos login, then run createos sandbox setup herdr. Claude Code is the default agent. Open Herdr in a git worktree, press prefix+shift+s, and sign Claude Code in within the new pane.

Which coding agents does the CreateOS Herdr plugin support?

The plugin runs Claude Code, Codex, OpenCode, Pi and Cursor inside the sandbox. It can also open a plain shell. Pick one with --agent at setup or the agent key in config.json.

Which createos CLI version does the Herdr setup command need?

You need createos CLI v0.0.26 or newer, because createos sandbox setup herdr first shipped in that release. Run createos sandbox --help, and if setup is not listed, run the installer again to upgrade in place.

Can the agent in a Herdr sandbox reach the internet?

Yes, by default. Outbound traffic is open until you add an egress list to the plugin's config.json. Once any rule is set, only listed destinations pass, and everything else is dropped in-kernel on the host, outside the VM.

How do I get the agent's changes back to my local worktree?

Press prefix+shift+a to run the apply action. It exports a Git patch from the sandbox and applies it locally after git apply --check passes. Each apply carries only work done since the last one.

What happens to an idle Herdr sandbox?

It pauses after 30 minutes with no activity by default. Pause snapshots the box and keeps its disk. Press prefix+shift+c to attach, which resumes the box and restarts the agent if it has died. Change the timeout with --auto-pause or autoPause.

Next step

The Herdr integration page has the installer, every config key and the known issues. Open the CreateOS Sandbox docs for Herdr and start your first sandbox pane.

About CreateOS

CreateOS runs AI agents and the code they write. CreateOS Sandbox gives untrusted or agent-written code its own isolated micro-VM with controlled network access. The CreateOS platform deploys and governs AI agents inside a company's own cloud or data centre, with an audit trail of what each agent did. Start at createos.sh.