Sandbox

The TypeScript SDK runs the same sandbox in Node and in a browser tab. The API below is identical in both; what differs is where snapshots are cached and what the guest’s network can reach. See Browser for that.

Install

npm install @capsule-run/vpod

import { Sandbox } from "@capsule-run/vpod";

In a browser, import from @capsule-run/vpod/browser instead. The package root resolves by export condition, which some bundlers get wrong for client code.

Overview

Method	Description
`Sandbox.create(options?)`	Create a new sandbox
`sandbox.commands.run(cmd, options?)`	Run a shell command
`sandbox.commands.interrupt()`	Stop the command that is running
`sandbox.code.run(source, options?)`	Run Python code
`sandbox.close()`	Shut down the running sandbox
`sandbox.tier`	Which engine the sandbox runs on
`sandbox.suspend()`	Suspend and return the delta bytes
`sandbox.suspendToOpfs()`	Suspend into browser storage, returns an instance id
`Sandbox.resume(idOrInstance, options?)`	Resume a suspended instance
`Sandbox.listInstances()`	List instances held in browser storage
`Sandbox.destroy(id)`	Delete a stored instance

Everything is async, because loading the engine and fetching a snapshot are.

Persistent sessions

All calls share one running sandbox, so state carries across them. Declaring it with await using closes it when the scope ends:

import { Sandbox } from "@capsule-run/vpod";

await using sandbox = await Sandbox.create();

await sandbox.commands.run("export API_KEY=secret");
const result = await sandbox.commands.run("echo $API_KEY");
console.log(result.stdout); // secret

If your toolchain does not support await using, call await sandbox.close() yourself. Shell commands and Python code share one filesystem:

await sandbox.commands.run("echo 'from shell' > /tmp/shared.txt");
await sandbox.code.run("print(open('/tmp/shared.txt').read().strip())");

An export inside a command does not cross between the two. commands.run("export FOO=bar") is invisible to code.run(...). Set env at creation for variables both sides should see, and use the filesystem to pass data between them afterwards.

Return values

`sandbox.commands.run(cmd)`

Field	Type	Description
`stdout`	`string`	Standard output
`stderr`	`string`	Standard error
`exitCode`	`number`	Exit code
`success`	`boolean`	True when `exitCode` is `0`

const result = await sandbox.commands.run("whoami");
console.log(result.stdout);   // root
console.log(result.exitCode); // 0

`sandbox.code.run(source)`

Field	Type	Description
`text`	`string`	Output of the executed code
`error`	`string \| null`	Error message when execution failed
`logs`	`string[]`	Log lines produced during execution
`stderr`	`string`	Anything the code wrote to standard error
`success`	`boolean`	True when `error` is `null`

await sandbox.code.run("import json");
await sandbox.code.run("data = [1, 2, 3]");

const result = await sandbox.code.run("print(sum(data))");
console.log(result.text);  // 6
console.log(result.error); // null

Variables and imports live for the lifetime of the session, so a REPL built on this behaves the way people expect.

For commands that run long enough to bound, watch, or feed input to — timeouts, interrupts, AbortSignal, streaming output, and stdin — see Process I/O.

`Sandbox.create()` options

Option	Type	Description
`snapshot`	`string \| { path } \| { bytes, name }`	What to boot from. Defaults to `vsnap-base:latest`
`network`	`boolean`	Force the guest’s network on or off
`trace`	`boolean \| TraceSources`	Record what the sandbox does. Off by default
`mounts`	`Record<string, string>`	Host directories to mount into the guest. Node only
`env`	`Record<string, string>`	Environment variables the guest starts with
`secrets`	`Record<string, SecretSpec>`	Credentials the guest can use but never read
`corsProxy`	`string`	A relay for hosts that send no CORS headers. Browser only, see Browser
`registryUrl`	`string`	Where to resolve snapshot names
`engine`	`"auto" \| "default"`	Whether a snapshot’s own engine may be used. Defaults to `"auto"`
`workerUrl`	`string \| URL`	Where the emulator worker is served from
`componentUrl`	`string \| URL`	Where the wasm component is served from
`networkWorkerUrl`	`string \| URL`	Where the network worker is served from

`snapshot`

A registry name, or a snapshot you built yourself:

await Sandbox.create({ snapshot: "vsnap-data" });
await Sandbox.create({ snapshot: { path: "./alpine-3.23.0-256mb.snap" } });
await Sandbox.create({ snapshot: { bytes, name: "alpine-3.23.0-256mb.snap" } });

Keep the RAM size in the file name, because the emulator reads it from there.

The first Sandbox.create() downloads the snapshot and caches it, on disk in Node and in origin-private storage in a browser. Later runs use the cache. See Snapshots.

`network`

The guest’s network is on by default wherever it can be. Pass false to run fully offline, or true to fail loudly instead of silently starting without it:

const offline = await Sandbox.create({ network: false });

sandbox.network reports what the guest can actually reach:

const { backend, rawTcp, corsRestricted } = sandbox.network;

