How to run Herdr coding agents in isolated Vercel Sandboxes

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 for Herdr, a terminal workspace manager for AI coding agents, moves each agent into its own Vercel 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.

Copy link to headingOverview

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

Copy link to headingPrerequisites

Before you begin, you need:

• Herdr 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.

Copy link to headingHow 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.

Copy link to headingSupported agents

The plugin supports three agents at pinned, verified versions.

You choose which one with the agentKind option in the plugin configuration.

Copy link to headingLifecycle 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.

Copy link to headingBilling

Sandbox usage is billed as normal Vercel Sandbox usage, which covers Active CPU, provisioned memory, creations, network, and snapshot storage. See Vercel Sandbox pricing for rates.

Copy link to headingSteps

Copy link to heading1. Install the plugin

Install the plugin from its GitHub repository:

herdr plugin install vercel-labs/herdr-vercel-sandbox-plugin

Copy link to heading2. Link your repository to a Vercel project

Link the Git repository you want the agent to work on to a Vercel project:

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.

Copy link to heading3. 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 <Agent> · 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.

Copy link to heading4. 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.

Copy link to heading5. 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.

Copy link to heading6. Stop, reconnect, or delete the Sandbox

When you finish a work session, pick the action that matches what you want:

Copy link to headingConfiguration

The plugin reads a config.json file. Print its directory with:

herdr plugin config-dir vercel.sandbox

The verified options are:

Copy link to headingTroubleshooting

Copy link to headingThe 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).

Copy link to headingStart 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.

Copy link to headingThe 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.

Copy link to headingtar 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.

Copy link to headingFAQ

Copy link to headingDoes 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.

Copy link to headingDoes 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.

Copy link to headingIs 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).

Copy link to headingDoes 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.

Copy link to headingCan 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.

Copy link to headingWhat 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.

Copy link to headingNext steps

• Learn more about isolated compute in the Vercel Sandbox documentation
• Review usage rates and plan limits in Vercel Sandbox pricing
• Browse the vercel.sandbox plugin source on GitHub
• Explore Herdr and its plugin system