Capsule Run

capsule-run

A lightweight, secure sandboxed command execution utility designed for AI agents and automated systems.

Features

• Secure Isolation: Linux namespaces, seccomp filters, and cgroups v2
• Resource Limits: Memory, CPU, process count, and I/O controls
• Fast Startup: Sub-50ms cold start times
• Zero Dependencies: Single static binary
• JSON API: Native integration with AI frameworks
• Comprehensive Monitoring: Resource usage tracking and metrics

Quick Start

Basic Usage

# Execute a simple command
capsule-run -- echo "Hello, World!"

# With resource limits
capsule-run --memory 256M --timeout 5000 -- python script.py

# JSON mode for programmatic use
echo '{"command":["python","-c","print(42)"]}' | capsule-run --json

JSON API

{
  "command": ["python", "-c", "print('Hello from sandbox')"],
  "environment": {"PYTHONPATH": "/workspace"},
  "timeout_ms": 5000,
  "resources": {
    "memory_bytes": 268435456,
    "cpu_shares": 1024,
    "max_output_bytes": 1048576
  },
  "isolation": {
    "network": false,
    "readonly_paths": ["/usr", "/bin"],
    "writable_paths": ["/tmp"],
    "working_directory": "/workspace"
  }
}

Installation

Pre-built Binaries

Download from the [releases page](https://github.com/haasonsaas/capsule-run/releases).

Build from Source

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/haasonsaas/capsule-run.git
cd capsule-run
cargo build --release

# The binary will be at target/release/capsule-run

Requirements

• Linux kernel 5.10+ (for cgroups v2)
• x86_64 or aarch64 architecture
• User namespaces enabled (usually default on modern systems)

Security

capsule-run implements defense-in-depth security:

1. User Namespaces: Maps container root to unprivileged host user
2. Mount Namespaces: Isolated filesystem with pivot_root
3. **PID N