English
Docs menu

Agent Sandboxes docs · Tasks

Templates: start sandboxes ready to work

Updated · 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). 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. 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.

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