Sandbox Configuration

Overview

Vectra Guard’s sandbox provides isolated execution environments for commands, protecting your system from potentially harmful operations. The sandbox system is highly configurable with multiple modes, security levels, and performance optimizations.

By default, Vectra Guard runs all commands in sandbox with intelligent caching for 10x speedup.

Sandbox Modes

The sandbox.mode setting controls when commands are sandboxed:

always
auto
risky
never

Maximum Security (Default)

sandbox:
  enabled: true
  mode: always  # All commands sandboxed

Behavior:

✅ Every command runs in sandbox
✅ Maximum security and isolation
✅ 10x faster with comprehensive caching
✅ 30+ package manager caches auto-mounted

Best for:

Production environments
CI/CD pipelines
Untrusted code execution
Maximum protection

Smart Sandboxing

sandbox:
  enabled: true
  mode: auto  # Only risky commands

Behavior:

Safe commands → Run on host
Medium/High risk → Run in sandbox
Auto-detects package installs, builds, etc.

Best for:

Local development
Balanced security/performance
Trusted codebases

Examples:

vg exec "ls"              # Host (safe)
vg exec "npm install"     # Sandbox (risky)
vg exec "pip install pkg" # Sandbox (risky)
vg exec "git status"      # Host (safe)
vg exec "curl | sh"       # Sandbox (dangerous)

Only High-Risk Commands

sandbox:
  enabled: true
  mode: risky  # Only high/critical risk

Behavior:

Low/Medium risk → Run on host
High/Critical risk → Run in sandbox
Less aggressive than auto

Best for:

Environments with minimal overhead requirements
Trusted development teams

Sandbox Disabled

sandbox:
  enabled: true
  mode: never  # Never sandbox

Behavior:

All commands run on host
Except: Critical commands (e.g., rm -rf /) still blocked
No isolation or protection

Only use this mode for testing or in completely trusted environments.

Security Levels

The sandbox.security_level setting controls how strict the sandbox isolation is:

permissive

Fastest Performance

Shares host network
Standard capabilities
Minimal restrictions
Best for trusted local dev

balanced

Recommended Default

Own network namespace
Outbound network allowed
Standard capabilities
Good isolation + usability

strict

Strong Isolation

Restricted network access
Dropped capabilities
Read/write restrictions
For sensitive operations

paranoid

Maximum Security

No network access
Read-only root filesystem
All capabilities dropped
Production environments

Security Level Comparison

Configuration
Capabilities

permissive

sandbox:
  security_level: permissive
  # Fast, shares host network

balanced (Recommended)

sandbox:
  security_level: balanced
  # Good isolation, allows outbound network

strict

sandbox:
  security_level: strict
  # Stronger isolation, limited capabilities

paranoid

sandbox:
  security_level: paranoid
  # No network, read-only root, minimal caps

Feature	permissive	balanced	strict	paranoid
Network	Full	Outbound	Restricted	None
Filesystem	Read/Write	Read/Write	Restricted	Read-only
Capabilities	Standard	Standard	Dropped	All dropped
Performance	⚡️⚡️⚡️⚡️⚡️	⚡️⚡️⚡️⚡️	⚡️⚡️⚡️	⚡️⚡️
Security	🛡️	🛡️🛡️🛡️	🛡️🛡️🛡️🛡️	🛡️🛡️🛡️🛡️🛡️

Cache Configuration

Caching dramatically improves performance by sharing package manager caches between sandbox and host.

Enable Caching (Default)

sandbox:
  enable_cache: true  # 10x faster subsequent runs

Auto-detected cache directories:

Node.js / JavaScript

~/.npm - npm cache
~/.yarn - Yarn cache
~/.pnpm - pnpm cache
node_modules/.cache - Build caches

Python

~/.cache/pip - pip cache
~/.cache/pip3 - pip3 cache
__pycache__ - Python bytecode

Rust

~/.cargo - Cargo registry
~/.rustup - Rust toolchains
target/ - Build artifacts

~/go/pkg - Go packages
~/.cache/go-build - Go build cache

