# 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](/docs/clrk/getting-started/quickstart.md)
and [Local development](/docs/clrk/getting-started/local.md).

### 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](/docs/clrk/reference/cli.md).

### 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](/docs/clrk/getting-started/core-concepts.md) 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.