Herdr Plugin Setup

Herdr is a terminal workspace manager for coding agents. The Upstash Box plugin runs your agent inside a box instead of on your machine: focus a pane in a Git worktree, start an agent, and the plugin uploads that worktree to a new box and opens the agent in a new pane.

Your local files are never edited directly. Changes come back when you run Apply changes and approve the patch.

1. Install the plugin#

Needs Herdr 0.8.0 or newer and Node.js 22 or newer. Have an Upstash Box API key ready for setup.

herdr plugin install upstash/herdr-upstash-box

2. Set up#

herdr plugin action invoke setup --plugin upstash.box

A popup asks for your Upstash Box API key and checks it before going on, then asks which agent to run and which provider credential, and saves the answers for you. Keys are typed without echo. For the Claude subscription, your browser opens to approve claude setup-token and the token is captured for you, then checked before it is saved.

Everything setup wrote lives in the directory printed by herdr plugin config-dir upstash.box, and every setting is listed in the plugin README.

3. Start an agent#

Focus a Herdr pane inside a Git worktree, then run:

herdr plugin action invoke start-agent --plugin upstash.box

The command only confirms in your terminal. The new pane opens in Herdr.

The plugin lists the files it will upload, creates the box, unpacks the worktree, and opens the agent. Credentials and .env files are left out of the upload, and every excluded file is shown with its reason first. Use excludedPaths to leave more out and allowSensitivePaths to keep something the filter would drop.

Bind it to a key so this is one keystroke:

[[keys.command]]key = "prefix+shift+u"command = "herdr plugin action invoke start-agent --plugin upstash.box"

To start on a different agent for one launch without editing config.json, use start-claude, start-codex, or start-opencode in place of start-agent.

4. Use the agent#

herdr plugin action invoke reconnect --plugin upstash.boxherdr plugin action invoke apply-changes --plugin upstash.boxherdr plugin action invoke info --plugin upstash.boxherdr plugin action invoke stop --plugin upstash.box

You can close the agent pane at any time and the agent keeps working. Reconnect brings it back, resuming the box first if it paused while you were away.

Apply changes exports what the agent changed as a Git patch, checks it against your worktree, and applies it after you approve.

Info shows the box status and paths. Stop ends the session and keeps the box.

5. Manage boxes#

herdr plugin action invoke pause --plugin upstash.boxherdr plugin action invoke resume --plugin upstash.boxherdr plugin action invoke snapshot --plugin upstash.boxherdr plugin action invoke previews --plugin upstash.boxherdr plugin action invoke delete-box --plugin upstash.boxherdr plugin action invoke dashboard --plugin upstash.box

Boxes pause on their own when idle. Snapshot saves the box state, and Previews exposes a configured port with a public URL.

The dashboard lists every box with its worktree, agent, and live status, and runs any action on the selected row:

[j/k] Select  [enter/r] Reconnect  [a] Apply  [i] Info  [s] Stop  [p] Pause  [u] Resume[n] Snapshot  [f] Fork  [v] Previews[d] Delete  [R] Refresh  [q] Close

Delete boxes from here rather than from the Upstash console, so the plugin forgets them too.

Troubleshooting#

The upload is too large. Uploads are capped at 100 MiB in total and 10 MiB per file, and Box rejects anything over 100 MB, so raising maxUploadBytes will not get you past it. The error names the heaviest directories. Exclude them:

{ "excludedPaths": ["img", "public/video"] }

Claude Code answers 401 OAuth access token is invalid. The token in secrets.json is wrong, which setup normally catches before saving. Run setup, press r at the credential prompt to get a new one, then run stop and reconnect so the agent restarts with it.

A second Start is refused. One box per worktree is the default. Reconnect to the existing box, or delete it from the dashboard, then start again.

An action says another popup is already open. Herdr shows one popup at a time. Close it and try again.

Next steps#