Capsule

capsule · capsulerun/capsule · ★ 285 · last commit 2026-05-15

Primitive shape

No installable primitives

Summary

Capsule — Summary

Capsule is a WebAssembly-based runtime for executing untrusted code in isolated, resource-controlled environments — written in Rust and using wasmtime (version 29.0) as the underlying WASM engine. Functions are decorated with a @task annotation (Python) or wrapped with task() (TypeScript/JS), then compiled to WASM modules at runtime and executed inside individual sandboxes with configurable CPU (Wasm fuel metering), memory (RAM limit), timeout, and network access (allowlist). The capsule CLI compiles and runs Python or TypeScript files as WASM tasks; the Python and npm SDKs expose run() for programmatic execution. The TypeScript adapter enables calling sandboxed Python/JS code from TypeScript applications, with cold start ~1 second and ~10ms after preload. Capsule's key differentiator is WASM as the isolation primitive — not containers, not VMs — giving it cross-platform portability (runs anywhere wasmtime runs) without requiring Linux/KVM/Docker.

Differs from seeds: No seed in the catalog uses WASM for isolation. All 11 seeds are text-only agent frameworks operating at the LLM instruction layer. Capsule is the execution environment for individual function calls, not for agent sessions — the granularity is a function, not a project. The @task decorator pattern is structurally closest to serverless function annotations (AWS Lambda, Modal), not to any seed pattern. Among batch entries, Capsule is the only one with WASM-native isolation; it is the most portable (no Linux/KVM requirement) but also the most limited in what it can run (WASM-compatible code only).

Overview

Capsule — Overview

Origin

Capsule (capsulerun/capsule) is a Rust project targeting the problem of executing untrusted or LLM-generated code safely. The project is Apache-2.0 licensed, actively maintained (v0.8.10 as of analysis), and positioned specifically for AI/LLM use cases (README keywords: webassembly, sandbox, isolation, llm, ai; crates.io categories: wasm, command-line-utilities).

Philosophy

The README is terse and technical, favoring code examples over philosophy. The key design choices:

"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"

The underlying philosophy is function-level isolation: rather than isolating an entire agent session or VM, Capsule isolates individual function invocations. This is coarser than process-level but finer than session-level.

WASM fuel metering

Capsule uses WebAssembly's built-in fuel metering mechanism to control CPU usage:

"Capsule controls CPU usage through WebAssembly's fuel mechanism, which meters instruction execution. The compute level determines how much fuel your task receives."

LOW: minimal allocation for lightweight tasks
MEDIUM: balanced for typical workloads
HIGH: maximum fuel for compute-intensive operations
CUSTOM: exact fuel value (e.g., compute="1000000")

This is a unique CPU control mechanism — not cgroups, not Kubernetes resource limits, but WASM instruction counting.

Target use case

The TypeScript adapter README makes the use case concrete:

"Execute Python and JavaScript code securely inside Capsule sandboxes from your TypeScript/JavaScript applications."

This is primarily an AI code interpreter use case: the calling agent or application runs outside Capsule; the LLM-generated or untrusted code runs inside a Capsule WASM sandbox.

Architecture

Capsule — Architecture

Sandbox primitive

WebAssembly (WASM) module via wasmtime (v29.0):

Each task is compiled to a WASM module at runtime
Executed inside a wasmtime component-model sandbox
Resource limits enforced by WASM engine:
- CPU: fuel metering (instruction counting)
- Memory: RAM limit per task (e.g., "512MB")
- Time: timeout per task (e.g., "30s")
- Network: domain allowlist per task
- Files: folder access list per task

No Linux-specific features required. Works on any platform where wasmtime runs.

Startup time claims

TypeScript adapter README:

Cold start: ~1 second
After preload (loadSandboxes() called in advance): ~10ms

This is faster than container cold starts but slower than microVM snapshot cloning (CubeSandbox <60ms) in absolute terms. The 10ms warm start is competitive.

Distribution

Python: pip install capsule-run
TypeScript/npm: npm install -g @capsule-run/cli + npm install @capsule-run/sdk
TypeScript adapter: npm install @capsule-run/adapter

Directory tree (repo)

