feat(agents): experimental ContainerHarness: Claude Code or Codex in a Container, driven from a Durable Object

[mattzcarey]

Adds experimental agents/harness/container: ContainerHarness runs an agent CLI (Claude Code or Codex) in a Cloudflare Container and drives it from a Durable Object. Its API matches PiHarness.

import { ContainerHarness, claudeCode, codex } from "agents/harness/container";

// Adds credentials outside the container; export it from the main module.
export { ContainerEgress } from "agents/harness/container";

export class CodingAgent extends DurableObject<Env> {
  readonly harness = new ContainerHarness({
    container: this.ctx.container,
    egress: this.ctx.exports.ContainerEgress,
    agent: claudeCode({                                 // or codex({ ... })
      baseUrl: `${this.env.AI_GATEWAY_URL}/anthropic`,
      apiKey: this.env.AI_GATEWAY_TOKEN
    })
  });
  readonly lifecycle = Lifecycle.install(this).use(this.harness);
}

const { text } = await this.harness.prompt("fix the failing test");
await this.harness.sessions.fork("root");

"containers": [{ "class_name": "CodingAgent", "scheduling_policy": "durable_object" }]

You don't build an image or write a Dockerfile, and the container never holds a credential.

How it works

flowchart LR
  subgraph DO[Durable Object]
    H[ContainerHarness] --- S[(HarnessStore<br/>sessions · operations<br/>transcript · CLI session files)]
  end
  subgraph W[Worker]
    E[ContainerEgress]
  end
  subgraph C[Container: cloudflare/debian-trixie]
    D[daemon] -->|one process per turn, as uid 10001| CLI[claude -p / codex exec]
  end
  H <-->|WebSocket per session via getTcpPort| D
  CLI -->|http://anthropic.harness.internal<br/>placeholder key| E
  E -->|real key| GW[AI Gateway / provider]

Loading

• No image. On first start the harness:

  • starts cloudflare/debian-trixie;
  • runs the preset's setup steps with exec() (an unprivileged user, npm install -g of the CLI, your own steps);
  • writes in the daemon (23 KiB, bundled into agents at build time);
  • snapshots the filesystem.

  Later starts restore a snapshot. Changing the setup sets up again.

• Customise with setup only. A step with user: "agent" runs in the agent's home, and every session home starts as a copy of it. Installing plugins and mods, settings, skills or a fork works as it does on a laptop:

  setup: [{ name: "my mods", user: "agent", command: ["sh", "-c", "claude plugin marketplace add you/mods && claude plugin install mine@mods"] }]

• Credentials stay outside the container. The CLI calls a placeholder host over plain HTTP with a placeholder key. interceptOutboundHttp hands that request to ContainerEgress, which swaps in apiKey / headers and forwards to baseUrl (https only).

• The daemon (agents/harness/container/runtime, no dependencies):

  • numbers frames and replays from the object's cursor;
  • queues turns;
  • runs the CLI and turns its JSON lines into messages and events;
  • mirrors the CLI's session folder (~/.claude/projects, ~/.codex/sessions) to the object.

  For any other CLI, cliAdapter({ command, parser, stateDirs }) is the extension point.

• Durable, like PiHarness.

  • Each session has one Lifecycle wake job (singleflight, recoveryLoop, a heartbeat) that starts or reattaches, reconciles and waits.
  • Operations, the transcript, cursors and the start-failure count all live in SQLite or in the job.

• Session store (agents/harness/store): sessions, operations with idempotency keys, and logs of opaque JSON. It doesn't depend on any one harness.

Recovery

Lost	What happens
Container idle	After idleTimeoutMs (5 min) the harness snapshots the container, workspace included, and stops it. The next prompt starts from that snapshot; the CLI resumes its own session (--resume, codex exec resume).
Container dies mid-run	The run settles container_lost (or reruns with onContainerLost: "retry"). The next container starts from the last snapshot plus the CLI's session files, and the session continues.
Object evicted mid-run	The container keeps going. The wake job reattaches and replays missed frames from its cursor.
Snapshot unusable	One failed start retries the same snapshot. After two in a row it is skipped for the next source (workspace → setup snapshot → fresh setup). If a fallback starts, the skipped snapshot is probed once more: it is kept if it starts, dropped if it fails. Snapshots too old to restore (30 days since last use) are skipped.

