Sandbox Modes

AgentVisor™ supports multiple sandbox modes. Docker and gVisor are both production-grade; gVisor adds syscall-level interception for slightly stronger defense-in-depth and is the default for built images. Docker runs on any platform that supports Docker.

What "sandbox" means in AgentVisor

A sandbox is a security isolation boundary — a hardened execution environment where agent code runs fully isolated from the host with no direct access to the network, filesystem, processes, or credentials. Dedicated resource limits (CPU, memory, processes) prevent resource abuse. This is production-grade containment, not a test environment.

Overview

Mode	Platform	Isolation Level	Hardening	Notes
`gvisor`	Linux	Container + Syscall interception	Full	Strongest isolation; default for built images
`docker`	Linux	Container	Full	Cross-platform; production-grade
`docker`	macOS/Windows	Container	Full†	Same posture as Docker/Linux; outbound restriction via in-guest nftables
`none`	Any	None	None	No isolation; agent development and debugging only

†Docker on macOS/Windows uses network_filtering (in-guest nftables) instead of --network=none because TCP transport to host.docker.internal is required. The agent's effective outbound network restriction is equivalent.

gVisor Mode
Linux Only

Syscall-level isolation — strongest security available, recommended for Linux production deployments.

Default for Built Images

gVisor is the default sandbox mode when deploying containers built with agentvisor build. It is recommended for Linux production deployments where slightly stronger isolation is preferred.

agentvisor serve ./my-agent --sandbox=gvisor

# Interactive terminal session with gVisor isolation
agentvisor exec ./my-agent --sandbox=gvisor

Local gVisor Installation

Container images built with agentvisor build already include gVisor — you get gVisor sandbox isolation on any platform through the normal build and deploy flow.

Installing gVisor's runsc locally is only needed if you want to run agentvisor serve --sandbox=gvisor directly on a Linux workstation:

curl -fsSL https://gvisor.dev/archive.key | sudo apt-key add -
sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases release main"
sudo apt-get update && sudo apt-get install runsc

Platform	`agentvisor build` (gVisor)	Local `--sandbox=gvisor`
macOS (Intel/Apple Silicon)	Yes	No
Windows (with Docker Desktop)	Yes	No
Linux (x86_64/arm64)	Yes	Yes

How It Works

Host runtime creates OCI bundle
runsc (gVisor runtime) spawns sandbox
Sentry (userspace kernel) intercepts all syscalls
Network disabled, only Unix socket available

Isolation Features

gVisor provides a userspace kernel (Sentry) that intercepts every syscall before it reaches the host kernel. AgentVisor layers additional hardening on top:

From gVisor:

Syscall interception: Every syscall goes through Sentry
No direct kernel access: Kernel vulnerabilities don't expose host

Added by AgentVisor:

Network isolation: network=none configuration — no network interface in the sandbox
Resource limits: cgroups v2 enforcement
Privilege separation: OpenSSH-style privsep with UID 2000 main process
Per-agent UID isolation: Unique UIDs (2001+) prevent cross-tenant memory reads
Environment curation: Allowlisted env vars only

Advantages

Strongest isolation available
Kernel vulnerabilities don't affect host
Comprehensive syscall filtering
Defense in depth

Privilege Modes

gVisor can run in two modes: rootless (default) or privileged.

Rootless Mode (Default)

gVisor creates a user namespace internally via CLONE_NEWUSER combined with --network=none. Container images built with agentvisor build have uidmap and subuid/subgid pre-configured for this.

Kernel Prerequisites

Rootless mode requires unprivileged user namespaces enabled on the host kernel:

Linux 5.15+ supports this by default on most distributions
Some distributions (Debian, Ubuntu 23.10+) require: sysctl -w kernel.unprivileged_userns_clone=1
Verify with: cat /proc/sys/user/max_user_namespaces (should be > 0)

These prerequisites only matter when running runsc directly on a host; container images from agentvisor build handle the rest.

# CLI — rootless is the default
agentvisor serve ./my-agent --sandbox=gvisor

# Docker — both flags required: seccomp and AppArmor can each block CLONE_NEWUSER
docker run --security-opt seccomp=unconfined \
    --security-opt apparmor=unconfined \
    -p 8090:8090 \
    my-agent:v1

Privileged Mode

Opt-in mode that requires Docker --privileged. Provides full gVisor capabilities with maximum defense-in-depth, including DirectFS for fastest I/O.

# CLI — opt in with --rootless=false
agentvisor serve ./my-agent --sandbox=gvisor --rootless=false

# Docker — must run as root with --privileged
docker run --user root --privileged     -p 8090:8090     -e AGENTVISOR_GUEST_ROOTLESS=false     my-agent:v1

Mode trade-offs:

Aspect	Rootless (default)	Privileged
Docker flags	`--security-opt seccomp=unconfined --security-opt apparmor=unconfined`	`--user root --privileged`
Filesystem	9P filesystem (slower)	DirectFS (fastest)
Defense in depth	Reduced (per gVisor docs)	Full
Privilege required	None (zero-capability)	Root-equivalent
Kernel prerequisites	Unprivileged userns + uidmap	None

