Skip to content
shardDocs

Sandboxes

shard.create

Section titled “shard.create”

Create a sandbox and wait until it is running.

shard.create(options?: CreateOptions): Promise<Sandbox>

Examples

const web = await shard.create({ image: "python:3.12", name: "web", memoryMiB: 512 });
const copy = await shard.create({ snapshot: "web-files", name: "web-copy" });
const worker = await shard.create({ image: "python:3.12", secrets: ["API_TOKEN"], policy: "api-only" });

Options

TypeScript Python Description
image image image to use, such as alpine:3.20; the first positional argument in Python
snapshot snapshot snapshot ID or name to start from instead of an image
name name sandbox name to use instead of its ID
env env environment every command in the sandbox starts with
workdir workdir default directory for commands
user user default user for commands, as a name or uid such as nobody or 1000
secrets secrets names of the stored secrets the sandbox may use
policy policy outbound network policy
memoryMiB memory_mib memory limit; a snapshot’s own limit, or else 512 MiB on Firecracker and vz and none on gVisor, runc and Sysbox
vcpus vcpus CPU count; the daemon’s default when left out
diskMiB disk_mib disk limit; the daemon’s default, or a snapshot’s own disk size
swapMiB swap_mib swap file inside the disk limit; 2048 MiB by default on Firecracker and vz
ports ports host ports to forward from the first start, as { hostPort, guestPort, public } or PortForward(host_port, guest_port, public=False)

Give an image or a snapshot, not both. The call can take minutes while the server pulls the image. It returns a sandbox in state running. When the create fails, it raises an error, or it returns a sandbox in state failed with the reason in info.failedReason (info.failed_reason in Python).

The sandbox starts with no processes. Use sandbox.run to start a supervised process in it, or sandbox.exec for a one-off command. The sandbox stays active until stopped.

Secrets

Store a secret with shard.secrets.set, then name it in secrets. Commands receive $NAME with a placeholder instead of the secret value. In HTTPS request headers sent to the secret’s destinations, the server replaces the placeholder with the value. The value stays outside the sandbox.

Network access

Without a policy, the sandbox can access the internet but not private networks.

Resource limits

On Firecracker and vz, a memory limit from 1 to 127 MiB is refused. gVisor, runc and Sysbox refuse any swap but 0.

shard.get

Section titled “shard.get”

Find a sandbox by ID, ID prefix or name.

shard.get(ref: string): Promise<Sandbox>

Examples

const web = await shard.get("web");

A sandbox that does not exist raises NotFoundError.

shard.list

Section titled “shard.list”

List active sandboxes.

shard.list(options?: { all?: boolean }): Promise<{ sandboxes: Sandbox[]; warnings: string[] }>

Examples

const { sandboxes, warnings } = await shard.list({ all: true });
for (const sandbox of sandboxes) console.log(sandbox.name, sandbox.info.state);

Options

TypeScript Python Description
all all include stopped sandboxes

The warnings name entries the daemon could not read, so check them before you treat the list as complete.

sandbox.inspect

Section titled “sandbox.inspect”

Read the sandbox’s record again.

sandbox.inspect(): Promise<SandboxInfo>

Examples

const info = await sandbox.inspect();
console.log(info.state, info.resources.memoryMiB);

sandbox.info holds the record that the last call on that handle returned, and sandbox.id and sandbox.name read from it.

sandbox.stop

Section titled “sandbox.stop”

Stop the sandbox and preserve its files.

sandbox.stop(): Promise<void>

Examples

await sandbox.stop();

Each process has up to 30 seconds to exit before it is terminated. Files remain available, but memory and process state are lost.

Use sandbox.start to start the sandbox again. Use shard.snapshots.create to save its files as a snapshot.

sandbox.start

Section titled “sandbox.start”

Start a stopped sandbox with its saved files.

sandbox.start(): Promise<void>

Examples

await sandbox.start();

Processes with the always or unless-stopped restart policy start again, except those killed.

sandbox.pause

Section titled “sandbox.pause”

Suspend the sandbox and save its state.

sandbox.pause(): Promise<void>

Examples

await sandbox.pause();

Memory and files are saved so its processes can continue after resume. The sandbox must be running. A provider without pause raises UnsupportedError.

sandbox.resume

Section titled “sandbox.resume”

Resume a paused sandbox from its saved state.

sandbox.resume(): Promise<void>

Examples

await sandbox.resume();

Processes continue from where they paused.

sandbox.fork

Section titled “sandbox.fork”

Create a sandbox from a running sandbox’s memory and files.

sandbox.fork(options?: { name?: string }): Promise<Sandbox>

Examples

const copy = await sandbox.fork({ name: "web-copy" });

Options

TypeScript Python Description
name name name for the new sandbox

The source briefly pauses, then continues running. The new sandbox starts from the captured state, runs, and has independent files. A provider without fork raises UnsupportedError.

sandbox.remove

Section titled “sandbox.remove”

Remove the sandbox and its files.

sandbox.remove(options?: { force?: boolean }): Promise<void>

Examples

await sandbox.remove({ force: true });

Options

TypeScript Python Description
force force stop a running or paused sandbox first

Stop a running or paused sandbox before removal, or pass force.