Capsule Sandbox Runtime
Run untrusted Python and TypeScript/JavaScript code in isolated WebAssembly sandboxes.
- Source repo
- capsulerun/runtime
- Stars
- ★ 301
- Last updated
- 24d ago
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 52/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Platform teams executing user-submitted code can use per-task resource limits in WebAssembly-isolated environments.
- Not a fit if
- Teams that need Python C-extension packages without wasm32-wasi wheels inside the sandbox
- Source review
- 52/100 · Major gaps 2 safety controls not found
What does this agent do, and when should you use it?
Capsule is a runtime for executing untrusted code, with a Rust CLI, a Python SDK, and a TypeScript/JavaScript SDK. Developers define tasks with Python’s @task decorator or the TypeScript/JavaScript task() wrapper, then start workflows with capsule run or the SDK’s run() function. The runtime compiles code into WebAssembly modules and runs each task in its own sandbox, with configurable CPU fuel, memory, timeouts, retries, file access, network domains, and environment variables. Each execution returns a structured JSON result with task output, errors, and execution metrics. It is documented for local projects and host-code integration; the README does not describe a hosted service or cloud deployment.
Run capsule run main.py or capsule run main.ts to read an entry file, compile it to WebAssembly, and execute the task named main in an isolated sandbox. Tasks can receive arguments, access explicitly allowed directories and environment variables, and make HTTP requests to domains listed in allowed_hosts; outbound requests are disabled by default. Configure execution resources and retry behavior with compute, ram, timeout, and max_retries. Use capsule build to precompile tasks and capsule exec to execute exported .wasm files; CLI --mount or SDK mounts can expose project directories under sandbox paths. The execution result includes the task return value, error status, duration, retries, fuel consumed, memory used, and host request records.
- Platform teams executing user-submitted code can use per-task resource limits in WebAssembly-isolated environments.
- Python developers building data-processing tasks can define them with
@taskand run them through the CLI. - TypeScript/JavaScript teams can use the npm SDK to integrate sandbox tasks into existing Node.js programs.
- Workflow developers that need tasks to read input directories and write output directories can configure separate read-only and read-write access.
- Applications that need to restrict task network access can allowlist domains with
allowed_hostsand inspect host request records.
How do you install or deploy this agent?
The Python quickstart installs the Python package and uses the Capsule CLI. The TypeScript/JavaScript quickstart installs the global CLI and SDK. The README does not specify API credentials or paid services.
How do you use this agent?
Python install and first run:
pip install capsule-runfrom capsule import task
@task(name="main", compute="LOW", ram="64MB")
def main() -> str:
return "Hello from Capsule!"capsule run hello.pyTypeScript/JavaScript install and first run:
npm install -g @capsule-run/cli
npm install @capsule-run/sdkimport { task } from "@capsule-run/sdk";
export const main = task({
name: "main",
compute: "LOW",
ram: "64MB"
}, (): string => {
return "Hello from Capsule!";
});capsule run hello.tsTo launch a task from host code, import run in Python or import run from @capsule-run/sdk/runner in TypeScript/JavaScript; the TypeScript/JavaScript runner also requires @capsule-run/cli in the project dependencies.
What are this agent's strengths and limitations?
- Each task runs in its own WebAssembly sandbox, with per-task CPU fuel, memory, and timeout controls.
- Offers Python decorators, a TypeScript/JavaScript wrapper, a CLI, and a programmatic SDK
run()interface. - Lets developers control directory access modes, allowed network domains, and task-visible environment variables.
- Returns execution metrics including duration, retries, fuel, memory, and host requests.
- Python packages using C extensions need
wasm32-wasiwheels; the README says many common packages, including numpy and pandas, do not yet ship them. - Python and TypeScript/JavaScript have different dependency installation paths; the TypeScript/JavaScript runner also requires the CLI as a dependency.
- Python tasks must be buildable for WebAssembly, which can require replacing packages that depend on native extensions or moving that code to the host.
- The README provides no hosted service, pricing, or enterprise support details.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Capsule Sandbox Runtime This agent | 52 · Major gaps | CLIFree | ★ 301 | 24d ago | Rust | — |
| Daytona: Secure Elastic Infrastructure for AI Code | 44 · Major gaps | Library / SDKFreemium | ★ 71k | 3mo ago | — | — |
| E2B Cookbook: AI Agent Code Interpreter Examples | 36 · Major gaps | CLIFree + model costs | ★ 1.4k | 12d ago | TypeScript | OpenAI API · Claude API |
| CaveAgent | 62 · Some gaps | Library / SDKFree + model costs | ★ 205 | 1mo ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The README describes CPU, memory, and timeout limits, denies network access by default, and configures access by directory, domain, and environment variable. It also describes host_requests metadata, which provides some basis for assessing data flows and least privilege. Deductions: file directories are read-write by default, and memory and timeout default to unlimited; no pre-execution confirmation or rollback mechanism is described. API_KEY can be passed into a task, but dedicated secret-protection guidance is absent. Dependencies are named without a security audit or version pinning. The license and credits provide attribution clues, but publisher identity is unverified and maintenance responsibility is unclear.
The README describes task entry points, resource configuration, retries, and structured results. The CI files specify formatting checks, clippy, and Rust test workflows. Deductions: README links and the workflow badge use capsule while the object repository is capsulerun/runtime, and the documented run paths cannot be cross-checked against implementation files here. Dependency retrieval relies on external services and toolchains such as PyPI, npm, and Rust without a fallback path. The error field is described only as a type and message, with no concrete failure examples or recovery guidance.
The README addresses Python and TypeScript/JavaScript users and covers CLI, SDK, network, file, environment-variable, and production-build scenarios. It also describes compatibility limits for Python native extensions and WASI wheels. Deductions: scenarios and capability boundaries are asserted primarily in the README and lack additional implementation evidence; the documented triggers cover capsule run, run(), and the main entry point but not more complex integration environments.
The README is organized around setup, configuration, network, files, production, and compatibility, with installation steps and extensive examples. The LICENSE file includes the Apache-2.0 text. Deductions: capsule, capsule-run, and @capsule-run naming coexist, and repository links do not match the object name; no changelog is provided; contribution instructions and CI indicate a contribution path and automated checks but do not establish a clear long-term maintainer or update commitment.
Resource isolation, task lifecycle tracking, retries, and structured execution metadata address the stated use case of running untrusted code. The README includes practical setup and access-control examples. Deductions: these benefits and performance claims are primarily documentation assertions and are not confirmed by implementation materials in this review; runtime, compilation, and maintenance costs are not quantified, and the cost implications of unlimited default resources are not explained.
The README makes specific claims about configuration, response fields, access rules, and compatibility; the license and CI files provide separate evidence for licensing and workflow claims. Deductions: the supplied materials omit implementation code, dependency manifests, and change history, so core security and runtime claims cannot be independently cross-checked; the README does not systematically distinguish verified behavior from product description. This supports only a low-confidence static assessment.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- The examples pass environment variables such as API_KEY into tasks. Expose only the variables required and review the task's network access.
- File access defaults to read-write, while resource limits default to unlimited. Set the necessary directory permissions, memory, and timeout limits before running untrusted tasks.
- Implementation code and dependency manifests were not supplied, and repository naming differs from README links; core isolation and dependency-security claims remain uncorroborated.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Improvements TypeScript SDK Polyfills - Add more built-in methods to fs - Add a real Wasi‑based stats system for files and folders - Add support for symlinks inside sandboxesView on GitHub ↗ -
Release notes excerpt
Improvements Rust Core - Fix cache issues for multi-language projects - Improve task reporter to have better logs Typescript SDK - Fix worker process issue for run() command - Fix absolute path issue for fs polyfills Python SDK - Fix worker process issue for run() commandView on GitHub ↗ -
Release notes excerpt
Smaller Python bundle, worker mode, and path fixes Improvements Core - Worker mode: Added a capsule worker to reduce child process overhead when using the run() function. - Trace rebuild fix: Fixed trace rebuild for projects using both Python and TypeScript sandboxes. SDKs - Smaller Python bundle: Only import the necessary built-ins, reducing the overall size. - TypeScript path fixes: Resolved absolute path issues with fs polyfills.View on GitHub ↗
FAQ
Can tasks access the internet by default?
allowed_hosts is empty by default, so outbound requests are blocked. Add permitted domains when network access is needed.Which host files can a sandbox access?
allowed_files or paths mounted through --mount/mounts are exposed; directory access can be read-only or read-write.Are failed tasks retried automatically?
max_retries (maxRetries in TypeScript/JavaScript). The default is 0, so there are no retries unless configured.Can I use any Python package in the sandbox?
wasm32-wasi wheel, and the README notes that many common packages do not have one.