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):
- The loop: reasoning, tool dispatch, permissions.
- Clients: terminal, UI, API or another agent.
- The execution environment: the sandbox where the agent’s commands run.
- Tools: a catalog the agent may call, often over MCP.
- 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 ).
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 ).
- 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 ).
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 ). Everything in this section is what the 1.0 alpha documents, not a production promise.
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 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
). Minimal shape, from the docs:
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 ).
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 ). Checkpoints and forks were in the first 1.0 alpha (v1.0.0-alpha1 release notes ). For the release in detail, see kagent v1.0: Claude Code harness on Kubernetes .
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 ).
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
, sandboxing
). The source at v1.0.0-alpha7 maps a WorkerPool sandboxClass of microvm to a micro-VM sandbox config (PR #2918
, “support microvm sandboxes”, listed in the v1.0.0-alpha4 release notes
). I haven’t run either. For standing Substrate up on kind, see kagent and Agent Substrate
, and to watch Workers and restores live, 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
).
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 | 1.x Harness reference |
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
):
- Models:
codextakes OpenAI or an OpenAI-compatible Bedrock deployment;claudetakes Anthropic or Bedrock.kagentandbyoaccept the widest provider list. - ModelConfig settings: neither
codexnorclaudeacceptsdefaultHeaders,tlsorapiKeyPassthrough. - 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=Falsewith reasonUnsupportedConfiguration.
The alpha1 post 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 .
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
, agentgateway models
). Budgets in open-source Kubernetes mode are token-based rate limits that reject with a 429 (budget and spend 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
), MCP authorization with CEL (MCP authorization
), an HTTP CONNECT egress proxy (egress proxy
), and per-key budgets in USD or tokens (per-key budgets
). I’ve written up keys held at the gateway
and per-key USD caps
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
).
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 ). Substrate’s egress demo defaults to Envoy and can use agentgateway’s built-insubstrateEgresspolicy (egress demo README ). - In released agentgateway v1.5.0,
substrateEgressonly 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 ). - Actor-identity authorization at CONNECT, failing closed, arrives in the v1.6.0 prereleases (v1.6.0-alpha.1 , PR #3237 ). Egress credential injection is in 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 , egress.rs at v1.6.0-alpha.2 ), and unreleased main has since changed the format of the actor SPIFFE ID the egress code uses (PR #3677 ).
For why egress control matters, see how agent egress controls get bypassed . 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 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-Idheader; 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 (on kagent v0.10.0; that harness is a stand-in for the kagent runtime). The full series lives at 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
(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
. 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
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.