CRD reference — Workspace and CalibanTask

Both custom resources live in group caliban.caliban-ai.dev, version v1alpha1, and are namespaced with a status subresource. v1alpha1 means the shape may change without conversion webhooks (ADR 0001).

The Rust types in src/crd.rs and src/workspace.rs are the source of truth; deploy/crd/{calibantask,workspace}.yaml is generated from them and a test fails if the committed YAML drifts. See Regenerating the CRDs.

Runnable samples: deploy/samples/.

Workspace

Durable, shared config a CalibanTask references by name: git sources, named model providers (with their credential references), workspace-wide env, egress and agent policy. The operator is the sole reader of provider credential Secrets — a client such as prospero only ever sees the by-name reference (ADR 0004).

The Workspace controller provisions nothing. It validates the spec and writes status.

spec

sources[] entries:

providers[] entries:

Base URL and API key are projected under provider-native env names, because caliban implements no CALIBAN_* namespace for them — it reads OPENAI_BASE_URL, ANTHROPIC_API_KEY and so on. The kind is additionally projected as CALIBAN_PROVIDER, not as a provider selector (selection travels in caliband's SpawnSpec) but because it is the documented input to a user-configured apiKeyHelper.

egress restricts agent-pod egress to DNS plus the listed destinations, replacing the default allow-all rule. An empty allow list is DNS-only.

When you set egress, remember to include the workspace's git remotes, its model provider endpoints, and gonzalod if a task uses spec.state.

agentPolicy — what agents in this workspace may do

Typed settings for caliban's own permission and extension surface, so a cluster author configures them as CRD fields rather than as raw env entries. They win over an env entry of the same name. Every field is optional, and an unset field leaves caliban's own default alone — which is not the same as setting it to false.

The whole block is pinned into status.resolvedWorkspace.agentPolicy with the rest of the Workspace, so it cannot change under a running task.

The authorization switch:

Permission settings. The three marked ⚠ leave no human answering prompts, so each is admitted only when allowUnattended: true — otherwise the task is denied before pinning with reason PostureNotPermitted, and the message names the setting. One switch is the whole answer to "may agents here run unsupervised?", so the same power cannot be reached through a back door (ADR 0006, decision 7).

Extension settings. These reduce what an agent can reach rather than granting it power, so none of them needs allowUnattended.

Unlike a task's own posture, this policy is checked at admission only. It travels inside the pin, so it cannot change under a running task — and revoking a setting therefore does not disturb a task already running.

status

Validation runs in this order, first problem wins: source paths (under root, distinct) → egress CIDRs and ports → duplicate provider names → a resolvable defaultProvider → an existing Secret key for every credentialsRef.

The controller deliberately does not watch Secrets — that would need cluster-wide list/watch on every Secret. Recovery rides the requeue instead: a Ready workspace is re-checked every 300s, a Pending or Failed one every 15s, so creating a missing Secret unblocks it within seconds.

CalibanTask

One agent session: a reference to a Workspace, the prompt, and per-run overrides. The operator reconciles it into an agent-sandbox Sandbox, a token-less ServiceAccount and a NetworkPolicy (ADR 0002).

spec

Which closed sets the API server enforces. task.permissionPosture, state.mode and the Workspace's agentPolicy.permissionMode carry an enum in the generated schema, so a typo in any of them is rejected at admission.

state.mode is a deliberate hybrid: the enum lives in the schema while the Rust type stays a String. A task stored before the enum existed may hold any value, and a typed enum would make such an object fail to deserialize — the operator could not read it at all. So storage::state_problem still rejects an unknown mode at reconcile time (InvalidState), which is what those pre-existing objects get.

The strings in isolation.worktrees, resources.class and lifecycle.* carry no schema enum and are unread. For lifecycle.onDelete that is deliberate rather than an oversight: #42 implements it (drain finalizer → Draining phase → status.checkpointRef, designed in caliban ADR 0057) and waits only on prospero reporting AgentsDrained, so pinning the accepted values now would freeze a surface that work may still refine.

model.name — per-task model override

A task may name its own model without the Workspace binding a whole new provider for it. The override is applied to the pinned resolution, so:

• the bound provider's endpoint and credential still apply — only the model moves;
• it cannot change under a running task, like everything else in the pin (ADR 0004);
• prospero needs no change, since it already builds SpawnSpec.model from the pinned provider.

It is applied after admission, because which model to run is not an admissibility question. A blank name is treated as a misconfiguration rather than a selection: it leaves the provider's model alone instead of clearing it, and the schema's minLength: 1 rejects it outright. model.name is independent of model.routerConfigRef and may be set alongside it.

spec.isolation is a per-run override that wins over the workspace default. That is exactly why egress and agentPolicy are Workspace-level fields and not part of the shared isolation block — a task must not be able to widen a restriction the workspace imposed.

permissionPosture

unattended is admitted only when the referenced Workspace sets agentPolicy.allowUnattended: true. A missing policy — including a pin made before the field existed — does not permit it. The check runs before pinning, so a denied task is never pinned to the policy that denied it; allowing it on the Workspace, or editing the task back to supervised, recovers it. The operator never silently downgrades a posture.

The same switch also authorizes the Workspace's own unsupervised agentPolicy settings, so a task is denied with the same PostureNotPermitted reason whether the unsupervised power was asked for by the task or by the workspace — see agentPolicy.

A pinned task is re-checked against its pin on every reconcile. Revoking allowUnattended therefore does not disturb a task already running, but editing a running task's spec to unattended fails it if the pin does not allow it.

The operator does not hand the posture to caliband. prospero maps it onto SpawnSpec.permission_posture, reading status.permissionPosture — the posture the operator admitted — not the spec field.

state (gonzalo persistence)

spec.state becomes caliban's storage settings by environment (CALIBAN_STORAGE_SUBSTRATE, CALIBAN_STORAGE_REMOTE_URL, CALIBAN_STORAGE_REMOTE_TOKEN_ENV), so the operator never authors caliban's settings file. The CRD's local is caliban's fs. Requires a caliban build with environment overrides for those settings.

A tokenRef projects the gonzalod bearer token into the pod as GONZALO_TOKEN from the named Secret; only the variable's name appears in the pod spec. Use a principal with read/write on the gonzalod caliban namespace only — no write on fleet or fleet-audit.

These combinations fail the task with reason InvalidState: an unknown mode; mode: remote without gonzaloEndpoint; mode: local with a gonzaloEndpoint it would never use; a tokenRef without remote storage; a tokenRef whose Secret or key is missing.

status

The operator writes status with server-side apply under field manager caliban-operator. A field it owns but omits is removed, so a cleared value is omitted rather than serialized as null.

Phases

A serviceFQDN alone is not readiness: it appears as soon as the Service object exists, before caliband has bound its port. Running gates on agent-sandbox's own Ready condition instead.

Terminal phases come from prospero, because infrastructure cannot tell "agent running" from "agent finished, pod still up" — only caliband's agent list knows, and the operator is never a caliband client. Without prospero deployed, a finished task stays Running.

Ready condition reasons (operator-owned)

AgentsSettled reasons are prospero's: Succeeded, Failed, or AgentsActive (not settled — an idle interactive task stays unsettled).

A task whose Workspace exists but is still Pending is not failed: it is not pinned either, and the reconcile simply requeues in 10s to re-check once the Workspace controller has validated it.

Events

kubectl describe calibantask <name> shows what the logs would otherwise hold. Notes are truncated at 1 kB; publishing is best-effort and never fails or delays a reconcile.

What one CalibanTask creates

All three carry a controller OwnerReference to the task, so deleting the task cascades, and are applied with server-side apply so re-reconciles converge on one object. Deleting a task tears its Sandbox down immediately, without checkpointing in-flight agents (the drain finalizer is deferred).

The pod runs every container — the git-clone init container included — as one uid/gid (default 10001, caliban's app user) with runAsNonRoot: true and fsGroup set to the same gid, so the clone step and the agent cannot drift apart and a non-root clone succeeds whatever mode the volume provisioner gave the volume root. See Deploying for the one case this does not repair.

The reconcile re-runs on every change to the task and to the Sandboxes it owns, so a Sandbox becoming Ready reconciles the task at once. The 300s periodic resync is only a safety net against missed events.

Regenerating the CRDs

The committed YAML is generated, never hand-edited. A *_is_in_sync test fails if it drifts from the Rust types:

cargo run --bin crdgen calibantask > deploy/crd/calibantask.yaml
cargo run --bin crdgen workspace   > deploy/crd/workspace.yaml
cargo test --workspace

The Sandbox type in src/sandbox.rs is a read/write view of a CRD agent-sandbox owns, not a schema of record. crdgen never emits it and no test drift-guards it; fields the operator omits are pruned by the API server's structural schema.

After a CRD change, the copies in the caliban-crds Helm chart need the same update — that chart names deploy/crd/*.yaml here as its source of truth.