# What Is a Cloud-Native Agent Harness? (kagent)

> When a desktop coding harness stops fitting: what a cloud-native agent harness is, and how kagent splits harness, template, instance and sandbox on Kubernetes.

- Canonical URL: https://webofmike.com/what-is-a-cloud-native-agent-harness/
- Author: Mike Moore (https://webofmike.com/about/)
- Published: 2026-10-12
- Last modified: 2026-10-12
- Tags: AI Agents, Kubernetes, Platform Engineering, Generative AI, AI Gateways
- Cite as: Mike Moore, "What Is a Cloud-Native Agent Harness? (kagent)", Web of Mike (webofmike.com), 2026-10-12. https://webofmike.com/what-is-a-cloud-native-agent-harness/


Coding agents grew up on laptops: one person, one machine, and one process that is the UI, the agent loop, the sandbox, the credential store and the session database at once (a framing credited further down). Claude Code and Codex on a desktop work well in that shape. It starts to strain when agents serve many users, run unattended, or have to survive losing a node on Kubernetes. A **cloud-native agent harness** is the answer to that strain, and kagent 1.0 is one open-source way to build it.

*Disclosure: I work at Solo.io, which created kagent and agentgateway (both now open-source projects) and sells Solo Enterprise for kagent and Solo Enterprise for agentgateway. Everything below is open source unless labelled Solo Enterprise, kagent 1.0 is alpha software, and every claim links to the project's own docs or release notes as of 2026-10-01.*

## What is a cloud-native agent harness?

A cloud-native agent harness is an agent runtime built as a distributed application rather than a single desktop process. The agent loop is one replaceable component, and the things a desktop harness bundles into the same process each sit behind their own interface: the client, the sandbox where commands run, the tool catalog, session state, identity, and the network path. That split is what lets an organisation run many sessions at once, keep a conversation alive when a pod dies, govern which tools each agent may call, and attach several clients to the same agent.

Five concerns, each separable (the decomposition follows the CNCF post credited further down):

1. **The loop**: reasoning, tool dispatch, permissions.
2. **Clients**: terminal, UI, API or another agent.
3. **The execution environment**: the sandbox where the agent's commands run.
4. **Tools**: a catalog the agent may call, often over MCP.
5. **Supporting services**: session state, identity, models and the network path.

kagent's docs draw the same line in their own words: the 1.0 model "separates what an agent can do from how it is allowed to run" ([core concepts](https://kagent.dev/docs/kagent/1.x/about/core-concepts/)).

## Signs your desktop harness has stopped fitting

Each sign is a mechanism, not a product:

- **More than one person needs the same session.** A desktop session lives in one process on one machine.
- **Runs happen with nobody watching.** Scheduled or event-driven runs need a home that isn't a laptop, and regression checks once nobody reads every transcript (see [kagent trajectory evals](/kagent-trajectory-evals/)).
- **A pod or node dies mid-task and the conversation must survive.** That needs session state outside the process.
- **Security wants a tool catalog, not an unrestricted shell.**
- **Each call must carry a user identity**, not the developer's own credentials.
- **Outbound traffic must be limited and logged.**
- **Model keys must not sit in the agent's environment.**

If none of these apply, a desktop harness is the simpler choice. If several do, you need the loop, state, sandbox and network boundary as separate, operable components.

### Why "put it in a container" isn't the answer

A container moves the process and leaves its structure alone: UI, loop, sandbox, credentials and session state are still coupled to one long-lived machine. kagent's answer is structural. The controller compiles a runtime policy and a behaviour definition into an immutable revision, and each conversation runs on its own sandboxed Actor that can be suspended and resumed elsewhere ([core concepts](https://kagent.dev/docs/kagent/1.x/about/core-concepts/)).

## What it looks like on Kubernetes: kagent 1.0's model

*Last checked 2026-10-01, kagent v1.0.0-alpha7, agentgateway v1.5.0.* kagent 1.0 is alpha: the docs open with "This documentation covers the kagent 1.0 alpha", even though GitHub shows the v1.0.0-alpha tags as regular releases rather than prereleases ([releases](https://github.com/kagent-dev/kagent/releases)). Everything in this section is what the 1.0 alpha documents, not a production promise.

```text
Harness (CRD) ----------+
  how an agent may run  |
                        +--> kagent controller --> ActorTemplate (immutable revision, SHA-256 digest)
AgentTemplate (CRD) ----+                               |
  what an agent can do                                  v
                                AgentInstance (gRPC API + PostgreSQL, not a CRD)
                                                        |
                                                        v
                                Actor (sandboxed process on Agent Substrate)
```

Redrawn from the diagram in kagent's [core concepts](https://kagent.dev/docs/kagent/1.x/about/core-concepts/) page.

### Harness: how an agent is allowed to run

A `Harness` (1.0, `kagent.dev/v1alpha3`) selects exactly one runtime (`kagent`, `codex`, `claude` or `byo`), a workload image pinned by digest, the Agent Substrate WorkerPool its Actors schedule onto, and where their snapshots go. Its `allowedAgentTemplates` selector is a one-way label match: an AgentTemplate has no field naming a Harness, and omitting the selector admits none. A Harness owns no compute by itself. Credentials don't go in its `env` either: a `credentialRef` there is rejected at compile time, and credentials belong on a ModelConfig or RemoteMCPServer ([Harness reference](https://kagent.dev/docs/kagent/1.x/agents/agent-harness/)). Minimal shape, from the docs:

```yaml
apiVersion: kagent.dev/v1alpha3
kind: Harness
metadata:
  name: my-harness
  namespace: kagent
spec:
  kagent: {}          # exactly one of kagent, codex, claude, byo
  workload:
    image: ghcr.io/kagent-dev/kagent/golang-adk@sha256:c953de42f7d58b70eb452955dc9312635bf3e6b626bf2788d2ebfae0c74af341
  substrate:
    workerPoolRef:
      name: kagent-default
    snapshotPolicy:
      location: s3://ate-snapshots/kagent/
  allowedAgentTemplates:
    selector:
      matchLabels:
        kagent.dev/harness: my-harness
```

### AgentTemplate: what the agent can do

An AgentTemplate holds the model configuration (the only required field), the system prompt, tool bindings and skills or plugins. A tool binding is either an MCP server reached through a RemoteMCPServer or another AgentTemplate used as a tool ([core concepts](https://kagent.dev/docs/kagent/1.x/about/core-concepts/)).

### AgentInstance: the conversation as a first-class object

An AgentInstance is a running conversation pairing a Harness and an AgentTemplate. It is not a CRD: kagent's gRPC API creates it and kagent's PostgreSQL database tracks it. It runs the revision it was created from, so editing either resource only affects instances created afterwards, and callers reach it over A2A through kagent's A2A gateway ([core concepts](https://kagent.dev/docs/kagent/1.x/about/core-concepts/)). Checkpoints and forks were in the first 1.0 alpha ([v1.0.0-alpha1 release notes](https://github.com/kagent-dev/kagent/releases/tag/v1.0.0-alpha1)). For the release in detail, see [kagent v1.0: Claude Code harness on Kubernetes](/kagent-v1-agentinstance-claude-code-harness/).

### Actor and Agent Substrate: the sandbox and durable state

Agent Substrate runs each Actor in a sandbox on a pre-started Worker from a WorkerPool. Suspend writes the Actor's state to a snapshot in object storage (GCS or S3) and frees the Worker, and resume restores it onto any free Worker in the pool. Each ActorTemplate gets a golden snapshot, so new Actors start from an already-booted image, and a checkpoint pins one snapshot so it isn't collected ([suspend and resume](https://kagent.dev/docs/kagent/1.x/substrate-runtime/suspend-and-resume/)).

On sandbox class, the docs and the code currently disagree. Substrate supports `gvisor` (the default) and `microvm`, and kagent's docs say kagent compiles every ActorTemplate to `gvisor` and "does not yet select" the micro-VM class ([Agent Substrate architecture](https://kagent.dev/docs/kagent/1.x/about/architecture/agent-substrate/), [sandboxing](https://kagent.dev/docs/kagent/1.x/substrate-runtime/sandboxing/)). The source at v1.0.0-alpha7 maps a WorkerPool `sandboxClass` of `microvm` to a micro-VM sandbox config ([PR #2918](https://github.com/kagent-dev/kagent/pull/2918), "support microvm sandboxes", listed in the [v1.0.0-alpha4 release notes](https://github.com/kagent-dev/kagent/releases/tag/v1.0.0-alpha4)). I haven't run either. For standing Substrate up on kind, see [kagent and Agent Substrate](/kagent-agent-substrate/), and to watch Workers and restores live, [Substrate Scope](/substrate-scope/).

## "kagent harness": two different resources

Search "kagent harness" and the docs return two resources with nearly the same name. The 1.x docs say the 1.0 `Harness` "is unrelated to 0.x's AgentHarness resource, which provisions OpenClaw or Hermes coding-agent sandboxes", and is "not a renamed or expanded version" of it ([core concepts](https://kagent.dev/docs/kagent/1.x/about/core-concepts/)).

| | `AgentHarness` (kagent 0.x) | `Harness` (kagent 1.0 alpha) |
| --- | --- | --- |
| API version | `kagent.dev/v1alpha2` | `kagent.dev/v1alpha3` |
| What it does | Provisions a long-running OpenClaw or Hermes sandbox on Agent Substrate | Defines how any agent is allowed to run: runtime, workload, WorkerPool, snapshots, admitted AgentTemplates |
| How kagent talks to it | ACP, through an in-sandbox `acp-shim`, shown in the kagent UI like other agents | A2A, through kagent's A2A gateway to each AgentInstance |
| Source | [0.x AgentHarness example](https://kagent.dev/docs/kagent/0.x/examples/agent-harness/) | [1.x Harness reference](https://kagent.dev/docs/kagent/1.x/agents/agent-harness/) |

## Claude Code and Codex as harness runtimes

For readers coming from a desktop harness, this is the bridge. A 1.0 `Harness` can select the `claude` or `codex` runtime, which the docs describe as purpose-built adapters that accept a narrower slice than `kagent` and `byo` ([Harness reference](https://kagent.dev/docs/kagent/1.x/agents/agent-harness/)):

- **Models:** `codex` takes OpenAI or an OpenAI-compatible Bedrock deployment; `claude` takes Anthropic or Bedrock. `kagent` and `byo` accept the widest provider list.
- **ModelConfig settings:** neither `codex` nor `claude` accepts `defaultHeaders`, `tls` or `apiKeyPassthrough`.
- **Tools:** Claude binds an MCP server whole, so the agent sees every tool the server offers (the compiler warns); Codex requires Streamable HTTP MCP servers and rejects SSE.
- **Mismatches:** an incompatible pair reports `Compatible=False` with reason `UnsupportedConfiguration`.

The [alpha1 post](/kagent-v1-agentinstance-claude-code-harness/) covers how the Claude and Codex runtimes landed.

## The boundary: models, tools and egress through agentgateway

The harness meets the network at the gateway, the layer I described in [what is an agentic mesh](/what-is-an-agentic-mesh/).

### Kubernetes mode: kagent agents behind agentgateway

kagent 1.x documents agentgateway as a model provider: an OpenAI-compatible ModelConfig whose base URL points at the agentgateway Gateway. The `AgentgatewayModel` feature is experimental and disabled by default (`agentgatewayModels.enabled=true` turns it on), and the provider key belongs to the gateway, not to kagent ([agentgateway model provider](https://kagent.dev/docs/kagent/1.x/setup/model-providers/byo-agentgateway/), [agentgateway models](https://agentgateway.dev/docs/kubernetes/latest/documentation/llm/models/about/)). Budgets in open-source Kubernetes mode are token-based rate limits that reject with a 429 ([budget and spend limits](https://agentgateway.dev/docs/kubernetes/latest/documentation/llm/cost-controls/budget-limits/)).

### Standalone mode: putting a desktop harness behind the same gateway first

Teams not on Kubernetes yet can start with agentgateway standalone. It documents the Anthropic Messages API at `/v1/messages` ([Messages](https://agentgateway.dev/docs/standalone/latest/documentation/llm/api-types/messages/)), MCP authorization with CEL ([MCP authorization](https://agentgateway.dev/docs/standalone/latest/documentation/mcp/mcp-authz/)), an HTTP CONNECT egress proxy ([egress proxy](https://agentgateway.dev/docs/standalone/latest/documentation/configuration/egress-proxy/)), and per-key budgets in USD or tokens ([per-key budgets](https://agentgateway.dev/docs/standalone/latest/documentation/llm/cost-controls/budget-limits/per-key/)). I've written up [keys held at the gateway](/secretless-ai-agents/) and [per-key USD caps](/agentgateway-per-key-llm-budgets/) on OSS v1.5.0 standalone. The docs don't include a guide for pointing a desktop Claude Code or Codex at the gateway, and I haven't tested it, so treat that as plausible from the Messages API doc, not documented. A gateway in front doesn't make a desktop harness cloud-native. It gives you the same model, tool and egress boundary you'll keep when the harness moves.

### Egress: what kagent 1.0 documents, and what agentgateway has shipped

kagent's 1.x docs describe strong egress control. An agent reaches the network only through Agent Substrate's egress gateway, which identifies the Actor by the SPIFFE ID in its client certificate. The policy is default-deny, first match wins, up to 256 rules. TLS is terminated so hostname rules apply to HTTPS. kagent compiles the allowlist from the AgentTemplate, and credentials can be injected from ModelConfig or RemoteMCPServer secrets. The gateway logs come from `deploy/atenet-egress -c agentgateway` ([networking and egress](https://kagent.dev/docs/kagent/1.x/substrate-runtime/networking-and-egress/)).

Grade all of that **alpha and unreleased**:

- Substrate's agentgateway overlay pins `cr.agentgateway.dev/agentgateway:v0.0.0-alpha.9e78d1da`, a development build, not a release ([kustomization](https://github.com/agent-substrate/substrate/blob/main/manifests/ate-install/components/agentgateway/kustomization.yaml)). Substrate's egress demo defaults to Envoy and can use agentgateway's built-in `substrateEgress` policy ([egress demo README](https://github.com/agent-substrate/substrate/blob/main/demos/egress/README.md)).
- In released agentgateway **v1.5.0**, `substrateEgress` only adds actor metadata and enforces nothing. The v1.5.0 source still reads `// TODO: implement egress policy in Substrate` ([egress.rs at v1.5.0](https://github.com/agentgateway/agentgateway/blob/v1.5.0/crates/agentgateway/src/http/substrate/egress.rs#L57)).
- Actor-identity authorization at CONNECT, failing closed, arrives in the **v1.6.0 prereleases** ([v1.6.0-alpha.1](https://github.com/agentgateway/agentgateway/releases/tag/v1.6.0-alpha.1), [PR #3237](https://github.com/agentgateway/agentgateway/pull/3237)). Egress credential injection is in [v1.6.0-alpha.2](https://github.com/agentgateway/agentgateway/releases/tag/v1.6.0-alpha.2).
- Destination rules (hostname and CIDR matching, denied when no rule matches) are not in any stable release. They first appear in the v1.6.0 prereleases ([PR #3318](https://github.com/agentgateway/agentgateway/pull/3318), [egress.rs at v1.6.0-alpha.2](https://github.com/agentgateway/agentgateway/blob/v1.6.0-alpha.2/crates/agentgateway/src/http/substrate/egress.rs#L318)), and unreleased main has since changed the format of the actor SPIFFE ID the egress code uses ([PR #3677](https://github.com/agentgateway/agentgateway/pull/3677)).

For why egress control matters, see [how agent egress controls get bypassed](/agent-egress-control-bypasses/). Note that its demo ran behind a Python CONNECT stand-in, not agentgateway.

## Identity and multi-tenancy: what the open-source alpha does and doesn't do

kagent's [identity doc](https://kagent.dev/docs/kagent/1.x/substrate-runtime/identity/) describes three planes. Kubernetes RBAC governs Harness and AgentTemplate (plus a gRPC path through the controller). kagent's own gRPC principal governs AgentInstance. Substrate components authenticate each other with mTLS. The same doc carries plain warnings for the open-source build:

- The authenticator admits every request and reads the caller from an unverified `X-User-Id` header; the authorizer permits every check.
- "Do not expose port 8083 outside the cluster."
- Agent Substrate "authenticates callers but does not authorize them."

For agent-to-tool tokens, see [kagent audience-bound agent tokens](/kagent-audience-bound-agent-tokens/) (on kagent v0.10.0; that harness is a stand-in for the kagent runtime). The full series lives at [agent identity](/agent-identity/).

## Other open-source takes on the same shape

The phrase "cloud-native harness" in this news cycle comes from Craig McLuckie of Stacklok, whose CNCF post [The case for a cloud native agent harness](https://www.cncf.io/blog/2026/09/28/the-case-for-a-cloud-native-agent-harness/) (2026-09-28) describes the desktop harness as one process that is "simultaneously the UI, the agent loop, the sandbox, the credential store, the tool host, and the session database", argues that "a monolith in a container is still a monolith", and introduces Stacklok's open-source [Mecatl](https://github.com/stacklok/mecatl). In Mecatl the engine owns the loop, with clients, execution environments, tools and supporting services behind interfaces. The post describes its durability as turn-level, "not a distributed transaction", and its identity design (a SPIFFE trust domain with the delegation chain in a JWT) as a draft. The repo is Apache-2.0 Go, with a `mecak8s` Kubernetes runtime that uses Redis and Kubernetes session leases, and releases at v0.0.44 on 2026-10-01. It was a [Show HN](https://news.ycombinator.com/item?id=49892249) on 2026-09-29.

## Methodology and disclosure

Checked 2026-10-01 (PT): kagent 1.x docs (core concepts, Harness reference, sandboxing, suspend and resume, identity, networking and egress, agentgateway model provider), the kagent 0.x AgentHarness example, kagent releases through v1.0.0-alpha7 and the v1.0.0-alpha7 source, the Agent Substrate repo, agentgateway docs labelled 1.5 (latest) and releases v1.5.0 through v1.6.0-alpha.2, the CNCF post, the Mecatl repo and releases, and the Show HN item via the Hacker News API. I read all of this. I did not run kagent, Agent Substrate or Claude Code for this page, so nothing here is graded as tested. Solo Enterprise material is labelled where it appears. Re-check when kagent 1.0 and agentgateway v1.6.0 are generally available, because the egress grading changes then.

*Disclosure: I work at Solo.io, which created kagent and agentgateway (both now open-source projects) and sells Solo Enterprise for kagent and Solo Enterprise for agentgateway. Everything above is open source unless labelled Solo Enterprise, kagent 1.0 is alpha software, and every claim links to the project's own docs or release notes as of 2026-10-01.*