Herdr

Herdr is a terminal workspace manager. This plugin inverts the usual arrangement: instead of running an agent locally and sending work to a sandbox, it runs the agent itself inside a sandbox and attaches its terminal to a Herdr pane.

One pane maps to one sandbox. Your keystrokes go into the microVM; the agent's output comes back. Herdr stays the local control room and can still tell you whether each pane is working, waiting, or idle.

At a glance

Plugin: createos.sandbox
Agents: Claude Code, Codex, OpenCode, Pi, Cursor
Requires: Herdr 0.7.5 or newer, Bun, a git worktree
Auth: createos login, and the agent signs in inside its own sandbox

Prerequisites

Install the createos CLI:

Bash
1curl -sfL https://raw.githubusercontent.com/NodeOps-app/createos-cli/main/install.sh | sh -

Then authenticate. At a terminal, sign in:

Bash
1createos login

For CI or headless use, set an API key instead:

Bash
1export CREATEOS_API_KEY=<key>

You also need Herdr 0.7.5 or newer, Bun, and a git worktree.

Two sets of credentials

This integration involves two, and mixing them up is the most common setup mistake.

Your CreateOS credentials live on your machine. They are what creates and manages the sandbox, and they are what createos login sets up.

The agent's own credentials — its Anthropic, OpenAI, or other provider key — belong inside the sandbox. Sign the agent in within its own pane the first time you start it. Do not put them in the plugin's config.json, and do not export them expecting them to reach the box.

Install

The quickest route is the CLI's setup command, which checks prerequisites, installs the plugin, writes a config, and binds keys:

Bash
1createos sandbox setup herdr

Add --doctor to check without changing anything.

To install manually:

Bash
1herdr plugin install NodeOps-app/createos-claude-plugins/packages/herdr-plugin

For local development, link the directory and then build it — linking alone does not run the build:

Bash
1herdr plugin link /path/to/packages/herdr-plugin
2sh /path/to/packages/herdr-plugin/build.sh

How a pane becomes a sandbox

Starting the plugin from a pane opens a new pane and provisions into it: a sandbox is created, your worktree is uploaded, a baseline git commit is made inside the box, the agent is installed, and its process starts under a PTY that is then attached to the pane.

If anything fails after the sandbox exists, the sandbox is deleted. If that cleanup itself fails, you get the createos sandbox rm command to run yourself.

Provisioning takes around twenty seconds, and a second key press during that window is ignored rather than starting a second sandbox.

Herdr restores panes when it restarts, but not the processes inside them. Use the attach action to reconnect a pane to its sandbox — it will resume a paused box and restart the agent if it has died.

The pane-to-sandbox mapping is keyed by pane ID, so moving a pane to another workspace loses the mapping.

Configuration

Settings live in config.json in the plugin's config directory, which herdr plugin config-dir createos.sandbox will print.

Key	Default	Purpose
`agent`	`claude-code`	Which agent to run in the box
`shape`	`s-2vcpu-4gb`	Machine size
`rootfs`	—	Base image or template
`autoPause`	`30m`	Idle timeout before the box pauses itself
`remoteRoot`	`/workspace`	Where the worktree lands inside the box
`egress`	—	Allowed hosts; empty means unrestricted
`excludes`	—	Paths to leave out of the upload
`syncExcludes`	—	Paths to leave out of file sync

An unrecognised key is an error rather than a silent no-op.

Do not put tokens in this file — see Two sets of credentials above.

What gets uploaded

The upload is built from the files git knows about, then filtered — submodules, then your own excludes, then a built-in deny-list, then anything git ignores.

The deny-list covers the usual credential shapes: .env files (though .env.example and similar templates are allowed through), SSH and GPG directories, cloud credentials for AWS, GCP, Azure, Kubernetes and Docker, .netrc, .npmrc, .pypirc, .git-credentials, private keys and certificate bundles, and Terraform state.

Treat this as a safety net, not a guarantee. It matches names, not contents — a credential in a file it does not recognise will be uploaded.

Sync

The start action does not need SSH or file sync. The separate sync action does: it needs an SSH key in the sandbox and downloads Mutagen the first time it runs, so expect a delay on first use.

Known issues

On createos CLI v0.0.24 and earlier, pause and resume fail with a Content-Length is required error. Rely on autoPause instead, or upgrade the CLI.
The CLI resolves a sandbox by scanning only the first 200 rows of your sandbox list. A box outside that window reports as missing even when you give its full ID. This affects every action.