Sandboxes

ccp apply also manages Sandbox templates — versioned, organization-scoped recipes for ephemeral VMs. Applying a template reconciles its stable identity and admits one immutable build for its exact recipe; ccp sandbox create launches a fresh, short-lived Sandbox from a template's current ready build.

Apply a template

ccp apply -f sandbox.yaml --org-id "$CCP_ORG_ID"

Reapplying an unchanged manifest reuses the same template and its ready or in-progress build — it never creates a duplicate. Pass --dry-run to run the same reconciliation without writing a template or build.

A SandboxTemplate manifest looks like:

apiVersion: sandboxes.clusterbase.ai/v1
kind: SandboxTemplate
metadata:
  name: python-tools
spec:
  base: development
  resources:
    vcpu: 2
    memory_mb: 1024
  packages:
    apt: [jq]
    pip: [cowsay==6.1]
  steps:
    - run: touch /workspace/ready

metadata.name is the stable organization-scoped template identity. spec.resources is required and must be one supported vcpu / memory_mb pair — 1/256, 1/512, 2/1024, 4/2048, or 4/4096 (vCPU/MiB); any other pair is rejected. The manifest accepts the same typed apt, pip, npm, cargo, gem, and go package specifications as Sandbox template builds, followed by exactly one run step.

Changing resources, packages, or the run step admits a new immutable build; existing builds are never mutated. Build execution, publication, scheduling, and every Sandbox launch use the exact resource pair snapshotted by that build.

Keep manifests commit-safe. Unknown fields are rejected, including plaintext secrets or env blocks and mutable templateId, templateBuildId, vmId, or sandboxId fields — build and runtime identities are server-derived.

Launch a Sandbox

Ephemeral creation is a separate lifecycle operation from applying a template. Creating a Sandbox launches the applied template's current exact ready build:

ccp sandbox create --template python-tools --ttl 15m --org-id "$CCP_ORG_ID"

--ttl defaults to 15m and accepts whole-second human durations from 1m through 24h. Every invocation creates a distinct Sandbox while reusing the same immutable build; applying a template's desired state never launches a Sandbox on its own.

create fails with template_not_found when the active organization-scoped name doesn't exist, and template_not_ready while its current recipe has no ready build yet — wait for the applied build to publish, then retry.