Struct SandboxBuilder 

pub struct SandboxBuilder<Runtime = Needs, Stdlib = Needs> { /* private fields */ }

Builder for constructing a Sandbox.

Type parameters track configuration state at compile time:

• Runtime: Whether WASM runtime is configured (state::Needs or state::Has)
• Stdlib: Whether Python stdlib is configured (state::Needs or state::Has)

The build() method is only available when both are state::Has.

Examples

// With embedded feature - simplest path
let sandbox = Sandbox::embedded()
    .with_callback(MyCallback)
    .build()?;

// Without embedded - must specify both runtime and stdlib
let sandbox = Sandbox::builder()
    .with_wasm_file("runtime.wasm")
    .with_python_stdlib("/path/to/stdlib")
    .build()?;

Implementations

impl SandboxBuilder<Needs, Needs>

pub fn new() -> Self

Create a new sandbox builder with default settings.

You must configure both a runtime source and Python stdlib before building. Use Sandbox::embedded() for zero-config setup when the embedded feature is enabled.

impl<S> SandboxBuilder<Needs, S>

pub fn with_embedded_runtime(self) -> SandboxBuilder<Has, Has>

Available on crate feature embedded only.

Explicitly use the embedded pre-compiled runtime.

Note: You usually don’t need to call this. When the embedded feature is enabled, the embedded runtime is used automatically for sandboxes without native extensions. This method exists for explicit control in advanced use cases.

Automatic Runtime Selection

The runtime is selected automatically based on your configuration:

• No native extensions → Embedded runtime (fast, ~2ms)
• Has native extensions → Late-linking (required for .so files)

// These are equivalent when embedded feature is enabled:
let sandbox = Sandbox::builder().build()?;
let sandbox = Sandbox::builder().with_embedded_runtime().build()?;

// With native extensions, late-linking happens automatically:
let sandbox = Sandbox::builder()
    .with_package("/path/to/numpy-wasi.tar.gz")?  // Has .so files
    .build()?;  // Uses late-linking, not embedded runtime

Explicitly use the embedded pre-compiled runtime and stdlib.

This transitions the builder to a fully-configured state, ready to build.

Note: Consider using Sandbox::embedded() instead for cleaner code.

pub fn with_wasm_bytes( self, bytes: impl Into<Vec<u8>>, ) -> SandboxBuilder<Has, S>

Set the WASM component from bytes.

Use this to embed the WASM component in your binary. You still need to configure the Python stdlib with with_python_stdlib() or with_auto_stdlib().

pub fn with_wasm_file(self, path: impl Into<PathBuf>) -> SandboxBuilder<Has, S>

Set the WASM component from a file path.

You still need to configure the Python stdlib with with_python_stdlib() or with_auto_stdlib().

pub unsafe fn with_precompiled_bytes( self, bytes: impl Into<Vec<u8>>, ) -> SandboxBuilder<Has, S>

Available on crate features embedded or preinit only.

Set the WASM component from pre-compiled bytes.

Pre-compiled components load much faster because they skip compilation (~50x faster sandbox creation). Create pre-compiled bytes using PythonExecutor::precompile().

Safety

This function is unsafe because wasmtime cannot fully validate pre-compiled components for safety. Loading untrusted pre-compiled bytes can lead to arbitrary code execution.

Only call this with pre-compiled bytes that:

• Were created by PythonExecutor::precompile() or precompile_file()
• Come from a trusted source you control
• Were compiled with a compatible wasmtime version and configuration

Example

// Pre-compile once (safe operation)
let precompiled = PythonExecutor::precompile_file("runtime.wasm")?;

// Load from pre-compiled (unsafe - you must trust the bytes)
let sandbox = unsafe {
    Sandbox::builder()
        .with_precompiled_bytes(precompiled)
        .with_python_stdlib("/path/to/stdlib")
        .build()?
};

pub unsafe fn with_precompiled_artifact( self, artifact: PrecompiledArtifact, ) -> SandboxBuilder<Has, S>

Available on crate features embedded or preinit only.

Set the WASM component from a shared PrecompiledArtifact.

