---
title: "Templates: start sandboxes ready to work | Pethost Agent Sandboxes"
description: "Save a sandbox's disk as a template, with your packages and Docker images, and start new sandboxes from it on any server in about 0.2 s."
---

[Agent Sandboxes docs](https://pethost.dev/docs/sandboxes/) · Tasks

# Templates: start sandboxes ready to work

Updated 22 November 2026 · 6 min read

A template is what a sandbox starts from. Ours, `base`, has the tools; yours is a sandbox's disk saved as it is, with the packages you installed, your code and its Docker images. A sandbox from it starts in about 0.22 s with nothing left to install.

**In short**

- **`CreateTemplate`** saves a sandbox's disk and settings as a new version, `my-app@1`, `my-app@2`, while the sandbox runs on.
- **SAVING, then READY** in about 1.5 s for a small one, and about 10 s a GiB of what it holds of its own.
- **`CreateSandbox`** with `"my-app"` starts from its newest READY version, on any server.
- **Files only:** a template keeps no memory, no processes and no agent conversations. It is not billed; your plan bounds its size.

### Step 1: Prepare a sandbox

Make a sandbox from `base` and set it up as every new one should be: clone your code, install its dependencies, pull the Docker images it runs, warm the caches ([commands and files](https://pethost.dev/docs/sandboxes/commands-and-files/)). Its settings count too: the template takes the sandbox's lifecycle, egress, public ports and environment as they are now, and sandboxes from it start with them unless their create says otherwise.

### Step 2: Save it as a template

`CreateTemplate` answers the new version SAVING within milliseconds, once it holds the disk as it is: the sandbox runs on. The server then shrinks the version to what it holds and uploads it. Wait for READY before you start from that version.

Python

```
import time

from pethost.sandboxes import TemplateState

version = sandboxes.create_template("my-app", sandbox_id=sandbox_id, description="Node 22 and our dependencies")
while version.state == TemplateState.SAVING:
    time.sleep(1)
    version = sandboxes.get_template(f"my-app@{version.version}")
print(version.name, version.version, version.state.name, version.min_size.name, version.size_bytes)
# my-app 1 READY SMALL 25447048
```

TypeScript

```
let version = await sandboxes.createTemplate({
  name: "my-app",
  sandboxId,
  description: "Node 22 and our dependencies",
});
while (version.state === TemplateState.SAVING) {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  version = await sandboxes.getTemplate({ template: `my-app@${version.version}` });
}
console.log(version.name, version.version, version.state, version.minSize, version.sizeBytes);
```

Go

```
version, err := client.CreateTemplate(ctx, &sandboxes.CreateTemplateRequest{
	Name:        "my-app",
	SandboxID:   id,
	Description: "Node 22 and our dependencies",
})
for err == nil && version.State == sandboxes.TemplateStateSaving {
	time.Sleep(time.Second)
	version, err = client.GetTemplate(ctx, &sandboxes.GetTemplateRequest{Template: fmt.Sprintf("my-app@%d", version.Version)})
}
if err != nil {
	log.Fatal(err)
}
fmt.Println(version.Name, version.Version, version.State, version.MinSize, version.SizeBytes)
```

Rust

```
let mut version = sandboxes
    .create_template(CreateTemplateRequest {
        name: "my-app".into(),
        sandbox_id: id.clone(),
        description: "Node 22 and our dependencies".into(),
        ..Default::default()
    })
    .await?;
while matches!(version.state, TemplateState::Saving) {
    tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    let template = format!("my-app@{}", version.version);
    version = sandboxes.get_template(GetTemplateRequest { template, ..Default::default() }).await?;
}
println!("{} {} {:?} {:?} {}", version.name, version.version, version.state, version.min_size, version.size_bytes);
```

CLI

```
$ pethost sandbox template save api-dev my-app --description 'Node 22 and our dependencies'
✓ Saving my-app@2: it is ready once uploaded. See:  pethost sandbox template show my-app@2
my-app@2
$ pethost sandbox template ls my-app
my-app@2   ready   68 MB      55 s ago    Node 22 and our dependencies
my-app@1   ready   24 MB      1 min ago   Node 22 and our dependencies
```

MCP

```
CreateTemplate {"name": "my-app", "sandbox_id": "…", "description": "Node 22 and our dependencies"}
ListTemplates {"name": "my-app"}
```

### Step 3: Start sandboxes from it

Name the template in `CreateSandbox`: `"my-app"` is its newest READY version, `"my-app@2"` exactly that one. The first sandbox of a version on a server fetches it, about 10 s a GiB; the server keeps it, and the next ones start in about 0.22 s.

Python

```
preview = sandboxes.create_sandbox("my-app")
print(preview.sandbox_id, preview.template)  # 8j37xshusqwdz8cs my-app@1
```

TypeScript

```
const preview = await sandboxes.createSandbox({ template: "my-app" });
console.log(preview.sandboxId, preview.template);
```

Go

```
preview, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "my-app"})
if err != nil {
	log.Fatal(err)
}
fmt.Println(preview.SandboxID, preview.Template)
```

Rust

```
let preview = sandboxes
    .create_sandbox(CreateSandboxRequest { template: "my-app".into(), ..Default::default() })
    .await?;
println!("{} {}", preview.sandbox_id, preview.template);
```

CLI

```
$ pethost sandbox new --template my-app
✓ Made sandbox ofvm8by6buvd4rkd: default, running, from my-app@2, in <1 s
  port 5173: https://5173-ofvm8by6buvd4rkd.sbx1.sandboxes.pethost.network
ofvm8by6buvd4rkd
Next:   pethost sandbox run ofvm8by6buvd4rkd -- <command>   ·   pethost sandbox shell ofvm8by6buvd4rkd
```

MCP

```
CreateSandbox {"template": "my-app"}
```

The answer's `template` names the exact version it started from, as `my-app@1`.

## What a template keeps

- **Kept:** every file of the sandbox's disk, the packages, your code, Docker's images and containers among them; and the sandbox's settings, which its sandboxes start with unless their create says otherwise.
- **Not kept:** memory and processes, so a sandbox from a template starts with nothing of its running; the commands' history and the coding agents' conversations, which its sandboxes start without.
- **Fresh in every sandbox:** its own id, hostname, machine-id and kernel randomness.

To copy a sandbox with its memory and processes, as it is this second, fork it instead: [forks](https://pethost.dev/docs/sandboxes/forks/). A template is for many sandboxes over days; a fork is for a few copies now.

## Versions and sizes

Each save of a name is its next version. `"my-app"` always means the newest READY one, the one before while a new one saves, so saving never breaks your creates. A name keeps 10 versions; a FAILED version takes nothing and goes a day after. A workspace saves one version at a time, and a sandbox keeps the version it started from, even after you delete the template.

A READY version has a `min_size`: the smallest size whose disk holds what it saved. Its sandboxes take any size from it up. A create with a smaller size is refused, naming the one that fits.

## Where it is kept, and what it costs

A version is shrunk to what it holds, compressed, encrypted with a key of its own and kept in object storage in the EU, where every server can start sandboxes from it. Only its own bytes count, not the base under it. Templates are not billed: your plan bounds what the workspace's versions take together, 5 GiB on the $20 plan and 30 GiB on the $100 plan (`Limits.template_gib`; `Workspace.template_bytes` is what they take now). `DeleteTemplate` deletes every version of a name and frees the room at once; sandboxes made from it go on running, pausing and resuming.

## Our template: base

`base` is Ubuntu 24.04 with build tools and git, Python 3, Node.js 22, Docker with Compose, Claude Code, Codex and OpenCode, and a desktop with Google Chrome. We rebuild it monthly, and at once for a security fix of Chrome, the kernel or a package. `Template.base` names the version a template's sandboxes start on, by a hash of what it holds: a version you save keeps the base its sandbox started on, so your template does not change under you.

There is no build from a Dockerfile: run your Dockerfile's steps in a sandbox, or `docker build` inside it, and save that sandbox.

## When it does not work

- **`RESOURCE_EXHAUSTED` with `LimitReached`, `template_gib`:** the workspace's versions take its plan's room, or another version is saving. Delete an old template, or wait for the save.
- **`LimitReached`, `template_versions`:** the name has 10 versions. Save under a new name, or delete the template and save again.
- **The version is FAILED:** `failure_message` says why, as a version whose own bytes passed the room left. Free room, then save again.
- **`INVALID_ARGUMENT` naming a size:** the size is smaller than the version's `min_size`. Ask for that size or a larger one.
- **The first sandbox from a new version is slow:** its server fetched the version, about 10 s a GiB. The next ones there start in about 0.22 s.

## Questions

### How do I make a custom sandbox template?

Set a sandbox up as you want new ones, then `CreateTemplate` with a name and its id. Start new sandboxes with that name.

### Does a template keep running processes?

No: files and settings only. To copy a running sandbox with its memory and processes, fork it.

### Are templates billed?

No. Your plan bounds how many GiB the workspace's templates take in object storage.

### Can I build a template from a Dockerfile?

Not directly: run the Dockerfile's steps, or `docker build`, in a sandbox, then save the sandbox as a template.

### Do Docker images survive in a template?

Yes. Docker's images and containers are on the sandbox's disk, which the template keeps.

[PreviousComputer use: Chrome on a desktop in a sandbox](https://pethost.dev/docs/sandboxes/computer-use/) [NextSecrets and egress: keys a sandbox never holds](https://pethost.dev/docs/sandboxes/secrets-and-egress/)

## Try Pethost Agent Sandboxes

A 7-day trial with $1 of usage and 4 vCPUs, with a card. Then a plan from $20 a month, which includes as much usage.

[Start the trial](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/templates/)
- [About](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Terms](https://pethost.dev/terms/)
- [Privacy](https://pethost.dev/privacy/)
- [Refunds](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Databases

- [Postgres](https://pethost.dev/postgres/)
- [Valkey](https://pethost.dev/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/sandboxes/)
- [Pricing](https://pethost.dev/sandboxes/#pricing)
- [Docs](https://pethost.dev/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparisons

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/blog/coolify-cloud-vs-dokploy-cloud/)
- [Railway vs Render vs Fly.io pricing](https://pethost.dev/blog/railway-vs-render-vs-fly-io-pricing/)
- [Managed Docker Compose hosting](https://pethost.dev/blog/managed-docker-compose-hosting/)

Alternatives

- [Railway alternatives](https://pethost.dev/blog/railway-alternatives/)
- [Heroku alternatives](https://pethost.dev/blog/heroku-alternatives/)
- [Dokploy alternatives](https://pethost.dev/blog/dokploy-alternatives/)
- [Coolify alternatives](https://pethost.dev/blog/coolify-alternatives/)
- [Render alternatives](https://pethost.dev/blog/render-alternatives/)
- [Sliplane alternatives](https://pethost.dev/blog/sliplane-alternatives/)
