Deep Dive into Harness’s Sandbox Infra: How Deep Agents Enable Secure AI Execution

Core Definition of Deep Agents Sandbox Infra

Sandbox is an isolated execution environment that provides file system operations and arbitrary command execution while fully protecting the host machine from accidental or malicious actions.

Backend Positioning

Two backend types are defined: FilesystemBackend , which offers only file‑system capabilities without any execution rights, and SandboxBackend , which adds the execute() method to enable safe command and script execution. The framework treats execute() as the sole entry point for all sandbox actions.

Capabilities

File operations: ls, read_file, write_file, edit_file, glob, grep.

Arbitrary shell or script execution via execute().

Complete isolation of host files, environment variables, credentials, system processes, and network resources.

execute() Method Details

The method runs a command inside the sandbox and returns a standardized result containing four fields: standard output ( stdout), standard error ( stderr), exit code ( exit_code), and a truncation flag ( truncated) for oversized outputs.

All higher‑level file tools are thin wrappers that generate a script and delegate the actual work to execute(). The following snippet shows the implementation of the ls tool:

def ls(self, path: str) -> LsResult:
    """Structured listing with file metadata using os.scandir."""
    path_b64 = base64.b64encode(path.encode("utf-8")).decode("ascii")
    cmd = f"""python3 -c \"import os
import json
import base64
path = base64.b64decode('{path_b64}').decode('utf-8')
try:
    with os.scandir(path) as it:
        for entry in it:
            result = {
                'path': os.path.join(path, entry.name),
                'is_dir': entry.is_dir(follow_symlinks=False)
            }
            print(json.dumps(result))
except FileNotFoundError:
    pass
except PermissionError:
    pass\" 2>/dev/null"""
    result = self.execute(cmd)

Security Model

Sandbox prevents the agent from reading, modifying, or deleting host files, leaking environment variables or credentials, and interfering with host processes. It also isolates network access, allowing administrators to disable outbound traffic when needed. However, sandbox cannot stop malicious commands that run inside the isolated container; additional policies such as input sanitisation, resource quotas, and human‑in‑the‑loop approval are recommended.

Lifecycle Management

Two isolation scopes are supported:

Thread‑scoped (default): each user conversation gets a fresh sandbox; the sandbox is destroyed when the thread ends.

Assistant‑scoped : all conversations for a single assistant share one sandbox, which requires explicit TTL (time‑to‑live) idle timeout, periodic snapshots, and cleanup to avoid resource bloat.

TTL mechanisms automatically reclaim idle containers, preventing uncontrolled cost growth and resource exhaustion.

Integration Patterns

Two standard patterns are described:

Agent‑in‑Sandbox : the entire agent runtime is packaged inside the sandbox image. This yields perfect environment parity but requires rebuilding the image for every code change and stores secrets inside the container.

Sandbox‑as‑Tool (default): the agent runs on the host and calls the sandbox only for high‑risk operations. This keeps secrets on the host, enables rapid agent updates, and supports parallel sandbox instances.

Standard Integration Steps

Create a sandbox instance using the provider SDK (Docker, Kubernetes, commercial service, etc.).

Wrap the instance as a SandboxBackend that implements execute(), upload_files(), and download_files().

Pass the backend to create_deep_agent() so the agent can invoke sandbox‑enabled tools.

After the task finishes, explicitly destroy the sandbox to free resources.

These steps are identical across Docker, K8s, and commercial sandbox providers, demonstrating the plug‑in architecture of Deep Agents.