Summary

Capsule provides a secure, durable runtime for AI agent tasks, enabling untrusted code execution within isolated WebAssembly sandboxes. It targets developers building complex AI systems who need to manage long-running workflows, large-scale processing, or multi-agent interactions safely, offering robust isolation, resource control, and automatic failure handling.

How It Works

The core approach leverages WebAssembly sandboxing. Python or TypeScript/JavaScript functions are annotated or wrapped as tasks, compiled into Wasm modules, and executed in isolated environments. Capsule enforces resource limits (CPU via fuel metering, RAM, timeouts) and provides automatic retries, ensuring task failures are contained and do not impact the host system or other tasks.

Quick Start & Requirements

• Installation: Python: pip install capsule-run. TypeScript/JavaScript: npm install -g @capsule-run/cli and npm install @capsule-run/sdk.
• Primary Run Command: capsule run <your_file.py> or capsule run <your_file.ts>.
• Prerequisites: For contributing, Rust (latest stable), Python 3.13+, and Node.js 22+ are required.
• Cache: A .capsule directory caches compiled artifacts for faster subsequent runs. capsule build can precompile tasks.

Highlighted Details

• Task Configuration: Fine-grained control over tasks via parameters like name, compute (CPU allocation via fuel metering), ram, timeout, max_retries, allowed_files, allowed_hosts, and env_variables.
• Network & File Access: Configurable allowed_hosts and allowed_files restrict sandbox network and file system interactions. Python uses a custom capsule.http client, while TS/JS uses standard fetch.
• Environment Variables: Tasks can securely access specified environment variables.
• Performance: Caching and ahead-of-time compilation (capsule build) significantly reduce task initialization latency.
• Response Format: Tasks return structured JSON including success status, results, errors, and detailed execution metadata (duration, retries, fuel consumed).

Maintenance & Community

The project features an active CI pipeline. No specific community channels (e.g., Discord, Slack) or notable contributors/sponsorships are detailed in the provided README.

Licensing & Compatibility

• License: Apache License 2.0.
• Compatibility: Python tasks are restricted to pure Python code; C extensions (like NumPy) are not supported within sandboxes. TypeScript/JavaScript tasks offer broader compatibility with npm packages and Node.js built-ins.

Limitations & Caveats

Python code executed within Capsule's WebAssembly sandboxes cannot utilize C extensions (e.g., NumPy, Pandas). While the host environment running capsule run or capsule exec retains full Python ecosystem access, sandboxed code is strictly limited to pure Python.