> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a sandbox template from a Dockerfile

> Build a sandbox template from a Dockerfile or OCI image, then inspect the immutable template's build status.

Build a sandbox template from a Dockerfile or public OCI image as an immutable private version. Each reservation creates a new version; rebuilding does not overwrite an existing template ID.

## Reserve a version

```bash theme={null}
bead template-reserve --name project-tools
```

Keep the returned `templateID` and `buildID`. The API is `POST /v3/templates`; it also accepts runtime `cpuCount` and `memoryMB`.

## Start the build

Save this as `build.json`:

```json theme={null}
{"fromImage":"docker.io/library/debian:bookworm-slim"}
```

Replace `TEMPLATE_ID` and `BUILD_ID` with the reservation values:

```bash theme={null}
bead template-build TEMPLATE_ID BUILD_ID --input build.json
bead template-status TEMPLATE_ID BUILD_ID --offset 0 --limit 100
```

Choose exactly one of `fromImage` or `dockerfile`. Dockerfile inputs use Dockerfile text plus `context`, a byte array containing a tar archive. Context is bounded to 32 MiB compressed and 256 MiB expanded; entries must be regular files or directories with relative paths.

Custom images require a Debian bookworm-compatible userland. Private registry credentials and `fromTemplate` are rejected. Build secrets are unsupported: keep credentials out of Dockerfiles, context, and startup commands.

## Configure startup

Optional `startCmd` and `readyCmd` are shell commands. The app starts before the prepared checkpoint; readiness must succeed within 60 seconds. Use these fields for your application rather than relying on OCI ENTRYPOINT to replace the machine's init.

`defaultKind` selects the default machine kind. Optional `buildResources` selects builder CPU and memory independently of the published runtime shape. `timeoutSeconds` accepts 1–3600 seconds; omission defaults to 720.

## Wait for readiness

Status is `waiting`, `building`, `ready`, or `error`. Continue logs with `--offset`. A ready template can be used for new machines:

```bash theme={null}
bead create --template TEMPLATE_ID --size small --timeout 300
```

## Retire a version

```bash theme={null}
bead template-delete TEMPLATE_ID
```

Retirement prevents new creates. Existing machine references keep their immutable version. Reserve a new version for changes; names do not implicitly switch a mutable alias.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.