Sandbox
Direct sandbox operations for executing commands, managing files, and controlling snapshots.
The SandboxClient provides direct access to the underlying sandbox (Firecracker microVM). Access it via instance.sandbox.
Setup
Sandbox access requires provider configuration when connecting:
const instance = client.connect(url, jwtSecret, {
provider: "vercel",
providerOptions: { projectDir: "/path/to/.vercel" },
});
const sandbox = instance.sandbox;List sandboxes
const sandboxes = await sandbox.list();
// [{ id, status, createdAt, timeout, memory, vcpus }]Execute commands
const result = await sandbox.exec("sbx-123", "ls", ["-la", "/home"]);
console.log(result.exitCode); // 0
console.log(await result.stdout());Read and write files
// Read
const content = await sandbox.readFile("sbx-123", "/home/agent/config.toml");
// Write
await sandbox.writeFiles("sbx-123", [
{ path: "/home/agent/notes.md", content: Buffer.from("# Notes\n") },
]);Snapshots
// List snapshots
const snapshots = await sandbox.listSnapshots();
// [{ id, createdAt, sandboxId }]
// Delete a snapshot
await sandbox.deleteSnapshot("snap-123");Stop a sandbox
await sandbox.stop("sbx-123");