Vectra Guard’s sandbox system provides transparent, fast, and secure isolation for risky commands. It intelligently decides when to sandbox based on risk level and context.
Sandbox Modes Vectra Guard supports three sandbox modes:
Always (Default)
Auto
Never
sandbox : enabled : true mode : always # Maximum security
All commands run in sandbox
✅ Maximum security out of the box
✅ 10x speedup with caching enabled
✅ Provable isolation for everything
✅ Perfect for AI agents and untrusted code
vg exec "echo hello" # → Sandbox (cached, fast) vg exec "npm install" # → Sandbox (cached, 10x faster) vg exec "curl remote.com" # → Sandbox (isolated) vg exec "rm -rf /" # → Blocked (critical)
sandbox : enabled : true mode : auto # Balanced security & speed
Smart sandboxing based on risk
✅ Low-risk on host (instant)
✅ Medium/high-risk sandboxed (cached)
✅ Automatic protection without thinking
✅ Best for development workflows
vg exec "echo hello" # → Host (instant) vg exec "ls -la" # → Host (instant) vg exec "npm install" # → Sandbox (cached, fast) vg exec "curl remote.com" # → Sandbox (isolated)
sandbox : enabled : false # OR mode : never
Traditional validation-only mode
⚠️ No isolation (except critical commands)
✅ Fastest execution
⚠️ Less secure
⚠️ Only for trusted environments
vg exec "npm install" # → Direct execution vg exec "rm -rf /" # → Still blocked (critical)
Recommended: Use mode: always (default) for maximum security with intelligent caching for speed.
Cache Mounting: 10x Speedup The caching magic that makes sandbox execution fast:
The Problem: Slow Repeated Installs Without caching, every sandbox execution starts fresh:
# Without cache: SLOW ❌ vg exec "npm install express" # → Creates fresh container # → Downloads 50 packages from internet: 12.3s # → Container destroyed vg exec "npm install lodash" # → Creates NEW fresh container # → Downloads 30 packages AGAIN: 8.7s # → Container destroyed # Total wasted: ~21 seconds + repeated downloads
The Solution: Shared Cache Mounts Vectra Guard mounts your host cache directories into the sandbox:
# WITH cache: FAST ✅ vg exec "npm install express" # → Creates container # → Mounts ~/.npm into container # → Checks cache FIRST (most packages already there!) # → Only downloads NEW/MISSING packages: 1.2s ⚡ # → Cache persists on host vg exec "npm install lodash" # → Creates NEW container # → Mounts SAME ~/.npm cache # → Finds express deps ALREADY in cache! # → Only downloads lodash: 0.8s ⚡ # → Everything reused! # Total time: ~2 seconds (vs 21 seconds!) # 🎉 10x FASTER
How Cache Mounting Works Architecture
Configuration
┌──────────────────────────────────────────────────────┐ │ Your Host Machine │ ├──────────────────────────────────────────────────────┤ │ │ │ ~/.npm/ (Cache Root) │ │ ├── express@4.18.0/ ← Already downloaded │ │ ├── lodash@4.17.21/ ← Already downloaded │ │ └── ...1000+ packages ← Accumulated over time │ │ │ │ ┌────────────────────────────────────────────┐ │ │ │ Docker Container (Sandbox) │ │ │ │ ┌──────────────────────────────────────┐ │ │ │ │ │ /.npm → Points to ~/.npm │ │ │ │ │ │ (SHARED with host!) │ │ │ │ │ └──────────────────────────────────────┘ │ │ │ │ │ │ │ │ When npm runs inside: │ │ │ │ 1. Checks /.npm cache │ │ │ │ 2. Finds packages already there! ✅ │ │ │ │ 3. No download needed │ │ │ │ 4. Installs in seconds ⚡ │ │ │ └────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────┘
Supported Cache Directories Vectra Guard automatically detects and mounts caches for:
Ecosystem Host Cache Location Container Mount Speedup npm ~/.npm/.npm10.2x Yarn v1 ~/.yarn/.yarn8.4x Yarn v2+ ~/.yarn/cache/.yarn/cache9.1x pnpm ~/.pnpm-store/.pnpm-store12.3x pip ~/.cache/pip/.cache/pip9.6x Poetry ~/.cache/pypoetry/.cache/pypoetry8.8x Cargo ~/.cargo/.cargo15.2x Go ~/go/pkg/go/pkg11.0x Ruby ~/.gem/.gem7.3x Maven ~/.m2~/.m26.8x Gradle ~/.gradle~/.gradle7.1x
Caching is enabled by default in always mode - you get 10x speedup automatically!
Docker/Container Isolation Vectra Guard supports multiple container runtimes:
Runtime Selection sandbox : runtime : docker # docker, podman, process (Linux only) image : ubuntu:22.04 timeout : 300 # seconds
Docker
Podman
Bubblewrap (Linux)
Most compatible, works everywhere
✅ Works on macOS, Linux, Windows
✅ Full isolation (process, network, filesystem)
✅ Battle-tested and widely available
⚠️ 2-5s startup overhead
# Install Docker Desktop # macOS brew install --cask docker # Linux sudo apt install docker.io sudo systemctl enable --now docker sudo usermod -aG docker $USER
Rootless alternative to Docker
✅ Same CLI as Docker
✅ Rootless by default (more secure)
✅ Works on Linux and macOS
⚠️ 2-5s startup overhead
# Linux sudo dnf install podman # macOS brew install podman podman machine init podman machine start
Fastest runtime - <1ms overhead
✅ < 1ms overhead (essentially native speed)
✅ All caches work seamlessly
✅ Zero configuration needed
⚠️ Linux only
# Install sudo apt install bubblewrap # Debian/Ubuntu sudo dnf install bubblewrap # Fedora sudo yum install bubblewrap # RHEL/CentOS
Auto-Detection Vectra Guard intelligently selects the best runtime:
sandbox : runtime : auto # Auto-select best runtime auto_detect_env : true # Detect dev vs CI prefer_fast : true # Prefer fast runtimes in dev
Selection priority:
Dev: bubblewrap → namespace → dockerCI: docker → bubblewrap → namespaceProd: docker → bubblewrap → namespace
Scenario: Installing 50 packages Without Vectra Guard
With Sandbox (First Time)
With Sandbox (Cached - MAGIC!)
npm install # 50 packages, 12.3s
Real-World Benchmarks Operation Direct Sandbox (No Cache) Sandbox (Cached) Speedup npm install (50 pkg) 12.3s 12.8s 1.2s 10.2x ⚡pip install (20 pkg) 8.7s 9.1s 0.9s 9.6x ⚡cargo build 45.2s 46.1s 4.1s 11.0x ⚡go mod download 3.4s 3.6s 0.4s 8.5x ⚡
Overhead:
First run: +3-5% (builds cache)
Cached runs: 10x FASTER than direct!
Trusted commands: 0% (runs on host)
Security Levels Tune isolation without sacrificing speed:
Permissive
Balanced
Strict
Paranoid
sandbox : security_level : permissive
Full network access
R/W filesystem
2GB memory, 2.0 CPU
Use for: Development sandbox : security_level : balanced
Restricted network
R/W filesystem
1GB memory, 1.0 CPU
Use for: Default (recommended) sandbox : security_level : strict
Restricted network
Read-only root filesystem
512MB memory, 0.5 CPU
Use for: CI/CD sandbox : security_level : paranoid
No network access
Read-only root filesystem
256MB memory, 0.25 CPU
Use for: Production, untrusted code Developer Experience Single-Line Notices Every sandbox decision includes clear reasoning:
📦 Running in sandbox (cached). Why: medium risk + networked install
No Prompts Unless Needed
Low-risk: Silent executionMedium-risk: Automatic sandboxing, no promptHigh-risk: Approval only if --interactiveTrusted: Remembered approvals skip prompts
Trust Store Integration Approve commands once, run them on host forever:
# First time - interactive approval vg exec --interactive "npm test" ⚠️ Command requires approval Options: y - Yes, run once r - Yes, and remember (trust permanently ) ← Choose this ! n - No, cancel Choose: r ✅ Approved and remembered # Every subsequent time vg exec "npm test" # → Runs immediately on HOST ⚡ # → No prompt, no sandbox, instant!
Configuration Examples Developer Preset (Fast Development) sandbox : enabled : true mode : auto # Smart sandboxing security_level : permissive enable_cache : true # 10x speedup network_mode : full
CI/CD Preset (Balanced) sandbox : enabled : true mode : always # All commands sandboxed security_level : strict enable_cache : true # Fast CI builds network_mode : restricted
Production Preset (Maximum Security) sandbox : enabled : true mode : always # Everything sandboxed security_level : paranoid enable_cache : false # Reproducibility network_mode : none
Metrics & Analytics Track sandbox usage and performance:
Example output: Vectra Guard Sandbox Metrics =============================== Total Executions: 1,247 - Host: 834 (66.9%) ← Trusted commands - Sandbox: 413 (33.1%) ← Risky commands - Cached: 389 (31.2%) ← Cache hits! 🎉 Average Duration: 0.8s By Risk Level: - low: 834 (66.9%) ← Running on host - medium: 387 (31.0%) ← Sandboxed but cached - high: 26 (2.1%) ← Sandboxed, slower By Runtime: - docker: 413 Time Saved (estimated): 4.2 hours this week! ⚡
What This Tells You:
67% of commands trusted → Fast path
31% cached → 10x faster
Only 2% truly risky → Properly isolated
Result: Security + Speed! 🎉 Troubleshooting Slow Execution Enable Caching
Trust Common Commands
sandbox : enable_cache : true
Docker Not Available # Use podman instead sandbox : runtime : podman # Or process sandbox (Linux only) sandbox : runtime : process
Network Issues # Allow full network access sandbox : network_mode : full
Permission Errors # Use permissive security level sandbox : security_level : permissive # Or bind mount with write access sandbox : bind_mounts : - host_path : /path/to/data container_path : /data read_only : false
Best Practices Always enable caching for 10x speedup:sandbox : enable_cache : true
Use auto mode for development to balance security and speed:Trust common commands to skip sandboxing:vg trust add "npm test" vg trust add "npm run build"
Monitor metrics weekly to see time saved:Next Steps
Command Protection Learn about risk detection and guard levels
Sessions & Audit Track and audit sandbox execution