Classes
Sandbox
A sandbox: one Chainguard Workspaces session with your packages. Commands run one at a time per sandbox.
Properties
Section titled “Properties”client
Section titled “client”
readonlyclient:Client
The underlying Workspaces client, for anything this package doesn’t wrap.
commands
Section titled “commands”
readonlycommands:Commands
Run commands.
readonlyfiles:Filesystem
Read and write files.
readonlyname:string
Full resource name (instances/
sandboxId
Section titled “sandboxId”
readonlysandboxId:string
Short sandbox ID (8 hex characters), usable with Sandbox.connect.
Methods
Section titled “Methods”[asyncDispose]()
Section titled “[asyncDispose]()”[asyncDispose]():
Promise<void>
await using sbx = await Sandbox.create() kills the sandbox at the end of the scope.
Returns
Section titled “Returns”Promise<void>
getInfo()
Section titled “getInfo()”getInfo():
Promise<SandboxInfo>
Returns
Section titled “Returns”Promise<SandboxInfo>
isRunning()
Section titled “isRunning()”isRunning():
Promise<boolean>
Returns
Section titled “Returns”Promise<boolean>
keepAlive()
Section titled “keepAlive()”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.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”Promise<void>
kill()
Section titled “kill()”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.
Returns
Section titled “Returns”Promise<boolean>
pause()
Section titled “pause()”pause():
Promise<void>
Snapshot (memory and disk) and stop the sandbox. Processes, including background commands, continue on the next call.
Returns
Section titled “Returns”Promise<void>
connect()
Section titled “connect()”
staticconnect(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.
Parameters
Section titled “Parameters”sandboxId
Section titled “sandboxId”string
ConnectOpts = {}
Returns
Section titled “Returns”Promise<Sandbox>
create()
Section titled “create()”
staticcreate(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.
Parameters
Section titled “Parameters”SandboxOpts = {}
Returns
Section titled “Returns”Promise<Sandbox>
kill()
Section titled “kill()”
statickill(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.
Parameters
Section titled “Parameters”sandboxId
Section titled “sandboxId”string
ConnectOpts = {}
Returns
Section titled “Returns”Promise<boolean>
list()
Section titled “list()”
staticlist(opts?):Promise<SandboxInfo[]>
The sandboxes this package created in the instance.
Parameters
Section titled “Parameters”ConnectOpts = {}
Returns
Section titled “Returns”Promise<SandboxInfo[]>
