base fragment. Create-time overrides can’t change or remove these attachments.
This page shows how to create and manage templates, how to start sandboxes from them, and complete template documents for common use cases. Replace TEMPLATE_ID with the template’s universally unique identifier (UUID) and SNAPSHOT_ID with a file system snapshot ID. Replace GITHUB_ORG with your GitHub Container Registry organization or user name.
Create a template
Organization admins manage templates. Write operations require the Sandbox Admin role. Every sandbox user in the organization can read templates and start sandboxes from them.- CLI
- curl
Create a template from a file:Inspect and list existing templates:
template.json
displayNameis required and must be unique among the organization’s active templates: 1 to 128 characters after trimming. Prefer names that aren’t UUID-shaped, so they don’t collide with ID-first lookup.specis a partial sandbox specification, capped at 1 MiB. It uses the same fields as a create request, and everything in it can be overridden at create time.speccan’t select an instance type or attach sandbox networks yet: A template that setsinstanceTypeornetworkIdsis rejected as unimplemented.- Template contents are visible to every sandbox user in the organization: A template isn’t a secret-distribution channel. Literal credentials don’t belong in one.
Start a sandbox from a template
Start a sandbox from a template by ID. Selection is by UUID only. Display names work for lookup and listing, not for create.Create a sandbox from a template
overrides with the same shape as a sandbox specification. Overrides replace whole fields:
- A message you set replaces the template’s whole message. A message you omit keeps the template’s value.
- A non-empty list replaces the template’s whole list. An empty JSON list, such as
tags: []orservices: [], preserves the template’s list. To remove some entries, send the full non-empty list you want to keep. An empty list can’t clear an inherited list. - A map you set replaces the template’s whole map. For example,
annotations: {}clears inherited annotations in a direct HTTP request. Software development kit (SDK) serialization can differ. See the version-specific TypeScript behavior in this section. - Overriding any container field replaces the entire container list. A template container has no sparse patch, so an override that touches the container must carry the full container, including
image.
Override the container per run
Sandbox.run_from_template() and client.runFromTemplate(). See the Python client for the Python workflow.
In version 1.0.0 of the TypeScript client, tags: [], services: [], annotations: {}, and runnerIds: [] preserve template values. network: {} replaces the template network. For per-field override behavior, see SandboxRunFromTemplateOptions.
Example templates
The following examples are complete documents forcwic sandbox template create -f template.json. Unlike a policy, an organization can hold many templates, so these compose: create one per recurring workload shape.
Web service with a public HTTPS endpoint
A template for sandboxes that serve HTTP to the public internet through a platform-issued HTTPS endpoint. The assigned URL is echoed on the sandbox after create.template.json
Workspace restored from a snapshot
A template whose scratch volume starts from the same file system snapshot every time: a golden workspace that each sandbox forks privately.template.json
Curated egress
A template that grants a fixed set of destinations: one classless inter-domain routing (CIDR) range on port443 plus sibling sandboxes in the same organization. Every rule must fit inside the runner policy’s allowedEgress envelope, or the create is rejected.
template.json
network.egress opts into the policy’s defaultEgress when network.denyEgress is unset or false. Keep the egress list on the template when the workload’s destinations are known, and leave it empty when the policy default is the right posture.
With the dynamic network configuration API, each sandbox created from a template receives its own network configuration. Templates keep inline network rules and can’t pin a networkConfigId. For the create-time override, see Sandbox and template fields.
CKS-only: Pod attachments
On your own CKS cluster, an admin can put anattachments block on a template: a Kubernetes Pod-specification fragment applied to every sandbox created from it. This is how a template pins Node selection, tolerations, or a pull Secret that the sandbox specification itself has no fields for.
template.json
- A template with attachments is CKS-only: Its
requiresCksoutput field istrue, and creating from it withmodeset toSANDBOX_MODE_SERVERLESSfails withFailedPrecondition. An unset mode is treated as CKS. - Attachments are admin-owned: Only
sandbox_admincan write them, plain create requests can’t supply them, and create-time overrides can’t change or remove them. - The fragment uses Kubernetes JSON, with camelCase keys under
specandmetadata, unlike the sandbox specification fields elsewhere in the template. Unknown keys are rejected. - The allowed surface is deliberately narrow: scheduling and runtime configuration such as
nodeSelector,tolerations,imagePullSecrets,volumes,topologySpreadConstraints,hostAliases, DNS settings, and a singlecontainersentry limited toname,env,envFrom,volumeMounts, andvolumeDevices, plus Pod labels and annotations. Security-sensitive fields are rejected:securityContext,runtimeClassName,initContainers,affinity, host namespaces,hostPathvolumes, and non-default ServiceAccounts, among others. - Attachments layer on top of the policy’s
basefragment: List-valued fields combine with the policy base:imagePullSecretsandtolerationsare deduplicated, whiletopologySpreadConstraints,hostAliases, andreadinessGatesappend. Single-valued fields such asnodeSelectorkeys specialize the base. A same-name volume, environment variable, or mount-path conflict between the two layers rejects the create.
Manage templates
- CLI
- curl
- Reads accept an ID or a display name: If the path segment parses as a UUID it’s looked up by ID. Otherwise it’s resolved as a display name among active templates.
- Every successful update increments the template’s
revision: Sandboxes record the revision they were created from, so you can tell which sandboxes predate a template change. - Delete is a soft delete: Existing sandboxes are unaffected, new creates can no longer select the template, and the display name becomes reusable for a new template.
Next steps
For related guidance, see the following pages:- Policy examples: complete runner policies to pair these templates with.
- Configure a sandbox policy: the constraint groups a template’s spec is validated against.
- Policies overview: how templates and policies divide the work profiles used to do.
- Use your own compute: runner setup and your first sandbox.