--- title: How to run Herdr coding agents in isolated Vercel Sandboxes description: Install the vercel.sandbox plugin for Herdr, approve an upload manifest, run each AI coding agent in its own isolated Vercel Sandbox microVM, and apply its changes back to your local worktree. url: /kb/guide/run-herdr-coding-agents-isolated-vercel-sandboxes canonical_url: "https://vercel.com/kb/guide/run-herdr-coding-agents-isolated-vercel-sandboxes" published: 2026-08-10 last_updated: 2026-08-10 authors: Elisabeth Rülke related: - /docs/sandbox - /docs/sandbox/pricing install_vercel_plugin: npx plugins add vercel/vercel-plugin --- AI coding agents execute shell commands and edit files. When they run on your machine, they use your real filesystem, credentials, and network. The [vercel.sandbox plugin](https://github.com/vercel-labs/herdr-vercel-sandbox-plugin) for [Herdr](https://herdr.dev/), a terminal workspace manager for AI coding agents, moves each agent into its own [Vercel Sandbox](https://vercel.com/docs/sandbox), an isolated Firecracker microVM in the cloud created from a copy of your Git worktree. Your Herdr pane stays a live terminal into that VM, so you work with the agent in natural language exactly as if it ran locally, while every command it executes and every file it edits stays inside the Sandbox. Its changes come back only as a Git patch you review. ## Overview In this guide, you'll learn how to: - Install the vercel.sandbox plugin for Herdr - Link your repository to a Vercel project - Start an agent in its own Sandbox and approve the upload manifest - Work with the agent in a live terminal pane - Apply the agent's changes to your local worktree - Stop, reconnect to, and delete Sandboxes ## Prerequisites Before you begin, you need: - [Herdr](https://herdr.dev/) installed and running. The plugin is verified with Herdr 0.7.5. - The Vercel CLI installed and logged in. - A Git repository linked to a Vercel project with `vercel link`. If you're not logged in or the worktree isn't linked, the plugin doesn't fail silently and doesn't create anything. Instead, it opens the official Vercel CLI login or project-linking flow in a pane so you can complete the missing step. ## How it works Each agent pane gets its own Sandbox. When you start an agent, the plugin: 1. Creates a Vercel Sandbox. 2. Uploads an approved set of files from your worktree. 3. Runs the agent process inside the VM at `/vercel/sandbox/workspace`. The pane in Herdr is a real TTY connected to that process. Interactive terminal UIs render live, and your keystrokes go straight to the agent. ### Supported agents The plugin supports three agents at pinned, verified versions. You choose which one with the `agentKind` option in the plugin configuration. | Agent | Verified version | | ----------- | ---------------- | | Claude Code | 2.1.220 | | Codex | 0.146.0 | | OpenCode | 1.18.9 | ### Lifecycle actions Nine actions cover the full loop: - Start an agent in a new Sandbox - Apply the agent's changes locally - Stop the Sandbox - Reconnect the agent to the Sandbox - Replace the Sandbox - Delete the Sandbox and forget the mapping - Show the Sandbox mapping - Connect your Vercel account - Link the worktree to a Vercel project Every action also writes its result to the plugin log as JSON (`HERDR_SANDBOX_RESULT`), so an orchestrating agent can start and monitor sandboxed agents without scraping terminal text. ### Billing Sandbox usage is billed as normal Vercel Sandbox usage, which covers Active CPU, provisioned memory, creations, network, and snapshot storage. See [Vercel Sandbox pricing](https://vercel.com/docs/sandbox/pricing) for rates. ## Steps ### 1\. Install the plugin Install the plugin from its GitHub repository: ```bash herdr plugin install vercel-labs/herdr-vercel-sandbox-plugin ``` ### 2\. Link your repository to a Vercel project Link the Git repository you want the agent to work on to a Vercel project: ```bash vercel link ``` You can also do this from inside Herdr. The plugin's "Connect Vercel account" and "Link this worktree to a Vercel project" actions open the official Vercel CLI flows in a pane. ### 3\. Start the agent and approve the upload manifest From a Herdr pane inside the linked Git worktree, run the plugin's Start configured agent in a new Sandbox action from Herdr's action menu. No keybindings or extra setup are needed. Starting takes two invocations by design: 1. The first Start prints the complete upload manifest, listing every file to be uploaded with sizes and SHA-256 hashes, along with a digest of the entire manifest. No Sandbox is created yet. 2. Invoking Start again within 10 minutes approves that exact file set. After you approve, the plugin creates the Sandbox, uploads the files, installs the agent, and opens it in a new pane titled ` · Vercel Sandbox`. If any file changes locally between the two invocations, the manifest digest changes. The next start then shows a fresh manifest for review. ### 4\. Work with the agent On first start, the agent asks you to log in inside the Sandbox. That login is stored on the Sandbox disk and persists across reconnects. After that, use the new pane exactly as you would a local agent session. The pane is a real TTY, so interactive terminal UIs render live and keystrokes go to the agent. Because the agent works in `/vercel/sandbox/workspace` inside the VM, every command it runs and every file it edits stays inside the Sandbox. The agent doesn't depend on your laptop staying connected. Short network interruptions and brief laptop sleeps survive on their own. The connection resumes, the agent never notices, and it keeps working in the cloud. ### 5\. Apply the agent's changes to your local worktree Exit the agent in the pane first. Apply and the other destructive actions refuse to run while an agent is still active in the mapped pane. Then run the Apply Sandbox changes locally action. This will: 1. Exports the agent's changes from the Sandbox as a binary Git patch (the diff between the current state and a baseline tag). 2. Downloads the patch. 3. Runs `git apply --check` to verify it applies cleanly. 4. Applies the patch to your local worktree only if the check passes. If your local work conflicts, nothing is applied, and the action reports the conflict. Repeated applies export only changes newer than the last applied snapshot, so you can pull the agent's work in increments. ### 6\. Stop, reconnect, or delete the Sandbox When you finish a work session, pick the action that matches what you want: | Action | What it does | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Stop this Sandbox | Stops compute and preserves the filesystem, including the agent's conversation history stored on the Sandbox disk. | | Reconnect agent to this Sandbox | Launches the agent again in the same Sandbox. For Claude Code, run `/resume` to pick up the previous conversation. | | Replace this Sandbox | Permanently deletes the Sandbox and recreates it fresh. Because this destroys data, it opens the same typed confirmation pane as deletion. | | Delete Sandbox and forget mapping | Removes the Sandbox, its filesystem, and the local pane mapping. To prevent accidents, it requires typing `DELETE` in a confirmation pane. Pressing Enter alone cancels, and the request expires after 60 seconds. | | Show Sandbox mapping | Prints the agent kind, versions, capabilities, paths, and lifecycle state. Useful before deciding between the options above. | ## Configuration The plugin reads a `config.json` file. Print its directory with: ```bash herdr plugin config-dir vercel.sandbox ``` The verified options are: | Option | Default | Description | | ------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agentKind` | — | Which agent to run, one of `"claude-code"`, `"codex"`, or `"opencode"`. | | `runtime` | `"node24"` | The Sandbox runtime. | | `timeout` | `"1h"` | The Sandbox lifetime. The platform maximum is 45 minutes on Hobby and 24 hours on Pro and Enterprise plans, per [Vercel Sandbox pricing](https://vercel.com/docs/sandbox/pricing). | | `projectConfigPath` | — | A path to a `.vercel/project.json` file that pins the target team and project. | ## Troubleshooting ### The agent pane shows the session ended after your laptop slept Brief sleeps survive on their own. The connection resumes, and the agent keeps working. If the connection remains silent long enough to time out, the Sandbox closes the terminal session and terminates the agent process. Your work is not lost. The Sandbox itself keeps running until its own timeout or an explicit stop, and its filesystem, including the agent's conversation history, is preserved. Run Reconnect agent to this Sandbox to launch the agent again in the same Sandbox, then resume the previous conversation (for Claude Code, `/resume`). ### Start printed a manifest but created nothing This is the approval step working as designed. The first Start prints only the upload manifest for review, and invoking Start again within 10 minutes approves the exact same file set and creates the Sandbox. If more than 10 minutes pass, or any file changes locally, the next Start prints a fresh manifest to review instead. ### The Sandbox hit its timeout mid-task The timeout ends the session, not your work. The filesystem persists, and Reconnect agent to this Sandbox starts a fresh session on the same Sandbox. The default timeout is 1 hour. For longer tasks, raise the `timeout` option in `config.json`, up to the platform maximum of 45 minutes on Hobby and 24 hours on Pro and Enterprise plans. ### tar prints xattr warnings during upload on macOS On macOS, the upload can print repeated `LIBARCHIVE.xattr.com.apple.provenance` warnings inside the Sandbox. They're harmless, and the upload completes normally. ## FAQ ### Does the plugin upload my credentials or my whole filesystem? No. The upload contains only the files from the one Git worktree you start from, as selected by Git's own file listing. The plugin excludes: - Git-ignored files - `.env` files - `.git`, `.vercel`, and `node_modules` Every file's contents are also scanned for private keys and common token formats (AWS, GitHub, Slack) before upload, and the manifest you approve is the complete list. Your home directory, SSH keys, shell environment, and Vercel CLI login stay on your machine. The agent authenticates inside the Sandbox, and that login is stored on the Sandbox disk. ### Does the agent keep working if I close my laptop? For brief interruptions, yes. The agent runs in the cloud, so it keeps working while your laptop sleeps, and the pane catches up when you reopen it. If the connection stays down long enough to time out, the Sandbox ends that terminal session and the agent process with it, while the Sandbox and its filesystem keep running. ### Is the same agent still there when I reconnect? Reconnect launches a fresh agent process in the same Sandbox. It behaves like the same agent because its state lives on the Sandbox disk. The login persists, the workspace files persist, and the conversation history persists, so the new process can resume the previous conversation (for Claude Code, `/resume`). ### Does the agent's code get applied to my machine automatically? No. Changes come back only through the Apply Sandbox changes locally action, as a Git patch that is checked with `git apply --check` first and applied only if it applies cleanly. If it conflicts with local work, nothing is changed. ### Can another agent orchestrate sandboxed agents? Yes. Every plugin action can be invoked from the command line and writes its result to the plugin log as JSON (`HERDR_SANDBOX_RESULT`), so a local agent can start a sandboxed agent, poll its lifecycle state, and apply its changes without scraping terminal output. ### What does it cost? Standard Vercel Sandbox usage rates apply while a Sandbox runs, covering Active CPU, provisioned memory, creations, network, and snapshot storage. Stopping a Sandbox stops compute charges, but the snapshot that preserves its filesystem is billed as snapshot storage until it expires or you delete the Sandbox. See [Vercel Sandbox pricing](https://vercel.com/docs/sandbox/pricing). ## Next steps - Learn more about isolated compute in the [Vercel Sandbox documentation](https://vercel.com/docs/sandbox) - Review usage rates and plan limits in [Vercel Sandbox pricing](https://vercel.com/docs/sandbox/pricing) - Browse the [vercel.sandbox plugin source on GitHub](https://github.com/vercel-labs/herdr-vercel-sandbox-plugin) - Explore [Herdr](https://herdr.dev/) and its plugin system