Crate aardvark_core 

Aardvark is an embeddable multi-language runtime for executing sandboxed bundles inside V8.

The crate targets host services that need a predictable, resource-constrained way to run guest code without shipping a full browser. It currently supports Python (via Pyodide) and an experimental JavaScript engine. It exposes:

• PyRuntime – a single-tenant runtime that prepares bundles, enforces resource limits, and surfaces structured outcomes.
• PyRuntimePool – a reset-aware pool for amortising Pyodide startup cost.
• Bundle and BundleManifest helpers for normalising user-provided ZIP archives and their manifest metadata.
• InvocationDescriptor – a host-controlled contract describing inputs, outputs, and budgets for individual invocations.
• ExecutionOutcome and SandboxTelemetry – diagnostics tailored for observability pipelines.

Quick Example

use aardvark_core::{Bundle, PyRuntime, PyRuntimeConfig};

fn invoke(bytes: &[u8]) -> anyhow::Result<()> {
    let mut runtime = PyRuntime::new(PyRuntimeConfig::default())?;
    let bundle = Bundle::from_zip_bytes(bytes)?;
    let (session, _manifest) = runtime.prepare_session_with_manifest(bundle)?;
    let outcome = runtime.run_session(&session)?;
    if let Some(payload) = outcome.payload() {
        println!("payload kind: {}", payload.kind());
    }
    if outcome.sandbox_telemetry().has_policy_violations() {
        eprintln!("invocation tripped sandbox policy");
    }
    Ok(())
}

See the docs/architecture and docs/api directories in the repository for a deeper discussion of the runtime design, manifest schema, and integration patterns.

Re-exports

pub use bundle::Bundle;

pub use bundle::BundleFingerprint;

pub use config::HostHooks;

pub use config::PyRuntimeConfig;

pub use config::WarmHook;

pub use config::WarmState;

pub use error::PyRunnerError;

pub use error::Result;

pub use host::FilesystemTelemetry;

pub use host::MemoryTelemetry;

pub use host::NetworkTelemetry;

pub use host::PoolTelemetry;

pub use host::SandboxTelemetry;

pub use invocation::FieldDescriptor;

pub use invocation::InvocationDescriptor;

pub use invocation::InvocationLimits;

pub use invocation::WindowConfig;

pub use outcome::Diagnostics;

pub use outcome::ExecutionOutcome;

pub use outcome::FailureKind;

pub use outcome::OutcomeStatus;

pub use outcome::ResultPayload;

pub use outcome::SharedBufferHandle;

pub use persistent::BundleArtifact;

pub use persistent::BundleHandle;

pub use persistent::BundlePool;

pub use persistent::CleanupMode;

pub use persistent::HandlerSession;

pub use persistent::InlinePythonOptions;

pub use persistent::IsolateConfig;

pub use persistent::PoolOptions;

pub use persistent::PoolStats;

pub use persistent::PythonIsolate;

pub use persistent::QueueMode;

pub use pool::PoolConfig;

pub use pool::PyRuntimePool;

pub use runtime::PyRuntime;

pub use strategy::DefaultInvocationStrategy;

pub use strategy::JavaScriptInvocationStrategy;

pub use strategy::JsonInvocationStrategy;

pub use strategy::PyInvocationStrategy;

pub use strategy::RawCtxBindingBuilder;

pub use strategy::RawCtxInput;

pub use strategy::RawCtxInvocationStrategy;

pub use strategy::RawCtxMetadata;

pub use strategy::RawCtxPublishBuilder;

pub use strategy::RawCtxTableColumnBuilder;

pub use strategy::RawCtxTableSpec;

pub use strategy::RawCtxTableSpecBuilder;

Modules

assets

Embedded Pyodide assets exposed to the runtime.

bundle

Utilities for handling user-provided Python bundles.

config

Runtime configuration options.

error

Error types exposed by the runtime.

host

Host-facing helpers for consuming sandbox diagnostics.

invocation

Invocation descriptor and budget definitions.

outcome

Structured execution outcome returned by the runtime.

persistent

Persistent-runtime helpers: isolates, bundle handles, and pools.

pool

Simple runtime pool with reset and tracing hooks.

pyodide

runtime

Runtime coordination between the host and language-specific engines.

strategy

Invocation strategy abstraction allowing custom adapters to participate in execution.

Structs

BundleManifest

Normalised view of aardvark.manifest.json.

ExecutionOutput

ManifestCpuResources

CPU-related defaults.

ManifestFilesystemResources

Filesystem sandbox configuration.

ManifestNetworkResources

Network sandbox configuration.

ManifestPyodide

Pyodide-specific overrides applied when Python is selected.

ManifestResources

Resource policy hints the runtime should enforce per invocation.

ManifestRuntime

Runtime-specific manifest configuration selected per bundle.

OverlayBlob

Overlay blob entry associated with a snapshot export/import.

OverlayExport

Overlay export bundle containing metadata JSON and associated tar blobs.

PySession

Represents a prepared execution context for a specific bundle.

Enums

ManifestFilesystemMode

Filesystem access level requested by the bundle.

RuntimeLanguage

Supported guest language runtimes.

Constants

BUNDLE_MANIFEST_BASENAME

Canonical filename for the manifest within the bundle archive.

BUNDLE_MANIFEST_SCHEMA

Embedded JSON schema used by tooling for validation.

BUNDLE_MANIFEST_SCHEMA_VERSION

Current schema version supported by the runtime.