The three asset URL options only matter in a browser, where the worker and the wasm are fetched at runtime rather than imported.

`mounts`

Host directories the guest can see, as a guest path per host path. Read only unless you append :rw:

const sandbox = await Sandbox.create({
    mounts: { "./workspace": "/workspace:rw", "./data": "/data" },
});

await sandbox.commands.run("ls /workspace");

Host paths are resolved against the working directory, and a path that is not a directory is an error rather than an empty mount. Changes are visible both ways while the sandbox runs: what the guest writes to an :rw mount lands on the host, and it sees host edits as they happen.

Mounts need a host filesystem, so they work under Node and throw in a browser. Everything else in this SDK runs in both.

`env`

Environment variables the guest starts with. They reach commands, anything those commands spawn, and code.run.

const sandbox = await Sandbox.create({
    env: { TZ: "UTC", API_BASE: "https://example.com" },
});

await sandbox.commands.run("echo $TZ"); // UTC

Values are passed literally, so quotes, $, and backticks in a value are never interpreted by the shell. Names must be plain identifiers.

Values set this way are visible inside the sandbox. Anything running there can read them from the environment, so treat env as configuration rather than a place for API keys or tokens. Use secrets for those.

`secrets`

A credential the sandbox can use but never read. The guest is given a stand-in through its environment; the value itself goes only to the network gateway, which swaps it back in on the way out, and only for a host you named.

const sandbox = await Sandbox.create({
    secrets: {
        ANTHROPIC_API_KEY: {
            value: process.env.ANTHROPIC_API_KEY,
            hosts: ["api.anthropic.com"],
        },
    },
});

Agent frameworks read credentials from the environment already, so code in the sandbox needs no changes. What it reads back is the stand-in:

await sandbox.commands.run("echo $ANTHROPIC_API_KEY");
// vpod-secret-anthropic_api_key-3f9c1a04

Key	Description
`value`	The credential. Never enters the sandbox
`hosts`	Where it may be sent. A string, or a list. `*.example.com` matches one label
`placeholder`	What the guest sees. Generated when left out

Set placeholder yourself when a client library checks the shape of a key:

secrets: {
    API_KEY: { value: key, hosts: ["api.example.com"], placeholder: "sk-live-vpod0000" },
}

The sandbox cannot read the credential, but it can spend it: any code running there can call the allowlisted host and the gateway will authenticate the request. This hides the credential, it does not restrain its use.

A request carrying a stand-in to a host that is not on its list fails rather than going out unswapped, so a mistake surfaces as an error instead of a puzzling 401 somewhere else. Substitution covers the request line and headers, which is where every API this was built for puts its key; a credential sent in a JSON body is not swapped. A client that pins certificates cannot be used this way, because the gateway terminates TLS.

`trace`

Records what the sandbox actually did, which programs ran, which files changed and where it connected. Off unless you ask for it, and chosen at creation:

const sandbox = await Sandbox.create({ trace: true });
const result = await sandbox.commands.run("sh -c 'cd /app && make'");

result.trace.processes();  // what ran
result.trace.files();      // what it touched

See Tracing.

`engine`

Some private snapshots come with their own engine, which runs the tools installed in them faster. With the default "auto", the sandbox uses that engine when it is already cached, and otherwise starts on the engine bundled with the SDK while the snapshot’s engine downloads for next time. See Private snapshots. Pass "default" to always use the bundled engine, for instance on a page that should not download anything extra:

const sandbox = await Sandbox.create({ snapshot: "my-snapshot", engine: "default" });

sandbox.tier says which engine it got: "image" for the snapshot’s own, "aot" or "base" for the bundled one.

Differences from the Python SDK

Three things differ, and all three surprise people who move between the two:

The default snapshot is vsnap-base:latest here and alpine in Python.
sandbox.suspend() returns the delta bytes, not an instance id. Browsers have nowhere to put a file, so where the state goes is your decision. See Suspend & resume.
There is no mounts option. Mounting a host directory has no meaning in a browser tab, so the TypeScript SDK does not offer it anywhere.

Get Started

TypeScript SDK

Python SDK

Embedded preview (In Iframe)

CLI

Resources

Install

Overview

Persistent sessions

Return values

`sandbox.commands.run(cmd)`

`sandbox.code.run(source)`

`Sandbox.create()` options

`snapshot`

`network`

`mounts`

`env`

`secrets`

`trace`

`engine`

Differences from the Python SDK

​Install

​Overview

​Persistent sessions

​Return values

​sandbox.commands.run(cmd)

​sandbox.code.run(source)

​Sandbox.create() options

​snapshot

​network

​mounts

​env

​secrets

​trace

​engine

​Differences from the Python SDK

Install

Overview

Persistent sessions

Return values

`sandbox.commands.run(cmd)`

`sandbox.code.run(source)`

`Sandbox.create()` options

`snapshot`

`network`

`mounts`

`env`

`secrets`

`trace`

`engine`

Differences from the Python SDK