#Template Warm Processes

Use spec.warmProcesses when a template needs a helper process to be running before an idle pod is claimed from the warm pool. Procd remains PID 1 in the sandbox container and starts each warm process during template pod creation.

Warm processes are intended for long-running helpers such as agents, language servers, REPL sessions, and daemon-style workers. If a configured warm process exits, procd exits and Kubernetes restarts the sandbox container with the pod's restart policy.

Warm process stdout and stderr are mirrored to Kubernetes pod logs by default. Procd still keeps the normal process-output API as the source of truth; container logs are an extra diagnostic sink with bounded JSON lines. Set SANDBOX0_PROCESS_LOGS=false in template envVars to disable the container-log mirror. Set SANDBOX0_PROCESS_LOG_MAX_BYTES to change the per-line mirror limit from the default 4096 bytes.

Spec#

yaml
spec:
    mainContainer:
        image: ubuntu:24.04
        resources:
            cpu: "1"
            memory: 2Gi
    warmProcesses:
        - name: codex
          type: cmd
          alias: codex
          command: ["/bin/sh", "-lc", "/app/start-codex.sh"]
          cwd: /workspace
          envVars:
              MODE: warm
          probes:
              readiness:
                  process: {}
              liveness:
                  exec:
                      command: ["/bin/sh", "-lc", "test -S /tmp/codex.sock"]
    pool:
        minIdle: 2
        maxIdle: 10

SandboxProbe#

Warm-pool capacity is based on pod readiness. Sandbox0 does not attach Kubernetes startup, readiness, or liveness probes to sandbox pods. Manager asks ctld to run SandboxProbe checks, and ctld forwards each check to procd inside the target sandbox. Procd evaluates itself plus each managed warm process, then returns one aggregated result.

A pod with Ready=False does not count toward idle capacity and is not selected for a hot claim. Without an explicit probe, procd uses a process-state check: the warm process must still be running. Use exec, httpGet, or tcpSocket probes when the helper can be alive but not useful.

For cmd warm processes, use commands that keep running. One-shot setup commands that exit successfully still make readiness fail because there is no warm process left to claim.

Startup and readiness failures keep the pod out of the claimable warm pool. Liveness failures make procd terminate after returning the failed SandboxProbe response, so Kubernetes restarts PID 1 with the pod's normal restart policy. A frozen paused sandbox reports liveness as suspended from ctld instead of failing.

Process Placement#

Put template-owned helper binaries in the main sandbox image and start them with warmProcesses.

yaml
spec:
    mainContainer:
        image: ghcr.io/example/sandbox-with-helper:v1
        resources:
            cpu: "1"
            memory: 2Gi
    warmProcesses:
        - name: helper
          type: cmd
          alias: helper
          command: ["/bin/sh", "-lc", "/app/helper"]

If the helper needs persistent files, use normal sandbox volume mounts and paths visible inside the main sandbox container.

Next Steps#