Wasm Wasmtime

wasmtime — Server-Side WASM Runtime

Purpose

Guide agents through wasmtime: running WASM modules from the CLI, WASI APIs, the component model with WIT interfaces, embedding wasmtime in Rust applications, fuel metering for sandboxed execution, and debugging WASM with DWARF debug info.

Triggers

• "How do I run a WASM file with wasmtime?"
• "How does WASI work with wasmtime?"
• "How do I embed wasmtime in my Rust application?"
• "What is the WebAssembly component model?"
• "How do I limit WASM execution with fuel?"
• "How do I debug a WASM module in wasmtime?"

Workflow

1. wasmtime CLI

# Install
curl https://wasmtime.dev/install.sh -sSf | bash

# Run a WASM module
wasmtime hello.wasm

# Run with WASI arguments
wasmtime prog.wasm -- arg1 arg2

# Pre-open directories (WASI filesystem sandbox)
wasmtime --dir /tmp::/ prog.wasm    # map host /tmp to WASI root

# Pass environment variables
wasmtime --env HOME=/home/user prog.wasm

# Invoke specific exported function
wasmtime run --invoke add math.wasm 3 4

# Inspect exports
wasmtime explore math.wasm    # interactive explorer
wasmtime inspect math.wasm    # show all exports/imports

# Compile to native ahead-of-time
wasmtime compile prog.wasm -o prog.cwasm
wasmtime run prog.cwasm

2. WASI preview2 APIs

WASI preview2 provides a capability-based POSIX-like API set:

# wasmtime supports WASI p2 natively
wasmtime --wasi-modules experimental-wasi-http prog.wasm

# Key WASI interfaces (WIT)
# wasi:filesystem — file and directory access
# wasi:sockets — TCP/UDP networking (preview2)
# wasi:http — HTTP client/server (experimental)
# wasi:cli — stdin/stdout/stderr, environment
# wasi:random — secure random numbers
# wasi:clocks — system and monotonic clocks

3. Embedding wasmtime in Rust

# Cargo.toml
[dependencies]
wasmtime = "24"
wasmtime-wasi = "24"
anyhow = "1"

use wasmtime::*;
use wasmtime_wasi::WasiCtxBuilder;

fn main() -> anyhow::Result<()> {
    // Create engine with default config
    let engine = Engine::default();

    // Load and compile WASM module
    let module = Module::from_file(&engine, "prog.wasm")?;

    // Set up WASI context
    let wasi = WasiCtxBuilder::new()
        .inherit_stdio()
        .inherit_env()
        .preopened_dir("/tmp", "/")?
        .build();

    // Create a store (holds WASM state)
    let mut store = Store::new(&engine, wasi);

    // Instantiate the module
    let instance = Instance::new(&mut store, &module, &[])?;

    // Call an exported function
    let add = instance.get_typed_func::<(i32, i32), i32>(&mut store, "add")?;
    let result = add.call(&mut store, (3, 4))?;
    println!("Result: {result}");

    Ok(())
}

4. Fuel metering — CPU limiting

Fuel metering limits the number of WASM instructions executed, preventing runaway or malicious code:

use wasmtime::*;

let mut config = Config::default();
config.consume_fuel(true);    // enable fuel consumption

let engine = Engine::new(&config)?;
let module = Module::from_file(&engine, "untrusted.wasm")?;

let mut store = Store::new(&engine, ());
store.set_fuel(1_000_000)?;   // allow 1M instructions

let instance = Instance::new(&mut store, &module, &[])?;
let run = instance.get_typed_func::<(), ()>(&mut store, "run")?;

match run.call(&mut store, ()) {
    Ok(_) => println!("Completed, fuel remaining: {}", store.get_fuel()?),
    Err(e) if e.to_string().contains("all fuel consumed") => {
        println!("Timed out (fuel exhausted)");
    }
    Err(e) => eprintln!("Error: {e}"),
}

5. Component model and WIT

The component model adds typed interface definitions (WIT) on top of core WASM:

// math.wit — interface definition
package example:math@1.0.0;

interface calculator {
    add: func(a: s32, b: s32) -> s32;
    sqrt: func(x: f64) -> f64;
}

