How sandboxd works

wasmtime is the runtime that does the heavy lifting: compilation via Cranelift, linear-memory protection, trap handling. sandboxd is a thin policy layer on top of it.

A single wasmtime::Engine is built with consume_fuel set true and epoch_interruption set true. Both flags are mandatory: fuel is bookkeeping the runtime cannot opt out of once enabled, and epoch interruption is the only mechanism wasmtime exposes for asynchronous wall-clock cancellation. wat is enabled so .wat fixtures parse without a separate step.

A deterministic instruction counter is the only CPU bound that gives the same answer on every machine. That is what makes fuel usable as a quota and a billing unit.

Limits::new takes a fuel budget. Store::set_fuel arms it before instantiation. Every wasm instruction deducts. When the budget hits zero the guest traps with Trap::OutOfFuel, which map_runtime_error translates to SandboxError::FuelExhausted. RunOutput::fuel_consumed reports what was spent, which is the number you size next time from.

Fuel says nothing about wall-clock time. A guest that calls a slow host function, or one the OS deschedules, can hold a thread while burning almost nothing. The watchdog catches that.

Sandbox::run spawns one thread per call. It sleeps until the configured deadline, calls engine.increment_epoch() once, then exits. A shared AtomicBool lets the main thread signal completion so the watchdog can exit early. The guest checks the epoch at safe points and traps with Trap::Interrupt, which becomes SandboxError::Timeout. One thread per run, no idle ticker, precise per-call deadline.

Linear memory is the obvious denial-of-service vector. Without a cap a single memory.grow loop can starve the host.

A struct implementing wasmtime::ResourceLimiter is attached to the Store. memory_growing returns Ok(false) once the requested size exceeds the cap, which refuses the growth without trapping. growth_was_denied is recorded; the guest sees memory.grow return -1; however the guest reacts (panic, unreachable, retry) the wrapper reports SandboxError::MemoryLimitExceeded so callers always see the real cause.

A linker that fails to define an import would still let the parsed module sit in memory. Better to reject at the door, name the offending import, and never construct the store at all.

Before Store creation, every Module::imports() entry is checked against the allow-list. Today the only allowed pair is ("host", "log") when HostAbi::log_allowed() is true. Anything else returns SandboxError::DisallowedImport with the exact module and name. As belt and braces, if this check were ever bypassed, the linker only defines granted imports, so wasmtime instantiation would fail and map_instantiation_error translates that back into DisallowedImport too.

A sandbox with literally zero observable side effects is useful for pure computation only. Logging is the smallest, safest first import to ship, and it acts as the worked reference for any future capability.

Signature (param i32 i32): pointer and length into the guest&rsquo;s exported memory. The host reads memory.data(&caller), validates with ptr.checked_add(len), slices with .get(ptr..end) so any out-of-range read returns None and traps cleanly, and decodes with String::from_utf8_lossy so invalid bytes become replacement characters rather than aborting the host. The line is appended to an Arc<Mutex<Vec<String>>> sink that the embedder owns.

wasmtime is the BytecodeAlliance reference runtime. Its fuel and epoch_interruption APIs are exactly the primitives this design needs, and Cranelift is the most-audited wasm code generator in production. CVE history is short and disclosure is professional.

wasmer, fine runtime, less polished fuel and timeout story, smaller security history. WAVM, research-grade. Native wasm interpreters, too slow for non-trivial guests.

wasmtime is Rust, so the embedding is zero-overhead and the borrow checker keeps the host boundary honest. thiserror gives typed errors without boilerplate, clap is the obvious CLI choice.

C, manual lifetime management on guest memory is exactly the bug class this is supposed to prevent. Go, viable, but no first-class wasmtime binding and the host-call FFI cost is real.

A per-run thread gives every call its own precise deadline and no idle thread between runs. The thread spawn cost is in the noise next to module compile.

A global ticker thread bumping the epoch every N milliseconds is simpler but gives you coarse shared timing and a thread that runs forever, neither of which I want.

Starting from nothing and adding one audited function means the allow-list is short enough to read in full and the default is the safe one. The allow-list grows only as fast as I can audit each addition.

wasmtime-wasi plus a capability filter. WASI&rsquo;s surface is large and its preview still moves, and grant-all-then-claw-back is exactly the deny-list posture that leaks. If you need files, WASI is the right tool, but it is a different project.

Callers branch on why a run stopped, bill it, retry it, ban the module, without scraping strings. The CLI maps each variant to its own exit code, which makes scripting around it trivial.

An opaque error with a message string. Works once, becomes a parsing exercise the second time you need to react to a specific failure.

Fuel, the epoch deadline, the limiter, linear memory and globals are all per-store. A fresh one per run gives bullet-proof isolation between calls with no cleanup logic.

Reusing a store across runs to save compile time. The interactions between leftover globals, residual fuel and the epoch counter become a footgun fast. Module caching is a better optimisation if needed.