Pre-compiled components load much faster because they skip compilation (~50x faster sandbox creation). Create pre-compiled files using PythonExecutor::precompile_file().

Unlike Self::with_precompiled_bytes, the artifact is cheaply cloned, so repeated sandbox creation does not copy its component bytes. When the embedded feature is enabled, use PrecompiledArtifact::new_cached to enable content-safe caching.

Safety

This function is unsafe because wasmtime cannot fully validate pre-compiled components for safety. Loading untrusted pre-compiled bytes can lead to arbitrary code execution.

Only call this with pre-compiled bytes that:

• Were created by PythonExecutor::precompile() or precompile_file()
• Come from a trusted source you control
• Were compiled with a compatible wasmtime version and configuration

pub unsafe fn with_precompiled_file( self, path: impl Into<PathBuf>, ) -> SandboxBuilder<Has, S>

Available on crate features embedded or preinit only.

Set the WASM component from a pre-compiled file path.

Pre-compiled components load much faster because they skip compilation (~50x faster sandbox creation). Create pre-compiled files using PythonExecutor::precompile_file().

Safety

This function is unsafe because wasmtime cannot fully validate pre-compiled components for safety. Loading untrusted pre-compiled files can lead to arbitrary code execution.

Only call this with pre-compiled files that:

• Were created by PythonExecutor::precompile() or precompile_file()
• Come from a trusted source you control
• Were compiled with a compatible wasmtime version and configuration

Example

// Pre-compile once and save to disk
let precompiled = PythonExecutor::precompile_file("runtime.wasm")?;
std::fs::write("runtime.cwasm", &precompiled)?;

// Load from pre-compiled file (unsafe - you must trust the file)
let sandbox = unsafe {
    Sandbox::builder()
        .with_precompiled_file("runtime.cwasm")
        .with_python_stdlib("/path/to/stdlib")
        .build()?
};

impl<R> SandboxBuilder<R, Needs>

pub fn with_python_stdlib( self, path: impl Into<PathBuf>, ) -> SandboxBuilder<R, Has>

Set the path to the Python standard library directory.

This is required when not using the embedded feature. The directory should contain the extracted Python stdlib (e.g., from componentize-py’s python-lib.tar.zst).

The stdlib will be mounted at /python-stdlib inside the WASM sandbox.

pub fn with_auto_stdlib(self) -> Result<SandboxBuilder<R, Has>, Error>

Auto-detect Python stdlib from common locations.

Searches in order:

1. ERYX_PYTHON_STDLIB environment variable
2. ./python-stdlib (relative to current directory)
3. <exe_dir>/python-stdlib (relative to executable)
4. <exe_dir>/../python-stdlib (sibling of executable directory)

Errors

Returns Error::MissingPythonStdlib if no valid stdlib directory is found.

Example

let sandbox = Sandbox::builder()
    .with_wasm_file("runtime.wasm")
    .with_auto_stdlib()?  // Explicit fallible auto-detection
    .build()?;

pub fn with_embedded_stdlib(self) -> Result<SandboxBuilder<R, Has>, Error>

Available on crate feature embedded-stdlib only.

Use the embedded Python standard library.

Extracts the stdlib bundled in the binary to a cached temp directory and configures the builder to use it. This is useful when loading a custom pre-compiled runtime via with_precompiled_file() but still wanting the convenience of the embedded stdlib.

Requires the embedded-stdlib feature (also enabled by embedded).

Errors

Returns an error if stdlib extraction fails.

Example

let sandbox = unsafe {
    Sandbox::builder()
        .with_precompiled_file("custom-runtime.cwasm")
        .with_embedded_stdlib()?
        .build()?
};

impl<R, S> SandboxBuilder<R, S>

pub fn with_native_extension( self, name: impl Into<String>, bytes: impl Into<Vec<u8>>, ) -> Self

Available on crate feature native-extensions only.

Add a native Python extension (.so file) to be linked into the component.

Native extensions allow Python packages with compiled code (like numpy) to work in the sandbox. The extension is linked into the WASM component at sandbox creation time using late-linking.