world math-world {
    export calculator;
}

# Install component toolchain
cargo install wasm-tools cargo-component

# Create a Rust component
cargo component new --lib math-component
# Implement the WIT interface in src/lib.rs

# Build component
cargo component build --release

# Run with wasmtime component
wasmtime run math-component.wasm

// Embed a component in Rust
use wasmtime::component::*;

wasmtime::component::bindgen!({
    world: "math-world",
    path: "math.wit",
});

let component = Component::from_file(&engine, "math.wasm")?;
let (calculator, _) = MathWorld::instantiate(&mut store, &component, &linker)?;
let result = calculator.call_add(&mut store, 3, 4)?;

6. WASM debugging with DWARF

# Build WASM with debug info (Rust)
cargo build --target wasm32-wasi    # debug profile includes DWARF by default

# Run with source-level debugging
WASMTIME_BACKTRACE_DETAILS=1 wasmtime prog.wasm

# Full DWARF stack traces
wasmtime --debug-info prog.wasm 2>&1

# GDB with WASM (wasmtime dev build)
wasmtime debug prog.wasm   # experimental

# wasm-tools for inspection
wasm-tools print prog.wasm | head -50     # disassemble to WAT
wasm-tools validate prog.wasm             # validate WASM binary

7. WASM GC (garbage-collected objects)

WASM GC proposal adds struct and array types with managed allocation:

;; GC-enabled module (toolchain dependent)
(struct $point (field (mut f32) x) (field (mut f32) y))

# wasm-tools with GC support
wasm-tools validate --features gc module.wasm
wasmtime run --wasm gc module.wasm

In Rust/component builds, check wasmtime feature flags for gc support. Use struct.new, array.new, struct.get, array.get instructions in WAT or compiled output.

8. WASM threads and shared memory

# Requires SharedArrayBuffer in JS hosts; WASI pthreads in native hosts
# Compile with threading enabled (Clang/Rust wasm32-wasi-threads)
clang --target=wasm32-wasi -pthread -matomics -mbulk-memory -o prog.wasm prog.c

# Current wasmtime enables threads + shared-memory by default (see stability-wasm-proposals)
wasmtime run prog.wasm

Atomics (i32.atomic.*) and memory.atomic.wait/notify require bulk-memory and threads proposals. Check wasmtime --help for -W/-S overrides if running an older build.

9. WASM exception handling

(try (do $exn)
  (throw $exn)
  (catch $exn (local.get 0) (return)))

# Exception handling enabled by default in current wasmtime releases
wasmtime run module.wasm

Replaces longjmp-style Emscripten patterns with native try/catch/throw in WASM. For embedding, enable explicitly if needed:

config.wasm_exceptions(true);  // usually on by default in recent wasmtime

10. WASI Preview 2 (p2) stabilization

WASIp2 uses the component model with typed interfaces instead of raw syscall imports:

# wasmtime 17+ supports component model / WASI p2 (see examples-wasip2.html)
wasmtime run component.wasm

# wit-bindgen generates host/guest bindings from WIT files
wit-bindgen rust ./deps/wasi-cli.wit

Migrate from WASI p1 (wasi_snapshot_preview1) by regenerating bindings with cargo component and WIT packages.

11. Performance configuration

// High-performance embedding config
let mut config = Config::default();
config.cranelift_opt_level(OptLevel::SpeedAndSize);
config.parallel_compilation(true);
config.cache_config_load_default()?;    // disk cache for compiled modules

// Ahead-of-time compilation for production
// 1. Pre-compile in build pipeline
let serialized = module.serialize()?;
std::fs::write("prog.cwasm", &serialized)?;

// 2. Load pre-compiled at runtime (zero compilation cost)
let module = unsafe { Module::deserialize_file(&engine, "prog.cwasm")? };

Related skills

• Use skills/runtimes/wasm-emscripten for compiling C/C++ to WASM for browser/WASI
• Use skills/rust/rust-async-internals for async patterns in wasmtime Rust embedding
• Use skills/runtimes/binary-hardening for sandboxing considerations with WASM