Automatic Privilege Dropping

In rootless mode (default), the process never starts as root — no privilege is required or dropped. In privileged mode, the host runtime starts as root only to initialize the gVisor sandbox, then permanently drops privileges to uid/gid 1000 (unprivileged agentvisor user) via irreversible setuid()/setgid() syscalls. All subsequent operations run as the unprivileged user.

When to use privileged mode

When maximum I/O performance (DirectFS) is required
On hosts without unprivileged user namespace support
When your environment already allows --privileged and you want full defense-in-depth

Rootless limitations

Performance: Uses 9P filesystem instead of DirectFS
Symlinks: Container root path must not contain symlinks
Isolation: Some defense-in-depth guarantees are reduced per gVisor documentation

When to Use

Production deployments
Multi-tenant environments
Running untrusted code
Regulated industries

Docker Mode

Docker container isolation — production-grade containment that runs the guest in a Docker container.

Default for the CLI

Docker is the default sandbox mode for agentvisor run, agentvisor serve, and agentvisor exec because it works on any platform (Linux, macOS, Windows) without extra host setup.

agentvisor serve ./my-agent

How It Works

Host runtime starts on the host machine
Guest container started via Docker API
Host and guest communicate over a hostlink session, carried by UDS on Linux or TCP+mTLS on macOS/Windows (see Hostlink Transport below)
Agent runs inside the container

Hostlink Transport

The hostlink session (see Architecture) is the multiplexed gRPC connection between the host runtime and the guest sandbox. The wire-level transport depends on host OS:

Linux: Unix domain socket bind-mounted into the container. OS-level isolation; no TLS needed.
macOS / Windows: TCP + mTLS via host.docker.internal. UDS bind-mounts don't cross the Docker Desktop VM boundary, so AgentVisor falls back to TCP — and mTLS keeps the channel authenticated and encrypted across that boundary. The mTLS credentials are short-lived and scoped to the sandbox lifetime.

Advantages

Works on macOS, Windows, and Linux
Container-level isolation
Uses familiar Docker tooling
Default mode — no extra flags needed

Limitations

Uses TCP instead of Unix sockets on macOS/Windows (Docker Desktop VM limitation)
Docker Desktop VM overhead on non-Linux platforms
Does not include syscall-level interception (use gVisor on Linux if that layer matters)

When to Use

