# Templates and volumes

A template is a sandbox's disk made ready ahead of time: an image, a Dockerfile or a list of packages, built once. Sandboxes start from it with everything installed. A volume is a disk of its own that keeps its data after sandboxes are deleted. Both are on every plan.

## Make a template

Start from a public image (anything `docker pull` takes) or one in your [Groundbox registry](https://groundbox.dev/docs/registry), from a Dockerfile, or from Groundbox's own image (Ubuntu 24.04 with Docker, Node, Python, Go, Rust and Java) when you give neither. Then add `apt`, `pip` and `npm` packages, `files` and `run` commands; they are applied in that order. A failing command fails the build.

```
curl https://api.groundbox.dev/v1/templates \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "python-ml", "image": "python:3.12-slim", "apt": ["git"], "pip": ["numpy", "pandas"], "cpus": 2}'
```

A Dockerfile is built with no context folder, so `COPY` and `ADD` of local files fail: put files in `files` instead.

```
curl https://api.groundbox.dev/v1/templates \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile df Dockerfile '{name: "node-app", dockerfile: $df}')"
```

The first version starts building at once. Building is free. A team keeps up to 20 templates, and each keeps its newest 3 versions. `POST /templates/{name}/builds` builds a new version; with an empty body it builds the same spec again, with fresh packages.

## Follow the build

`GET /templates/{name}/builds/{version}/logs` returns the lines after `after`, the build's `status`, `next` and `done`. With `wait_s` (up to 25) it waits for a new line, so you follow a build by calling again with `after` set to `next` until `done` is true.

```
# Lines after seq -1, waiting up to 25 s for one. Call again with after=<next> until "done": true.
curl "https://api.groundbox.dev/v1/templates/python-ml/builds/1/logs?after=-1&wait_s=25" \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY"
```

The CLI and the SDKs do this for you: `groundbox templates create` follows the log to the end and exits 1 when the build fails; the TypeScript SDK's `follow_template_logs` yields each line and returns the final status.

```
const template = await groundbox.create_template({ name: "python-ml", image: "python:3.12-slim", pip: ["numpy"] });
const logs = groundbox.follow_template_logs(template.id, 1);
let step = await logs.next();
for (; !step.done; step = await logs.next()) console.log(step.value.text);
if (step.value.status !== "ready") throw new Error("the build failed");
const sandbox = await groundbox.create_sandbox({ template: "python-ml" });
```

## Start sandboxes from it

Pass `template` when you create a sandbox: the name, the id, or `name:version` for one version. Without a version you get the newest ready one.

```
curl https://api.groundbox.dev/v1/sandboxes \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": "python-ml"}'
```

## Warm start

When a build ends, the template is booted once and a snapshot of the running VM is kept. A sandbox of the template's exact size (its `cpus`, `memory_gb` and `disk_gb`) starts from that snapshot in well under a second. Leave the size out to get the template's own. Any other size boots the template cold, which takes a few seconds. The sandbox's `start` field says which it got (`pool`, `warm` or `cold`) and `boot_ms` how long it took.

## Templates made from images

A sandbox created with [image](https://groundbox.dev/docs/sandboxes#image) starts from a template Groundbox makes for you: one per image digest, built the same way as your own. These templates are hidden. They are not in `GET /templates` unless you add `?include_hidden=true`, and they do not count toward your 20 templates. Building and keeping them is free, like any template.

- The sandbox's `template` field has the hidden template's id and version. Read the build's log with `GET /templates/{id}/builds/{version}/logs`.
- A hidden template that no sandbox was created from for 14 days is deleted. The next sandbox from that image builds it again.
- You can delete one yourself by id. It cannot be the default template, and you cannot build a new version of it.
- What an image's sandboxes get is the same as for a template made from that image: its `ENV`, commands as root, no `ENTRYPOINT` or `CMD`.
- A template made from an image does not need Node.js in it: every sandbox feature works. A terminal needs the `script` program from util-linux.

## Default template

Make a template the team's default and every new sandbox that names no template starts from it. Set it back to `null` for Groundbox's own image.

```
curl -X PUT https://api.groundbox.dev/v1/templates/default \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": "python-ml"}'
```

## Volumes

A volume is 1 to 500 GB, for datasets, model weights or caches that more than one sandbox needs. Attach up to 4 to a sandbox with `volumes`, each at its own path, read-write or with `read_only: true`.

```
curl https://api.groundbox.dev/v1/volumes \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "datasets", "size_gb": 50}'

curl https://api.groundbox.dev/v1/sandboxes \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": "python-ml", "volumes": [{"volume": "datasets", "path": "/data"}]}'
```

- A volume is read-write in one sandbox at a time, or read-only in any number of them.
- A sandbox with volumes cannot be paused or forked. It can be stopped and started: its volumes are attached again on start.
- A volume costs $0.08 per GB-month for its whole size, used or not, until it is deleted. A team keeps up to 20.
- Deleting a volume deletes its data for good. It is refused while a sandbox that is not stopped has it attached.

## From the CLI and MCP

```
groundbox templates create python-ml --image python:3.12-slim --pip numpy --pip pandas
groundbox templates default python-ml
groundbox volumes create --size 50 --name datasets
groundbox sandbox create --template python-ml --volume datasets:/data
```

The MCP server has `create_template`, `list_templates`, `get_template_logs`, `create_volume`, `list_volumes` and `delete_volume`, and `create_sandbox` takes `template`, `image` and `volumes`. In the dashboard they are under [Sandboxes, Templates](https://app.groundbox.dev/sandboxes/templates) and [Volumes](https://app.groundbox.dev/sandboxes/volumes).
