Skip to content
GroundboxDocs
API referenceStatusPricing
DashboardStart free
GroundboxGitHub Actions runners and Linux sandboxes for AI agents. One key, one bill.System status

Product

CI runnersSandboxesBuilds and cacheAgent computersPricing

Developers

DocsAPI referenceAPI explorerCLIMCP serverBenchmark

Compare

vs GitHub-hostedvs Blacksmithvs E2Bvs DaytonaAll comparisons

Company

Talk to usSupportcontact@groundbox.devGroundmail ↗
© 2026 Groundbox
TermsPrivacyllms.txt
OverviewCI in one lineFirst sandboxHand it to your agent
Sizes and labelsCachesBuild cachesMigrateci waitTerminal on a jobPublic repositoriesAuto sizeAuto size: own runnersFlexCI tune-upSplit tests by timeDocker buildsGitLab CI
Start, exec, filesFrom a Docker imageCommandsForkTime machineSnapshotsPause and resumeStop and startIdle pause and wakeScheduled runsPreviewsSecretsEgress allowlistFlex sandboxesTemplatesVolumes
Push and pullIn GitHub ActionsStorage and retention
Desktop and actionsLive view in your appHuman handoffSign in onceAgent loop example
BucketsAccess keysMount a bucket
Move from Runloop
Omnara
REST APIAPI explorerOpenAPI referenceCLIMCP serverSDKsKeys and capsLeave or delete a team
  1. Sandboxes
  2. Templates and volumes
Markdown
Open in
ClaudeChatGPT
On this page

    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.

    Terminal
    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.

    Terminal
    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.

    Terminal
    # 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.

    TypeScript
    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.

    Terminal
    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 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.

    Terminal
    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.

    Terminal
    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

    Terminal
    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 and Volumes.

    ← PreviousPreviewsNext →Image registry
    System statusSupportPricingllms.txtgroundbox.dev