Product: Clawdlinux. Component: Kubernetes operator.
In-cluster governance for AI agents on Kubernetes.
Runtime-agnostic workload contracts, isolation and egress configuration, model-cost evidence, and offline-verifiable audit primitives.
Platform teams running AI agents on Kubernetes face the same regulated-ops questions regardless of which agent runtime they use.
Who can the agent call? Which runtime isolates it? What did it cost? What did it do? Can an auditor replay it later?
Clawdlinux is building the in-cluster governance boundary around those workloads. It does not replace the agent runtime.
The repository currently ships the AgentWorkload lifecycle, runtime adapters, admission mutation, generated network-policy objects, model routing and cost paths, and HMAC hash-chain verification primitives. These components have different integration depth. The current controller does not yet emit a complete signed artifact from each run.
The target contract connects caller identity, declared access, action policy, approval, cost, outcome, and independently verifiable evidence in one transaction. That target is the product direction, not a claim about the current end-to-end path.
How an action is decided, as a target design (see decision architecture):
- Invariants in code. Credentials never reach the agent. Egress only to declared destinations.
- A decision model scores each action. It can only escalate to a human.
- Humans approve, reject, or edit. Every decision is a signed, labelled example.
Today the repo ships invariants, policy packs, a threshold evaluator, and human approvals. The decision model exists but is escalate-only, runs in shadow mode by default, and only once an artifact is mounted. The shipped artifact is trained on synthetic DRAFT scenarios and is not validated on real decisions. The ADR lists what is built and what is not.
| Capability | Current repository state |
|---|---|
| Runtime isolation | gVisor RuntimeClass mutation for labeled pods; nodes must provide runsc |
| Network controls | Default-deny and allow-list policy generation; enforcement depends on the cluster CNI |
| Audit | Opt-in Ed25519 decision receipts on the direct action path (receipts), plus HMAC hash-chain primitives; execution outcomes and runtime-adapter runs are not receipted |
| Cost | Per-workload usage and estimated-cost paths plus chargeback hooks |
| Context | ANF view snapshots (internal tooling): agentctl renders token-minimal Kubernetes and agent state for the model |
| Delivery | Helm packaging and offline JWT validation; full air-gapped install testing remains a release gate |
| Orchestration | Argo Workflows DAG orchestration |
Clawdlinux currently registers 3 Kubernetes runtime adapters:
- Clawdlinux AgentWorkload (built-in CRD)
- CNCF agent runtimes like kagent
- Custom agent pods with the right labels
The runtime handles agent lifecycle, tools, and model dispatch. Clawdlinux supplies workload, policy, isolation, cost, and evidence primitives around it. A production integration must map those controls to the customer's identity, network, storage, and compliance program.
| Problem | Clawdlinux |
|---|---|
| Agent sprawl across namespaces | Single AgentWorkload CRD per agent |
| No network boundaries | Kubernetes and optional Cilium policy objects generated from reviewed configuration |
| Invisible costs | Per-workload token metering + cost attribution |
| Manual DAG wiring | Argo Workflows orchestrates agent steps |
| Vendor lock-in | Any LLM via LiteLLM proxy routing |
| Cloud-only control planes | Self-managed, in-cluster deployment with offline licensing support |
Any agent deployment can opt into Clawdlinux's gVisor injector with one label:
agentic.clawdlinux.org/runtime-sandbox: gvisorThe Clawdlinux webhook mutates matching Pods on create:
runtimeClassName: gvisorBy default, the webhook denies a matching Pod unless the RuntimeClass exists
and a Ready node can run it. When the RuntimeClass has no scheduling selector,
set this label on each node after confirming runsc is installed:
agentic.clawdlinux.org/gvisor-ready: "true"Set global.runtimeSandbox.enforcementMode=best-effort only when you accept an
unsandboxed fallback.
No fork required. No custom build required. Works with any pod that carries the label.
kubectl apply -f config/samples/agentworkload_demo.yaml
kubectl -n agentic-system get agentworkloads -wFor the reproducible evidence demo, use
docs/SHOWCASE-DEMO-WALKTHROUGH.md.
It labels current-run, configuration-only, and prior-run evidence separately.
Clawdlinux's AgentWorkload CRD is already an agent-readable interface. Agents
can read the schema and reason about the spec. agentctl mcp serve is the
wire-protocol surface so an external orchestrator agent (Claude Desktop,
Cursor, ChatGPT, custom Python) can provision its own Clawdlinux execution
environments without a human running kubectl.
export CLAWDLINUX_MCP_TOKEN=$(uuidgen)
agentctl mcp serve --addr :8765 --default-namespace agentic-systemSix tools, 1:1 with CRD verbs: create_workload, get_workload_status,
list_workloads, get_workload_logs, get_workload_cost, delete_workload.
Full reference in docs/agentctl/mcp.md. Examples in
examples/mcp-claude-desktop/ and
examples/mcp-orchestrator/.
Option A: One command (requires kind + helm):
curl -sSL https://raw.githubusercontent.com/Clawdlinux/agentic-operator-core/main/scripts/install.sh | bashOption B: Step by step:
git clone https://github.com/Clawdlinux/agentic-operator-core
cd agentic-operator-core
# Create local cluster
kind create cluster --name agentic-operator
# Install CRD + operator
kubectl apply -f config/crd/agentworkload_crd.yaml
helm dependency build ./charts
helm upgrade --install agentic-operator ./charts \
--namespace agentic-system --create-namespace \
--set license.key=dev-only-not-a-valid-license
# The development license value is packaging-only in OSS mode.
# Do not use it in production.
# Deploy your first agent
kubectl apply -f config/agentworkload_example.yaml
kubectl -n agentic-system get agentworkloads -wOption C: GitHub Codespaces (zero local setup):
One script proves the decision-architecture claims on a fresh kind cluster. No API keys. A deterministic mock MCP server plays the agent. Each scenario prints its command and a PASS or FAIL line. The script exits nonzero on any failure and deletes its cluster at the end.
Prerequisites: docker (running), kind, kubectl, helm, go, python3, openssl, curl.
scripts/demo-claims.sh # --keep, --skip-build, --cluster-name, --dry-run, --helpRuntime: about 5 minutes end to end, build included. Two runs from a fresh cluster took 252s and 297s on an Apple Silicon laptop (kind v0.31, images already pulled). About 90s of that is a settle wait after each of the two operator restarts. A new pod's first connections stall on kind, and the operator then fails closed with INV-05.
The demo runs the secure configuration. It creates the receipt signing key,
pins the writer public key from it, and mounts an approval stamp HMAC key. It
never sets RECEIPTS_INSECURE_NO_PIN.
It proves invariants (INV-01, INV-03, INV-06), write-ahead receipts, pack
escalation, HMAC-stamped approvals, identity digests in receipts, replay
refusal for a consumed approval, offline verification with a signed manifest,
rejection of a removed manifest and a wrong pin, an operator pinned to the
wrong writer key denying by INV-05, and the shadow decision model. It does not
prove the runtime-adapter path, Argo approval gates, execution outcome
receipts, production model quality, packet-level egress, caller identity,
escalate mode on a failed model load, or agentctl resourceVersion conflicts.
The script ends with the full list. It builds a demo-only image from host
binaries until the receiptspec dependency is tagged. See
BLOCKERS.md.
flowchart LR
USER["Platform engineer or orchestrator"] --> API["Kubernetes API"]
API --> OP["Clawdlinux operator"]
OP --> REG["Runtime registry"]
REG --> ARGO["Argo adapter"]
REG --> POD["Pod adapter"]
REG --> KAGENT["kagent adapter"]
OP --> COST["CostReporter interface"]
OP --> STATUS["AgentWorkload status"]
LABELS["Governance labels"] --> ADMISSION["gVisor admission mutation"]
LABELS --> NETPOL["Network-policy objects"]
AUDIT["Audit hash-chain primitives"] --> VERIFY["audit-verify JSONL verifier"]
The operator selects argo, pod, or kagent through pkg/runtime.Registry.
Adapters stamp shared governance labels. The admission webhook and network-policy
templates consume those labels. Actual sandboxing requires gVisor on the nodes.
Network enforcement depends on the cluster CNI.
The audit package and offline JSONL verifier are implemented. The controller does not yet append each run event into that chain. Separately, opt-in signed decision receipts cover each direct-path decision before it runs. Durable storage, key rotation, and independently verified checkpoints remain integration work.
| Component | Description |
|---|---|
| AgentWorkload CRD | Declarative spec for agent objective, model, quotas, egress rules |
| Controller | Reconciles workloads → namespaces, network policies, workflows, artifacts |
| Argo Integration | Agent steps execute as DAG nodes with retries and timeouts |
| Network policy | Default-deny and allow-list policy templates; optional Cilium FQDN policy |
| Model Routing | Operator classifier plus optional LiteLLM multi-provider proxy |
| MinIO | Optional in-cluster object storage subchart; same-run audit bundling is not connected |
| Multi-tenancy | Namespace isolation with quota enforcement per tenant |
| Cost Attribution | CostReporter interface, no-op default, and in-memory demo reporter |
| Python Agent Runtime | Batteries-included agent framework with tool integrations |
| Available in this repository | Target product work |
|---|---|
| AgentWorkload CRD and runtime adapters | Actor identity propagated into every run |
| Argo DAG and BYO pod execution | Universal tool-call mediation |
| Admission mutation and policy-object generation | Enforcing-cluster packet tests |
| Model routing and cost-reporting interfaces | Durable cost and chargeback integration |
| Audit hashing, signing, and JSONL verification | Same-run capture, durable storage, and external checkpoints |
Clawdlinux does not claim compliance certification. It provides technical controls that customers can map into their own security and compliance program.
The Helm chart renders default-deny egress NetworkPolicies for selected pods
when networkPolicy.enabled=true. It can also create a gVisor RuntimeClass
and register a mutating webhook for labeled pods. The cluster must provide an
enforcing CNI and install runsc. agentctl doctor network-policy reports
passive CNI evidence. Its --active-probe mode tests scratch-namespace packet
flow when given an updated operator image. See docs/07-security.md.
cmd/ Operator entrypoint
internal/controller/ Reconciliation logic
api/v1alpha1/ CRD API types and schema
agents/ Python agent runtime
charts/ Helm umbrella chart
config/ CRD, RBAC, sample manifests
docs/ Documentation
pkg/ Shared packages (billing, license, autoscaling, routing)
tests/ Integration + E2E test suites
assets/ Branding assets (logo, etc.)
| Doc | Description |
|---|---|
| Quick Start | 5-minute setup guide |
| Installation | Production deployment options |
| Configuration | CRD fields, Helm values, tuning |
| Architecture | System design deep dive |
| Multi-tenancy | Tenant isolation and quota enforcement |
| Cost Management | Per-workload billing and chargeback |
| Security | Cilium, action rules, RBAC, and egress hardening |
| Policy input | Declared, observed, and agent-claimed decision inputs |
| Policy packs | Invariants and opt-in Rego packs (dpdp-in, gdpr-eu) |
| Receipts | Opt-in signed decision receipts, receipt-writer, offline verify |
| Approvals | Human approve, reject, edit protocol and the signed approval dataset |
| Decision model | Escalate-only scoring, shadow by default, offline eval, not production-validated |
| Troubleshooting | Common issues and fixes |
This repository is the open-source core. It supports self-managed Kubernetes deployment and offline JWT validation. A reproducible full air-gap installation test remains a release gate.
The private companion adds enterprise features built on top of the core's cost-attribution primitives:
- License validation and trial enforcement
- External billing system integrations (e.g. OpenMeter, Stripe, internal chargebacks)
- Production DOKS deployment overlays
- Customer-specific security and compliance integrations
Neither repository alone makes a deployment compliant with a named framework. Scope, controls, operations, and independent assessment remain customer-specific.
We welcome contributions! See CONTRIBUTING.md for guidelines.
# Fork, clone, create a branch
git checkout -b feat/my-improvement
# Run tests
make test
# Submit a PRSee ROADMAP.md for the public roadmap and quarterly milestones.
Design proposals in flight live in docs/rfcs/. Currently in design:
- RFC-0001: Cross-Cluster Agent Identity Federation (SPIFFE/SPIRE): multi-cluster identity for agents in air-gapped and regulated environments. Validation gate: 6+ use cases or 1 paying customer. GitHub Discussion opens shortly; track status in epic #146.
- Discord: Join our Discord for questions, discussions, and design partner conversations
- Issues: Report bugs or request features
- Releases: Subscribe to releases for changelog updates
Apache License 2.0. See LICENSE.