# 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-/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 | Initial RootFS filesystem capacity for image imports. 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`. | On deployments with automatic RootFS growth, the runtime expands mounted XFS before free space is exhausted, within the deployment's sparse device ceiling. Expansion keeps the sandbox's processes and open files running. Persisted data lives in regional object storage; host cache and uncommitted write journals have separate bounded budgets. Storage outages or sustained writes faster than publication can delay writes. A large logical ceiling does not reserve the same amount of host disk and does not mean unlimited storage. Fixed-size deployments use `ephemeralStorage` as the immutable device capacity. Changing an import setting or template does not resize existing generations; snapshots, captured templates and paused sandboxes retain their committed geometry. `df` inside the sandbox reports the current filesystem capacity. CPU is platform-derived from memory and is intentionally absent from the public API. Claim-time `config.resources.memory` can override the template default. A standalone `config.resources.memory` update replaces an existing sandbox's runtime lease, preserving its ID and files while restarting processes. Paused sandboxes stay paused. 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: 1. image environment, template `envVars`, and `mainContainer.env`; 2. claim-time `config.env_vars`; and 3. 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](/docs/sandbox/network), [Protocol Controls](/docs/sandbox/protocol-controls), and [Credential](/docs/sandbox/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](/docs/sandbox/template/pool). ## Next Steps Publish, restore, fork, and rebase durable RootFS state.