vercel/vercel-plugin/offload-to-sandbox
Claude Code and agent skill by vercel/vercel-plugin
- vendor
Checking that the SKILL.md file is still in the repository.
Offload heavy builds, full test suites and parallel experiments from the local machine to Vercel Sandboxes with the `vercel sandbox` CLI. Use when a local machine is overloaded or shared by several agents, when a test suite should be sharded, or when many tasks should run side by side without consuming local CPU, memory or disk.
Install
npx vskill@latest install vercel/vercel-plugin/offload-to-sandboxSKILL.md
The same SKILL.md was published earlier as vercel/vercel-plugin/offload-to-sandbox.
Offloading work to a Vercel Sandbox
A Vercel Sandbox is a Linux microVM (x86_64) you can create in seconds and remove when you're done. That makes it a good remote worker: it keeps heavy builds and long test suites off your laptop and gives every agent or task its own clean machine. This skill covers how to do that efficiently with the vercel sandbox CLI. For the @vercel/sandbox SDK and running untrusted code, see the vercel-sandbox skill.
When to offload, and what to keep local
Offload:
- Full test suites, especially when they can be sharded.
- Builds that take minutes or need Linux.
- Many tasks at once: one sandbox per task or per agent.
- Anything that fills the local disk (large build trees, many worktrees).
Keep local:
- Editing,
git, small focused tests, type checks and lint, and orchestration. - Anything needing local credentials or hardware the sandbox doesn't have.
A good default when several agents share one machine: agents edit locally and run quick focused checks, and everything heavy goes to their own sandboxes.
Plan limits
| Hobby | Pro | Enterprise | ||
|---|---|---|---|---|
| Max vCPUs (2 GB memory each) | 4 (8 GB) | 8 (16 GB) | 32 (64 GB) | |
| Max session duration | 45 minutes | 24 hours | 24 hours | |
| Concurrent sandboxes | 10 | 10,000 | 10,000 |
--vcpus takes 1 or an even number up to your plan's maximum; the default is 2. The examples below use Pro sizes (--vcpus 8, --timeout 3h). On Hobby, use --vcpus 4 and a timeout of 45m or less. Hobby also includes only 5 hours of Active CPU a month, so heavy offloading realistically needs Pro.
Running sandboxes are billed for Active CPU and provisioned memory. Snapshots are billed as Snapshot Storage per GB-month for as long as they exist.
Prepare a base snapshot once
Installing toolchains and dependencies in every new sandbox wastes minutes and money. Do it once, snapshot, and start everything else from the snapshot:
Check that step 2 printed exit=0 before you snapshot (see Run commands for why).
What to put in the base:
- The exact toolchain versions your project pins (compilers, runtimes, package manager).
- An installed and built copy of the main branch at a known commit, as a read-only baseline (for example
/vercel/sandbox/base). - Small helper scripts the tasks will reuse (for example a
prepare.shthat turns a freshly pushed tree into a runnable checkout).
Keep the snapshot ID in a file next to your tooling. --expiration 0 means the snapshot never expires, so it is billed until you delete it. When the toolchain changes, build a new snapshot and delete the old one with vercel sandbox snapshots delete <old-id>. Before a big run, check that vercel sandbox snapshots get "$(cat BASE_SNAPSHOT)" still shows the status created; a deleted or expired snapshot shows deleted.
Create one sandbox per task
- Name by owner and purpose (
exp-parser,exp-parser-2) so parallel agents never collide. Names are unique per project and stay taken until the sandbox is removed. Never use another agent's sandbox. - Size: each vCPU comes with 2 GB of memory, and that is the only way to get more memory. Memory-heavy steps (large compiles, big linker jobs) can be killed by the Linux OOM killer. Below your plan's vCPU maximum, size up. At the maximum, lower the step's parallelism (for example fewer build jobs) or run it alone.
- Tags (up to 5 per sandbox) make cleanup easy: list and remove everything with your owner tag at the end.
Lifetime and cleanup
Sandboxes are persistent by default: when a session stops, the filesystem is snapshotted so the sandbox can resume later, and that snapshot is billed as Snapshot Storage. Task sandboxes don't need that, which is why every create here passes --non-persistent.
- `--timeout` sets the session length, not the sandbox's lifetime. The default is 5 minutes. When it runs out, the session stops and everything running in it is killed, detached jobs included. A non-persistent sandbox loses its whole filesystem at that point. Set the timeout for the whole task.
vercel sandbox config timeout <name> <duration>changes it later, and a higher value also extends the running session. - `vercel sandbox remove <name>` when a task is done.
vercel sandbox stoponly ends the current session: the sandbox keeps its name, and a persistent sandbox keeps billing for its snapshot. Vercel removes sandboxes that can't resume after 14 days of inactivity, so a stopped non-persistent sandbox blocks its name until then unless you remove it. - Removing a sandbox does not delete snapshots, so the base snapshot survives task cleanup.
--delete-orphan-snapshotsonremovealso deletes the sandbox's own snapshots that no other sandbox uses. Don't pass it when removing the builder that made your base snapshot. - Sweep orphans from crashed agents with
vercel sandbox list --all --tag owner=<agent>.--allincludes stopped sandboxes (the default shows only running ones), andlistfilters by one tag at a time. Remove everything it shows withvercel sandbox remove <name>.... Sweep the whole project (--tag app=my-project) only when no agent is still working.
Move code in without reinstalling dependencies
Send source, not build output. Package the files git knows about (tracked plus untracked but not ignored) as one tarball, copy it, and extract it next to the old tree. Then move heavy directories (node_modules) from the old tree into the new one so they don't need reinstalling, and swap the two. sbx push in the wrapper script does exactly this:
- Push after every change; it takes seconds. Then run an idempotent prepare step that installs or rebuilds only what changed (for example, install dependencies only when the lockfile changed).
- Build platform-specific artifacts inside the sandbox. Don't copy macOS binaries into a Linux VM.
- Don't push
.gitor dependency directories. If you need git history remotely, push a bundle orgit cloneinside the sandbox. - A tracked file you deleted but didn't stage makes
tarfail. Stage the deletion (git rm) first.
Read, write, and copy files directly
The standalone sandbox CLI supports file commands in releases containing vercel/sandbox#380. Install or update it with npm i -g sandbox, then check the installed commands before using the examples:
Confirm that read and write exist and that copy --help lists --recursive. If they are unavailable, keep using vercel sandbox copy and the sbx wrapper below. The Vercel CLI bundles its own Sandbox CLI version, so support in sandbox does not establish support in vercel sandbox.
Use the same team and project as the existing task sandbox. Set SBX_SCOPE and SBX_PROJECT as described in Authentication and scope; the standalone CLI must also be authenticated.
read (also cat) prints file contents to stdout. write replaces the destination with stdin; redirect a local file with < ./script.sh when you already have one. Both return a non-zero status on failure.
Recursive copy puts the source directory's contents inside the destination and preserves empty directories, symlinks, and permissions. Windows downloads reject filenames containing backslashes or colons. It copies every entry, including ignored files, and leaves unrelated destination files in place. Use it for prepared input directories and results. Keep sbx push for project updates that need Git-based selection, removal of stale files, and reuse of remote node_modules.
Run commands
- Pass the whole command as one single-quoted string to
sh -c. Your local shell otherwise expands$VARSand globs before the sandbox sees them. zsh in particular errors on unmatched globs and treats$var:r,$var:hand similar as modifiers; use${var}. - Check the bundled CLI's exit behavior. With
vercel64.5.0 (Sandbox CLI 4.4.0),vercel sandbox execexits 0 even when the remote command fails. On that version, end the remote command withecho "exit=$?"and read that, or usesbx exec, which returns the remote status. The standalone Sandbox CLI (npm i -g sandbox, thensandbox exec ...) does pass the remote exit code through. - For anything longer than a line, write a script locally,
vercel sandbox copyit in, and run it. That is easier to quote, review and rerun. exec --timeoutis optional and has no default. When it expires, the command is killed with SIGKILL and the CLI printsCommand was killed (SIGKILL, exit code 137). Without it, a command runs until it finishes or the session times out.- If you compare timings, run both versions in the same sandbox, because hosts of the same size can differ in speed.
Run long jobs with the standalone CLI
Use native command management when your installed CLI supports it. With the standalone CLI installed and authenticated as described above, check:
Confirm that exec lists --detach and --stdin, and that commands lists get, logs, wait, and kill. Check these independently of the file commands above: CLI releases may support command management before read, write, and recursive copy. The Vercel CLI bundles its own Sandbox CLI version.
Start the task in the existing sandbox and save its command ID:
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files. Certified 25 Oct 2026.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/offload-to-sandbox/SKILL.md
Popularity
- 7-day trend score
- 0
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/vercel/vercel-plugin/offload-to-sandbox)