Repolode
Submit
capsulerun

capsulerun/runtime

A runtime that executes untrusted code for AI agents inside isolated WebAssembly sandboxes, with CPU, memory and timeout limits per task.

View on GitHub
Stars
303
Forks
22
Open issues
0
Last commit
26 days ago

What is it?

Capsule is a runtime for running untrusted code in isolated environments. Each task runs inside its own WebAssembly sandbox, separated from the host system. Developers mark Python or TypeScript/JavaScript functions with a task wrapper, and the runtime compiles the file to WebAssembly and executes it.

Each task can be given a compute level, a RAM limit, a timeout and a retry count. CPU usage is controlled through WebAssembly fuel metering. File access is limited to explicitly allowed directories with read-only or read-write modes, and outbound network access is limited to an allowlist of hosts. Environment variables are exposed only when listed. Every run returns a JSON envelope with the result, error details and execution metrics such as duration, fuel consumed and peak memory.

The project offers a CLI (capsule run, capsule build) and Python and npm SDKs, including a run() function for calling sandboxed tasks from host code. Python packages that rely on C extensions must have a wasm32-wasi build to run inside the sandbox.

Key features

  • 01Runs each task in its own WebAssembly sandbox isolated from the host.
  • 02Limits CPU through fuel metering, plus per-task RAM and timeout settings.
  • 03Restricts file access to listed directories with read-only or read-write modes.
  • 04Allows outbound HTTP only to allowlisted domains.
  • 05Supports Python and TypeScript/JavaScript tasks with automatic retries.
  • 06Returns a structured JSON result with duration, fuel and memory metrics.

Use cases

  • Executing LLM-generated code in a code interpreter without exposing the host machine.
  • Running tool calls from AI agents with strict limits on files, network hosts and environment variables.
  • Packaging small serverless-style functions that need predictable resource caps.
  • Calling sandboxed Python or TypeScript code from a host application via run().

Quick start

  1. 1

    Install the Python package

    pip install capsule-run
  2. 2

    Create hello.py with a main task that returns a greeting

  3. 3

    Run the file with the Capsule CLI

    capsule run hello.py

Things to know

  • The README shows Python and TypeScript examples only, so other languages are not covered.
  • Compiling source files adds seconds of latency on first run unless you precompile with capsule build.

In collections

Sandboxes for AI agentsOpen-source AI agent frameworks & apps

Topics

#ai-agents#sandbox#webassembly#code-execution#wasm#rust#python#typescript#agentic-workflow#code-interpreter

FAQ

What is runtime?
A runtime that executes untrusted code for AI agents inside isolated WebAssembly sandboxes, with CPU, memory and timeout limits per task. Capsule is a runtime for running untrusted code in isolated environments. Each task runs inside its own WebAssembly sandbox, separated from the host system. Developers mark Python or TypeScript/JavaScript functions with a task wrapper, and the runtime compiles the file to WebAssembly and executes it.
Is runtime free to use? What license does it have?
runtime is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is runtime still maintained?
Actively maintained. The last commit to runtime was on Oct 12, 2026.
What can I use runtime for?
Executing LLM-generated code in a code interpreter without exposing the host machine. Running tool calls from AI agents with strict limits on files, network hosts and environment variables. Packaging small serverless-style functions that need predictable resource caps. Calling sandboxed Python or TypeScript code from a host application via run().
How do I install runtime?
Install the Python package: pip install capsule-run Create hello.py with a main task that returns a greeting Run the file with the Capsule CLI: capsule run hello.py
Where can I get runtime?
The source code and installation instructions are on GitHub: https://github.com/capsulerun/runtime

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects