---
title: "Your First Sandbox"
description: "Install the Sandbox SDK, create your first Sandbox, run a single command inside the microVM, and stop it. The simplest possible round-trip before we add anything to it."
canonical_url: "https://vercel.com/academy/vercel-sandbox/your-first-sandbox"
md_url: "https://vercel.com/academy/vercel-sandbox/your-first-sandbox.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-05-17T02:04:52.516Z"
content_type: "lesson"
course: "vercel-sandbox"
course_title: "Vercel Sandbox"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Your First Sandbox

# 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

1. Install `@vercel/sandbox` and load your auth env vars.
2. Call `Sandbox.create()` and `runCommand('echo hello')`.
3. 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.

```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();
```

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.

\*\*Warning: 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.

\*\*Note: 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

```bash
pnpm tsx src/sandbox-lifecycle.ts
```

Expected output:

```txt
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

```bash
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

```ts title="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();
```


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)