---
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-10-29T03:19:31.302Z"
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. Copy the starter, install dependencies, and pull your auth env vars with `vercel env pull .env`.
2. Call `Sandbox.create({ name, persistent: false })` and `runCommand('echo', ['hello'])`.
3. Call `sandbox.stop()` and confirm it exits with no errors.

## Hands-on exercise

The starter lives in the [`vercel-sandbox/starter`](https://github.com/vercel/academy-starters/tree/main/vercel-sandbox/starter) folder of `vercel/academy-starters`. There's no Deploy button here because `repo-review` is a CLI that runs on your machine, not a site we host. Copy the folder out as `repo-review/` and install dependencies:

```bash
git clone https://github.com/vercel/academy-starters.git
cp -R academy-starters/vercel-sandbox/starter repo-review
cd repo-review
pnpm install
```

For local authentication, link the directory to a Vercel project and pull a development OIDC token:

```bash
vercel link
vercel env pull .env
```

The same OIDC token authenticates both Sandbox and AI Gateway during local development. We load it with `tsx --env-file=.env` every time we run a script.

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({
    name: `repo-review-${Date.now()}`,
    persistent: false,
    timeout: 10 * 60 * 1000
  });
  console.log(`Sandbox created: ${sandbox.name}`);

  const result = await sandbox.runCommand('echo', ['hello from inside the sandbox']);
  console.log(`Output: ${(await result.stdout()).trim()}`);
  console.log(`Exit code: ${result.exitCode}`);

  await sandbox.stop();
  console.log('Sandbox stopped.');
}

main();
```

We pick the `name` ourselves. Names are unique within a project, and the SDK generates a random one when we leave it off. A `repo-review-` prefix plus a timestamp tells us which Sandboxes came from this tool and keeps every run distinct.

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", run `vercel link` and `vercel env pull .env` again, and keep `--env-file=.env` in the command. Do not print tokens into your terminal history.

\*\*Warning: Troubleshooting: .env: not found\*\*

If the command stops with `node: .env: not found` before any of our code runs, the env file is missing. Run `vercel env pull .env` from the `repo-review` folder, then try again.

\*\*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 --env-file=.env src/sandbox-lifecycle.ts
```

Expected output:

```txt
Sandbox created: repo-review-...
Output: hello from inside the sandbox
Exit code: 0
Sandbox stopped.
```

If you see a sandbox name, 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 whose name starts with `repo-review-`
- [ ] `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({
    name: `repo-review-${Date.now()}`,
    persistent: false,
    timeout: 10 * 60 * 1000
  });
  console.log(`Sandbox created: ${sandbox.name}`);

  const result = await sandbox.runCommand('echo', ['hello from inside the sandbox']);
  console.log(`Output: ${(await 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)