Template Configuration

A template describes reusable sandbox inputs. The public spec is runtime-neutral: it contains an image, default memory and RootFS storage, guest security class, claim-lifetime ephemeral mounts, environment variables, metadata, and a default network policy. Scheduling and warm-pool topology are platform concerns and are not embedded in a template.

Example#

yaml
spec:
    displayName: "Python 3.12 Data Science"
    description: "Python with project dependencies preinstalled"
    tags:
        - python
        - data-science

    mainContainer:
        image: registry.example.com/t-<team-key>/my-ds-env@sha256:<64-hex-digest>
        securityClass: privileged
        resources:
            memory: 8Gi
            ephemeralStorage: 8Gi
        env:
            - name: PYTHONPATH
              value: /workspace

    ephemeralMounts:
        - mountPath: /var/lib/docker
          sizeLimit: 16Gi

    envVars:
        LOG_LEVEL: info
        TZ: UTC

    network:
        mode: block-all
        egress:
            trafficRules:
                - name: allow-python-package-indexes
                  action: allow
                  domains:
                      - "*.pypi.org"
                  ports:
                      - port: 443
                        protocol: tcp

`mainContainer`#

Field	Required	Description
`image`	Yes	Normalized public or team-scoped private OCI reference pinned as `@sha256:<64 lowercase hex>`. Mutable tags and shorthand names are rejected.
`resources.memory`	Yes	Default sandbox memory, such as `2Gi` or `512Mi`. It must be within the platform limits.
`resources.ephemeralStorage`	No	Immutable RootFS block-device size. The default is `8Gi`; values must be exact bytes, between `300Mi` and `1Ti`, and 4096-byte aligned.
`securityClass`	No	The only supported value is `privileged`, which is also the default. Capabilities apply inside the gVisor guest and do not bypass runsc or expose host devices.
`env`	No	Base environment entries with `name` and `value`.

CPU is platform-derived from memory and is intentionally absent from the public API. Claim-time config.resources.memory can override the template default. The runtime update API does not change an existing sandbox's resource lease. Every value remains subject to the platform maximum.

Carrier allocation resources do not define these limits. Manager leases exact CPU and memory from ctld-reported dedicated-node capacity and the task driver writes the committed lease into the OCI spec.

`ephemeralMounts`#

Each entry creates a size-bounded tmpfs for one runtime generation. Its files are intentionally discarded on pause, runtime replacement, fork, snapshot, or deletion and never enter the block-COW RootFS ledger. Mount paths must be canonical absolute paths, cannot overlap, and cannot shadow runtime-owned paths such as /proc, /sys, /config, or /procd. Size limits range from 1Mi to 1Ti and remain subject to the sandbox memory cgroup.

Use this for throwaway Docker state such as /var/lib/docker. Keep source and durable outputs outside ephemeral mounts.

`envVars`#

envVars defines defaults for procd-managed child processes:

yaml
envVars:
    LOG_LEVEL: info
    TZ: UTC
    APP_ENV: production

Environment precedence is:

image environment, template envVars, and mainContainer.env;
claim-time config.env_vars; and
context, command, service, or function env_vars.

Claim-time and runtime updates affect newly created procd-managed processes; they do not rewrite the environment of an already running process.

`network`#

Templates and sandbox claim/update requests share the same public SandboxNetworkPolicy shape.

Field	Description
`mode`	Required when `network` is present. Use `allow-all` or `block-all` as the unmatched-traffic default.
`egress.trafficRules`	Ordered allow/deny destination and protocol matchers. First match wins.
`egress.protocolRules`	HTTP and MCP operation controls applied after traffic is allowed.
`credentialBindings`	Named credentials available to destination-scoped injection rules.
`egress.credentialRules`	Egress authentication rules that reference a credential binding.
`egress.proxy`	Optional customer-managed SOCKS5 proxy for allowed TCP traffic.

The legacy allowed* and denied* egress fields remain compatibility inputs; prefer ordered trafficRules for new policies. See Network, Protocol Controls, and Credential.

Metadata#

Field	Description
`displayName`	Short human-readable name.
`description`	Longer purpose or provenance text.
`tags`	String labels used for organization and filtering.

Metadata does not change runtime compatibility.

Scheduling And Resources#

Template specs define the image, environment, memory, RootFS storage, security class, ephemeral mounts, network policy, and metadata. CPU is derived from memory by platform policy. The API uses strict decoding and rejects unknown fields.

Platform administrators configure the concrete runtime classes, dedicated node capacity, and the unified resource-neutral carrier pool. A template selects only its public securityClass; manager resolves that selector to one exact compatible carrier class. See Unified Warm Pool.

Next Steps#

Snapshot And Restore

Publish, restore, fork, and rebase durable RootFS state.

Continue

Example#

mainContainer#

ephemeralMounts#

envVars#

network#