Capsule

Getting Started • Documentation • Issues • Contributing

---

Overview

Capsule is a runtime for executing untrusted code in isolated environments. 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

How It Works

With Python

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."""
    # Your code runs safely in a Wasm sandbox
    return {"processed": len(dataset), "status": "complete"}

With TypeScript / JavaScript

Use the task() wrapper function with full access to the npm ecosystem:

import { task } from "@capsule-run/sdk";

export const analyzeData = task({
  name: "analyze_data",
  compute: "MEDIUM",
  ram: "512MB",
  timeout: "30s",
  maxRetries: 1
}, (dataset: number[]): object => {
  // Your code runs safely in a Wasm sandbox
  return { processed: dataset.length, status: "complete" };
});

[!NOTE] The runtime requires a task named "main" as the entry point. Python will create one automatically if none is defined, but it's recommended to set it explicitly.

When you run capsule run main.py (or main.ts), 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

pip install capsule-run

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

TypeScript / JavaScript

npm install -g @capsule-run/cli
npm install @capsule-run/sdk

Create hello.ts:

import { task } from "@capsule-run/sdk";

export const main = task({
  name: "main",
  compute: "LOW",
  ram: "64MB"
}, (): string => {
  return "Hello from Capsule!";
});

Run it:

capsule run hello.ts

[!TIP] Add --verbose to see real-time task execution details.

Run From Your Code

The run() function lets you execute tasks programmatically from your code instead of using the CLI. The args are automatically forwarded as parameters to the main task.

Python

from capsule import run

result = await run(
    file="./sandbox.py",
    args=["code to execute"]
)

Create sandbox.py:

from capsule import task

@task(name="main", compute="LOW", ram="64MB")
def main(code: str) -> str:
    return eval(code)

TypeScript / JavaScript

[!IMPORTANT] You need @capsule-run/cli in your dependencies to use the runner functions in TypeScript.

import { run } from '@capsule-run/sdk/runner';

const result = await run({
  file: './sandbox.ts',
  args: ['code to execute']
});

Create sandbox.ts:

import { task } from "@capsule-run/sdk";

export const main = task({
  name: "main",
  compute: "LOW",
  ram: "64MB"
}, (code: string): string => {
  return eval(code);
});

[!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
name	Task identifier	str	function name (Python) / required (TS)	"process_data"
compute	CPU allocation level: "LOW", "MEDIUM", or "HIGH"	str	"MEDIUM"	"HIGH"
ram	Memory limit for the task	str	unlimited	"512MB", "2GB"
timeout	Maximum execution time	str	unlimited	"30s", "5m", "1h"
max_retries / maxRetries	Number of retry attempts on failure	int	0	3
allowed_files / allowedFiles	Folders accessible in the sandbox (with optional access mode)	list	[]	["./data"], [{"path": "./data", "mode": "ro"}]
allowed_hosts / allowedHosts	Domains accessible in the sandbox	list	[]	["api.openai.com", "*.anthropic.com"]
env_variables / envVariables	Environment variables accessible in the sandbox	list	[]	["API_KEY"]

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., compute="1000000") for precise control over execution limits.

Response Format

Every task returns a structured JSON envelope containing both the result and execution metadata:

{
  "success": true,
  "result": "Hello from Capsule!",
  "error": null,
  "execution": {
    "task_name": "data_processor",
    "duration_ms": 1523,
    "retries": 0,
    "fuel_consumed": 45000,
    "ram_used": 1200000,
    "host_requests": [{...}]
  }
}

Response fields: - success — Boolean indicating whether the task completed successfully - result — The actual return value from your task (json, string, null on failure etc.) - error — Error details if the task failed ({ error_type: string, message: string }) - execution — Performance metrics: - task_name — Name of the executed task - duration_ms — Execution time in milliseconds - retries — Number of retry attempts that occurred - fuel_consumed — CPU resources used (see Compute Levels) - ram_used — Peak memory used in bytes - host_requests — List of host requests made by the task

Network Access

Tasks can make HTTP requests to domains specified in allowed_hosts. By default, no outbound requests are allowed ([]). Provide an allowlist of domains to grant access, or use ["*"] to allow all domains.

Python

import json
from capsule import task
from urllib.request import urlopen

@task(name="main", allowed_hosts=["api.openai.com", "*.anthropic.com"])
def main() -> dict:
    with urlopen("https://api.openai.com/v1/models") as response:
        return json.loads(response.read().decode("utf-8"))

TypeScript / JavaScript

import { task } from "@capsule-run/sdk";

export const main = task({
    name: "main",
    allowedHosts: ["api.openai.com", "*.anthropic.com"]
}, async () => {
    const response = await fetch("https://api.openai.com/v1/models");
    return response.json();
});

File Access

Tasks can read and write files within directories specified in allowed_files. Any attempt to access files outside these directories is not possible.

[!NOTE] allowed_files supports directory paths only, not individual files.

Each entry can be a plain path (read-write by default) or a structured object with an explicit mode: - "read-only" (or "ro") - "read-write" (or "rw")

Python

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

from capsule import task

@task(name="main", allowed_files=[
    {"path": "./data", "mode": "read-only"},
    {"path": "./output", "mode": "read-write"},
])
def main() -> str:
    with open("./data/input.txt") as f:
        content = f.read()
    with open("./output/result.txt", "w") as f:
        f.write(content)
    return content

Plain strings are still accepted: allowed_files=["./output"] defaults to read-write.

TypeScript / JavaScript

Common Node.js built-ins are available. Use the standard fs module:

import { task } from "@capsule-run/sdk";
import fs from "fs/promises";

export const main = task({
    name: "main",
    allowedFiles: [
        { path: "./data", mode: "read-only" },
        { path: "./output", mode: "read-write" },
    ]
}, async () => {
    const content = await fs.readFile("./data/input.txt", "utf8");
    await fs.writeFile("./output/result.txt", content);
    return content;
});

Plain strings are still accepted: allowedFiles: ["./output"] defaults to read-write.

Dynamic directory aliases (--mount)

The --mount flag (CLI) or mounts parameter (SDK) mount a host directory into the sandbox under an alias. Mounts propagate to sub-tasks and add access to new paths, they don't change the access mode of paths already declared in allowed_files.

Format: HOST_PATH[::GUEST_PATH][:ro|:rw]

Part	Required	Description
HOST_PATH	yes	Path on the host machine (relative to cwd, must stay inside project root)
::GUEST_PATH	no	Path the task sees inside the sandbox. Defaults to HOST_PATH
:ro / :rw	no	Access mode. Defaults to read-write

CLI

# Mount a session workspace and expose it as "workspace" inside the task
capsule run main.py --mount sessions/abc123_workspace::workspace

# Multiple directories
capsule run main.py \
  --mount sessions/abc123_workspace::workspace \
  --mount sessions/bce456_workspace::workspace:ro

Python SDK

from capsule import run

result = await run(
    file="main.py",
    mounts=[".capsule/sessions/abc123_workspace::workspace"],
)

TypeScript / JavaScript SDK

import { run } from "@capsule-run/sdk";

const result = await run({
    file: "main.py",
    mounts: [".capsule/sessions/abc123_workspace::workspace"],
});

Inside the task, the directory is accessed via the guest path:

# task sees it at "workspace/", not at the full session path
with open("workspace/output.txt", "w") as f:
    f.write("done")

[!NOTE] --mount paths must be relative and must not escape the project root. Absolute paths are rejected.

Environment Variables

Tasks can access environment variables to read configuration, API keys, or other runtime settings.

Python

Use Python's standard os.environ to access environment variables:

from capsule import task
import os

@task(name="main", env_variables=["API_KEY"])
def main() -> dict:
    api_key = os.environ.get("API_KEY")
    return {"api_key": api_key}

TypeScript / JavaScript

Use the standard process.env to access environment variables:

import { task } from "@capsule-run/sdk";

export const main = task({
    name: "main",
    envVariables: ["API_KEY"]
}, () => {
    const apiKey = process.env.API_KEY;
    return { apiKeySet: apiKey !== undefined };
});

Project Configuration (Optional)

You can create a capsule.toml file in your project root to set default options for all tasks and define workflow metadata:

# capsule.toml

[workflow]
name = "My Workflow"
version = "1.0.0"
entrypoint = "src/main.py"  # Default file when running `capsule run`

[tasks]
default_compute = "MEDIUM"
default_ram = "256MB"
default_timeout = "30s"
default_max_retries = 2

With an entrypoint defined, you can simply run:

capsule run

Task-level options always override these defaults when specified.

Cache Management

When you run your code, Capsule creates a .capsule 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] .capsule should be added to .gitignore. The cache is specific to your own environment and will be regenerated automatically.

.capsule/
├── wasm/
│   ├── main_a1b2c3d4.wasm    # Compiled WebAssembly module
│   └── main_a1b2c3d4.cwasm   # Native precompiled cache
├── wit/                       # Interface definitions
└── trace.db                   # Execution logs

Use capsule build to precompile ahead of time and skip the compilation cost on the first run:

capsule build main.ts # or `main.py`

Production

Running source code directly (like .py or .ts) 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.

# Generates an optimized hello.wasm file
capsule build hello.py --export

# Execute the compiled artifact directly
capsule exec hello.wasm

[!NOTE] Or from your existing code:

```python from capsule import run

result = await run( file="./hello.wasm", # or hello.py args=[] )

print(f"Task completed