add-sandbox

Adds working, production-shaped Vercel Sandbox code to an app you already have. It never creates a project.

npx add-sandbox

You see a summary of what was detected, answer one question (what the sandbox is for), press Enter, and get:

• lib/sandbox/profiles.ts — five documented presets; the comments are the docs, grounded in the current SDK defaults and plan limits.
• lib/sandbox/client.ts — create / get-or-create / fork / with-sandbox wrappers that apply the profile and the right auth path.
• lib/sandbox/handler.ts — one framework-agnostic Request → Response handler for the chosen workload.
• A route shim at the right path for your framework, or the exact lines to paste when there is no file convention.
• An appended block in .env.example and in every agent-instructions file you already have (AGENTS.md, CLAUDE.md, .cursorrules, …).
• lib/sandbox/manifest.json — what was written, with hashes, so reruns are idempotent and remove is safe.

Then it installs @vercel/sandbox and runs your project's own tsc to prove the result compiles.

Detected, not asked

Package manager, framework (Next.js App Router, SvelteKit, Nuxt, Hono; anything else gets the handler plus mount lines), TypeScript vs JavaScript, src/ layout, tsconfig import aliases, monorepo workspaces, whether the directory is linked to a Vercel project (OIDC vs access-token auth), and whether ai or workflow are installed (which changes what is generated). Python projects get the same treatment with the vercel package and a FastAPI router.

Profiles

| Profile | Shape | | --- | --- | | code-interpreter | One request, one throwaway VM. 1 vCPU, non-persistent, deny-all egress. | | preview | Named persistent sandbox per preview; resumes and restarts its dev server; port exposed. | | build-test | Warm persistent sandbox per repo with dependencies installed; each run is an ephemeral fork. Sync or async. | | agent-workspace | One persistent sandbox per user, resumed on demand, tagged for tenancy. | | multi-agent | One VM, one Linux user per agent, shared group directory. JS only. |

Flags

-p, --profile <id>     skip the question
    --mode sync|async  build-test only
-w, --workspace <dir>  monorepo package to target
-y, --yes              accept the summary
    --dry-run          plan only
    --no-install, --no-typecheck, --json

npx add-sandbox remove deletes everything the manifest lists that you have not edited.

Constraints it keeps

It never parses or edits your existing source. It refuses to overwrite a file it did not write. Files you have edited since the last run are left alone (and the route that mounts an edited handler with them). Imports resolve through your alias when one covers the target, relative paths otherwise.