Harness Architecture & Sandboxing

A production harness must bridge two contradictory requirements: giving an AI agent enough power to execute complex code changes while strictly bounding its blast radius to prevent catastrophic operations, host corruption, or data exfiltration.

Think of a foundation model as a high-powered racecar engine, and the Harness as the entire vehicle around it: the steering wheel, brakes, roll cage, and fuel injection. If you run a bare engine on a workbench, it will quickly overheat or tear itself apart.

The harness wraps the model in a closed cybernetic loop: it decides what instructions the model sees, feeds its tool requests into an isolated sandbox, catches bugs before they touch real systems, and forces the model to verify its own work before claiming victory.

1. The Outer Execution Loop

An autonomous agent does not execute as an open prompt. It runs inside a tightly supervised state machine managed by the harness runtime:

Architecture

Formula: Agent = Model + Harness

HARNESS COMPONENT: VERIFIER

4. 3-Layer Verifier

Eliminates premature victory. Executes Layer 1 (ruff & mypy --strict), Layer 2 (pytest test suites), and Layer 3 (runtime/browser smoke probes). Only genuine passing tests can advance state.

✓ Guaranteed Invariant

Critical Invariant

Truth Invariant: Model assertions of success are ignored; verified evidence is the only proof of completion.

HARNESS IMPLEMENTATION PATTERN:

# Python 3-layer deterministic verification pipeline
audit = await verifier.audit(
    l1_static=await run_ruff_and_mypy(),
    l2_tests=await run_pytest_suite(),
    l3_runtime=await run_smoke_probes(),
)
if not audit.passed:
    return harness.feed_diagnostic(audit.format_feedback())

The cybernetic agent formula: Agent = Model + Harness. The Model provides reasoning; the Harness provides instructions, sandboxing, automated verification, and state persistence.

The Turn Contract

Each turn in the harness satisfies a formal contract:

Pre-turn Invariant: The workspace is clean or has a known diff recorded in the git index.
Action Invariant: The model may only emit structured tool calls conforming to a declared JSON Schema. Raw text with implied terminal commands is rejected before execution.
Post-turn Invariant: Execution output (stdout, stderr, exit_code) is captured, bounded in size, and sanitized before returning to the model context.

Predict First

If an autonomous agent hallucinates a background process or fork loop (e.g. while True: os.fork()), what happens if your harness executes it via standard subprocess.run(shell=True) without cgroups or process groups?

2. Sandboxing Technologies: Containing Blast Radius

When an autonomous agent writes and executes code, running commands directly on the host machine is a catastrophic vulnerability. A model hallucinating rm -rf / or executing a rogue Python script can wipe home directories or leak credentials.

Interactive simulation of the sandboxing layers and security policies:

Interactive Sandbox Telemetry

Subprocess Sandbox & Kernel Jail Simulator

Attack & Execution Scenario

Untrusted Agent Process

Host Path Traversal Attempt

$ cat /etc/shadow || cat ~/.ssh/id_ed25519

Syscall emitted: openat(AT_FDCWD, "/etc/shadow", O_RDONLY)

Kernel Sandbox ShieldBLOCKED

Bubblewrap mount namespace and chroot isolate the agent process. Host sensitive paths are unmounted and masked with empty read-only mounts.

CPU Time: 14 ms

Peak Memory: 4 MB

Exit Code: 1

Security Alert: TRIPPED

Structured Harness Response

Parsed Pydantic ExecutionResult injected into context:

{
  "status": "permission_denied",
  "exit_code": 1,
  "stdout": "",
  "stderr": "cat: /etc/shadow: Permission denied (Bubblewrap sandbox mount isolation)",
  "timed_out": false,
  "security_alert": "PATH_TRAVERSAL_INTERCEPTED"
}

The sandbox turns dangerous raw commands into deterministic, structured JSON payloads. The foundation model never talks directly to the operating system; every action passes through an isolated process boundary with Linux namespaces, cgroups, and timeout watchdogs.

Isolation Tiers Compared

Tier	Technology	Boot Time	Isolation Level	Best Used For
Tier 1: OS-Level Jail	Linux namespaces + `chroot` / `bwrap`	~10ms	Moderate	Local CLI tools (e.g. Claude Code, Codex CLI)
Tier 2: User-Space Kernel	Docker with `gVisor` (`runsc`)	~200ms	High	Cloud evaluation & CI harnesses
Tier 3: MicroVM	AWS Firecracker / Fly.io Machines	~150ms	Complete hardware virtualization	Multi-tenant untrusted user code execution

3. Tool Dispatch & Schema Validation

Every tool exposed to the model must be strictly typed. Using Pydantic, schemas validate every parameter before the sandbox is touched:

Run it yourself

from pydantic import BaseModel, Field, ValidationError

from typing import Optional

import re

# 1. Pydantic Tool Schema Definition

class RunCommandArgs(BaseModel):

command: str = Field(..., description="The shell command to execute")

cwd: str = Field(default="/workspace/repo", description="Working directory")

timeout_sec: float = Field(default=15.0, ge=1.0, le=60.0)

allow_network: bool = Field(default=False)

# 2. Dangerous Command Interceptor (Regex Guard)

FORBIDDEN_PATTERNS = [

r"rm\s+-rf\s+[/~]", # Root / home deletion

r"cat\s+~?/\.(ssh|aws|env)", # Credential probing

r":\(\)\s*\{\s*:\|:&\s*\};:", # Fork bomb

r"curl.*\|\s*(bash|sh)", # Pipe to shell

]

def intercept_command(cmd: str) -> Optional[str]:

for pattern in FORBIDDEN_PATTERNS:

if re.search(pattern, cmd):

return f"SECURITY_VIOLATION: Command matches forbidden pattern '{pattern}'"

return None

# Test Scenario: Model proposes an exfiltration command

test_payloads = [

{"command": "pytest tests/test_math.py", "timeout_sec": 10.0},

{"command": "cat ~/.ssh/id_rsa", "timeout_sec": 5.0},

{"command": "rm -rf / --no-preserve-root", "timeout_sec": 20.0},

]

print("=== Harness Tool Dispatcher Simulation ===\n")

for idx, payload in enumerate(test_payloads, 1):

print(f"Test {idx}: Command: '{payload['command']}'")

try:

Production Golden Rule

Never trust model generated bash commands directly. Always enforce schema validation with Pydantic, sanitize shell arguments to prevent injection, run inside isolated namespaces with resource limits, and wrap subprocess executions in process-group supervisors (os.killpg).

Next in Curriculum

Learn how to organize repository instructions and prevent prompt bloat in Context & Instruction Architecture.