Overview
What CLRK is and how the major pieces fit together.
CLRK is a Kubernetes-native runtime for LLM agents. It runs each agent in an isolated
sandbox with fully intercepted networking, so credentials, telemetry, and policy all live
in the platform - not in the agent process. It is shipped as a CLI plus two server
binaries (controller-manager and worker) under the clrk.apoxy.dev/v1alpha1 API group.
CLRK exists to solve four problems every agent platform hits once it leaves a notebook:
- Auto-instrumented telemetry. Every LLM, MCP, and tool call an agent makes is captured at the egress proxy as an OTLP record - request URL, provider, model, tokens, latency - without any agent-side SDK.
- Governance. Default-deny outbound, rate limits, token budgets, header rewrites, and TLS MITM are applied uniformly to every sandbox so a single misbehaving agent can't reach the open internet or burn unlimited spend.
- Attribution. Each execution carries an identity surfaced through ext_proc, so you can trace one inbound request through every downstream LLM call it produced.
- Credential hygiene. Provider keys live in Kubernetes Secrets and are injected by the proxy on the way out. The agent process never holds them.
Deployment options
CLRK runs the same controller-manager, worker, and egress data plane in every deployment. The shape of the host environment is the only thing that changes.
Local development
clrk dev brings up the full stack on your laptop: a k3d cluster (docker container
k3d-clrk-dev-server-0, plus a clrk-registry container when a local registry is enabled)
running the controller-manager as an in-cluster Deployment in the clrk namespace and N
workers behind the default-workers Deployment in the default namespace. State persists
under ~/.clrk/ and a host-side kubeconfig is written to ~/.clrk/kubeconfig.host.
Recommended for hands-on exploration and the entire authoring loop. See the Quickstart
and Local development.
Bring-your-own Kubernetes
In production CLRK is deployed as two workloads - controller-manager (Deployment) and
worker (Deployment) - into a Kubernetes cluster you operate. The CRDs install
once; agents, pools, and gateways are then applied against your cluster's apiserver with
clrk apply -f or plain kubectl apply -f. Worker pods require privileged access for
libcontainer and TUN devices; size a node pool accordingly.
Contact Apoxy if you want a hosted control plane - that is on the roadmap but not yet generally available.
Configuration
All deployments use the same primitives.
clrk CLI
The clrk command is a thin client for everyday operations: bring the local stack up,
apply manifests, list agents and pools, materialize Secrets from environment variables,
and target any cluster via standard --kubeconfig/--context flags (or --local for the
dev session). See the CLI reference.
YAML manifests
Every CLRK resource - TaskAgent, DaemonAgent, WorkerPool, EgressGateway,
AIProviderRoute, CredentialInjectionPolicy, and friends - is a Kubernetes-style
custom resource. Apply them with clrk apply -f or kubectl apply -f. See
Core concepts for the full resource model.
kubectl
clrk dev exposes a standard kubeconfig at ~/.clrk/kubeconfig.host. Anything CLRK can
do over its CLI you can also do with kubectl - get, describe, port-forward,
logs against the worker pods, and so on. The CLI is a convenience layer, not a
requirement.