> ## Documentation Index > Fetch the complete documentation index at: https://upstash-dx-2965.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Herdr Plugin Setup [Herdr](https://herdr.dev) 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](/box/overall/quickstart#1-get-your-api-key) ready for setup. ```bash theme={null} herdr plugin install upstash/herdr-upstash-box ``` *** ## 2. Set up ```bash theme={null} 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](https://github.com/upstash/herdr-upstash-box#configure). *** ## 3. Start an agent Focus a Herdr pane inside a Git worktree, then run: ```bash theme={null} 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: ```toml theme={null} [[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 ```bash theme={null} herdr plugin action invoke reconnect --plugin upstash.box herdr plugin action invoke apply-changes --plugin upstash.box herdr plugin action invoke info --plugin upstash.box herdr 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 ```bash theme={null} herdr plugin action invoke pause --plugin upstash.box herdr plugin action invoke resume --plugin upstash.box herdr plugin action invoke snapshot --plugin upstash.box herdr plugin action invoke previews --plugin upstash.box herdr plugin action invoke delete-box --plugin upstash.box herdr 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](/box/overall/preview). 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: ```json theme={null} { "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 How interactive sessions into a box work. Save and restore box state. Open a port on the box with a public URL. The plugin repository and full configuration reference.