Development and production on any platform that supports Docker
Cross-platform deployments (Linux, macOS, Windows)
CI/CD environments
Production on non-Linux hosts (or Linux hosts where gVisor's runsc is not available)

Unsandboxed Mode

No isolation — runs the agent directly in your local environment.

agentvisor serve ./my-agent --sandbox=none

Setup Required

Running with --sandbox=none requires a Python virtual environment with the AgentVisor SDK installed. See Local Development Setup for complete setup instructions.

How It Works

Host runtime starts directly (no container)
Agent process spawned as a child process
HTTP proxy runs in the same process
Policy enforcement still applies

Advantages

Fast startup
Easy debugging with standard tools
No container overhead
Works on any platform

Limitations

No security isolation
Agent has full filesystem access
Agent could bypass proxy (if malicious)
Requires manual environment setup (e.g., Python venv for LangGraph agents)

When to Use

Debugging agent code
Quick iteration with breakpoints
When Docker is not available

Granular Hardening

AgentVisor's security hardening is organized into six feature groups. Each group defaults to auto, which enables features when supported by the sandbox type.

Hardening Feature Groups

Feature Group	What It Controls
`process_isolation`	Privilege separation, UID isolation, capability dropping
`env_curation`	Environment variable allowlisting, umask 0077
`network_isolation`	Loopback-only networking (`--network=none`)
`network_filtering`	In-guest nftables ruleset restricting outbound traffic to loopback + hostlink only
`filesystem_hardening`	Read-only rootfs, seccomp profiles, tmpfs mounts
`kernel_hardening`	Capability bounding set, NoNewPrivileges, user namespace blocking

Configuration Values

Value	Behavior
`auto`	Enable if supported by sandbox type (default)
`enabled`	Force enable — fails startup if not supported
`disabled`	Force disable — WARNING logged

Auto-Detection Matrix

Sandbox Type	Platform	process_isolation	env_curation	network_isolation	network_filtering	filesystem_hardening	kernel_hardening
`gvisor`	Linux	✓	✓	✓	—	✓	✓
`docker`	Linux	✓	✓	✓	—	✓	✓
`docker`	macOS/Windows	✓	✓	—	✓	✓	✓
`none`	Any	✗	✗	✗	✗	✗	✗

network_isolation and network_filtering are mutually exclusive: Linux modes use --network=none (OS-level); Docker on macOS/Windows uses in-guest nftables instead, achieving equivalent outbound restriction.

Configuration Example

guest:
  hardening:
    process_isolation: auto    # AGENTVISOR_GUEST_HARDENING_PROCESS_ISOLATION
    env_curation: auto         # AGENTVISOR_GUEST_HARDENING_ENV_CURATION
    network_isolation: auto    # AGENTVISOR_GUEST_HARDENING_NETWORK_ISOLATION
    network_filtering: auto    # AGENTVISOR_GUEST_HARDENING_NETWORK_FILTERING
    filesystem_hardening: auto # AGENTVISOR_GUEST_HARDENING_FILESYSTEM_HARDENING
    kernel_hardening: auto     # AGENTVISOR_GUEST_HARDENING_KERNEL_HARDENING

Use auto for most deployments

The auto setting is recommended for most deployments. It enables all hardening features supported by your sandbox type without manual configuration.

Comparison

Note: Both docker and gvisor are production-grade. The difference is that gVisor adds a userspace kernel that intercepts every syscall, while Docker relies on container isolation and seccomp filtering. none has no isolation and is for local development only.

Configuration

Resource Limits

Available in gvisor and docker modes (memory/CPU/PIDs limits map to Docker's --memory/--cpus/--pids-limit flags in docker mode, and to the equivalent OCI/cgroups settings in gvisor mode):

# Memory limit (512MB)
export AGENTVISOR_GUEST_MEMORY_LIMIT=536870912

# CPU limit (1 core)
export AGENTVISOR_GUEST_CPU_LIMIT=1.0

# Process limit
export AGENTVISOR_GUEST_PIDS_LIMIT=1024

Timeouts

# Startup timeout
export AGENTVISOR_GUEST_STARTUP_TIMEOUT=30s

# Shutdown timeout
export AGENTVISOR_GUEST_SHUTDOWN_TIMEOUT=10s

Docker/Kubernetes Deployment

For container deployments, the sandbox mode is configured via environment variable. Images built with agentvisor build default to gVisor, so AGENTVISOR_GUEST_SANDBOX can be omitted unless you need to override it.

Rootless Mode (Default)

No extra capabilities required. Images built with agentvisor build work out of the box:

# docker-compose.yml (rootless — default)
services:
  agentvisor:
    image: my-agent:v1
    security_opt:
      - seccomp=unconfined  # Required: default seccomp profile may block CLONE_NEWUSER
      - apparmor=unconfined  # Required on Ubuntu 24.04+, GKE, AKS
    ports:
      - "8090:8090"

# Kubernetes deployment (rootless — default)
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: agent
    image: my-agent:v1
    securityContext:
      seccompProfile:
        type: Unconfined  # Required: default seccomp profile may block CLONE_NEWUSER
      appArmorProfile:
        type: Unconfined  # Required on Ubuntu 24.04+, GKE, AKS

Privileged Mode

Opt-in when you need DirectFS performance or lack unprivileged user namespace support:

# docker-compose.yml (privileged)
services:
  agentvisor:
    image: my-agent:v1
    user: root
    privileged: true
    environment:
      - AGENTVISOR_GUEST_ROOTLESS=false

# Kubernetes deployment (privileged)
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: agent
    securityContext:
      privileged: true
      runAsUser: 0
    env:
    - name: AGENTVISOR_GUEST_ROOTLESS
      value: "false"

Choosing a Mode

Scenario	Recommended Mode
Local development (default)	`docker`
Debugging/breakpoints	`none`
Production on Linux (strongest isolation)	`gvisor`
Production on non-Linux / cross-platform	`docker`
Multi-tenant SaaS on Linux	`gvisor`
CI/CD testing	`docker`
Interactive sessions (exec)	`docker` or `gvisor`

Overview​

How It Works​

Isolation Features​

Advantages​

Privilege Modes​

Rootless Mode (Default)​

Privileged Mode​

When to Use​

Docker Mode​

How It Works​

Hostlink Transport​

Advantages​

Limitations​

When to Use​

Unsandboxed Mode​

How It Works​

Advantages​

Limitations​

When to Use​

Granular Hardening​

Hardening Feature Groups​

Configuration Values​

Auto-Detection Matrix​

Configuration Example​

Comparison​

Configuration​

Resource Limits​

Timeouts​

Docker/Kubernetes Deployment​

Rootless Mode (Default)​

Privileged Mode​

Choosing a Mode​

Overview

How It Works

Isolation Features

Advantages

Privilege Modes

Rootless Mode (Default)

Privileged Mode

When to Use

Docker Mode

How It Works

Hostlink Transport

Advantages

Limitations

When to Use

Unsandboxed Mode

How It Works

Advantages

Limitations

When to Use

Granular Hardening

Hardening Feature Groups

Configuration Values

Auto-Detection Matrix

Configuration Example

Comparison

Configuration

Resource Limits

Timeouts

Docker/Kubernetes Deployment

Rootless Mode (Default)

Privileged Mode

Choosing a Mode