Skip to content

Classes

Sandbox

A sandbox: one Chainguard Workspaces session with your packages. Commands run one at a time per sandbox.

readonly client: Client

The underlying Workspaces client, for anything this package doesn’t wrap.


readonly commands: Commands

Run commands.


readonly files: Filesystem

Read and write files.


readonly name: string

Full resource name (instances//sessions/).


readonly sandboxId: string

Short sandbox ID (8 hex characters), usable with Sandbox.connect.

[asyncDispose](): Promise<void>

await using sbx = await Sandbox.create() kills the sandbox at the end of the scope.

Promise<void>


getInfo(): Promise<SandboxInfo>

Promise<SandboxInfo>


isRunning(): Promise<boolean>

Promise<boolean>


keepAlive(ms): Promise<void>

Hold the sandbox running (not parked when idle) for this long. There is no hard deadline: an idle sandbox parks after about 10 minutes.

number

Promise<void>


kill(): Promise<boolean>

Delete the sandbox and everything in it; resolves once it is gone, so the session slot is free. Resolves false if it was already gone. Rejects with TimeoutError if the sandbox still exists 30 s after the delete request (or that can’t be confirmed): deletion was requested, but the slot may not be free yet.

Promise<boolean>


pause(): Promise<void>

Snapshot (memory and disk) and stop the sandbox. Processes, including background commands, continue on the next call.

Promise<void>


static connect(sandboxId, opts?): Promise<Sandbox>

A handle to an existing sandbox (short ID, display name or resource name). A paused sandbox resumes on its first command.

string

ConnectOpts = {}

Promise<Sandbox>


static create(opts?): Promise<Sandbox>

Create a sandbox; resolves when it can run commands (about 8–20 s). A session the plane places on a host that never starts is deleted and recreated (up to 3 attempts). On failure nothing is left behind.

SandboxOpts = {}

Promise<Sandbox>


static kill(sandboxId, opts?): Promise<boolean>

Delete a sandbox by ID (short ID, display name or resource name). Resolves false if there was none. Unlike connect it does not attach to the sandbox first, so it also deletes one that never started or cannot be attached to. Rejects as the instance method does.

string

ConnectOpts = {}

Promise<boolean>


static list(opts?): Promise<SandboxInfo[]>

The sandboxes this package created in the instance.

ConnectOpts = {}

Promise<SandboxInfo[]>