kagent v1.0 Can Run Claude Code as a Managed Kubernetes Agent

Kagent released v1.0.0-alpha1, replacing its Deployment-backed agent model with AgentInstance, an imperative gRPC lifecycle object with a fixed state machine, PostgreSQL persistence, and synchronous suspend/resume. The release adds an authenticated A2A gRPC gateway and a chat UI checkpoint/fork feature that applies a git-like model to agent conversation state. The project notes that durable public task persistence, ID mapping, ordering, and idempotency remain follow-up work.

Originally published at webofmike.com https://webofmike.com/kagent-v1-agentinstance-claude-code-harness/?utm source=devto&utm medium=syndication&utm campaign=kagent-v1-agentinstance-claude-code-harness on 2026-09-18. The demo repo and every command in it were run before publishing. kagent shipped v1.0.0-alpha1 https://github.com/kagent-dev/kagent/releases/tag/v1.0.0-alpha1 this morning, its first 1.0 line after nine months on 0.x. The tag says alpha; GitHub's own release flag says otherwise; it's marked prerelease: false , listed as Latest . Release notes lie about formatting more than they should, and this is a version-number one: don't assume the tag string tells you how GitHub, or a Helm repo index, actually classifies the artifact. Check both, every time. The changelog runs to roughly 130 pull requests. Most of it is refactoring: refactor: remove deployment-backed agent API , refactor: remove legacy controller runtime , chore: remove legacy ACP and controller runtime . That pattern, repeated a dozen times, is the actual story. kagent didn't add a feature to its old agent model. It replaced the model. Through 0.x, a kagent agent was, underneath, a Kubernetes Deployment. v1.0 introduces AgentInstance : an imperative gRPC lifecycle object with a fixed state machine, not a workload spec a controller reconciles toward. PR 2436 https://github.com/kagent-dev/kagent/pull/2436 adds the service and its PostgreSQL persistence, with idempotent create, ownership checks, and Actor identity fencing. PR 2445 https://github.com/kagent-dev/kagent/pull/2445 adds suspend and resume, synchronous, backed by Substrate, and explicit about what happens when two callers collide: Kind smoke: Create → READY → Suspend → SUSPENDED → Resume → READY → conflicting Resume → ABORTED → Delete → DELETED → Get → NOT FOUND That's not a happy-path test. It's a test that a second, conflicting resume gets rejected outright rather than racing the first one. A Deployment reconciler doesn't offer that; it just converges, eventually, and two competing writers get whatever order the informer delivers. AgentInstance answers with a status code instead. PR 2446 https://github.com/kagent-dev/kagent/pull/2446 puts an authenticated A2A gRPC gateway in front of ready instances, routing through Atenet to private root Substrate actors. The PR is explicit about what's still missing: "Durable public Task persistence, public/private ID mapping, ordering, and idempotency remain follow-up work." Worth knowing before you point production A2A traffic at it on day one of an alpha. The most visible v1.0 feature lives in the chat UI, not the API. PR 2775 https://github.com/kagent-dev/kagent/pull/2775 adds a Checkpoint button next to Send. It saves the conversation's current turn boundary. "Everything above it travels into a fork and nothing below it does" is how the PR describes the contract. Duplicate chat in the rail's row menu is the same mechanism: checkpoint plus fork, in one click. PR 2847 https://github.com/kagent-dev/kagent/pull/2847 renames the concept from "checkpoint" to "snapshot" in the chat, gives each one a name <agentInstanceId -<headTaskId by default , and puts Fork, Rename, and Delete on its mark in the transcript. PR 2804 https://github.com/kagent-dev/kagent/pull/2804 adds deletion: releasing a checkpoint's snapshot doesn't break chats already forked from it, because a fork copies the checkpoint's identity rather than referencing it live. This is a git-like model applied to an agent conversation, and it's a genuinely different way to think about agent state. An agent conversation that goes sideways isn't something you restart from scratch or patch in place; you fork from the last good checkpoint and try again, keeping the bad branch around to compare. The performance story sits underneath the UI, in PR 2715 https://github.com/kagent-dev/kagent/pull/2715 : resuming a suspended actor from a Substrate "golden snapshot" a FULL gVisor snapshot plus the latest DATA snapshot instead of cold-booting the actor from its OCI image every time. The PR includes its own benchmark, 25 turns per harness, cold boot versus golden resume: | Metric | Codex: cold / golden | Claude: cold / golden | |---|---|---| | Median first output | 725 / 695 ms | 1,282 / 1,068 ms | | Median turn completion | 971 / 957 ms | 2,007 / 1,731 ms | | Mean Substrate restore | 235 / 234 ms | 294 / 196 ms | | Mean checkpoint | 232 / 232 ms | 243 / 212 ms | Codex barely moves. Claude's numbers move more, which tracks: a heavier CLI process pays more for a cold OCI boot and gets more back from skipping it. I haven't reproduced this benchmark myself; it's quoted from the PR description, not a run against my own cluster, and I'm saying so rather than presenting it as something I measured. The PR is also specific about when an old golden snapshot stops working: a Substrate upgrade doesn't automatically invalidate one, because the snapshot manifest pins its own sandbox class, runtime asset hash, and pause image. It breaks only if an upgrade changes the snapshot format itself, or the restore contract, or drops host support for the pinned runtime. That's a real answer to "what happens to my snapshots when I upgrade Substrate," not a "should be fine" hand-wave. The change I'd call the headline feature is PR 2602 https://github.com/kagent-dev/kagent/pull/2602 : kagent can now run the actual Claude Code CLI as an agent harness, pinned version, over A2A, with streaming, cancellation, session resume, and durable state through Substrate. PR 2645 https://github.com/kagent-dev/kagent/pull/2645 adds Codex the same way, reusing most of the Claude harness's plumbing, driven through the Codex App Server's JSON-RPC-over-stdio protocol. That means kagent's own harness options are no longer limited to its ADK-based agent runtime. You can point an AgentTemplate at a coding CLI you already use daily and get a managed, checkpointable, forkable, suspend-and-resume-capable Kubernetes object wrapped around it. One detail in the Codex PR is worth calling out on its own, because it looks alarming out of context and isn't: Runs Codex with approvals set to never and native sandboxing set to danger-full-access; the Substrate Actor is intentionally the security boundary. Read on its own, "danger-full-access" sounds like turning off the safety rails. It's the opposite: kagent is deliberately not layering Codex's own approval prompts and sandbox on top of Substrate's, because that would be two enforcement points guessing about each other's state. The Substrate actor, the gVisor sandbox the harness runs inside, is the one boundary that's actually authoritative, so the harness-level controls are turned off rather than left to fight it. Whether you're comfortable with that tradeoff depends entirely on trusting the actor sandbox, which is a fair thing to want to verify yourself before running either harness against anything sensitive. Alpha means alpha. The A2A gateway PR names its own gaps in durable task persistence and ID mapping. This release also carries fix: migrate checkpoints to Substrate v0.0.26 and fix: preserve conversation identity and history across forks as fixes , both landing after the checkpoint/fork UI they support, which says the fork feature had real correctness bugs during its own development window. That's normal for a feature this new, not a red flag, but it means an alpha this size is worth running somewhere you can afford to lose state before you run it somewhere you can't. The architecture change is bigger than any one feature in it. kagent spent most of 2026 running agents as pods that Agent Substrate multiplexed onto a shared worker pool I wrote about that runtime here https://webofmike.com/kagent-agent-substrate/ . v1.0 keeps that runtime and puts a proper lifecycle API on top of it: agents you can suspend, resume, checkpoint, and fork as first-class operations, not side effects of a Deployment you're poking with kubectl. Adding Claude Code and Codex as harnesses on that same lifecycle is what makes it concrete: whatever you build against AgentInstance now works for a coding agent you already trust, not just kagent's own runtime. Full changelog: kagent-dev/kagent v1.0.0-alpha1 https://github.com/kagent-dev/kagent/releases/tag/v1.0.0-alpha1 . Compare against the last stable line: v0.10.0...v1.0.0-alpha1 https://github.com/kagent-dev/kagent/compare/v0.10.0-rc1...v1.0.0-alpha1 . Can I run Claude Code as an agent inside kagent on Kubernetes? Yes, as of kagent v1.0.0-alpha1. PR 2602 adds a native Claude harness that runs the pinned Claude Code CLI over A2A with streaming, cancellation, session resume, and durable state on Substrate. PR 2645 adds the same support for Codex, reusing most of the same plumbing, with feature parity to kagent's own ADK harness. What is an AgentInstance in kagent v1.0? AgentInstance is kagent v1.0's replacement for its old Deployment-backed agent API. It is an imperative gRPC lifecycle object, create/suspend/resume/delete, backed by Substrate actors and persisted in PostgreSQL. Competing transitions are conflict-fenced: a second resume against an already-resumed instance returns ABORTED instead of corrupting state. How much faster is resuming a kagent agent from a golden snapshot than cold-booting it? In kagent's own PR 2715 benchmark 25 turns per harness , the Claude harness's median turn completion dropped from 2,007ms cold to 1,731ms from a golden snapshot, and mean Substrate restore dropped from 294ms to 196ms. Codex, a lighter process, moved less: 971ms to 957ms median turn completion. Both numbers come from the PR description, not a run I reproduced myself. Can I fork a kagent conversation without losing earlier checkpoints? Yes. kagent v1.0's UI lets you checkpoint a chat turn, then fork from that checkpoint into a new, independent conversation that inherits the checkpoint's name PR 2775, 2847 . Deleting a checkpoint later releases the snapshot it pins, but chats already forked from it keep working PR 2804 . Canonical version, with machine-readable markdown at https://webofmike.com/kagent-v1-agentinstance-claude-code-harness/index.md : https://webofmike.com/kagent-v1-agentinstance-claude-code-harness/ https://webofmike.com/kagent-v1-agentinstance-claude-code-harness/