mavdol / capsule

**A secure, durable runtime for AI agents** Getting Started • Documentation • Contributing --- Overview is a runtime for coordinating AI agent tasks in isolated environments. It is designed to handle untrusted code execution, long-running workflows, large-scale processing, 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 This enables safe task-level execution of untrusted code within AI agent systems. How It Works With Python Simply annotate your Python functions with the decorator: With TypeScript / JavaScript Use the wrapper function with full access to the npm ecosystem: > [!NOTE] > The runtime requires a task named as the entry point. Python will create one automatically if none is defined, but it's recommended to set it explicitly. When you run (or ), your code is compiled into a WebAssembly module and executed in isolated sandboxes. Each task operates within its own sandbox with configurable resource limits, ensuring that failures are contained and don't cascade to other parts of your workflow. The host system controls every aspect of execution, from CPU allocation via Wasm fuel metering to memory constraints and timeout enforcement. Getting Started Python Create : Run it: TypeScript / JavaScript Create : Run it: > [!TIP] > Add to see real-time task execution details. Run From Your Code The function lets you execute tasks programmatically from your code instead of using the CLI. The are automatically forwarded as parameters to the task. Python Create : TypeScript / JavaScript > [!IMPORTANT] > You need in your dependencies to use the runner functions in TypeScript. Create : > [!TIP] > If you're looking for a pre-configured, ready-to-use solution, check out the Python adapter or TypeScript adapter. Documentation Task Configuration Options Configure your tasks with these parameters: | Parameter | Description | Type | Default | Example | |-----------|-------------|------|---------|---------| | | Task identifier | | function name (Python) / *required* (TS) | | | | CPU allocation level: , , or | | | | | | Memory limit for the task | | unlimited | , | | | Maximum execution time | | unlimited | , , | | / | Number of retry attempts on failure | | | | | / | Folders accessible in the sandbox | | | | | / | Domains accessible in the sandbox | | | | | / | Environment variables accessible in the sandbox | | | | Compute Levels Capsule controls CPU usage through WebAssembly's **fuel mechanism**, which meters instruction execution. The compute level determines how much fuel your task receives. • **LOW** provides minimal allocation for lightweight tasks • **MEDIUM** offers balanced resources for typical workloads • **HIGH** grants maximum fuel for compute-intensive operations • **CUSTOM** to specify an exact fuel value (e.g., ) for precise control over execution limits. Response Format Every task returns a structured JSON envelope containing both the result and execution metadata: **Response fields:** • — Boolean indicating whether the task completed successfully • — The actual return value from your task (json, string, null on failure etc.) • — Error details if the task failed ( ) • — Performance metrics: • — Name of the executed task • — Execution time in milliseconds • — Number of retry attempts that occurred • — CPU resources used (see Compute Levels) HTTP Client API Python The standard Python library and socket-based networking aren't natively compatible with WebAssembly's sandboxed I/O model. Capsule provides its own HTTP client that works within the Wasm environment: TypeScript / JavaScript Standard libraries like are already compatible, so no custom HTTP client is needed for TypeScript/JavaScript. Network Access Tasks can make HTTP requests to domains specified in . By default, all outbound requests are allowed ( ). Restrict access by providing a whitelist of domains. Python TypeScript / JavaScript File Access Tasks can read and write files within directories specified in . Any attempt to access files outside these directories is not possible. > [!NOTE] > Currently, supports directory paths, not individual files. Python Python's standard file operations work normally. Use , , , or any file manipulation library. TypeScript / JavaScript Common Node.js built-ins are available. Use the standard module: Environment Variables Tasks can access environment variables to read configuration, API keys, or other runtime settings. Python Use Python's standard to access environment variables: TypeScript / JavaScript Use the standard to access environment variables: Project Configuration (Optional) You can create a file in your project root to set default options for all tasks and define workflow metadata: With an entrypoint defined, you can simply run: Task-level options always override these defaults when specified. Cache Management When you run your code, Capsule creates a folder in your project root. This is the build cache. It stores compiled artifacts so subsequent runs are fast (from seconds to few milliseconds). > [!TIP] > should be added to . The cache is specific to your own environment and will be regenerated automatically. Use to precompile ahead of time and skip the compilation cost on the first run: Production Running source code directly (like or ) evaluates and compiles your file at runtime. While great for development, this compilation step adds a few seconds of latency on first call. For use cases where sub-second latency is critical, you should build your tasks ahead of time. > [!NOTE] > Or from your existing code: > > Executing a file bypasses the compiler completely, reducing initialization…