capsule/
├── crates/
│   ├── capsule-cli/      # `capsule` binary (Rust, uses wasmtime)
│   │   └── src/main.rs
│   ├── capsule-core/     # Core library (wasmtime integration, task management)
│   │   ├── src/config.rs
│   │   └── src/wasm.rs (not found — likely different path)
│   ├── capsule-sdk/      # SDK crate
│   └── capsule-wit/      # WIT interface definitions (WASM component model)
├── integrations/
│   ├── python-adapter/   # Python adapter for calling sandboxed code from Python apps
│   └── typescript-adapter/ # TypeScript adapter for calling sandboxed code from TS/JS apps
├── examples/
└── assets/

Core Rust dependencies

From capsule-core/Cargo.toml:

wasmtime = { version = "29.0.0", features = ["component-model", "async"] }
wasmtime-wasi = "29.0.0"
wasmtime-wasi-http = "29.0.0"
rusqlite = { version = "0.37.0", features = ["bundled"] }

SQLite is bundled for task lifecycle tracking.

Required runtime

Rust (for building from source)
Python 3.x (for Python tasks + Python SDK)
Node.js (for TypeScript/JS tasks + npm packages)
No Linux/KVM/Docker required — WASM runs on any OS

Host-OS posture

Strong isolation from host OS: WASM modules run inside wasmtime's sandbox and have no access to the host filesystem, network, or OS APIs except what is explicitly allowed via the task configuration:

allowed_files: specific folders accessible (with optional read/write mode)
allowed_hosts: domain allowlist for network access
env_variables: explicit list of environment variables accessible

Config files

Per-task: task decorator parameters (inline in code)
No persistent config file (stateless per invocation)

Components

Capsule — Components

Rust crates

Crate	Binary	Purpose
`capsule-run` (crates/capsule-cli)	`capsule`	CLI: compile and run Python/TypeScript as WASM tasks
`capsule-core` (library)	—	wasmtime integration, task lifecycle management, SQLite state
`capsule-sdk`	—	SDK abstraction
`capsule-wit`	—	WIT interface definitions (WASM component model interfaces)

CLI (`capsule`)

capsule run hello.py          # Compile and run Python file as WASM task
capsule run hello.ts          # Compile and run TypeScript file as WASM task
capsule run hello.py --verbose # Show real-time task execution details

Python SDK (`pip install capsule-run`)

from capsule import task

@task(name="main", compute="MEDIUM", ram="512MB", timeout="30s", max_retries=1)
def main() -> str:
    return "Hello from Capsule!"

Task configuration parameters:

name: task identifier (required in TS, defaults to function name in Python)
compute: "LOW" / "MEDIUM" / "HIGH" / "CUSTOM:<fuel_count>"
ram: memory limit (e.g., "512MB", "2GB")
timeout: max execution time (e.g., "30s", "5m", "1h")
max_retries / maxRetries: retry count on failure
allowed_files / allowedFiles: accessible folders (with optional "ro" mode)
allowed_hosts / allowedHosts: domain allowlist (e.g., ["api.openai.com", "*.anthropic.com"])
env_variables / envVariables: accessible env vars

Programmatic runner (`run()`)

from capsule import run

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

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

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

Response format

Every task returns a structured JSON envelope:

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

TypeScript adapter (`@capsule-run/adapter`)

import { runPython, runJavaScript, loadSandboxes } from '@capsule-run/adapter';

await loadSandboxes();  // Preload for ~10ms subsequent execution
const result = await runPython('print("Hello!")');

Supports Session for persistent state across multiple calls.

Session (TypeScript adapter)

await using s = new Session("python");
await s.run("x = 1");
const result = await s.run("x += 1; x");  // Returns 2 — state preserved

Each session gets an isolated workspace directory automatically cleaned up on exit.

Prompts

Capsule — Prompts

Capsule is a WASM sandbox runtime with no LLM prompt files. Its "instructions" are task configuration parameters (compute, ram, timeout, allowed_hosts) rather than natural language.

Excerpt 1: README — @task decorator design (verbatim)

### With Python

Simply annotate your Python functions with the `@task` decorator:

```python
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"}


**Prompting technique**: Not a prompt — this is a function annotation API. The `@task` decorator is the closest thing Capsule has to a "configuration language." The key design insight is that all sandbox parameters are specified at the Python function level, not in a separate config file. This collocates security policy with the code it governs.

## Excerpt 2: README — structured response format (verbatim)

```markdown
Every task returns a structured JSON envelope containing both the result and execution metadata:
```json
{
  "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": [...]
  }
}


**Prompting technique**: Not a prompt — this is an API response schema. The `fuel_consumed` field is notable: it makes the WASM fuel metering mechanism observable to callers, enabling tuning of `compute` levels based on actual usage.

## Note

Capsule contains no CLAUDE.md, no skill files, and no LLM-facing instructions. This is expected for a WASM execution runtime. The project's README is code-first with minimal prose explanation.

Uniqueness

Capsule — Uniqueness & Positioning

Differs from seeds

Capsule has no counterpart among the 11 seeds — all seeds are LLM agent-loop frameworks operating at the instruction layer. Capsule is a WASM execution runtime. Within this batch, it is categorically unique: every other batch entry (AgentTier, CUA, sandboxed.sh, OpenSandbox, CubeSandbox, SWE-ReX) uses containers, VMs, or processes as the isolation primitive. Capsule uses WebAssembly. This gives it cross-platform portability (no Linux/KVM required) at the cost of scope (only WASM-compatible code can run). The @task decorator pattern and function-level granularity have no parallel in seeds or other batch entries — other platforms isolate agent sessions; Capsule isolates function invocations. The fuel_consumed observability metric (WASM instruction count) is unique in the batch.

Positioning

Capsule targets developers and AI application builders who want to safely execute LLM-generated or untrusted code in a Python or TypeScript application, without requiring Docker, Linux, or KVM. It is positioned as the "safe code interpreter" layer for AI applications — the component that runs when a user asks an LLM to "execute this code."

The TypeScript adapter is the most polished integration path: await loadSandboxes() + await runPython(code) is the simplest possible API for executing untrusted Python from a TypeScript application.

Key architectural bets

WASM as isolation — wasmtime's component-model provides memory safety and resource limits without OS-level isolation overhead
Function-level granularity — @task isolates individual functions, not entire sessions, which maps naturally to code-interpreter use cases ("execute this snippet")
Fuel metering for CPU control — using WASM's intrinsic instruction counting as a CPU control mechanism, rather than OS cgroups
Cross-platform by design — no Linux/KVM requirement makes it the only batch entry deployable on Windows or macOS without emulation

Observable failure modes

WASM compatibility constraint — not all Python packages work in WASM (packages with native extensions, C libraries, OS-level calls may fail or be unavailable)
No shared filesystem between tasks — tasks run in isolated WASM sandboxes with no shared global state; patterns requiring a shared file system need Session or explicit allowed_files configuration
Cold start ~1 second — first execution compiles Python/TypeScript to WASM, which takes ~1 second; preloading (loadSandboxes()) reduces subsequent calls to ~10ms but requires upfront latency
WASM interpreter overhead — interpreted execution (WASM) is slower than native code; compute-intensive tasks may need compute="HIGH" or CUSTOM:<large_fuel_value> to avoid fuel exhaustion
Limited to Python + TypeScript — only Python and TypeScript tasks are supported via the provided SDKs; arbitrary language support is not documented

Cross-references

No explicit competitor or partner named in README
wasmtime (Bytecode Alliance) as the underlying engine
Competitor positioning: E2B (Docker-based code interpreter), Modal (serverless containers), OpenSandbox (container sandbox)

Workflow

Capsule — Workflow

CLI workflow

pip install capsule-run
capsule run hello.py

Phase-to-artifact map:

Phase	Artifact
`capsule run hello.py`	Python compiled to WASM module
WASM module loaded	wasmtime sandbox initialized
Task execution	Structured JSON result
Task completion	Sandbox destroyed, resources released

Python SDK workflow

from capsule import task, run

@task(name="main", compute="MEDIUM", ram="512MB")
def main(code: str) -> str:
    return eval(code)  # Runs safely in WASM sandbox

# Programmatic invocation
result = await run(file="./sandbox.py", args=["1 + 1"])

TypeScript application integration (adapter)

import { loadSandboxes, runPython } from '@capsule-run/adapter';

await loadSandboxes();  // Preload: ~10ms subsequent cold starts
const result = await runPython('print("Hello!")');

Session workflow (persistent state)

await using s = new Session("python");
await s.run("x = 1");
await s.run("x += 1");
const result = await s.run("x");  // 2 — state persists within session
// Session cleanup happens automatically on scope exit

Retry workflow

@task(name="flaky_task", max_retries=3)
def flaky() -> str:
    import random
    if random.random() < 0.5:
        raise ValueError("Random failure")
    return "success"

On failure: Capsule retries up to max_retries times, tracking attempts in the response envelope.

Multi-task pipeline

@task(name="step1", compute="LOW")
def step1(x: int) -> int:
    return x * 2

@task(name="main", compute="MEDIUM")
def main() -> int:
    # Each sub-call runs in its own WASM sandbox
    r1 = step1(5)  # Returns 10 in isolated sandbox
    return r1 + 1

Approval gates

None — Capsule is a library/runtime, no human approval gates.

Memory Context

Capsule — Memory & Context

Task-level isolation (no cross-task memory)

Each Capsule task runs in its own WASM sandbox. By default, there is no shared memory between tasks — each invocation starts fresh.

SQLite task state (internal)

The capsule-core crate bundles SQLite (rusqlite) for task lifecycle tracking:

Task name, status (running/completed/failed), attempt count
Duration, fuel consumed, RAM used
This is internal metadata, not accessible to the user's task code

Session memory (TypeScript adapter)

The TypeScript adapter's Session type provides explicit cross-call state:

await using s = new Session("python");
await s.run("x = 1");
const result = await s.run("x += 1; x");  // Returns 2

Each session gets an isolated workspace directory that persists for the session's lifetime and is automatically cleaned up on scope exit. This is the only form of cross-invocation memory in Capsule.

Workspace directory (Session)

Within a session, the isolated workspace directory provides filesystem persistence:

Files written in one s.run() call are visible in subsequent calls
Workspace is cleaned up when session ends (TypeScript await using pattern)

LLM context management

None — Capsule is a code execution runtime. The calling application (which may be an LLM-based agent) manages its own context. Capsule returns structured JSON results that the agent can include in its context.

Memory type classification

Primary: sqlite (internal task lifecycle tracking)
Session: file-based (workspace directory for TypeScript adapter sessions)
No vector DB, no graph DB, no LLM-level context management

Orchestration

Capsule — Orchestration

Multi-agent support

Not a multi-agent platform. Capsule is a function-level execution sandbox. Multiple tasks can run concurrently (via async/await), but there is no built-in agent coordination.

Orchestration pattern

None from Capsule's perspective. The calling application orchestrates task calls. Each task is an isolated WASM execution.

Isolation mechanism

WebAssembly (WASM) via wasmtime component-model:

No Linux/KVM required
Cross-platform (any OS where wasmtime runs)
Resource limits enforced by WASM engine itself (fuel metering for CPU, memory limits for RAM)
Network access: domain allowlist per task
File access: explicit folder allowlist per task

This is the only WASM-based isolation in the batch (all others use containers or VMs).

Execution mode

One-shot per task invocation (compile to WASM → execute → return result → sandbox destroyed). Session mode enables short-lived cross-call state.

Multi-model routing

Not applicable — Capsule is not model-aware.

Cross-tool portability

High — available as Python CLI, npm package, Python SDK, TypeScript SDK, TypeScript adapter. Works on any OS. No container runtime required.

Crash recovery

Yes — built-in retry mechanism via max_retries task parameter. Capsule retries failed tasks up to the specified count. The response envelope includes retries: N showing how many attempts occurred.

Streaming output

No — task execution is synchronous; the full JSON result is returned when the task completes (or fails after max_retries).

Consensus mechanism

None.

Parallel execution

Caller can invoke multiple tasks concurrently via standard async patterns. Capsule does not limit parallelism but each task runs in its own WASM sandbox.

Ui Cli Surface

Capsule — UI & CLI Surface

Dedicated CLI binary

Yes — binary name: capsule

Install: pip install capsule-run (includes CLI) or npm install -g @capsule-run/cli
Not a thin wrapper — it is the WASM compilation and execution runtime
Subcommands: capsule run <file> (primary), --verbose flag
Subcommand count: 1 known (run)

capsule run hello.py
capsule run hello.ts
capsule run hello.py --verbose

Local web dashboard

None — Capsule is a CLI and library. No web UI.

IDE integration

None — no IDE extension or plugin.

Observability

Built into the response envelope:

{
  "execution": {
    "duration_ms": 1523,
    "retries": 0,
    "fuel_consumed": 45000,
    "ram_used": 1200000,
    "host_requests": [...]
  }
}

Every task execution returns resource usage metrics:

duration_ms: wall-clock execution time
fuel_consumed: WASM instruction count (CPU proxy)
ram_used: peak memory in bytes
host_requests: network requests made (domains hit)

The --verbose flag shows real-time task execution details.

Language support

Language	SDK	CLI
Python	`pip install capsule-run`	Yes
TypeScript/JS	`npm install @capsule-run/sdk`	Yes (`@capsule-run/cli`)

npm ecosystem access

TypeScript tasks have full access to the npm ecosystem (from README):

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

Related frameworks

same archetype · same primary tool · same memory type

Daytona ★ 72k

A9 Sandbox substrate

Provide secure, elastic, sub-90ms sandbox compute infrastructure for running AI-generated code, accessible via multi-language…

CUA ★ 17k

A9 Sandbox substrate

Unified SDK for building, benchmarking, and deploying agents that interact with full OS GUIs via isolated VMs.

E2B ★ 12k

A9 Sandbox substrate

Run AI-generated code safely in cloud-hosted isolated sandboxes via a 3-line SDK integration.

OpenSandbox ★ 11k

A9 Sandbox substrate

Protocol-first general-purpose sandbox platform for AI applications with multi-language SDKs and pluggable isolation backends.

Microsandbox ★ 6.3k

A9 Sandbox substrate

Spawn hardware-isolated microVMs as child processes directly from application code, with no server setup, in under 100ms.

CubeSandbox ★ 5.9k

A9 Sandbox substrate

Sub-60ms KVM microVM sandboxes for AI agents with E2B drop-in compatibility and <5MB memory overhead.

Distribution

Type: standalone-repo
License: Apache-2.0
Install: one-liner
Version: 0.8.10

Surfaces

CLI binary: capsule
CLI subcmds: 1
Local UI: No

Components

Commands: 0
Skills: 0
Subagents: 0
Hooks: 0
MCP servers: 0
MCP tools: 0
Scripts: 0
Templates: 2

Workflow

Phases: 5
Approval gates: 0
Spec format: none
Spec storage: none
Delta or full: none

Orchestration

Multi-agent: No
Pattern: none
Isolation: sandbox-api
Consensus: none
Prompt chaining: No

Multi-model

Multi-model: No
BYOK: Yes
Modal: text

Execution

Mode: one-shot
Crash recovery: Yes
Compaction: No
Session handoff: No
Streaming: No

Memory

Type: sqlite
Persistence: session
Search: none
State files: 2 files

Quality

TDD: No
TDD mechanism: none
Self-review: none

Git / Observability

Auto commit: No
Auto PR: No
Auto merge: No
Worktree/feat: No
Audit log: Yes
Audit format: jsonl
Replay: No

Tools

Primary: none
Targets: 3
Portability: high

Signals

Stars: 285
Last commit: 2026-05-15
Contributors: 1
Maintainer: active
Quality score: 3/10

Summary

Capsule — Summary

Overview

Capsule — Overview

Origin

Philosophy

WASM fuel metering

Target use case

Architecture

Capsule — Architecture

Sandbox primitive

Startup time claims

Distribution

Directory tree (repo)

Core Rust dependencies

Required runtime

Host-OS posture

Config files

Components

Capsule — Components

Rust crates

CLI (capsule)

Python SDK (pip install capsule-run)

Programmatic runner (run())

Response format

TypeScript adapter (@capsule-run/adapter)

Session (TypeScript adapter)

Prompts

Capsule — Prompts

Excerpt 1: README — @task decorator design (verbatim)

Uniqueness

Capsule — Uniqueness & Positioning

Differs from seeds

Positioning

Key architectural bets

Observable failure modes

Cross-references

Workflow

Capsule — Workflow

CLI workflow

Python SDK workflow

TypeScript application integration (adapter)

Session workflow (persistent state)

Retry workflow

Multi-task pipeline

Approval gates

Memory Context

Capsule — Memory & Context

Task-level isolation (no cross-task memory)

SQLite task state (internal)

Session memory (TypeScript adapter)

Workspace directory (Session)

LLM context management

Memory type classification

Orchestration

Capsule — Orchestration

Multi-agent support

Orchestration pattern

Isolation mechanism

Execution mode

Multi-model routing

Cross-tool portability

Crash recovery

Streaming output

Consensus mechanism

Parallel execution

Ui Cli Surface

Capsule — UI & CLI Surface

Dedicated CLI binary

Local web dashboard

IDE integration

Observability

Language support

npm ecosystem access

Related frameworks

CLI (`capsule`)

Python SDK (`pip install capsule-run`)

Programmatic runner (`run()`)

TypeScript adapter (`@capsule-run/adapter`)