Sandboxing

Agent Harbor provides comprehensive sandbox isolation to ensure AI coding agents cannot harm your computer, access sensitive files, or interfere with each other.

Security Posture

The sandbox is designed with a clear threat model: agents execute potentially hostile code. Defense-in-depth principles apply throughout:

• No publicly known sandbox escapes
• Least privilege everywhere
• Host, secrets, and other tenants protected

Sandbox Strategies

Agent Harbor supports multiple sandboxing approaches:

Filesystem Isolation

Read-Only Baseline

The host filesystem is treated as read-only:

• Agents see your project files but cannot modify them directly
• All writes go to a copy-on-write overlay
• Changes are discarded when the session ends (unless explicitly saved)

Sensitive Areas Shielded

By default, access to sensitive directories is blocked:

Dynamic Read Allow-List

Two access control models are available:

Default (Interactive Approval)

• First access to a non-allowed path blocks until you approve or deny
• Access can be granted without restarting the session
• Choices can be saved to user, project, or organization config

Relaxed Mode (Blacklist)

• Read-only view with configurable blacklist for sensitive directories
• Configurable set of writable overlays
• No interactive gating

Writable Carve-Outs

Package manager caches can be made writable for efficiency:

# .ah/config.toml
[sandbox.writable_paths]
paths = [
  "~/.cargo/registry",
  "~/.cache/pip",
  "~/.npm/_cacache",
  "~/.cache/go-build"
]

Process Isolation

Agents see only their own session processes:

• ps, kill, and similar commands only show session processes
• No cross-tenant visibility
• Debugging is supported within the sandbox

Network Isolation

Network access is controlled per-session:

Resource Governance

Per-session limits prevent runaway builds/tests:

Nested Virtualization

Launching containers and VMs inside the sandbox is supported:

# Allow container operations (Docker, Podman)
ah agent start --agent claude --sandbox --allow-containers true --prompt "Build image"
 
# Allow KVM/VM operations
ah agent start --agent claude --sandbox --allow-kvm true --prompt "Test in VM"

Note: These options enable controlled access without exposing host control sockets.

Privilege Model

• No-sudo startup — Privileged steps happen in short-lived helpers that drop privileges immediately
• Capabilities dropped — Workloads run with minimal privileges
• Supervisor external — The supervisor process stays outside the sandboxed context

Usage

Enable Sandbox

ah agent start --agent claude --sandbox --prompt "Run tests"

With Specific Sandbox Type

# Local process sandbox (default)
ah agent start --agent claude --sandbox --sandbox-type local --prompt "Run tests"
 
# Devcontainer
ah agent start --agent claude --sandbox --sandbox-type devcontainer --prompt "Build"
 
# VM isolation
ah agent start --agent claude --sandbox --sandbox-type vm --prompt "Run untrusted code"

With Network Access

ah agent start --agent claude --sandbox --allow-network true --prompt "Install dependencies"

With Container Access

ah agent start --agent claude --sandbox --allow-containers true --prompt "Build Docker image"

CLI Options

Platform Support

Acceptance Criteria

A properly configured sandbox:

• Launches and tears down in seconds with no host residue
• Prevents writes outside approved locations
• Blocks secrets access without explicit approval
• Allows debugging of in-session processes while hiding host processes
• Makes internet/container/VM access a conscious, explicit action