Sandbox Deep Dive

Understand sandboxing modes, performance optimizations, and runtime options

What is Sandboxing?

Vectra Guard's sandbox provides isolated execution environments for commands, preventing them from affecting your host system. Commands run in containers with restricted access to files, network, and system resources.

Benefits

  • Protect your host system from malicious or buggy commands
  • Test commands safely before running on production
  • Isolate dependencies and prevent conflicts
  • Reproducible execution environments
  • 10x faster with intelligent caching

Sandbox Modes

Choose the sandbox mode that best fits your workflow. Each mode offers different trade-offs between security and performance.

Always Mode (Default)

Maximum security. All commands run in sandbox, no exceptions.

sandbox:
  enabled: true
  mode: always
  enable_cache: true

Use when: Working with untrusted code, production environments, or maximum security is required.

Auto Mode (Balanced)

Intelligent routing. Low-risk commands run on host, medium/high-risk in sandbox.

sandbox:
  enabled: true
  mode: auto
  enable_cache: true
  
  # Risk thresholds
  risk_threshold:
    low: host      # Run on host
    medium: sandbox  # Run in sandbox
    high: sandbox    # Run in sandbox

Use when: You want a balance between security and performance. Safe for trusted development workflows.

Manual Mode

You decide. Use --sandbox flag to explicitly sandbox commands.

sandbox:
  enabled: true
  mode: manual
Manual Mode Usage
# Run on host (default)
vg exec -- npm test

# Run in sandbox (explicit)
vg exec --sandbox -- npm test

Use when: You want full control over which commands are sandboxed.

Disabled

No sandboxing. All commands run on host (not recommended for untrusted code).

sandbox:
  enabled: false

Warning: Only disable sandboxing if you fully trust all commands. This removes a key security layer.

Performance & Caching

Sandboxing can be slow, but Vectra Guard's intelligent caching makes it 10x faster for repeated commands.

How Caching Works

When a command runs in the sandbox, Vectra Guard:

  1. Creates a hash of the command and its inputs
  2. Checks if this exact command ran before
  3. If cached, returns the previous result instantly
  4. If not cached, runs in sandbox and caches the result
Cache Configuration
sandbox:
  enabled: true
  enable_cache: true
  cache_ttl: 3600  # Cache for 1 hour (seconds)
  cache_size: 100MB  # Maximum cache size
  
  # Cache strategies
  cache_strategy: smart  # smart, aggressive, conservative

Without Cache

First run:

2.5s

Subsequent runs:

2.5s

With Cache

First run:

2.5s

Subsequent runs:

0.25s

10x faster!

Runtime Options

Configure the container runtime and resource limits for sandboxed commands.

Runtime Configuration
sandbox:
  runtime: docker  # docker, podman, containerd
  
  # Resource limits
  resources:
    cpu: 2          # CPU cores
    memory: 2GB     # Memory limit
    disk: 10GB      # Disk space
    network: true   # Allow network access
  
  # Isolation options
  isolation:
    filesystem: ro  # ro (read-only), rw (read-write)
    network: restricted  # full, restricted, none
    user: sandbox   # Run as non-root user
    capabilities: []  # Drop all capabilities

Docker (Default)

Uses Docker containers. Requires Docker daemon running. Best compatibility and performance.

Podman

Rootless containers. No daemon required. Good for systems without Docker.

Containerd

Lower-level runtime. More control, but requires more configuration.

File System Access

Control how sandboxed commands access your project files.

Volume Configuration
sandbox:
  volumes:
    # Mount project directory (read-only by default)
    - source: .
      target: /workspace
      mode: ro  # ro (read-only) or rw (read-write)
    
    # Mount specific directories
    - source: ./src
      target: /workspace/src
      mode: rw
    
    # Exclude sensitive files
    exclude:
      - .env
      - .git
      - node_modules

Network Access

Configure network access for sandboxed commands.

Network Configuration
sandbox:
  network:
    mode: restricted  # full, restricted, none
    
    # Restricted mode allows:
    allowed_hosts:
      - api.github.com
      - registry.npmjs.org
      - pypi.org
    
    # Block specific domains
    blocked_hosts:
      - malicious-site.com

Full Access

Commands can access any network resource. Use for commands that need internet access.

Restricted (Recommended)

Only allowlisted hosts are accessible. Balances functionality and security.

No Access

Complete network isolation. Use for maximum security when network isn't needed.

Best Practices

1. Enable Caching

Always enable caching for 10x performance improvement. The cache is automatically managed and cleaned.

2. Use Auto Mode for Development

Auto mode provides a good balance. Low-risk commands run fast on host, risky ones are protected.

3. Restrict Network Access

Use restricted network mode and only allowlist necessary hosts. Prevents data exfiltration.

4. Read-Only File System

Mount project files as read-only when possible. Only allow write access when necessary.

5. Monitor Resource Usage

Set appropriate resource limits to prevent sandboxed commands from consuming too much CPU or memory.