capsule-run 0.3.2

Secure WASM runtime to isolate and manage AI agent tasks

capsule-run

A secure, durable runtime for agentic workflows

Overview

Capsule is a runtime for coordinating AI agent tasks in isolated environments. It is designed to handle long-running workflows, large-scale processing, autonomous decision-making securely, or even multi-agent systems.

Each task runs inside its own WebAssembly sandbox, providing:

• Isolated execution: Each task runs isolated from your host system
• Resource limits: Set CPU, memory, and timeout limits per task
• Automatic retries: Handle failures without manual intervention
• Lifecycle tracking: Monitor which tasks are running, completed, or failed

Installation

pip install capsule-run

Quick Start

Create hello.py:

from capsule import task

@task(name="main", compute="LOW", ram="64MB")
def main() -> str:
    return "Hello from Capsule!"

Run it:

capsule run hello.py

How It Works

Simply annotate your Python functions with the @task decorator:

from capsule import task

@task(name="analyze_data", compute="MEDIUM", ram="512MB", timeout="30s", max_retries=1)
def analyze_data(dataset: list) -> dict:
    """Process data in an isolated, resource-controlled environment."""
    return {"processed": len(dataset), "status": "complete"}

When you run capsule run main.py, your code is compiled into a WebAssembly module and executed in a dedicated sandbox.

Documentation

Task Configuration Options

Parameter	Description	Type	Default	Example
name	Task identifier	str	function name	"process_data"
compute	CPU level: "LOW", "MEDIUM", "HIGH"	str	"MEDIUM"	"HIGH"
ram	Memory limit	str	unlimited	"512MB", "2GB"
timeout	Maximum execution time	str	unlimited	"30s", "5m"
max_retries	Retry attempts on failure	int	0	3
allowed_files	Folders accessible in the sandbox	list	[]	["./data", "./output"]

Compute Levels

• LOW: Minimal allocation for lightweight tasks
• MEDIUM: Balanced resources for typical workloads
• HIGH: Maximum fuel for compute-intensive operations
• CUSTOM: Specify exact fuel value (e.g., compute="1000000")

HTTP Client

Standard requests library isn't compatible with WASM. Use Capsule's HTTP client:

from capsule import task
from capsule.http import get, post

@task(name="fetch", compute="MEDIUM", timeout="30s")
def main() -> dict:
    response = get("https://api.example.com/data")
    return {"status": response.status_code, "ok": response.ok()}

File Access

The entry point task (main) has access to the entire project directory. Sub-tasks have no filesystem access by default and must declare allowed_files to access specific paths.

Python's standard file operations work normally. Use open(), os, pathlib, or any file manipulation library:

from capsule import task

@task(name="restricted_writer", allowed_files=["./output"])  # Sub-task with limited access
def restricted_writer() -> None:
    with open("./output/result.txt", "w") as f:
        f.write("result")

@task(name="main")  # Has access to entire project
def main() -> str:
    restricted_writer()

Compatibility

✅ Supported:

• Pure Python packages and standard library
• json, math, re, datetime, collections, etc.

⚠️ Not yet supported:

• Packages with C extensions (e.g numpy, pandas)

Links

• GitHub
• Issues