---
title: "Create sandboxes from TypeScript"
description: "Use @exedev/sdk to create exe.dev VMs from TypeScript in seconds, run code and serve previews in them, then copy, pause, or delete them."
url: https://exe-staging.dev/deploy/typescript-sandboxes
category: "AI agents"
published: 2026-10-19
updated: 2026-11-21
---

# Create sandboxes from TypeScript

Full VMs as sandboxes. Create, control, and destroy them from your code.

- **Software:** TypeScript sandboxes (https://www.npmjs.com/package/@exedev/sdk)
- **Source:** https://github.com/boldsoftware/exe-sdk-js
- **License:** MIT
- **Machine-readable:** https://exe-staging.dev/deploy/typescript-sandboxes/manifest.json

[`@exedev/sdk`](https://www.npmjs.com/package/@exedev/sdk) is exe.dev's
TypeScript SDK. `exe.new()` gives you a VM, `vm.ssh()` runs code in it, and
`vm.rm()` deletes it. In our tests that whole round trip, with a Python
script uploaded and run in between, took about three seconds.

The sandbox is a whole VM, not a container: its own kernel, root through
`sudo`, Docker, and an HTTPS address. Use one for code an AI agent wrote, a
test run, or a preview of a branch, and delete it when you're done. Or keep
it, copy it, or pause it: it's an ordinary exe.dev VM.

## Get a token

The SDK talks to exe.dev's [HTTPS API](/docs/https-api) with a token. Make
one that can only touch sandboxes. On your computer:

```bash
ssh exe.dev ssh-key generate-api-key --label=sandboxes --tag=sandbox --exp=90d \
  '--cmds="new,ls,rm,ssh,cp,pause,resume,restart,resize,stat,comment,share set-public,share set-private"'
```

It prints a token that starts with `exe1.`. Keep the single quotes around
`--cmds`: they keep the list, spaces and all, in one piece on its way to
exe.dev.

- `--tag=sandbox` scopes the token. Every VM it creates is tagged
  `sandbox`, and it can see and touch no other VM: `ls` lists only
  sandboxes, and `ssh` to any other VM answers "not found". It can't
  change tags, either.
- `--cmds` lists the commands the token may run. Keep `ssh`: it runs
  commands in sandboxes, and the SDK uses it to tell when a new VM is
  ready. Leave out what you won't use.
- The token expires in 90 days. To revoke it sooner, remove its key:
  `ssh exe.dev ssh-key remove sandboxes`.

Keep the token on your server, in an environment variable or a secret
store. Anyone who has it can create VMs on your account.

## Set up a project

The SDK is an ES module with no dependencies, for Node.js 18 or later, Bun,
and Deno. To follow along with TypeScript files run by [`tsx`](https://tsx.is):

```bash
mkdir sandboxes && cd sandboxes
npm init -y && npm pkg set type=module
npm install @exedev/sdk@^0.6.0
npm install -D tsx
export EXE_TOKEN=exe1.…   # the token from the previous step
```

`exedev()` reads the token from `EXE_TOKEN`; pass `{ token }` to give it
one yourself. This page is for `@exedev/sdk` 0.6, tested with 0.6.0. Until
1.0, a minor release can change the API, which is why the install pins
`^0.6.0` (0.6.x only). The
[changelog](https://github.com/boldsoftware/exe-sdk-js/blob/main/CHANGELOG.md)
lists what each release changed.

## Create a sandbox

```ts
// create.ts
import exedev from "@exedev/sdk";

const exe = exedev(); // reads EXE_TOKEN

const vm = await exe.new({ "no-email": true });
try {
  console.log(vm.name);     // halo-but-valley
  console.log(vm.httpsUrl); // https://halo-but-valley.exe.xyz

  const { stdout } = await vm.ssh("python3 --version");
  console.log(stdout);      // Python 3.12.3
} finally {
  await vm.rm();
}
```

Run it with `npx tsx create.ts`. `new` returns once the VM accepts
commands, so you can use it straight away, and the `finally` deletes it
whether or not the code in between throws.

Don't pick names: VM names are global across exe.dev, so let it choose a
free one. Without `"no-email": true`, exe.dev emails you about every VM it
creates.

Options are the flags of [`new`](/api?cmd=help+new), spelled the same way:

| Option | What it does |
| --- | --- |
| `cpu`, `memory`, `disk` | Size: `{ cpu: 4, memory: "8GB", disk: "50GB" }` |
| `sandbox: true` | A [sandbox](/deploy/sandbox) ([standalone VM](/docs/standalone-vms)): capacity of its own, billed by the second while it runs |
| `image` | A container image instead of the default Ubuntu 24.04 image ([private registries](/docs/private-image) work too) |
| `integration` | [Integrations](/docs/integrations) to attach, such as a GitHub repository |
| `egress` | `"integrations"` cuts the VM off from the internet: [Run untrusted code](#run-untrusted-code) |
| `comment` | A note shown in `ls`, like a job ID |
| `env` | Environment variables for every command, `["KEY=value"]` |
| `"setup-script"` | A script the default image runs as `exedev` at first boot |
| `prompt` | A task for [Shelley](/docs/shelley/intro), the agent on the VM |
| `waitUntil` | `"setup"` also waits for the setup script to finish. `"created"` returns as soon as the VM exists, without waiting for it to accept commands. |

To install things before you use a sandbox, give `new` a setup script and
wait for it:

```ts
const vm = await exe.new({
  "no-email": true,
  "setup-script": "#!/bin/bash\nset -e\nsudo apt-get install -y -q jq\n",
  waitUntil: "setup",
});
```

If the script fails, `new` throws a `VMReadyError` whose `cause` is a
`VMSetupError`, with the script's `exitCode` and the end of its log in
`details().output`. The VM is left for you to inspect or delete (see
[Delete it](#delete-it)).

The script runs once, at the VM's first boot, not again when it restarts.
Only the default image and images built on it run setup scripts. On
others, waiting for the script throws a `VMSetupError` whose `result` is
`"unsupported"`.

## Run code in it

`vm.ssh()` runs a shell command in the sandbox and waits for it to finish:

```ts
const r = await vm.ssh("echo hello from $(hostname); echo oops >&2; exit 3");
r.stdout;   // "hello from halo-but-valley\n"
r.stderr;   // "oops\n"
r.exitCode; // 3
```

A failing command isn't an exception: check `exitCode`. Commands run in
`bash` as the `exedev` user, in its home directory, with no terminal and no
stdin. Each call starts a fresh shell, so `cd` and variables don't carry
over from one to the next; files do. Variables from `new({ env })` are set
for every command.

The command is a bash script, so quote anything you put into it with the
SDK's `quote`:

```ts
import { quote } from "@exedev/sdk";

await vm.ssh(`API_URL=${quote(url)} python3 main.py ${quote(path)}`);
```

## Move files

```ts
await vm.writeFile("job/main.py", code);                 // a string or a Uint8Array; makes directories
await vm.writeFile("job/run.sh", script, { mode: 0o755 });
const data = await vm.readFile("job/out.csv");          // a Uint8Array
await vm.upload("./src", "app", { exclude: [".git", "node_modules"] });
await vm.download("app/dist", "./dist");                // a file or a directory
```

Paths in the sandbox are relative to the home directory unless they're
absolute. `upload` and `download` take a file or a directory; a
directory's contents are copied into the destination. A missing file
throws a `VMFileError` with `code` `"ENOENT"`, and a directory given to
`readFile` one with `"EISDIR"`.

The API has no stdin and a request can be at most 64 KB, so files travel
inside commands, as compressed base64 in pieces sent several at a time. In
our tests, writing 1 MB of random bytes took about 2 seconds, and 5 MB
about 7; text compresses, so 1.2 MB of it took under a second. Reading 5 MB
took about a second. For much bigger files, let the sandbox fetch them
(`git clone`, `curl`), or use `scp`.

Now the whole life of a sandbox: create it, upload a script, run it,
delete it.

```ts
// hello.ts
import exedev from "@exedev/sdk";

const MAIN = `import platform
print("hello from", platform.node())
raise SystemExit(3)
`;

const exe = exedev();

const vm = await exe.new({ "no-email": true, comment: "hello from TypeScript" });
console.log(`created ${vm.name}`);
try {
  await vm.writeFile("main.py", MAIN);
  const r = await vm.ssh("python3 main.py");
  process.stdout.write(r.stdout);
  console.log(`exit ${r.exitCode}`);
} finally {
  await vm.rm();
  console.log(`deleted ${vm.name}`);
}
```

```console
$ npx tsx hello.ts
created halo-but-valley
hello from halo-but-valley
exit 3
deleted halo-but-valley
```

## Stream output and set time limits

To see output as it happens, pass callbacks:

```ts
const r = await vm.ssh("cd app && make test", {
  onStdout: (text) => { process.stdout.write(text); },
  onStderr: (text) => { process.stderr.write(text); },
});
```

`ssh` still collects the output for `r.stdout` and `r.stderr`, up to 8 MiB
in all, and throws an `SSHStreamError` past that. Raise the limit with
`maxOutputBytes`, or pass `capture: false` to only stream it. For output
that isn't text, such as an image or a tarball written to standard output,
use `onStdoutBytes` and `onStderrBytes`: they get the bytes the command
wrote, as `Uint8Array`s.

To give a command a time limit, run it under `timeout` in the sandbox. It
stops the command, and everything the command started, when time runs
out, and exits with status 124:

```ts
const r = await vm.ssh("cd app && timeout 60 make test");
if (r.exitCode === 124) console.log("too slow");
```

To stop waiting from your side, pass a signal, such as
`{ signal: AbortSignal.timeout(90_000) }`: `ssh` then rejects with the
signal's reason, a `TimeoutError`.

> [!WARNING]
> In `@exedev/sdk` 0.6.0, aborting `ssh` stops the waiting but not the
> command: it keeps running in the sandbox (a known issue in the SDK's
> changelog). Bound the command itself with `timeout`, as above, or delete
> the sandbox.

## Run long jobs

`ssh` waits as long as the command runs, even if it prints nothing for many
minutes. But your program waits only as long as the request: if it exits or
the connection drops, you lose the command's output and exit status. For
jobs that should outlive your process, start them in the background and
check on them:

```ts
import type { SSHResult } from "@exedev/sdk";

await vm.ssh("setsid nohup bash -c './build.sh; echo $? > build.exit' > build.log 2>&1 < /dev/null &");

let done: SSHResult;
while ((done = await vm.ssh("cat build.exit")).exitCode !== 0) {
  await new Promise((r) => setTimeout(r, 5000));
}
console.log(`build.sh exited ${done.stdout.trim()}`);
console.log((await vm.ssh("tail -n 50 build.log")).stdout);
```

Redirect all three of the job's standard streams, as above. A background
process that still holds the output keeps `ssh` waiting until it exits.

## Serve a preview

exe.dev's [proxy](/docs/proxy) serves port 8000 of every VM at
`https://<vm>.exe.xyz/`, with TLS. Start a server and share the address:

```ts
await vm.writeFile("site/index.html", "<h1>Hello from a sandbox</h1>\n");
await vm.ssh("setsid nohup python3 -m http.server 8000 --directory site > http.log 2>&1 < /dev/null &");
await vm.ssh("curl -sf --retry 9 --retry-connrefused localhost:8000 > /dev/null");
await vm.shareSetPublic();
console.log(vm.httpsUrl); // https://halo-but-valley.exe.xyz
```

Redirect the server's standard streams here too, or `ssh` waits for it to
exit. The `curl` waits until the server answers, so the address works as
soon as you hand it out.

The address is private until `shareSetPublic`: visitors are sent to
exe.dev's login and need to be someone you've [shared](/docs/sharing) the VM
with. `shareSetPublic` opens it to anyone with the link, and
`shareSetPrivate` closes it again. For your own code to reach a private
sandbox, give it a [VM token](/docs/https-tokens-for-vms) and send it as
`X-Exedev-Authorization: Bearer <token>`.

## Copy, pause, and resize

Set up a sandbox once, then copy it for each task instead of installing
the same things every time:

```ts
// Once: a base sandbox with your dependencies.
const base = await exe.new({ "no-email": true, comment: "base" });
await base.ssh("uv venv -q ~/venv && uv pip install -q --python ~/venv pandas && sync");
await base.pause();

// For each task: a copy of it, ready for commands, like new().
const vm = await base.cp();
await vm.ssh("~/venv/bin/python -c 'import pandas; print(pandas.__version__)'");
```

- `cp` copies the disk. Run `sync` first, or recent writes that are still
  in memory are left out of the copy.
- A paused VM can be copied. Copies keep their source's tags and comment,
  so the token can still see them.

Pausing writes a VM's memory to disk and frees its CPU and memory. Resuming
brings it back with its processes still running:

```ts
await vm.pause();  // about 3 seconds
await vm.resume(); // about 1 second, ready for commands
```

`resume` resolves to exe.dev's answer, whose `cold_booted` is `"true"` if
the VM had to boot afresh and lost what was in memory.
While it's paused, `ssh` throws an `ExeAPIError` with status 422 ("is not
running"). Pausing or restarting a VM cuts off commands that are running
through `ssh`: they throw an `SSHStreamError`.

To change a sandbox's size, resize it and restart it. The new CPU count
applies after the restart:

```ts
await vm.resize({ cpu: 4 });
await vm.ssh("sync");
await vm.restart();
```

Restarting is like pulling the plug: files written in the last half
minute or so that haven't reached the disk are lost. Run `sync` first.

## Run many at once

Every call returns a promise, so `Promise.all` runs sandboxes side by side.
Ten at once:

```ts
// many.ts
import exedev from "@exedev/sdk";

const exe = exedev(); // reads EXE_TOKEN

async function square(n: number): Promise<string> {
  const vm = await exe.new({ "no-email": true, comment: `square ${n}` });
  try {
    const r = await vm.ssh(`python3 -c 'print(${n} ** 2)'`);
    return r.stdout.trim();
  } finally {
    await vm.rm();
  }
}

console.log(await Promise.all(Array.from({ length: 10 }, (_, n) => square(n))));
```

```console
$ npx tsx many.ts
[
  '0',  '1',  '4',
  '9',  '16', '25',
  '36', '49', '64',
  '81'
]
```

Your plan has a VM limit, so cap how many run at once in bigger batches.
Requests refused for going over the rate limit throw an `ExeAPIError` with
status 429: wait, then try again.

## Delete it

```ts
await vm.rm();
```

Delete sandboxes in a `finally`, as `hello.ts` does, so a failed task
doesn't leave its VM behind. `rm` throws if the VM wasn't deleted, with
`status` 404 if it was already gone.

If `new` creates a VM that never becomes ready, or whose setup script
fails, it throws a `VMReadyError` without deleting the VM. Its `vm` is the
VM, to inspect or delete:

```ts
import { VMReadyError } from "@exedev/sdk";

try {
  const vm = await exe.new({ "no-email": true });
  // ...
} catch (err) {
  if (err instanceof VMReadyError) await err.vm.rm();
  throw err;
}
```

Processes still die without cleaning up, so sweep up now and then. This
deletes running sandboxes more than an hour old; paused ones, like the base
you copy from, stay. The token sees only VMs tagged `sandbox`, so nothing
else can be touched.

```ts
// reap.ts
import exedev from "@exedev/sdk";

const exe = exedev();

const hour = 60 * 60 * 1000;
const stale = (await exe.ls()).filter(
  (vm) => vm.info.status === "running" && Date.now() - Date.parse(vm.info.createdAt ?? "") > hour,
);
const { deleted, failed } = await exe.rm(stale);
console.log(`deleted ${deleted.length}, failed ${failed.length}`);
```

`exe.rm` deletes a list of VMs in one request. It doesn't throw for the ones
it couldn't delete: they're in `failed`, with reasons in `errors`. It
deletes every sandbox of that age, whoever made it: if some live longer, or
several apps share the token, filter on `vm.info.comment` too. Run the
script from cron, or before creating new sandboxes.

## Run untrusted code

> [!WARNING]
> Integrations attached to `auto:all` reach every new VM, sandboxes
> included. On a new account those are the LLM gateway, billed to you, and
> reflection, which tells the VM your email address. Code you don't trust
> can use them.

To keep an integration off sandboxes, attach it by tag instead (see
[Attaching integrations](/docs/integrations-attach)). Then only VMs with
that tag get it, so tag your own VMs that need it. On your computer:

```bash
ssh exe.dev integrations list
ssh exe.dev integrations detach llm auto:all
ssh exe.dev integrations attach llm tag:dev
```

Otherwise a sandbox is like any VM: its web address is private until you
share it, only you and your tokens can run commands in it, and it can reach
the internet. To cut it off, set its egress policy to `"integrations"`.
Install what the code needs in a base VM that has the internet, then run
the code in copies that don't:

```ts
const base = await exe.new({ "no-email": true, comment: "base" });
await base.ssh("uv venv -q ~/venv && uv pip install -q --python ~/venv pandas && sync");
await base.pause();

const vm = await base.cp({ egress: "integrations" });
try {
  await vm.writeFile("untrusted.py", code);
  const r = await vm.ssh("timeout 60 ~/venv/bin/python untrusted.py");
} finally {
  await vm.rm();
}
```

`exe.new({ egress: "integrations" })` works the same way. With that
policy, names of public hosts don't resolve, so `pip install`, `uv`, and
HTTP requests fail with DNS errors. Copies keep their source's policy
unless you pass `egress`. exe.dev's own addresses and the integrations
attached to the VM, such as the LLM gateway, still work, which is why the
warning above matters too. `vm.info.egressPolicy` is a VM's policy, and
`vm.egress("all")` changes it, if the token has `egress` in its `--cmds`.
See [Egress policy](/docs/internet-access).

## Errors and limits

- `ExeAPIError`: exe.dev refused the request. The message says why, as in
  `exe.dev API error (422) during ssh: VM "x" is not running`, and `status`
  is the HTTP status.
- `SSHStreamError`: a command's output was cut off. `code` is
  `"interrupted"` (the VM restarted or paused, or the connection failed)
  or `"output_limit"`. The command may or may not have finished, so don't
  blindly run it again. `stdout` and `stderr` have what arrived.
- `ExeNetworkError`: the request failed on the way, for example because
  the connection dropped. Whether it took effect is unknown: `new` may
  have created a VM. Find it with `ls()` by its `comment`, or let the
  [cleanup script](#delete-it) catch it.
- `VMReadyError`: a VM was created, copied, restarted, or resumed but
  didn't accept commands within 60 seconds (`timeoutMs`), or its setup
  script failed or didn't run. `vm` is the VM, and `cause` the reason: a
  `VMSetupError` for the setup script.
- `VMFileError`: `readFile` or `download` found no such file (`code`
  `"ENOENT"`), or a directory where it wanted a file (`"EISDIR"`).
  `CommandError` is a file method's command failing in the sandbox, with
  its `exitCode`.

An aborted call rejects with the signal's reason, such as a `TimeoutError`.
The HTTP statuses you'll see:

| Status | Means |
| --- | --- |
| 401 | The token is malformed, expired, or revoked |
| 403 | The token isn't allowed that command (`--cmds`) |
| 413 | The request is over 64 KB |
| 422 | The command failed: VM not found or not running, a bad flag |
| 429 | Too many requests from this token's key; slow down and retry |

The [HTTPS API](/docs/https-api#troubleshooting) docs list the rest. Every
method's documentation comment shows the command's help, and the
[API explorer](/api?cmd=help+new) shows what each command accepts.

## Frequently asked questions

### Is a sandbox a container or a VM?

A VM, with its own kernel. The default image is Ubuntu 24.04 with `sudo`, Docker, Python, `uv`, Go, and git, so code in a sandbox can install packages, run containers, and start services as it would on any Linux machine. Pass `image` to `new` to start from another container image instead.

### How fast is it?

In our tests `new` returned a VM ready for commands in about 2 seconds. Each `ssh` took about a third of a second plus the command's own time, `cp` about 2 seconds, `pause` and `restart` about 3, and `resume` about 1. Ten sandboxes created at once were all done in about 7 seconds. Images other than the default can take longer to start the first time.

### What does it cost?

By default `new()` makes an ordinary VM, which shares your plan's CPU and memory: more VMs split the same capacity rather than add to the bill, up to the plan's VM limit (50 on [Personal](/docs/billing/personal), 1,000 in each [Work pool](/docs/pools)). Disk and bandwidth beyond your allowance are billed as [usage](/docs/billing/usage). `new({ sandbox: true })` makes a [sandbox](/deploy/sandbox) (a [standalone VM](/docs/standalone-vms)) instead, with capacity of its own, billed by the second while it runs: ten seconds of 2 vCPU is about $0.0003. See [pricing](https://exe.dev/pricing).

### Can I use SSH instead?

Yes. Every sandbox is also `ssh <vm>.exe.xyz` for the SSH keys on your account, so the `ssh` command or an SSH library gives you stdin, interactive sessions, and `scp`. The SDK is simpler to run from a server: one token, no keys on disk, no known_hosts. To let someone, or some other program, into one sandbox and nothing else, add their key scoped to it: `exe.sshKeyAdd(publicKey, { vm: vm.name })`, which needs `ssh-key add` in the token's `--cmds`. See [VM-scoped SSH keys](/docs/vm-scoped-ssh-keys).

### Can I call the SDK from a browser?

Don't: anyone who can read the token can create VMs on your account until it expires. Keep it on your server, and have the browser ask your server for a sandbox.

### Does it work with Bun or Deno?

Yes. The package is an ES module with no dependencies that uses the runtime's `fetch`. `hello.ts` below ran unchanged on Node.js 18 (with `tsx`), Bun 1.4, and Deno 2.9 (`deno run --allow-env --allow-net hello.ts`). From CommonJS, load it with `await import("@exedev/sdk")`.

### Can code in a sandbox use AI models?

Yes, if your [LLM integration](/docs/integrations-llm) is attached to it, as it is by default: code in the sandbox can call `https://llm.int.exe.xyz` without an API key, billed to you. `new({ prompt })` goes further and hands the sandbox's own agent, Shelley, a task to work on.


## Related

- [Sandboxes on exe.dev](https://exe-staging.dev/deploy/sandbox.md): A VM with its own CPU and memory, billed by the second while it runs.
- [Create sandboxes from Python](https://exe-staging.dev/deploy/python-sandboxes.md): Full VMs as sandboxes. A with block creates one, runs your code, and deletes it.
- [Running Agents](https://exe-staging.dev/deploy/agents.md): Use exe.dev VMs as a sandbox
- [Run Claude Code on a remote server](https://exe-staging.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop.
- [Self-hosted sandbox for Claude Managed Agents](https://exe-staging.dev/deploy/claude-managed-agents.md): Anthropic runs the agent. Each session's tools run on a VM of its own.
- [Self-host OpenClaw on an always-on server](https://exe-staging.dev/deploy/openclaw.md): An AI sidekick with its own computer. Your laptop can take a nap.