Arguments

• name - The name of the .so file (e.g., “numpy/core/_multiarray_umath.cpython-314-wasm32-wasi.so”)
• bytes - The raw WASM bytes of the compiled extension

Example

// Load numpy native extension
let numpy_core = std::fs::read("numpy/core/_multiarray_umath.cpython-314-wasm32-wasi.so")?;

let sandbox = Sandbox::builder()
    .with_native_extension("numpy/core/_multiarray_umath.cpython-314-wasm32-wasi.so", numpy_core)
    .with_site_packages("path/to/site-packages")  // For Python files
    .build()?;

// Now numpy can be imported!
let result = sandbox.execute("import numpy as np; print(np.array([1,2,3]).sum())").await?;

Note

When native extensions are added, the sandbox creation is slower because the component needs to be re-linked. Consider caching the linked component for repeated use with the same extensions.

pub fn with_cache(self, cache: Arc<dyn ComponentCache>) -> Self

Available on crate feature native-extensions only.

Set a component cache for faster sandbox creation with native extensions.

When native extensions are used, the sandbox must link them into the base component and then JIT compile the result. This can take 500-1000ms.

With caching enabled, the linked and pre-compiled component is stored and reused on subsequent calls, reducing creation time to ~10ms.

Example

use eryx::{Sandbox, cache::InMemoryCache};

let cache = InMemoryCache::new();

// First call: ~1000ms (link + compile + cache)
let sandbox1 = Sandbox::builder()
    .with_native_extension("numpy/core/*.so", bytes)
    .with_cache(Arc::new(cache.clone()))
    .build()?;

// Second call: ~10ms (cache hit)
let sandbox2 = Sandbox::builder()
    .with_native_extension("numpy/core/*.so", bytes)
    .with_cache(Arc::new(cache))
    .build()?;

pub fn with_cache_dir(self, path: impl AsRef<Path>) -> Result<Self, Error>

Available on crate feature native-extensions only.

Set a custom filesystem cache directory for late-linked components.

Note: You usually don’t need to call this. A default cache at $TMPDIR/eryx-cache is used automatically when native extensions are present. Use this method only if you need a specific cache location.

The cache stores pre-compiled WASM components to avoid expensive re-linking on subsequent sandbox creations with the same extensions.

Errors

Returns an error if the cache directory cannot be created.

Example

// Usually not needed - default cache is automatic
let sandbox = Sandbox::builder()
    .with_package("/path/to/numpy.tar.gz")?
    .build()?;  // Uses $TMPDIR/eryx-cache automatically

// Only if you need a specific location:
let sandbox = Sandbox::builder()
    .with_package("/path/to/numpy.tar.gz")?
    .with_cache_dir("/custom/cache/path")?
    .build()?;

pub fn with_library(self, library: RuntimeLibrary) -> Self

Add a runtime library (callbacks + preamble + stubs).

pub fn with_callbacks(self, callbacks: Vec<Box<dyn Callback>>) -> Self

Add individual callbacks.

