DX-3020: add the Herdr plugin setup guide by alitariksahin · Pull Request #833 · upstash/docs

alitariksahin · 2026-09-09T19:55:10Z

Adds box/guides/herdr-setup.mdx, "Herdr Plugin Setup", and wires it into the Box Guides nav.

Herdr is a terminal workspace manager for coding agents. The plugin puts the agent in an Upstash Box instead of on your laptop: focus a pane in a Git worktree, invoke one action, and you get a box with a filtered copy of that worktree and your agent running in it. Changes come back as a checked Git patch only when you approve them.

Structure

Numbered steps, matching the other Box setup guides:

Requirements
Install the plugin
Add your keys
Choose a mode, TUI or native
Start an agent, including what does and does not get uploaded
Work with the agent: reconnect, apply, info, stop
Manage the box: pause, resume, snapshot, fork, previews, delete, and the dashboard
Server-side typed runs and schedules

Then troubleshooting and next steps.

How it was checked

Written from the plugin source rather than its README, then walked end to end against real boxes in a live Herdr session:

herdr plugin install upstash/herdr-upstash-box builds and prunes as described
Start uploaded 66 files and excluded 3, and the agent opened at the configured remote root with no trust dialog
closing the pane and reconnecting returned the live session
a second Start was refused with mapping_exists
an action hitting an open popup reported herdr_popup_open

That run also surfaced a plugin bug, fixed separately in upstash/herdr-upstash-box#1: an unanswered popup used to block every other action forever. The guide's two-minute claim is accurate as of that fix.

Two details come from what the live run showed rather than from the code alone: Reconnect is a genuine live reattach when the box has not paused, and the upload filter reads file content, so credential-shaped test fixtures are excluded as detected-secret.

Note

The install command needs upstash/herdr-upstash-box to be public. It is now, so the command and the source links resolve.

🤖 Generated with Claude Code

Covers running several coding agents at once, each in its own Upstash Box, and managing and monitoring them from the plugin dashboard: fanning out across Git worktrees, running a different agent and model per box, the dashboard columns and keys, scheduled and typed server-side runs, cost control, and collecting each agent's work back as a checked patch. Written against the plugin source rather than its README, and walked end to end against real boxes: install, start, the upload filter, reconnect, the second Start refusal, and the one-popup-at-a-time rule all behave as described. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

linear-code · 2026-09-09T19:55:14Z

DX-3020

context7 · 2026-09-09T19:55:18Z

Docs7 for upstash.com

Result	Status	Action
Deployment	✅ Ready	Open preview
Content review	✅ Passed. No problems found.	View findings

Commit af28f2c · Updated 2026-09-10 11:07 UTC · View build details

mintlify · 2026-09-09T19:58:07Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
upstash	🟢 Ready	View Preview	Sep 10, 2026, 11:02 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

Replaces the fleet-oriented page with the setup walkthrough: requirements, install, keys, mode, starting an agent, working with it, managing the box, and server-side runs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Drops the callouts and the background explanation so the page is the steps and nothing else: install, keys, config, start, use, manage, scheduled runs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The plugin now tightens a loose secrets.json itself rather than refusing to start, so there is nothing for the reader to do. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

It is the first thing that stops a Start on a repository carrying large assets, and raising the config cap does not help, so say what to do instead. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Step 3 is now the setup popup, with the environment and the file described as what it writes. Names the subscription token, the per-harness start verbs, and fixes the step reference in the mode description. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…popup Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…es in the upload error Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

chore(llms): regenerate llms.txt and llms-full.txt

4e43b46

mintlify Bot deployed to staging September 9, 2026 20:00 View deployment

context7 Bot deployed to Docs7 Preview: DX-3020 September 9, 2026 20:01 View deployment

mintlify Bot deployed to staging September 9, 2026 20:02 View deployment

alitariksahin and others added 2 commits September 10, 2026 00:14

chore(llms): regenerate for the setup guide

926d11d

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

alitariksahin changed the title ~~DX-3020: add the Herdr agent fleet guide~~ DX-3020: add the Herdr plugin setup guide Sep 9, 2026

mintlify Bot deployed to staging September 9, 2026 21:16 View deployment

context7 Bot deployed to Docs7 Preview: DX-3020 September 9, 2026 21:18 View deployment

DX-3020: trim the guide to setup and use

44ab2f4

Drops the callouts and the background explanation so the page is the steps and nothing else: install, keys, config, start, use, manage, scheduled runs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

mintlify Bot deployed to staging September 9, 2026 21:21 View deployment

context7 Bot deployed to Docs7 Preview: DX-3020 September 9, 2026 21:22 View deployment

context7 Bot mentioned this pull request Sep 9, 2026

docs: review fixes for #833 #834

Closed

alitariksahin mentioned this pull request Sep 9, 2026

Tighten a loose secrets file instead of refusing to start upstash/herdr-upstash-box#2

Merged

DX-3020: drop the chmod step from the guide

d151e32

The plugin now tightens a loose secrets.json itself rather than refusing to start, so there is nothing for the reader to do. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

mintlify Bot deployed to staging September 9, 2026 21:33 View deployment

context7 Bot deployed to Docs7 Preview: DX-3020 September 9, 2026 21:34 View deployment

DX-3020: add the upload size limit to troubleshooting

3ceda9a

It is the first thing that stops a Start on a repository carrying large assets, and raising the config cap does not help, so say what to do instead. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

mintlify Bot deployed to staging September 9, 2026 21:43 View deployment

context7 Bot deployed to Docs7 Preview: DX-3020 September 9, 2026 21:46 View deployment

enesakar approved these changes Sep 9, 2026

View reviewed changes

mintlify Bot deployed to staging September 10, 2026 09:12 View deployment

context7 Bot deployed to Docs7 Preview: DX-3020 September 10, 2026 09:15 View deployment

DX-3020: setup asks for the setup-token to be pasted, not run in the …

1235816

…popup Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

mintlify Bot deployed to staging September 10, 2026 09:29 View deployment

context7 Bot deployed to Docs7 Preview: DX-3020 September 10, 2026 09:32 View deployment

DX-3020: troubleshooting for a rejected subscription token, directori…

45db5cb

…es in the upload error Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

mintlify Bot deployed to staging September 10, 2026 10:54 View deployment

context7 Bot deployed to Docs7 Preview: DX-3020 September 10, 2026 10:55 View deployment

DX-3020: drop the setup-token sentence from step 3

73c57a3

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

mintlify Bot deployed to staging September 10, 2026 11:01 View deployment

DX-3020: put the setup-is-complete line in a note

af28f2c

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

mintlify Bot deployed to staging September 10, 2026 11:02 View deployment

context7 Bot deployed to Docs7 Preview: DX-3020 September 10, 2026 11:07 View deployment

Navigation Menu

Uh oh!

DX-3020: add the Herdr plugin setup guide - #833

DX-3020: add the Herdr plugin setup guide#833
alitariksahin wants to merge 12 commits into
mainfrom
DX-3020

alitariksahin commented Sep 9, 2026 •

edited

Loading

Uh oh!

linear-code Bot commented Sep 9, 2026

Uh oh!

context7 Bot commented Sep 9, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Sep 9, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

alitariksahin commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Structure

How it was checked

Note

Uh oh!

linear-code Bot commented Sep 9, 2026

Uh oh!

context7 Bot commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mintlify Bot commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alitariksahin commented Sep 9, 2026 •

edited

Loading

context7 Bot commented Sep 9, 2026 •

edited

Loading

mintlify Bot commented Sep 9, 2026 •

edited

Loading