Clawdlinux Operator Architecture

Clawdlinux Operator governs Kubernetes agent workloads without replacing their execution runtime. It provides workload contracts, runtime adapters, admission mutation, network-policy configuration, cost paths, and offline audit verification primitives.

Workload Flow

1. A platform engineer or external orchestrator submits an AgentWorkload through the Kubernetes API.
2. The controller checks configured license and budget interfaces.
3. pkg/runtime.Registry selects the configured runtime adapter.
4. Adapters stamp shared governance labels for admission and network configuration.
5. Workload status and available metrics record progress and outcomes.

The legacy direct path classifies tasks, routes models, and evaluates actions separately. Audit capture is not connected across either complete execution path.

Runtime Adapters

• argo: default Argo Workflows DAG execution.
• pod: bring-your-own single pod, using CLAWDLINUX_AGENT_IMAGE.
• kagent: BYO Agent through an unstructured client, without a typed Go dependency; requires kagent in the cluster.

Runtime selection uses spec.orchestration.type. Shared labels connect every adapter to common governance configuration. Actual gVisor isolation requires runsc on nodes. NetworkPolicy enforcement depends on the cluster CNI.

Tenant And Reporting Components

The Tenant reconciler creates namespaces, copies named provider Secrets, configures RBAC, and creates CPU, memory, and pod-count quotas. Some Tenant API fields lack complete enforcement; see the API reference.

The open-source license validator and cost reporter default to no-op implementations. Offline JWT validation requires a configured production validator. The optional in-memory cost reporter is volatile. Durable reporting requires an external implementation. LiteLLM provides optional in-cluster multi-provider proxying.

Separate Evidence Path

The audit package and offline JSONL verifier are implemented. The controller does not append every workload event to the audit chain. Automatic complete per-run signed evidence is not connected. Durable storage, production signing keys, and independently verified checkpoints remain integration work.

See security, monitoring, and evidence boundaries.