Ephemora Cell

Deterministic execution for untrusted AI-generated code.

Run AI-generated code, MCP tools and plugins with exact, predictable cost — every execution bounded, measured, and reproducible.

~0.5 ms warm · ~3M executions/hour per core (one-liner) up to ~5.5M pooled · deterministic, not "isolated and hoped for"

Built for AI agents, MCP tools, plugins, code interpreters, and other untrusted workloads.

Fast, capability-based WASM execution: CPU, memory, time, I/O and filesystem budgets enforced per execution, with sign-ready execution records (RFC 8785 JCS canonicalization + ES256 sign()/verify() primitives).

<p align="center"> <a href="https://pypi.org/project/ephemora-cell/"> <img src="https://img.shields.io/pypi/v/ephemora-cell" alt="PyPI"> </a> <a href="https://www.python.org/downloads/"> <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+"> </a> <a href="https://opensource.org/licenses/Apache-2.0"> <img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License"> </a> <a href="https://github.com/MichaelS1011/ephemora-cell"> <img src="https://img.shields.io/badge/status-stable-brightgreen" alt="Status"> </a> <a href="https://github.com/MichaelS1011/ephemora-cell/stargazers"> <img src="https://img.shields.io/github/stars/MichaelS1011/ephemora-cell" alt="GitHub stars"> </a> </p> <p align="center"> <a href="https://github.com/MichaelS1011/ephemora-cell/actions/workflows/ci.yml"> <img src="https://img.shields.io/github/actions/workflow/status/MichaelS1011/ephemora-cell/ci.yml.svg?label=CI" alt="CI"> </a> <a href="https://github.com/MichaelS1011/ephemora-cell/actions/workflows/ci.yml"> <img src="https://img.shields.io/badge/tests-440_passing-brightgreen" alt="Tests (440 pass, 4 skipped — see CI)"> </a> <a href="https://github.com/MichaelS1011/ephemora-cell/actions/workflows/ci.yml"> <img src="https://img.shields.io/badge/coverage-86%25-brightgreen" alt="Coverage"> </a> <a href="https://github.com/MichaelS1011/ephemora-cell/actions/workflows/ci.yml"> <img src="https://img.shields.io/badge/types-mypy%20clean-brightgreen" alt="Type-checked with mypy (22 files, 0 errors)"> </a> <a href="https://github.com/MichaelS1011/ephemora-cell/actions/workflows/ci.yml"> <img src="https://img.shields.io/badge/format-black%20%2B%20ruff-green" alt="Formatted with black, linted with ruff"> </a> <a href="https://github.com/MichaelS1011/ephemora-cell/security/code-scanning"> <img src="https://img.shields.io/badge/security-fuzz%20%2B%20cve%20%2B%20sast-brightgreen" alt="OSS-Fuzz + pip-audit CVE + bandit SAST + OSSF Scorecard run in CI"> </a> <a href="https://github.com/MichaelS1011/ephemora-cell/actions/workflows/wasi-conformance.yml"> <img src="https://img.shields.io/badge/WASI--Preview1-conformant-green" alt="WASI conformance"> </a> </p> <p align="center"> <a href="https://registry.modelcontextprotocol.io/v0/servers?search=ephemora-cell-mcp"> <img src="https://img.shields.io/badge/MCP-Registry-blue" alt="Listed in the official MCP Registry"> </a> <a href="https://glama.ai/mcp/servers/MichaelS1011/ephemora-cell"> <img src="https://glama.ai/mcp/servers/MichaelS1011/ephemora-cell/badges/score.svg" alt="Glama grade: license A, quality A, maintenance B"> </a> </p> <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/hero-dark.svg"> <img src="assets/hero-light.svg" alt="AI Agent → Ephemora Cell enforcement stack → bounded result"> </picture> </p>

The problem

AI agents increasingly need to write and execute code, call tools, and run plugins. The question that decides whether that is safe:

How do you let an agent execute untrusted code without giving that code access to your host, your credentials, your network, or unlimited compute — with nothing pre-opened by default?

AI Agent ──▶ Tool / MCP ──▶ Ephemora Cell ──▶ WASM ──▶ bounded result

Ephemora Cell is a small, capability-based WASM execution runtime for exactly that job: an execution primitive — not an agent framework — that sits underneath your existing agent stack, MCP server, plugin system, or application.

Every execution leaves evidence

Every tool call answers three questions at once — attached to the result as _meta.execution, canonicalized (RFC 8785 JCS) and signable:

| | Answer | Example fields | |---|---|---| | RESULT | what came back | status, stdout, exit_code | | COST | what it cost | fuel_consumed, elapsed_ms | | POLICY | under which rules it ran | memory limit, preopens, network policy, wasmtime_version |

"Verifying. Not claimed." is data, not a slogan: any record can be re-checked — rewrite one field and verify() fails. Runnable demo: python examples/signed_record_demo.py.

Quick Start

Three commands: install Cell, run something untrusted, read its audited receipt.

1 — Install (use a virtualenv; on Ubuntu ≥ 23.04 / Fedora a bare pip install is refused by PEP 668. Windows: use Git Bash or WSL, and python instead of python3):

python3 -m venv .venv && source .venv/bin/activate
python -m pip install ephemora-cell

2 — Run something untrusted (the repo ships examples, or bring any .wasm):

git clone https://github.com/MichaelS1011/ephemora-cell.git && cd ephemora-cell
ephemora-cell run examples/hello.wasm --isolated

