Spin Up Your First Sandbox

Running unknown code on your laptop is like inviting a raccoon into your kitchen and hoping it respects boundaries. It will not.

So we start small. Before we clone repos or run AI analysis or anything fun, we need to prove that we can create a Sandbox, run one command inside it, and stop it without leaving anything behind. That's it. One command, one microVM, one clean exit.

Outcome

Create a Sandbox, run a single echo command inside it, and stop it cleanly.

Fast Track

Install @vercel/sandbox and load your auth env vars.
Call Sandbox.create() and runCommand('echo hello').
Call sandbox.stop() and confirm it exits with no errors.

Hands-on exercise

Create src/sandbox-lifecycle.ts. We're going to keep growing this file across the next four lessons, so give it the name it'll have at the end.

import { Sandbox } from '@vercel/sandbox';
 
async function main() {
  const sandbox = await Sandbox.create();
  console.log(`Sandbox created: ${sandbox.sandboxId}`);
 
  const result = await sandbox.runCommand('echo hello from inside the sandbox');
  console.log(`Output: ${result.stdout.trim()}`);
  console.log(`Exit code: ${result.exitCode}`);
 
  await sandbox.stop();
  console.log('Sandbox stopped.');
}
 
main();

No try/finally, no error handling, no helpers. We're proving the round-trip works before we add anything to it. If this lesson errors out, every later lesson breaks in the same way, and we want to see that now.

Troubleshooting: auth errors on create

Sandbox.create() needs Vercel auth. If you see a 401 or "no credentials", confirm your env vars are loaded in the shell you're running from. Run echo $VERCEL_TOKEN (or whatever your project uses) to verify.

Troubleshooting: hangs on create

Sandbox creation usually takes a couple seconds. If it hangs for more than ~30s, there's likely a network or auth issue. Stop the process and check your env before retrying.

Try It

pnpm tsx src/sandbox-lifecycle.ts

Expected output:

Sandbox created: sbx_7N2k4A...
Output: hello from inside the sandbox
Exit code: 0
Sandbox stopped.

If you see a sandbox id, a hello, an exit code of 0, and a clean stop, you've got the foundation. Everything else in the course is more of this.

Commit

git add src/sandbox-lifecycle.ts
git commit -m "feat(sandbox): create, run, and stop a minimal sandbox"

Done-When

Sandbox.create() returns a sandbox with an id
runCommand('echo ...') returns exit code 0
sandbox.stop() completes without throwing
The script exits on its own (no hanging process)

Solution

src/sandbox-lifecycle.ts

import { Sandbox } from '@vercel/sandbox';
 
async function main() {
  const sandbox = await Sandbox.create();
  console.log(`Sandbox created: ${sandbox.sandboxId}`);
 
  const result = await sandbox.runCommand('echo hello from inside the sandbox');
  console.log(`Output: ${result.stdout.trim()}`);
  console.log(`Exit code: ${result.exitCode}`);
 
  await sandbox.stop();
  console.log('Sandbox stopped.');
}
 
main();