Coding Harness Design for Sandboxed AI Agents

How production AI agent runtimes enforce isolation and reliability through harness design.

· 8 min read
Cover illustration for “Coding Harness Design for Sandboxed AI Agents”
Sandboxed Code Execution · October 22, 2026 · 8 min read · 1,767 words

Persistent AI agent infrastructure keeps an agent’s environment and session state available across restarts, while stateless serverless functions require external storage and state reconstruction. Coding harness design determines how that continuity supports reliable execution, enforced boundaries, and fleet-scale operation. For long-running agents, persistent infrastructure versus serverless functions is therefore an architectural choice about memory, control, isolation, and compute delivery.

What a coding harness actually is and why it became a discipline

Barbaste et al. (2026) define a harness as the runtime that couples an LLM to the world and identify harness engineering as a discipline named in early 2026. The model supplies reasoning and generated actions, but the runtime controls how those actions run. Ning et al. (2026) describe this shift as “code as agent harness”, where code supports reasoning, acting, environment modeling, and execution-based verification.

That runtime is distinct from both a framework and a hosting platform. A harness runs one agent, a framework composes several, and a platform runs many harnesses over time. Maritime is part of the hosting layer and supplies persistent infrastructure for durable execution, cost attribution, and governance. A chat interface, prompt template, or serverless function wrapper does not by itself supply the runtime responsibilities that make an agent dependable.

The seven canonical subsystems and how they were identified

Barbaste et al. (2026) derive seven canonical subsystems from a source-code study of eleven production harnesses. These subsystems are loop structure, tool definition, sandbox enforcement, context management, session memory, safety controls, and orchestration. The corpus includes Claude Code, Codex CLI, Gemini CLI, Mistral Vibe, OpenHands, Aider, Mini-SWE-Agent, Hermes, Pi, OpenCode, and OpenClaw. The study maps minimal and maximal implementations across systems written in Python, TypeScript, and Rust, grounding the decomposition in production code.

Each subsystem has its own failure modes, so one that works well cannot automatically make up for another that works poorly. Ning et al. (2026) offer another view with three layers: harness interface, harness mechanisms, and scaling. Their structure connects reasoning and action to planning, memory, feedback-driven control, and multi-agent coordination. Together, these perspectives explain why treating the runtime as undifferentiated scaffolding hides consequential design choices.

Loop structure: the control flow decisions that determine agent reliability

Barbaste et al. (2026) find that all eleven production harnesses use hand-rolled async loops. Termination conditions distinguish completion from a stall, while error handling routes a failed tool call to a retry, escalation, or halt. Weak termination lets behavior run out of control, and continuing silently after a failure lets the loop go on without a valid result. Recursion limits and bounded, read-only subagents place further limits on how execution can expand.

The loop also needs control points that make its behavior inspectable. Step-level hooks let operators check, block, or redirect an iteration without changing the model. To keep that control across session boundaries, execution state must survive, which platforms such as Maritime support with persistent per-agent virtual machines and snapshot-restore scheduling. Ning et al. (2026) distinguish planning before execution from replanning in response to feedback during execution. Both are part of the loop’s control policy, which still needs clear rules for stopping or recovering.

Tool definition: how the harness shapes what the model is allowed to do

Within that loop, tool definitions set which actions the agent can take and how far those actions can reach. Schemas, validation rules, and path-based access controls constrain what an invocation can do. Open-ended shell access shifts much of the responsibility for constraining actions from the tool layer to sandbox enforcement. Barbaste et al. (2026) find that SKILL.md skills lead MCP in adoption across the corpus, with registries, trust tiers, and agent-authored skills appearing in production. The important distinction is not simply which protocol exposes an operation, but how clearly and safely the operation is defined.

A well-designed MCP server can bundle operations and load schemas hierarchically. Conversely, a CLI paired with a well-written skill file can outperform a bloated MCP implementation that floods the initial context. Ning et al. (2026) identify tool search and selection as a harness mechanism, making discoverability part of this design. Validation only at definition time is insufficient when the agent can create tools whose later invocation circumvents access controls.

Sandbox enforcement: the isolation boundary that makes untrusted code execution safe

Tool controls govern permitted actions, while the sandbox governs where those actions execute. Andronchik and Lokhmakov (2026) compare five AI-sandbox products across six engine-level security axes and find clear architectural differences between engine classes, but divergence among products within each class. OCI containers share the host kernel. Userspace kernels such as gVisor interpose a user-space kernel, while microVMs such as Firecracker provide a dedicated kernel and a deliberately small device-emulation surface.

Andronchik and Lokhmakov (2026) identify product pin policy as the dominant operator-facing variable, with downstream patch lag ranging from zero days to over 471 days, or remaining opaque or indefinite. Network policy, filesystem scope, package governance, secrets handling, and lifecycle controls still determine real risk. Maritime uses a Firecracker micro-VM per agent on bare metal, combining a separate kernel with persistent disk and package installation privileges. That architecture gives each agent an isolation boundary, but does not show that it is better on every security axis. The study’s unoccupied combination of microVM isolation and continuous public fuzzing also remains a measurement gap even with persistence.

Context management: keeping the model useful without letting the window become a liability

