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, 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 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
templatefield has the hidden template's id and version. Read the build's log withGET /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, noENTRYPOINTorCMD. - A template made from an image does not need Node.js in it: every sandbox feature works. A terminal needs the
scriptprogram 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:/dataThe 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 and Volumes.