Deploying and configuring caliban-operator

The operator is a controller: it watches Workspace and CalibanTask custom resources cluster-wide and creates Sandbox, ServiceAccount and NetworkPolicy objects. It serves no inbound traffic, so it has no Service, Ingress or port.

This page is the reference for the operator's own configuration surface and the cluster prerequisites it assumes. The Helm charts themselves live in caliban-ai/helm-charts; for chart values, see that repo.

Prerequisites

1. agent-sandbox — the agents.x-k8s.io/v1beta1 Sandbox CRD and its controller must be present. This is a cluster-level prerequisite, like a CNI or a RuntimeClass, normally installed by the cluster admin. The operator's Sandbox view is written against agent-sandbox v0.5.0; helm-charts vendors that version as charts/agent-sandbox and the umbrella bundles it by default. Without it, every reconcile's Sandbox apply fails and tasks stay Provisioning — a retried error, not a crash.
2. The caliban CRDs — calibantasks and workspaces, installed as their own step from the caliban-crds chart (Helm does not upgrade a crds/ directory, so that chart keeps them in templates/). They are copies of deploy/crd/ here, which is the source of truth. Applying them directly works too:

   kubectl apply -f deploy/crd/
   

   Upgrade the CRDs before the operator. Against an older CRD, a field the operator relies on — spec.task.permissionPosture, spec.agentPolicy, spec.model.name — is either rejected outright (kubectl apply decodes strictly: unknown field "spec.task.permissionPosture") or silently pruned by the structural schema, so an unattended task would read back as supervised.
3. Lease RBAC, before the operator image — leader election is on by default, so the operator needs coordination.k8s.io/leases in its own namespace. The chart's lease Role is harmless against an older operator, so upgrading the chart first is always safe; the reverse order is not. See Leader election.
4. A session-plane TLS Secret and token Secret — see Session plane below.
5. A default StorageClass — each task's workspace PVC is created with no storageClassName, so it binds the cluster default (deliberately cluster-agnostic).

Kubernetes versions

The operator compiles against the v1_32 k8s-openapi API surface (the lowest the kube 4.0 / k8s-openapi 0.28 pairing offers). It uses only long-stable PodSpec, NetworkPolicy and apiextensions.k8s.io/v1 fields, so it is forward-compatible across the usual skew. The original target was k3s v1.31 (ADR 0001); it currently runs on k3s v1.36. No chart declares a kubeVersion floor, so treat this as a record of what has been run, not an enforced constraint.

NetworkPolicy is only enforced if the cluster's CNI implements it. On a CNI that ignores it, the per-task policy is applied and inert — the isolation posture is silently absent.

Installing