pub fn with_callback(self, callback: impl Callback + 'static) -> Self

Add a single callback.

pub fn with_replay_journal(self, journal: CallbackJournal) -> Self

Replay callback results from a previously-recorded journal.

When set, Sandbox::execute_with_journal wraps every registered callback so that invocations matching journal (by callback name plus canonical arguments, consuming cached results FIFO per key) return the cached result instead of running live. The first miss (a callback not in the journal) switches to live execution for the remainder of the run. See the replay module for the full model.

This only affects Sandbox::execute_with_journal; plain Sandbox::execute ignores it.

Security

Journal entries are replayed verbatim — a crafted journal can inject arbitrary callback results. Only use journals from a trusted source (a previous execution you control, or one verified via HMAC signature).

pub fn with_trace_handler<H: TraceHandler + 'static>(self, handler: H) -> Self

Set a trace handler for execution progress.

pub const fn with_trace_collection(self, enabled: bool) -> Self

Configure whether execution trace events are collected in the result.

Trace collection is enabled by default for backward compatibility. It installs Python’s sys.settrace hook, which can be expensive for instruction-heavy workloads. A configured TraceHandler always keeps tracing enabled regardless of this setting.

pub fn with_output_handler<H: OutputHandler + 'static>(self, handler: H) -> Self

Set an output handler for streaming stdout.

pub const fn with_resource_limits(self, limits: ResourceLimits) -> Self

Set resource limits.

pub fn with_result_variable(self, name: impl Into<String>) -> Self

Set the name of the user variable captured as the structured result.

After each execute(), the variable with this name is read from the script’s namespace, JSON-serialized, and returned as ExecuteResult::result. If the value is not JSON-serializable, ExecuteResult::result_error explains why and result is None — execution still succeeds. Defaults to "result".

pub fn with_network(self, config: NetConfig) -> Self

Enable TLS networking with the given configuration.

This allows Python code in the sandbox to make HTTPS requests using libraries like requests or httpx. The configuration controls which hosts are allowed, connection limits, and timeouts.

Example

use eryx::{Sandbox, NetConfig};

let sandbox = Sandbox::embedded()
    .with_network(NetConfig::default())
    .build()?;

// Python code can now use requests/httpx
sandbox.execute(r#"
import requests
r = requests.get("https://httpbin.org/get")
print(r.status_code)
"#).await?;

Security

By default, connections to localhost and private networks (RFC1918) are blocked. Use NetConfig::allow_localhost or NetConfig::permissive for testing.

pub fn with_secret( self, name: impl Into<String>, value: impl Into<String>, allowed_hosts: Vec<String>, ) -> Self

Add a secret that will be substituted at the network boundary.

The sandbox will receive a placeholder via environment variable, and the real value will be injected only when making HTTP requests to allowed hosts.

Placeholders are automatically scrubbed from stdout/stderr/files to prevent leakage (see scrub_stdout, scrub_stderr, scrub_files).

Arguments

• name - Environment variable name (e.g., “OPENAI_API_KEY”)
• value - The real secret value
• allowed_hosts - Host patterns where this secret can be used. Supports wildcards: *.example.com, api.*.com.

⚠️ Important: allowed_hosts Behavior

• Empty allowed_hosts: Falls back to NetConfig.allowed_hosts. If that is also empty, the secret can be sent to ANY host (subject to blocked_hosts).
• Always specify allowed_hosts for production use to prevent accidental exfiltration to unauthorized hosts.

Security

• Python code only sees a placeholder like ERYX_SECRET_PLACEHOLDER_abc123
• Real value is substituted transparently when making HTTP requests
• Host checks use the TCP connection target, NOT the HTTP Host header (prevents spoofing)
• Placeholders are scrubbed from all outputs by default
• Secrets are ephemeral (regenerated on each sandbox creation)

Example

let sandbox = Sandbox::embedded()
    .with_secret("OPENAI_API_KEY", "sk-real-key", vec!["api.openai.com"])
    .with_network(NetConfig::default().allow_host("api.openai.com"))
    .build()?;

// Python code:
// key = os.environ["OPENAI_API_KEY"]  # Gets placeholder
// requests.get("https://api.openai.com", headers={"Authorization": f"Bearer {key}"})
// # Real key is injected transparently

pub fn scrub_stdout(self, policy: impl Into<OutputScrubPolicy>) -> Self

Control stdout scrubbing (default: All when secrets configured).

Accepts bool (for convenience) or OutputScrubPolicy (for future extensibility).

When enabled, secret placeholders are replaced with [REDACTED] in stdout.

Example

.scrub_stdout(true)   // Enable scrubbing (default)
.scrub_stdout(false)  // Disable for debugging

pub fn scrub_stderr(self, policy: impl Into<OutputScrubPolicy>) -> Self

Control stderr scrubbing (default: All when secrets configured).

Accepts bool (for convenience) or OutputScrubPolicy (for future extensibility).

When enabled, secret placeholders are replaced with [REDACTED] in stderr.

pub fn scrub_result(self, enabled: bool) -> Self

Control scrubbing of the structured result channel (default: false).

Unlike stdout/stderr — which are scrubbed by default because they tend to be surfaced to humans/LLMs — the result (and result_error) field is a programmatic side channel, so secret-placeholder scrubbing is opt-in. When enabled, placeholders in ExecuteResult::result and ExecuteResult::result_error are replaced with [REDACTED].

pub fn scrub_files(self, policy: impl Into<FileScrubPolicy>) -> Self

Control file scrubbing (default: All when secrets configured).

Accepts bool or FileScrubPolicy for forward compatibility.

When enabled, secret placeholders are replaced with [REDACTED] when writing files to the VFS.

Example

// Phase 1: Simple boolean
.scrub_files(true)

// Phase 2: Path-based policies (future)
.scrub_files(FileScrubPolicy::except(vec!["/tmp/cache/*"]))

pub fn with_volume(self, volume: VolumeMount) -> Self

Available on crate feature vfs only.

Add a host filesystem volume mount.

Mounts a host directory into the sandbox at the specified guest path, using cap-std for capability-based security.

pub fn with_volumes( self, volumes: impl IntoIterator<Item = VolumeMount>, ) -> Self

Available on crate feature vfs only.

Add multiple host filesystem volume mounts.

pub fn with_site_packages(self, path: impl Into<PathBuf>) -> Self

Set the path to additional Python packages directory.

The directory will be mounted at /site-packages inside the WASM sandbox and added to Python’s import path.

pub fn with_package(self, path: impl AsRef<Path>) -> Result<Self, Error>

Add a Python package from a wheel (.whl) or tar.gz archive.

The package format is auto-detected from the file extension:

• .whl - Standard Python wheel (zip archive)
• .tar.gz, .tgz - Tarball (used by wasi-wheels)
• Directory - Used directly without extraction

Pure Python packages

For pure-Python packages (no .so files), you can use with_embedded_runtime():

let sandbox = Sandbox::builder()
    .with_embedded_runtime()
    .with_package("/path/to/requests-2.31.0-py3-none-any.whl")?
    .build()?;

Packages with native extensions

For packages containing native extensions (like numpy), the extensions are automatically registered for late-linking. A cache is set up automatically at $TMPDIR/eryx-cache for fast subsequent sandbox creations:

let sandbox = Sandbox::builder()
    .with_package("/path/to/numpy-wasi.tar.gz")?
    .build()?;  // Caching is automatic!

Errors

Returns an error if:

• The package format cannot be detected
• The archive cannot be read or extracted

pub fn with_package_bytes( self, bytes: &[u8], format: PackageFormat, name_hint: impl Into<String>, ) -> Result<Self, Error>

Load a Python package from raw bytes.

This is useful when downloading packages from URLs. The format must be specified explicitly since it cannot be detected from bytes alone.

Example

use eryx::{Sandbox, PackageFormat};

// Download a package (using your preferred HTTP client)
let bytes = reqwest::get("https://example.com/numpy-wasi.tar.gz")
    .await?
    .bytes()
    .await?;

let sandbox = Sandbox::builder()
    .with_package_bytes(&bytes, PackageFormat::TarGz, "numpy")?
    .build()?;

Arguments

• bytes - The raw package bytes
• format - The package format (Wheel or TarGz)
• name_hint - Package name hint used if detection fails (e.g., “numpy”)

Errors

Returns an error if:

• The format is Directory (not supported for bytes)
• The archive cannot be read or extracted

impl SandboxBuilder<Has, Has>

pub fn build(self) -> Result<Sandbox, Error>

Build the sandbox.

Errors

Returns an error if:

• No WASM component was specified and no default is available
• The WASM component cannot be loaded
• The WebAssembly runtime fails to initialize

Native Extensions

If native extensions are registered (via with_native_extension() or with_package() with .so files), late-linking is used automatically. This overrides any with_embedded_runtime() setting since native extensions must be linked into the runtime.

Trait Implementations

impl<R, S> Debug for SandboxBuilder<R, S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SandboxBuilder<Needs, Needs>

fn default() -> Self

Returns the “default value” for a type.