A secure, durable runtime for AI agents that executes untrusted code in isolated WebAssembly sandboxes with fine-grained resource control including CPU, memory, timeout limits and permission management.
Overview#
Capsule is a task runtime environment designed for AI agents, addressing security concerns when executing untrusted or third-party code in AI applications. It achieves cross-platform isolation through WebAssembly (Wasm), supporting Python 3.13+ and Node.js 22+.
Core Capabilities#
Security Isolation
- Each task runs in an independent WebAssembly sandbox, completely isolated from the host system
- Filesystem access control: Only whitelisted directories accessible (
allowed_files) - Network access control: Only whitelisted domains accessible (
allowed_hosts) - Environment variable control: Selective exposure of environment variables
Resource Control
- CPU limits: Metered via Wasm Fuel mechanism, supports LOW/MEDIUM/HIGH/CUSTOM levels
- Memory limits: Configurable per-task memory caps (e.g., "512MB", "2GB")
- Timeout control: Configurable maximum execution time (e.g., "30s", "5m", "1h")
Fault Tolerance & Observability
- Automatic retry: Configurable retry count on task failure
- Lifecycle tracking: Monitor task status (running, completed, failed)
- Structured output: JSON-formatted task results and metadata
Technical Architecture#
Built with Rust (76.7%) for the core runtime, with TypeScript (15.6%) and Python (7.1%) SDK support.
Core Components
- capsule-core: Core runtime based on Rust and Wasmtime
- capsule-cli: Command-line interface (
capsule run,capsule build) - capsule-sdk: Python and TypeScript development kits
- capsule-wit: WebAssembly interface type definitions
Key Technologies
- Runtime: Wasmtime (WebAssembly runtime), WASI (system interface)
- Compilation: componentize-py (Python to Wasm), jco (JS to Wasm)
Installation & Quick Start#
Python
pip install capsule-run
Node.js
npm install -g @capsule-run/cli
npm install @capsule-run/sdk
Example (Python)
from capsule import task
@task(name="main", compute="LOW", ram="64MB")
def main() -> str:
return "Hello from Capsule!"
Integration into Existing Code
from capsule import run
result = await run(file="./hello.py", args=[])
print(f"Task completed: {result['result']}")
Configuration Options#
| Parameter | Description | Example |
|---|---|---|
| name | Task identifier | "process_data" |
| compute | CPU allocation level | "HIGH" |
| ram | Memory limit | "512MB" |
| timeout | Maximum execution time | "30s" |
| max_retries | Retry count on failure | 3 |
| allowed_files | Accessible directories | ["./data"] |
| allowed_hosts | Accessible domains | ["api.openai.com"] |
Supports capsule.toml project configuration file for default settings.
CLI Commands#
capsule run <file>: Execute task scriptcapsule build <file>: AOT pre-compile task--verbose: Show detailed logs--json: Output JSON-formatted results
Compatibility Notes#
- Python: Only supports pure Python packages and standard library modules; C extensions NOT supported (e.g., numpy, pandas)
- TypeScript/JavaScript: Supports npm packages and ES modules
Use Cases#
- AI Agent tool calling and orchestration
- Executing untrusted or user-provided code
- File data processing (CSV, images, datasets)
- API calls with restricted network access
- Resource-limited testing
Response Format#
{
"success": true,
"result": "<task return value>",
"execution": {
"task_name": "analyze_data",
"duration_ms": 1523,
"retries": 0,
"fuel_consumed": 45000
}
}
Current Version: v0.6.2 | License: Apache-2.0