The information boundary matters as much as the execution boundary for long-horizon reliability. Context management determines what the model sees now and what the harness clips, compresses, or evicts. Barbaste et al. (2026) identify clipping and compression, live repository context gathered before the first prompt, and a cached-prefix and variable-suffix split as components of well-formed design. The stable prefix holds things such as system instructions, skill definitions, and repository structure. Changing only the suffix between iterations reduces token spend and latency without making cost reduction the purpose of context management.

Retrieval sets which evidence goes into that managed window. Barbaste et al. (2026) find no use of vector embeddings for code retrieval in their production corpus. Instead, the harnesses use ripgrep, tree-sitter, glob, and auto-discovered Markdown context files, favoring predictable and auditable selection. Isolated subagent windows provide another way to keep exploration from bloating the main session. These mechanisms serve coherence first, because a larger window is not automatically a more useful one.

Session memory and persistent AI agent infrastructure vs serverless functions

Context management governs the current window, while session memory governs what survives beyond it. Barbaste et al. (2026) name structured session memory kept apart from the full transcript as a canonical component. Files such as CLAUDE.md, MEMORY.md, rules directories, and handoff documents provide durable, inspectable, agent-writable memory when backed by persistent disk. A transcript alone is not the curated memory system the harness requires.

This requirement exposes the limitation of stateless serverless execution for stateful agents. Without persistent local storage across sleep, redeployment, and restart, the application must preserve state externally and reconstruct it, introducing latency and consistency work. Serverless functions can thus be part of an agent system, but the function wrapper alone cannot keep sessions continuous. With Maritime’s per-agent micro-VMs and persistent disks, files, credentials, installed packages, and accumulated state remain available across sleep-wake cycles without application-level serialization overhead. Its snapshot-restore scheduler lets agents idle at storage cost and resume in under a second with their memory intact.

Safety controls: how behavioral policy migrated from prompt prose to harness configuration

Safety controls require enforcement mechanisms outside the model’s discretion, including hooks, exit codes, path-based access controls, and policy configuration. Barbaste et al. (2026) observe behavioral policy migrating from prompt prose to configuration across the first half of 2026. Gore (2026) investigates distributing off-the-shelf security controls through a custom harness to a distributed user base. Both frame safety as runtime engineering rather than a request for the model to behave carefully.

Hooks make that distinction concrete by firing at defined lifecycle events. In the hook convention described in the notes, exit code 2 blocks an action and exit code 1 warns, so enforcement does not depend on the model accepting an instruction. A hook that blocks credentials in bash commands works in both attended and autonomous runs. This remains one layer of defense rather than a substitute for network, filesystem, package, and lifecycle controls. Barbaste et al. (2026) note that Pwn2Own Berlin 2026 introduced a dedicated “coding agents” category, making harness boundaries an explicitly adversarial testing target.

Orchestration: when a single harness is not the right unit of deployment

Orchestration governs how agents work together and how entire harnesses become deployable components. Barbaste et al. (2026) analyze Omnigent from Databricks as the first meta-harness, placing interchangeable harnesses behind a common API with cross-harness policies, a uniform OS sandbox, and shareable multi-device sessions. ACP, the Agent Client Protocol, ships in six of the eleven systems in their corpus. OpenHands uses it to host Claude Code, Codex, or Gemini CLI as interchangeable backends. This moves orchestration beyond message passing into runtime hosting.

Shared artifacts then give agents a way to coordinate, review, and verify work, as Ning et al. (2026) describe. Bounded, read-only subagents with recursion limits contain the denial-of-service and cost risks of unrestricted spawning. With a per-user agent fleet, the focus shifts again, from shared-agent consistency to provisioning, scheduling, and cost attribution for instances that run independently. For such fleets, Maritime’s snapshot-restore scheduler addresses idle cost by storing sleeping agents with their compute inactive. Because most agents are idle most of the time, that distinction connects orchestration directly to whether persistent per-user agents are economically deployable at scale.

How the seven subsystems interact and where most harnesses break down

The framework’s practical value lies at the interfaces between its subsystems. A loop can define a recursion limit without enforcing it against spawned subagents. A tool layer can validate predefined operations while leaving agent-authored tools a bypass. A sandbox can contain code execution without preventing network exfiltration.

Convergence makes interface design more consequential. Barbaste et al. (2026) document Codex adopting Claude Code’s hook vocabulary verbatim and importing its sessions and settings, while OpenHands reads Claude Code’s plugin format. Shared conventions lower switching and orchestration costs, but can also propagate a leading implementation’s mistakes. Ning et al. (2026) identify consistent shared state across agents as an open challenge. Barbaste et al. (2026) provide a 90-line minimum-viable scaffold implementing ten of their 18 recommendations to coordinate execution, authority, information, and persistence across boundaries, the discipline’s defining work, which puts a team that understands all seven subsystems in a materially different position from one that treats the harness as boilerplate.

Sources

  1. Harness Engineering: Anatomy, Architecture, and Evolution of Coding Agents A Source-Code Study of Eleven Systems
  2. AI Code Sandboxes: A Comparative Security Study. Part 1 of 2 -- Engine-Level Properties (Attack Surface, Leakage, Stackability, CVE History, Patch Cadence, Fuzzing)
  3. Distributing Security Controls Through Harness Engineering
  4. Code as Agent Harness

More in Sandboxed Code Execution