# 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: 4Gi
    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
```

| Field | Required | Description |
|-------|----------|-------------|
| `name` | no | Stable name used in SandboxProbe check results. Defaults to the procd context ID. |
| `type` | yes | `cmd` or `repl`. |
| `alias` | no | Process alias stored in procd context metadata. |
| `command` | for `cmd` | Command path and arguments. Not allowed for `repl`. |
| `cwd` | no | Absolute working directory. Reserved paths such as `/config` and `/procd/bin` are rejected. |
| `envVars` | no | Process-specific environment variables. |
| `probes` | no | Optional `startup`, `readiness`, and `liveness` SandboxProbe definitions for this warm process. |

## 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: 4Gi
    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

<CardGroup>
  <Card title="Configuration" href="/docs/template/configuration" cta="Continue">
    Tune template resources, runtime behavior, mounts, and networking.
  </Card>

  <Card title="Overview" href="/docs/volume" cta="Continue">
    Use persistent volumes to keep workspace data beyond sandbox lifetimes.
  </Card>
</CardGroup>
