Sandboxes and Workspaces
A Sandbox is a deployed source declaration; a Workspace is a durable resource created from it.
export const repo = sandbox({ id: "repo" })
.image(image("repo").from("node:24-bookworm-slim"))
.resources({ cpu: 2, memory: "4GiB" })The builder requires .image(imageBuilder).resources({ cpu, memory }). Memory is expressed
as ${bigint}MiB or ${bigint}GiB. Create externally with
client.sandboxes.createWorkspace(declaredId, { key?, idempotencyKey?, secrets? }); the result is a WorkspaceRef.
client.workspaces.ref(id) exposes:
| API | Result |
|---|---|
retrieve() |
Current Workspace record and status. |
exec({ command, idempotencyKey, cwd?, env?, stdin?, timeout? }) |
Bounded stdout, stderr, and exit code. |
delete({ idempotencyKey? }) |
Deletion receipt. |
Workspace statuses are available, recovery_required, and deleting.
Secrets are bound at creation using plain string names; plaintext secret values are not part of a Workspace request.