Crate eryx 

Eryx

A Python sandbox with async callbacks, powered by WebAssembly.

Safety

By default, this crate uses #![forbid(unsafe_code)] for maximum safety. When the embedded or preinit features are enabled, this is relaxed to #![deny(unsafe_code)] to allow unsafe wasmtime APIs needed for pre-compiled component loading and CPU feature configuration (e.g., disabling AVX-512).

Eryx executes Python code in a secure WebAssembly sandbox with:

• Async callback mechanism - Callbacks are exposed as direct async functions (e.g., await get_time())
• Parallel execution - Multiple callbacks can run concurrently via asyncio.gather()
• Execution tracing - Line-level progress reporting via sys.settrace
• Introspection - Python can discover available callbacks at runtime
• Composable runtime libraries - Pre-built APIs with Python wrappers and type stubs

Quick Start

use eryx::Sandbox;

#[tokio::main]
async fn main() -> Result<(), eryx::Error> {
    // Use Sandbox::embedded() for zero-config setup (requires `embedded` feature)
    let sandbox = Sandbox::embedded().build()?;

    let result = sandbox.execute("print('Hello from Python!')").await?;

    println!("Output: {}", result.stdout);
    Ok(())
}

Re-exports

pub use net::ConnectionManager;

pub use net::NetConfig;

pub use net::TcpError;

pub use net::TlsError;

pub use package::ExtractedPackage;

pub use package::PackageFormat;

pub use pool::PoolConfig;

pub use pool::PoolError;

pub use pool::PoolStats;

pub use pool::PooledSandbox;

pub use pool::SandboxPool;

pub use secrets::FileScrubPolicy;

pub use secrets::OutputScrubPolicy;

pub use secrets::SecretConfig;

pub use secrets::generate_placeholder;

pub use secrets::scrub_placeholders;

pub use session::InProcessSession;

pub use session::PythonStateSnapshot;

pub use session::Session;

pub use session::SessionExecutor;

pub use session::SnapshotMetadata;

pub use session::SnapshotSession;

pub use session::VfsConfig;vfs

pub use session::VolumeMount;vfs

Modules

cache

Component caching for faster sandbox creation.

callback_handler

Shared callback, network, and trace handling for sandbox execution.

embeddedembedded

Embedded resources for zero-configuration sandboxes.

embedded_stdlibembedded-stdlib

Embedded Python standard library for use with custom runtimes.

net

Networking support for the sandbox.

package

Package extraction and management.

pool

Managed pool of warm sandbox instances for high-throughput scenarios.

preinitpreinit

Pre-initialization support for capturing Python memory state.

secrets

Secrets management with placeholder substitution.

session

Session-based execution for persistent WASM state.

state

Marker types for compile-time builder state tracking.

vfsvfs

Virtual filesystem support for sandboxed file operations.

Structs

CallbackRequest

Request to invoke a callback from Python code.

CancellationToken

A token which can be used to signal a cancellation request to one or more tasks.

DynamicCallback

A callback defined entirely at runtime.

DynamicCallbackBuilder

Builder for DynamicCallback.

ExecuteResult

Result of executing Python code in the sandbox.

ExecuteStats

Statistics about sandbox execution.

ExecutionHandle

Handle to a cancellable execution.

ExecutionOutput

Output from executing Python code in the WASM sandbox.

OutputRequest

Request to stream output from Python code in real-time.

PythonExecutor

The Python executor that manages the WASM runtime.

ResourceLimits

Resource limits for sandbox execution.

RuntimeLibrary

A composable set of callbacks with Python wrappers and type stubs.

Sandbox

A sandboxed Python execution environment.

SandboxBuilder

Builder for constructing a Sandbox.

Schema

An opaque JSON Schema type.

TraceEvent

An execution trace event.

TraceRequest

Request to report a trace event from Python code.

Enums

CallbackError

Errors that can occur during callback execution.

CpuFeatureLevel

CPU feature level for AOT compilation.

Error

The main error type for Eryx operations.

NetRequest

Request for a network operation from Python code.

TraceEventKind

The kind of trace event.

Traits

Callback

A callback that Python code can invoke.

JsonSchema

Re-export the JsonSchema derive macro.

OutputHandler

Handler for streaming output during execution.

TraceHandler

Handler for trace events during execution.

TypedCallback

A strongly-typed callback with compile-time schema generation.

Functions

empty_schema

Helper function to create an empty parameters schema (no arguments).

Attribute Macros

callbackmacros

Attribute macro for defining sandbox callbacks with minimal boilerplate.

Derive Macros

JsonSchema

Re-export the JsonSchema derive macro.