# Sandboxes and Workspaces

URL: https://helmr.dev/docs/reference/sdk/sandboxes-and-workspaces
Description: Declare Sandbox capacity and operate durable Workspaces.

# Sandboxes and Workspaces

A Sandbox is a deployed source declaration; a Workspace is a durable resource
created from it.

```ts
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.