Long-Running Agents

Managed Agent: Brain-Hand Separation

Core insight: split the Agent's thinking and execution into independent components, so the system can recover gracefully when any part fails.

Analogy: OS Virtualization

Operating System Virtualizes Hardware

When you call read(), you don't care whether the underlying storage is SSD, HDD, or a network drive — the OS abstracts away hardware details.
Managed Agent does the same thing: it virtualizes the Agent's components, so the brain doesn't care which container the hand is, and the hand doesn't care which model the brain uses.

Three Core Components

Session

Event Log

An append-only event stream with persistent storage. Records everything that has happened: user input, tool calls, and model output.

Harness

Brain

The loop that calls Claude and routes tool calls. Responsible for thinking: deciding what to do next and how to organize context.

Sandbox

Hand

The container environment for executing code and editing files. Responsible for execution: running commands, writing files, and interacting with external systems.

Why Separate: Pets vs. Cattle

Architecture Evolution

Old Approach (Pets)

Session + Harness + Sandbox all in the same container.

Container dies = session lost = can't debug = task completely fails.

Like a pet: if it dies, it's over — no replacement possible.

New Approach (Cattle)

Each component deployed independently, no mutual dependencies.

Container dies = tool call fails = Claude decides to retry = spin up a new container and continue.

Like cattle on a farm: one dies, spin up another — the system keeps running.

Try It: Fault Recovery Simulator

Harness

Brain

execute()

emitEvent()

Sandbox

Hand

Event Log

Session

Click a button below to observe system recovery behavior in different failure scenarios.

Benefits of Separating Brain from Container

Key Improvements

Containers become tool calls: execute(name, input) -> string — to the Harness, it's just a regular function
Container dies = tool call returns an error = Claude decides whether to retry = automatically spins up a new container to continue
Harness can start processing before the container is ready — no need to wait for container startup

-60%

TTFT p50 reduction

-90%+

TTFT p95 reduction

TTFT = Time to First Token

Security as an Architectural Solution

Architecture-Level Security Solutions

Old approach: Agent-generated code and API keys live in the same container — Prompt Injection can steal keys directly
Git Token: injected as container environment variables when cloning the repo; usable inside the sandbox, but the Agent never sees the token value
MCP OAuth Token: stored in an external vault, MCP calls are forwarded via a proxy — the sandbox cannot access the token directly

Multiple Brains, Multiple Hands

Components Can Be Freely Combined

Brain A

Brain B

Brain C

Multiple Brains: each is a stateless Harness, started on demand

Sandbox 1

Sandbox 2

Sandbox 3

Sandbox 4

Multiple Hands: each is an independent tool, passable to different Brains

This means you can have one Brain control multiple Sandboxes simultaneously (parallel execution), or pass the same Sandbox between different Brains (relay execution). Components are fully decoupled.

Good architecture lets components fail and be replaced independently. Brain-hand separation is not just a performance optimization — it fundamentally changes the system's reliability model: from "one pet dies and everything collapses" to "any part can be rebuilt."