CRDs first, then the operator. Via the charts (caliban-ai/helm-charts, published to the OCI registry oci://ghcr.io/caliban-ai/charts, not an HTTP chart repo — there is no helm repo add):

helm install caliban-crds     oci://ghcr.io/caliban-ai/charts/caliban-crds
helm install caliban-operator oci://ghcr.io/caliban-ai/charts/caliban-operator

(If the registry refuses an anonymous pull, the GHCR package is still private — helm registry login ghcr.io first.)

Or install the caliban-system umbrella chart, which can bring agent-sandbox, gonzalo and prospero with it. Either way, keep environment-specific values in a separate private overlay (-f private-values.yaml); the charts ship neutral, cluster-agnostic defaults only.

Then confirm it is up and try a task:

kubectl get deploy -l app.kubernetes.io/name=caliban-operator   # 1/1 available
kubectl apply -f deploy/samples/workspace.yaml
kubectl get workspaces          # wait for Phase: Ready
kubectl apply -f deploy/samples/calibantask.yaml
kubectl get calibantasks -A     # Phase, Posture

The samples target namespace team-a and reference Secrets that do not exist by default, so the Workspace will report Failed with the missing Secret named in status.message until you create them. That is the intended first signal.

Configuration

Every setting is an environment variable on the controller container; there are no flags and no config file. Unset means the default below.

Images and the agent pod

Note what is not here: caliban's own permission and extension behaviour is not operator configuration. It is set per workspace, as typed Workspace.spec.agentPolicy fields, which the operator projects into each agent pod as CALIBAN_* environment (CALIBAN_DEFAULT_PERMISSION_MODE, CALIBAN_AUTO_ALLOW, CALIBAN_NO_PERMISSIONS, CALIBAN_NO_MCP, CALIBAN_NO_HOOKS, CALIBAN_NO_SKILLS, CALIBAN_NO_SUB_AGENT, CALIBAN_STRICT_KNOWN_MARKETPLACES, CALIBAN_ENABLED_PLUGINS, CALIBAN_BLOCKED_MARKETPLACES, CALIBAN_PARALLEL_TOOL_LIMIT). Those values win over a Workspace.spec.env entry of the same name, and the three unsupervised ones are gated by agentPolicy.allowUnattended. There is deliberately no cluster-wide default for them: the authority is write access to a Workspace.

Ports

The operator validates these at startup and refuses to start on a port outside 1-65535, an empty window (BASE > END), or a CALIBAND_PORT that falls inside the agent window. The error names the offending variable, rather than letting a NetworkPolicy the API server rejects fail every reconcile.

Session plane

caliband serves TLS and requires a bearer token. Both come from pre-existing Secrets in the task's namespace, mounted or projected by the operator.

The token is never an argv value — it reaches the pod from the Secret as an environment variable, so it stays out of kubectl get pod -o yaml and the process table. The ca.crt is handed to caliband so it can pass a trust anchor down to the workers it spawns.

Agent pod resources

Defaults give every agent pod Burstable QoS: requests, no limits — so a pod is not first in line for eviction and is admitted under a ResourceQuota, without a guessed ceiling OOM-killing an agent. An explicitly empty value clears a default rather than only overriding it.

The git-clone init container gets the same values. A pod's effective request is the max of any init container and the sum of its app containers, so this costs nothing at scheduling while still admitting the init step under quota.

Cluster topology and network reach

Unconfigured, ingress to caliband is open to every pod in the task's own namespace — the historical default-deny-everything-else posture. In a real deployment, narrow it to prospero: set CALIBAN_INGRESS_NAMESPACE to prospero's namespace and CALIBAN_INGRESS_POD_SELECTOR to its pod labels.

Observability

RBAC the operator needs

The operator needs a cluster-scoped role — it watches both CRs across all namespaces. This is the verb set the charts grant:

The leases grant is required by default, because leader election is on by default — see Leader election. It only needs to be a namespaced Role in the operator's own namespace, since the lease lives there.

Notes on the shape of that set:

• get on secrets, never list or watch. The operator reads a Secret only by the name a Workspace references, to answer "does this key exist". It never lists or caches Secret data, which is why the Workspace controller re-checks on a requeue instead of watching Secrets.
• No create/delete on calibantasks or workspaces. Clients such as prospero own CR lifecycle; the operator only observes them and writes status.
• events.k8s.io is required for the Events in the CRD reference. Without it, publishing logs a warning and the reconcile proceeds — Events are best-effort.
• prospero needs patch on calibantasks/status of its own to write the AgentsSettled condition. Without it, tasks never reach a terminal phase. That grant lives in prospero's chart, not the operator's.

Leader election

The operator elects a leader through a coordination.k8s.io Lease before running either controller, and it is on by default. A single replica simply acquires the lease immediately; the point of the default is that raising replicaCount can never silently leave two controllers force-applying the same objects.

Operationally:

• Losing the lease stops the controllers and returns the process to standby rather than exiting, so an apiserver blip costs a pause instead of a crash loop. A replica that never wins simply waits, doing nothing.
• A clean shutdown releases the lease rather than waiting out the duration, so failover is prompt.
• Outside a cluster, there is no namespace file: either set CALIBAN_LEASE_NAMESPACE or CALIBAN_LEADER_ELECTION=false. The startup error says exactly this.
• The lease is applied under field manager caliban-operator, like everything else the operator writes.

Running with CALIBAN_LEADER_ELECTION on but without the leases RBAC above is the one new way a previously-working install can break on upgrade: the operator starts, fails to acquire, and never reconciles. Upgrade the chart before the operator image — the chart's lease Role is harmless against an operator that predates leader election (an unused Role and env it ignores), whereas the reverse order fails on lease RBAC. If you keep election off, keep replicaCount: 1: with election off, nothing stops two replicas from force-applying the same objects.

In the chart this is the leaderElection block (enabled, leaseName, durationSeconds, graceSeconds), on by default. Its lease Role is gated behind both leaderElection.enabled and rbac.create, so rbac.create=false with election on is the combination to watch.

The operator's own Deployment should run as uid 10001 with runAsNonRoot: true, allowPrivilegeEscalation: false, readOnlyRootFilesystem: true and all capabilities dropped. It writes nothing to disk, so a read-only root filesystem is safe. See the container image.

Pod identity and the workspace volume

Every container in a sandbox pod — the git-clone init container included — runs as CALIBAN_AGENT_UID/CALIBAN_AGENT_GID (default 10001, matching the app user in caliban's image), with runAsNonRoot: true and fsGroup set to the same gid.

The uid sits on the pod, not on each container, so there is nothing to keep in sync between the clone step and the agent. fsGroup is what makes a non-root clone work on any volume rather than by luck: kubelet applies the group to the mounted workspace with g+rwX, so the clone does not depend on the mode the provisioner gave the volume root. runAsNonRoot turns a misconfigured uid 0 into an admission failure instead of a silent return to root-owned sources.

CALIBAN_AGENT_UID must match the caliband image's user. caliban's image bakes HOME and an XDG_RUNTIME_DIR owned by uid 10001; a different uid cannot write them.

One case this does not repair: the clone is idempotent and skips a source whose <path>/.git already exists, so a workspace volume cloned by an older, root-running init container still holds root-owned sources. The init container is now non-root and cannot chown them back, and git compares the owner uid, so it refuses the checkout even though fsGroup made the files writable. Recreate the task, or delete its workspace PVC, to re-clone as the agent.

Troubleshooting

Start with the task's own status and Events — the failure reason is always on the object:

kubectl get calibantask <name> -o jsonpath='{.status.phase} {.status.permissionPosture}{"\n"}'
kubectl describe calibantask <name>      # conditions + Events
kubectl get workspace <name> -o jsonpath='{.status.phase}: {.status.message}{"\n"}'