Example

examples/next/harnesses/container runs Claude Code and Codex side by side: two Durable Objects that differ only in their preset.

All new entries are marked @experimental.

[changeset-bot]

🦋 Changeset detected

Latest commit: b28edcd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
agents	Patch
@cloudflare/agent-think	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[devin-ai-integration]

Note

Newer findings are available below. Devin Review posted a newer report on this PR, in addition to the findings presented here.

Devin Review found 7 potential issues.

[agent-think]

🟢 agents import sizes: 4 entry points changed, no growth

	Entry point	Exports	Largest gzip change	Size now
🆕	agents/harness/container	9 new	—	19.2 KiB
🆕	agents/harness/container/daemon	14 new	—	2.6 KiB
🆕	agents/harness/container/runtime	5 new	—	4.5 KiB
🆕	agents/harness/store	2 new	—	2.4 KiB

Changed exports (30)

	Import	Gzip change	Size now
🆕	agents/harness/container#ContainerHarness	—	19.2 KiB
🆕	agents/harness/container/runtime#serveFromEnv	—	4.5 KiB
🆕	agents/harness/container/runtime#serve	—	4.3 KiB
🆕	agents/harness/container/runtime#cliAdapter	—	2.7 KiB
🆕	agents/harness/container/daemon#ContainerDaemon	—	2.6 KiB
🆕	agents/harness/store#openHarnessStore	—	2.4 KiB
🆕	agents/harness/store#HarnessStore	—	2.3 KiB
🆕	agents/harness/container/runtime#claudeCodeCli	—	2.2 KiB
🆕	agents/harness/container/runtime#codexCli	—	1.6 KiB
🆕	agents/harness/container#claudeCode	—	1.1 KiB
🆕	agents/harness/container#ContainerSessions	—	1 KiB
🆕	agents/harness/container#ContainerSession	—	1 KiB
🆕	agents/harness/container#codex	—	1 KiB
🆕	agents/harness/container#ContainerEgress	—	977 B
🆕	agents/harness/container#containerAgent	—	755 B
🆕	agents/harness/container/daemon#parseDaemonMessage	—	747 B
🆕	agents/harness/container#echoAgent	—	708 B
🆕	agents/harness/container#ROOT_SESSION	—	656 B
🆕	agents/harness/container/daemon#echoAdapter	—	644 B
🆕	agents/harness/container/daemon#parseHostMessage	—	639 B
🆕	agents/harness/container/daemon#chunkEntries	—	176 B
🆕	agents/harness/container/daemon#inputText	—	132 B
🆕	agents/harness/container/daemon#CONTAINER_ENV	—	124 B
🆕	agents/harness/container/daemon#CONTAINER_TOKEN_HEADER	—	85 B
🆕	agents/harness/container/daemon#CONTAINER_SESSION_PATH	—	77 B
🆕	agents/harness/container/daemon#CONTAINER_HEALTH_PATH	—	75 B
🆕	agents/harness/container/daemon#CLOSE_REPLACED	—	69 B
🆕	agents/harness/container/daemon#CONTAINER_PROTOCOL_VERSION	—	66 B
🆕	agents/harness/container/daemon#CLOSE_UNAUTHORIZED	—	65 B
🆕	agents/harness/container/daemon#MAX_CHUNK_CHARS	—	58 B

How this works

Each runtime export is bundled on its own, minified, and gzipped. Changes smaller than 100 B, or smaller than 1% and 1 KiB, are ignored. Growth over 10% or 5 KiB is marked 🔴. This report is informational and does not fail CI. The workflow artifact contains every measurement.

_{Compared bda70b52 → b28edcd7 · workflow run · reported by agent-think[bot]}

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@2514

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@2514

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@2514

hono-agents

npm i https://pkg.pr.new/hono-agents@2514

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@2514

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@2514

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@2514

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@2514

commit: b28edcd

[devin-ai-integration]

Note

Newer findings are available below. Devin Review posted a newer report on this PR, in addition to the findings presented here.

Devin Review found 1 new potential issue.

[devin-ai-integration]

Devin Review found 2 new potential issues.