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

# What is a sandbox template?

> A template is the blueprint a sandbox starts from: base image, packages, files, environment and startup commands, compared with snapshots and Dockerfiles.

A template is the blueprint a sandbox is created from. It defines the base image, the installed packages, the files, the environment and the commands that run at startup. Every sandbox is spawned from a template, so building a template produces a reusable, ready-to-run environment.

```mermaid theme={null}
flowchart LR
  I[Docker image] -->|build| T[Template]
  T -->|spawn| S1[Sandbox]
  S1 -->|capture| SN[Snapshot]
  SN -->|spawn| S2[New sandbox]
```

## Template and Dockerfile

Templates are close to container images. A template is built from a Docker image, and the build is similar to writing a Dockerfile: start from a base image and layer instructions on top. The difference is where and how those instructions are expressed.

| | Template | Dockerfile or Docker image |
| - | - | - |
| Starts from | A Docker image, such as `fromImage('python:3.12')`, or another template | A base image declared with `FROM` |
| How steps are written | SDK builder calls such as `runCmd`, `copy` and `setEnvs`, like Dockerfile instructions but in code | Dockerfile instructions such as `RUN`, `COPY` and `ENV` |
| Extra configuration | Also captures sandbox settings: start command, ready command, CPU and memory | Only the image contents |
| Result | A `templateId` to pass to `sandbox.create(...)` | An image to run as a container |

In short, a template starts from a Docker image. Building one feels similar to authoring a Dockerfile, but the steps are SDK calls (`fromImage`, `runCmd`, `copy`, `setEnvs`) instead of a `Dockerfile`. The output is a `templateId` that PPIO uses to launch sandboxes quickly.

## Template and snapshot

A snapshot is a reusable saved state of a sandbox. It captures the sandbox filesystem and memory state, so new sandboxes can start from that point later.

Templates and snapshots both spawn a new sandbox from a predefined starting point. They differ in how that point is produced and in what it captures.

| | Template | Snapshot |
| - | - | - |
| How it is produced | Built from a Docker image with declared steps: install packages, copy files, set environment variables | Captured from a running sandbox at a moment in time |
| What it contains | A clean, reproducible blueprint authored up front | The filesystem and the live memory state, including anything created at runtime |
| When to use it | For a clean, reproducible base environment built from a Docker image and declared setup steps | To preserve the exact state of a specific running sandbox, including files created at runtime and its live memory state |

> [!NOTE]
>
> Snapshots are available only in some regions.

Use a snapshot to:

* Prepare dependencies once and reuse them in later sandboxes.
* Save a known-good state before running risky or expensive work.
* Start multiple sandboxes from the same captured environment.
* Keep a reusable state after the original sandbox is no longer needed.

## Public templates

On the **AGENT SANDBOX › Templates** page of the [console](https://console.ppio.ai/sandbox/templates), a template provided by PPIO carries the Public (Provided by PPIO and available to all users by default.) badge. Every team can use such a template by default.

Publishing and unpublishing a team's own template are described in [Manage templates](https://docs.ppio.ai/sandbox/templates/manage.md).

## Next steps

> [card] [Build with the SDK](https://docs.ppio.ai/sandbox/templates/build.md)
>
> Define a template with builder calls, then build it.

> [card] [Build with the CLI](https://docs.ppio.ai/sandbox/templates/build-cli.md)
>
> Build a Dockerfile into a template with `ppio template create`.

> [card] [Manage templates](https://docs.ppio.ai/sandbox/templates/manage.md)
>
> List templates, assign tags, publish or unpublish, and delete a template.


## Related topics

- [Agent Sandbox: secure cloud sandboxes for AI agents](https://docs.ppio.ai/sandbox/overview.md)
- [Build a template with the CLI](https://docs.ppio.ai/sandbox/templates/build-cli.md)
- [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md)


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