---
title: "Templates"
description: "Named environments that sandboxes start from."
---

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

# Templates

:::note[Planned]
Templates are not available yet. The samples show the planned API.
:::

:::note[Today]
Today every project has one template, `default`, and every sandbox starts from it. Another template name is `NOT_FOUND`, and a create that names an image is refused with `INVALID_ARGUMENT`.
:::

A template is a named environment that a sandbox can start from. Use one when many sandboxes need the same tools, settings and processes.

## Versions

A template has versions, and a version never changes. To change a template, create a new version. Sandboxes that already run keep the version they started from.

You build a version from one of two sources:

- An OCI image, such as `docker.io/library/python:3.12`.
- A [snapshot](https://docs.jgcp.mistrivedev.com/sandboxes/snapshots/) of a sandbox you set up by hand.

## Defaults

A version carries defaults for every sandbox started from it:

- Resources: CPU, memory and disk.
- Environment variables.
- [Ports](https://docs.jgcp.mistrivedev.com/sandboxes/ports/) and [volumes](https://docs.jgcp.mistrivedev.com/sandboxes/volumes/).
- A lifecycle policy, within your organization's limits.
- Processes to start when the sandbox boots, by name.

Values you pass when you create a sandbox override the defaults.

## Start a sandbox from a template

Set `source.template` when you create a sandbox. Pass the template's name to use its latest version, or a version's name to pin it.

For a quick start without a template, set `source.image` to an OCI image instead. Sutra builds it once and reuses the build for every sandbox with the same image digest.

## Built-in templates

Sutra has a catalog of built-in templates for common environments. They are read-only and shared by every project, so you can use them without creating anything. A sandbox created without a source starts from the default built-in template.

Source: https://docs.jgcp.mistrivedev.com/sandboxes/templates/index.mdx