(adds OS-level process isolation around the run, a few ms — recommended for code you didn't build)

Hello from Ephemora Cell!

3 — Read the audited receipt — same run, machine-readable. Here a hostile module (examples/fuel_bomb.wasm) is given a 100-unit fuel budget and stopped, exactly as budgeted:

ephemora-cell run examples/fuel_bomb.wasm --fuel 100 --isolated --json

{
  "status": "fuel_exhausted",
  "exit_code": 0,
  "fuel_consumed": 100,
  "fuel_budget": 100,
  "stdout_bytes": 0
}

Same from Python — every result carries status, cost and captured output:

from ephemora_cell import run_wasm

result = run_wasm("examples/hello.wasm", max_fuel=1_000_000, timeout_seconds=30)
print(result.stdout)          # captured output (10 KB cap)
print(result.status.name)     # SUCCESS
print(result.elapsed_ms)      # wall time
print(result.fuel_consumed)   # compute actually used

Time to value: no policy file, no access rules, no container to provision. One pip install, one call, and you are already running untrusted WASM under a hard fuel + memory boundary at ~0.5 ms warm — the same call that took a stock docker run ~186 ms to start (macOS M5, mean over 100 runs, benchmarks/results/2026-09-14/competitive_benchmark.json; on the DGX GB10 the same baseline measured 312–349 ms, mean–p95 across both images, while Cell stayed sub-millisecond — benchmarks/results/2026-09-20/competitive_benchmark-dgx-aarch64.json). Measure the cost you actually pay per execution instead of billing a container you can't see inside.

Scale check on a single core: the one-liner run_wasm() path sustains ~3M executions/hour (n=500, hello.wasm, Mac M5, wasmtime 47.0.1 — regenerate below). Reuse one WASIConfig/sandbox across calls in a hot loop and the pooled path reaches ~5.5M/hour — that is what "every call sandboxed" costs when it is not the exception.

from ephemora_cell import run_wasm
import time
t0 = time.perf_counter()
for _ in range(500):
    run_wasm("examples/hello.wasm", max_fuel=1_000_000)
per_hour = 500 / (time.perf_counter() - t0) * 3600
print(f"{per_hour/1e6:.1f}M executions/hour on this core (one-liner path)")

Where to next: agent/tool isolation → Secure MCP tool execution (3-line setup) · CI gating for untrusted PRs → GitHub Action · CLI reference and usage recipes → docs/recipes.md. Something failed? The usual suspects are venv not activated, python3 vs python on Windows, or a wrong .wasm path — docs/recipes.md covers them.

Real CLI session: install, first run, machine-readable --json report with the security baseline, a fuel bomb stopped at exactly 100/100 units, and an attack module (exploit.wasm) blocked at the WASI import layer. Verify every frame: the commands run as shown from a clone.

The local devtools loop for agent tools

The same three commands above are a development loop for agent tools — edit, run, read the receipt — with no Dockerfile, no image build, no container to provision:

| Command | What it does in the loop | |---|---| | ephemora-cell build tool.rs | Compile Rust, Go, C, AssemblyScript or Zig source straight to WASM (languages & recipes) | | ephemora-cell run tool.wasm --json | Execute and get the verdict immediately: status, exit code, fuel_consumed, elapsed_ms | | ephemora-cell inspect tool.wasm | Imports, exports, memory — see what a module wants before you run it | | ephemora-cell benchmark tool.wasm | Cold/warm latency and fuel spread while you iterate |

Failures come back graded, not crashing: an infinite loop returns status: "fuel_exhausted" with its receipt, a memory hog memory_exceeded, a crash a non-zero exit code — the same statuses the auto-grader and the CI test-bench job consume. A tool that misbehaves never takes your terminal with it; you read the cost it caused and fix the code. Warm executions run sub-millisecond (0.17 ms guest / 0.51 ms end-to-end, pooled, measured; benchmarks/results/) — feedback at edit speed, against the same enforced boundary your tools will face in production.

Why this matters

Agent-generated code is different from application code: it can be buggy, computationally unbounded, unexpectedly expensive — or hostile. The runtime must enforce boundaries, not document them. Every Cell run does:

• Enforced, not promised — fuel metering (CPU), memory caps, epoch-based wall-clock timeouts, output caps and I/O budgets are enforced per execution; the effective posture is attested in an execution record that is canonicalized (RFC 8785 JCS) and sign-ready (sign()/verify() shipped).
• Deterministic loop-stop — AI-generated code ships infinite loops and unbounded retries by default. Fuel is the hard CPU-instruction exhaustion boundary: a hostile or buggy module that loops forever is stopped at precisely the budget you set, every time, and the run cannot overshoot its fuel budget. The epoch-based wall-clock timeout is the safety net on top of it — fuel counts CPU, the clock bounds everything else; no timeout races, no heuristic kill.
• Measured isolation advantage — of the attack vectors that succeed against a stock Docker container (shell, fork, socket, host filesystem, symlink escape, …), all 8 are blocked here (live-verified, script in the repo).
• Sub-millisecond warm execution — 0.17 ms guest / 0.51 ms end-to-end (pooled, measured 2026-09-14; benchmarks/results/) makes sandboxing every call affordable instead of exceptional.

What is enforced

Security is never opt-in. Every execution — in-process or isolated — runs under enforced limits (CPU fuel, memory, wall-clock time, output caps — always on, neither the guest nor the caller can switch them off). The one thing you choose is the process boundary: add --isolated (or call run_isolated()) when the module comes from outside your own build — agent output, third-party plugins, PR-contributed code. The in-process path stays for modules you build and trust. The enforced defaults:

| Resource | Default | |---|---| | WASM memory | 128 MB (Store.set_limits) | | Fuel / CPU budget | 1,000,000 (~13 fuel/iter