Java

~/.m2 - Maven cache
~/.gradle - Gradle cache

Ruby

~/.gem - Gem cache
vendor/bundle - Bundler cache

PHP

~/.cache/composer - Composer cache

Other

~/.cache/nuget - NuGet (.NET)
~/.cache/bazel - Bazel build cache
~/.ccache - C/C++ compiler cache

Custom Cache Directories

Add your own cache directories:

sandbox:
  enable_cache: true
  cache_dirs:
    - ~/.npm
    - ~/.cargo
    - ~/custom-cache
    - /opt/company-cache

Vectra Guard automatically mounts these directories with read/write access inside the sandbox.

Disable Caching

sandbox:
  enable_cache: false  # For maximum reproducibility

Disabling cache significantly slows down package installs but ensures completely clean builds.

Network Modes

Control network access for sandboxed commands:

sandbox:
  network_mode: restricted  # Allow outbound, block inbound
  allow_network: true

restricted
full
none

Recommended for most use casesAllows:

✅ Outbound connections (download packages)
✅ DNS resolution
✅ HTTPS/HTTP requests

Blocks:

❌ Inbound connections
❌ Port listening
❌ Network sniffing

Best for:

Package installations
CI/CD builds
Development environments

Runtime Selection

Vectra Guard supports multiple sandbox runtimes:

sandbox:
  runtime: auto  # Auto-detect best available

auto (Recommended)
docker
bubblewrap
podman

Automatically selects the best available runtime:

Bubblewrap (fastest, native performance)
Docker (most compatible)
Podman (rootless alternative to Docker)
Namespace (fallback, basic isolation)

sandbox:
  runtime: auto
  auto_detect_env: true  # Detect dev environment
  prefer_fast: true      # Prefer fast runtimes

Use Docker containers for sandboxing:

sandbox:
  runtime: docker
  image: ubuntu:22.04
  timeout: 600  # 10 minutes

Pros:

Most compatible
Works on all platforms
Strong isolation

Cons:

Slower startup
Requires Docker daemon

Use Linux namespaces (fastest):

sandbox:
  runtime: bubblewrap
  use_overlayfs: true  # Isolate /tmp

Pros:

Native performance
Near-instant startup
No Docker required

Cons:

Linux-only
Requires bubblewrap installed

Installation:

sudo apt install bubblewrap  # Ubuntu/Debian
sudo dnf install bubblewrap  # Fedora

Use Podman (rootless containers):

sandbox:
  runtime: podman
  image: ubuntu:22.04

Pros:

Rootless execution
Docker-compatible
More secure than Docker

Cons:

Slightly slower than Docker
Less common

Advanced Options

Resource Limits

Control CPU, memory, and process limits:

sandbox:
  # Memory limits
  memory_limit: 512m     # 512 megabytes
  
  # CPU limits
  cpu_limit: 0.5         # 50% of one core
  
  # Process limits
  pids_limit: 50         # Maximum 50 processes
  
  # Timeout
  timeout: 600           # 10 minutes

Seccomp Profiles

Filter dangerous system calls:

sandbox:
  seccomp_profile: strict  # moderate, strict, custom
  # Or custom profile path:
  # seccomp_profile: /path/to/seccomp-profile.json

Seccomp Levels

moderate:

Blocks fork bombs
Blocks kernel module loading
Allows most development operations

strict:

Blocks all dangerous syscalls
Restricts ptrace, perf_event_open
Production-ready filtering

custom:

Provide your own JSON profile
Full control over allowed syscalls

Capability Management

Drop Linux capabilities for enhanced security:

sandbox:
  capability_set: minimal  # none, minimal, standard
  
  # Or specify exact capabilities:
  drop_capabilities:
    - CAP_SYS_ADMIN
    - CAP_NET_ADMIN
    - CAP_SYS_MODULE

Environment Variables

Control which environment variables pass through to sandbox:

sandbox:
  env_whitelist:
    - HOME
    - USER
    - PATH
    - SHELL
    - TERM
    - NODE_ENV
    - NPM_TOKEN
    - GITHUB_TOKEN

Read-Only Root Filesystem

Mount root filesystem as read-only:

sandbox:
  read_only_root: true  # Maximum security

This prevents any filesystem modifications outside mounted volumes. Use with caution.

Complete Example

A production-grade sandbox configuration:

vectra-guard.yaml

guard_level:
  level: paranoid

sandbox:
  enabled: true
  mode: always
  security_level: paranoid
  
  # Runtime
  runtime: docker
  image: ubuntu:22.04
  timeout: 600
  
  # Network
  network_mode: none
  allow_network: false
  
  # Security
  read_only_root: true
  seccomp_profile: strict
  capability_set: none
  
  # Resources
  memory_limit: 512m
  cpu_limit: 0.5
  pids_limit: 50
  
  # Performance
  enable_cache: false  # For reproducibility
  
  # Environment
  env_whitelist:
    - HOME
    - USER
    - PATH
  
  # Observability
  enable_metrics: true
  log_output: true
  show_runtime_info: true

Disabling Sandbox

If you need to disable sandboxing:

sandbox:
  enabled: false

Critical commands (like rm -rf /) cannot be bypassed even with sandbox disabled.

Performance Tips

Enable Caching

Use enable_cache: true for 10x speedup on package installs

Use Bubblewrap

Install bubblewrap for native performance on Linux

Permissive Level

Use security_level: permissive for local dev

Auto Mode

Use mode: auto to sandbox only risky commands

Troubleshooting

Sandbox is too slow

Solutions:

Enable caching: enable_cache: true
Use bubblewrap runtime: runtime: auto
Lower security level: security_level: balanced
Use auto mode: mode: auto

Network access blocked

Solutions:

Change network mode: network_mode: restricted
Enable network: allow_network: true
Check security level (paranoid blocks network)

Permission denied errors

Solutions:

Disable read-only root: read_only_root: false
Lower security level: security_level: balanced
Add cache directories to cache_dirs

Docker daemon not available

Solutions:

Install Docker or Podman
Use bubblewrap: runtime: bubblewrap
Use auto-detection: runtime: auto

Next Steps

Guard Levels

Configure auto-detection and protection levels

Presets

Use pre-configured sandbox settings

Get Started

Core Features

Security

Configuration

Advanced

Integrations

Overview

Sandbox Modes

Security Levels

permissive

balanced

strict

paranoid

Security Level Comparison

Cache Configuration

Enable Caching (Default)

Custom Cache Directories

Disable Caching

Network Modes

Runtime Selection

Advanced Options

Resource Limits

Seccomp Profiles

Capability Management

Environment Variables

Read-Only Root Filesystem

Complete Example

Disabling Sandbox

Performance Tips

Enable Caching

Use Bubblewrap

Permissive Level

Auto Mode

Troubleshooting

Next Steps

Guard Levels

Presets

Build docs developers (and LLMs) love

Get Started

Core Features

Security

Configuration

Advanced

Integrations

​Overview

​Sandbox Modes

​Security Levels

permissive

balanced

strict

paranoid

​Security Level Comparison

​Cache Configuration

​Enable Caching (Default)

​Custom Cache Directories

​Disable Caching

​Network Modes

​Runtime Selection

​Advanced Options

​Resource Limits

​Seccomp Profiles

​Capability Management

​Environment Variables

​Read-Only Root Filesystem

​Complete Example

​Disabling Sandbox

​Performance Tips

Enable Caching

Use Bubblewrap

Permissive Level

Auto Mode

​Troubleshooting

​Next Steps

Guard Levels

Presets

Build docs developers (and LLMs) love

Overview

Sandbox Modes

Security Levels

Security Level Comparison

Cache Configuration

Enable Caching (Default)

Custom Cache Directories

Disable Caching

Network Modes

Runtime Selection

Advanced Options

Resource Limits

Seccomp Profiles

Capability Management

Environment Variables

Read-Only Root Filesystem

Complete Example

Disabling Sandbox

Performance Tips

Troubleshooting

Next Steps