TEMPLATE/Configuration

#Template Configuration

Reference for the most commonly used template spec fields. Pass the spec as the spec field when creating or updating a template.

Spec Example#

yaml
spec:
    displayName: "Python 3.12 Data Science"
    description: "Python with numpy, pandas, and jupyter pre-installed"
    tags:
        - python
        - data-science

    mainContainer:
        image: registry.sandbox0-system.svc.cluster.local:5000/my-ds-env:v2.0
        resources:
            cpu: "2"
            memory: 8Gi
            ephemeralStorage: 8Gi
        env:
            - name: PYTHONPATH
              value: /workspace

    envVars:
        LOG_LEVEL: info
        TZ: UTC

    pool:
        minIdle: 3
        maxIdle: 10

    network:
        mode: block-all
        egress:
            trafficRules:
                - name: allow-python-package-indexes
                  action: allow
                  domains:
                      - "*.pypi.org"
                      - "*.anaconda.org"
                  ports:
                      - port: 443
                        protocol: tcp
        credentialBindings:
            - ref: gh-token
              sourceRef: github-source
              projection:
                  type: http_headers
                  httpHeaders:
                      headers:
                          - name: Authorization
                            valueTemplate: "Bearer {{ .token }}"

mainContainer#

The main sandbox container configuration.

FieldTypeDefaultDescription
imagestring—Container image reference. Use a public image (e.g., python:3.12-slim) or the Template image reference returned by s0 template image push for private images.
resources.cpustring—CPU limit for the sandbox (e.g., "1", "2", "500m").
resources.memorystring—Memory limit for the sandbox (e.g., "2Gi", "512Mi").
resources.ephemeralStoragestring8GiWritable-layer and container-log storage for the sandbox runtime. Checkpointed pause/resume saves and restores the writable root filesystem, but this quota still bounds writes to /tmp or image-local paths. Use rootfs snapshots and claim-time snapshot_id to version initialized sandbox files, and use Sandbox Volumes for sharing or long-lived durable data independent of sandbox identity.
envarray[]Per-container environment variables. Each entry has name and value.
ℹ

mainContainer.image, mainContainer.resources.cpu, mainContainer.resources.memory, and mainContainer.resources.ephemeralStorage are strictly validated by the API when creating or updating templates.

envVars#

Global environment variables injected into the procd-managed sandbox environment.

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

envVars are set at the template level and become part of the sandbox container's base environment, alongside mainContainer.env. Users can override or extend them at sandbox creation time via the env_vars field in the sandbox config.

Environment variable precedence for procd-managed child processes is:

  1. Container image, template envVars, and mainContainer.env
  2. Sandbox creation config.env_vars
  3. Context, command, service runtime, or function env_vars

Claim-time sandbox env_vars are applied to new procd-managed processes after the sandbox is claimed.

pool#

Warm pool configuration. See Warm Pool for a detailed guide.

FieldTypeDefaultDescription
minIdleinteger—Minimum idle pods to pre-warm. Required (>= 0).
maxIdleinteger—Maximum idle pods allowed. Required (>= minIdle).

Only ready idle pods count toward pool capacity.

network#

Template-level default network policy. Templates now use the same public SandboxNetworkPolicy shape as claim-time and runtime sandbox network configuration.

FieldTypeDefaultDescription
modestring—Required when network is set. Allowed values: allow-all, block-all. This is the fallback for unmatched traffic.
egress.trafficRulesarray—Ordered allow/deny rules. First matching rule wins. Recommended for new policies.
egress.protocolRulesarray—Protocol-aware controls for allowed traffic, such as HTTP request policy and MCP tool allowlists.
network.credentialBindingsarray—Credential bindings scoped under the same network object. Use this for outbound auth setup.
egress.credentialRulesarray—Destination-scoped auth injection rules that reference network.credentialBindings[*].ref.
egress.allowed* / egress.denied*array—Legacy compatibility fields. Prefer trafficRules instead.

See Network and Protocol Controls for traffic behavior, and Credential for bindings and egress auth.

displayName description tags#

Metadata fields for human-readable identification. Not used by the runtime.

FieldTypeDescription
displayNamestringShort human-readable name shown in UI and s0 template list.
descriptionstringLonger description of the template's purpose.
tagsstring[]Labels for filtering and organization.

Privileged Fields#

The following fields require a system-level token. They are not available to regular team API keys and are intended for platform operators configuring multi-tenant or advanced deployments.

FieldDescription
pod.nodeSelectorPin sandbox pods to nodes matching specific labels.
pod.affinityNode and pod affinity/anti-affinity rules.
pod.tolerationsAllow pods to be scheduled on tainted nodes.
pod.serviceAccountNameKubernetes service account for sandbox pods.
pod.emptyDirMountsEphemeral Kubernetes emptyDir mounts for system templates, such as /var/lib/docker for Docker in Sandbox runtime state.
mainContainer.securityContextLinux container security context for system templates. Supports privileged, allowPrivilegeEscalation, runAsUser, runAsGroup, runAsNonRoot, readOnlyRootFilesystem, capabilities.add, capabilities.drop, seccompProfile, and appArmorProfile.
mainContainer.imagePullPolicyPull policy override for the main container image. Only system administrators/system tokens can set this field.
clusterIdPin the template to a specific cluster in a multi-cluster deployment.
ℹ

Attempting to set privileged fields without a system identity returns 403 Forbidden. Contact your platform administrator if you need access to these fields.

pod.emptyDirMounts is backed by Kubernetes emptyDir on the node's default storage medium. Its contents are tied to the sandbox pod lifecycle and are not captured by SandboxVolume snapshots or restore operations. Use it for temporary runtime state and caches, not durable workspace data.

mainContainer.securityContext is intended for platform-owned templates that need runtime-specific privileges, such as container-engine templates on gVisor or Kata. It does not expose host devices or hostPath mounts.

Next Steps#

Overview

Use persistent volumes to keep workspace data beyond sandbox lifetimes.

Mounts

Mount volumes into sandbox templates and claims with correct access modes.