Unifies low-level byte buffers, garbage-collected object graphs, and 128-bit vector lanes inside each Store.
Core Functionality & Security Mechanics
Tracks 4 KiB Copy-on-Write dirty sub-pages for 5.7-10.2 us time-travel rollbacks
Stores structs/arrays via 32-bit ASLR-safe handles and unboxed 64-bit i31ref scalars
Executes all 256 0xFD fixed-width and deterministic Relaxed SIMD vector instructions
Host Control Plane
WASI 0.3 & Studio API
WASI 0.3 SandboxStudio Server
Component 6 of 6
Architectural Role & Purpose
Enforces zero-trust capability policies, WASI 0.3 stream/future rings, VVMS snapshots, and Studio HTTP UI.
Contextual Description & System Interaction
Connects sandboxed guest modules safely to vprevail, vgate, vwarden, vkbm, vllm, and vsight.
Core Functionality & Security Mechanics
Confines guest I/O via CapabilityPolicy, 64 MiB CoW VFS, and Preview 1 bridge
Seals VVMS v1 continuation snapshots with constant-time 32-byte SHA-256 digests
Serves 4-workspace Studio Web UI and HMAC-SHA256 authenticated OpenAPI 3.1.0 endpoints
Capability Pillar
What vvm Delivers
Primary Persona
WebAssembly 3.0 Core Engine
Full W3C Wasm 3.0 binary/text support: iso-recursive (rec ...) types, declared sub / sub final subtyping, WasmGC (struct, array, unboxed i31ref), try_table exceptions, return_call tail calls, Memory64, Multi-Memory, and 128-bit Fixed + Relaxed SIMD.
Guest Developers & Compiler Authors
16-Byte B1+B3 Frame IR
Single-pass lowering into 16-byte IrInst records (4 instructions per 64-byte CPU cache line) over unified frame[]u64 slots with 3-operand local forwarding and fused branch superinstructions (163.3 MIPS peak).
Sub-page 4 KiB Copy-on-Write dirty tracking (5.7–10.2 us restore) and "VVMS" v1 binary continuation envelopes protected by trailing 32-byte constant-time SHA-256 integrity digests.
Stateful Workflow & Edge Architects
Built-In vvm Studio & REST API
Light-Mode / Dark-Mode 4-workspace Web UI (/ui/auth, /ui/portal, /ui/delegated, /ui/admin) and OpenAPI 3.1.0 control plane for live .wat compilation, single-step IrInst debugging, and HMAC-SHA256 capability sessions.
Developers, Auditors & Operators
WAT / WAST & vwasm Toolchain
Folded and flat .wat parser/disassembler, B1+B3 IR disassembler, W3C .wast assertion runner (assert_return, assert_trap, assert_invalid), and vwasm guest compiler support.
QA & Toolchain Engineers
Visual Tour: vvm Studio & Cross-Runtime Benchmark Portal
Live WebAssembly 3.0 .wat Workbench & B1+B3 Frame IR Debugger
Cross-Runtime WebAssembly 3.0 Benchmark Studio (8 Standard Workloads)
Open http://127.0.0.1:8089/ui/portal in your browser to edit .wat modules live, mint HMAC-SHA256 capability sandbox tokens in /ui/auth, step individual 16-byte IrInst instructions, and inspect SHA-256 "VVMS" continuation snapshots.
Full 8-workload WebAssembly 3.0 benchmark results, B1+B3 dispatch throughput, CoW snapshot latency, and capacity sizing.
vvm — Step-by-Step How-To Guide
This guide provides task-oriented, copy-pasteable recipes for executing .wasm and .wat modules, configuring WASI capability sandboxes and fuel budgets, compiling guest programs with vwasm, running .wast conformance scripts, and debugging 16-byte B1+B3 Frame IR traces in vvm Studio.
Recipe 1: Inspect, Validate, and Execute .wasm and .wat Modules
vvm natively accepts both binary WebAssembly (.wasm, magic header \0asm) and folded or flat WebAssembly 3.0 Text Format (.wat) across all inspection and execution subcommands.
Step 1 — Author or Obtain a Module
Save the following Wasm 3.0 module with linear memory and exported functions as checksum.wat:
By default, vvm executes WASI modules inside a deterministic zero-trust capability sandbox:
Deterministic Clocks: Monotonic and wall clocks start at a fixed epoch (1,700,000,000,000,000,000 ns) and advance deterministically by 1,000 ns per clock read unless --real-clock is passed.
Deterministic Fuel Metering: Every executed IrInst deducts 1 fuel unit, and bulk memory/table/array operations deduct 1 + length / 64 fuel units before touching memory.
Bounded Copy-on-Write VFS: Preopened virtual paths live inside a quota-enforced in-memory Copy-on-Write filesystem (64 MiB total VFS ceiling, 16 MiB stdio cap, 16,384 max handles) with strict lexical .. traversal rejection.
Running a WASI Module with Strict Fuel vs Real Host Clocks
POWERSHELL
# Deterministic replay mode (fixed epoch clock + 2,500,000 instruction fuel ceiling)
vvm run --fuel 2500000 benchmarks/wasm/06_vwasm_arx_crypto.wasm bench
# Opt into real host wall/monotonic clock readings and unlimited fuel for trusted local CLI tools
vvm run --fuel max --real-clock benchmarks/wasm/04_shootout_sieve.wasm bench
Minting a Scoped Capability Policy Session via REST or Studio
Start vvm Studio on port 8089 and mint an HMAC-SHA256 capability token binding fuel, 64 KiB page ceilings, and allowed host import namespaces:
POWERSHELL
vvm studio 8089
Or mint the capability token directly from the command line:
Pass the returned token in Authorization: Bearer <token> on subsequent /api/v1/wat/execute calls to enforce those exact fuel, memory, and host import boundaries.
Recipe 3: Compile Guest Programs to WebAssembly with vwasm
The vwasm standalone WebAssembly guest compiler packaged alongside vvm in dist/bin/<os>/ compiles guest modules directly into compact, freestanding .wasm binaries with zero LLVM, Binaryen, or Emscripten dependencies.
Step 1 — Write a Freestanding Guest Kernel
Guest modules export functions using @[export: 'symbol_name'] so host sandboxes and CLI callers can invoke them directly by name:
Use -no-builtin for freestanding pure-compute kernels, and add -enable-globals when the guest module maintains stateful module-level globals across calls:
Recipe 4: Inspect B1+B3 IR Traces & "VVMS" Snapshots in vvm Studio
Step 1 — Launch Studio and Open /ui/portal
POWERSHELL
vvm studio 8089
Navigate to http://127.0.0.1:8089/ui/portal:
Paste any WebAssembly 3.0 .wat module into the WebAssembly 3.0 (.wat) Live Workbench editor.
Enter the target Export Function (for example, fib) and comma-separated Arguments (for example, 10, 0, 1).
Click Inspect IR to view the lowered 16-byte IrInst disassembly without executing, or click Compile & Execute to run the module inside a fresh capability sandbox.
Click Step 16B IrInst repeatedly to walk through the recorded instruction trace (step, PC, op, destination frame[rN] slot, 64-bit hex value, and remaining fuel).
Step 2 — Inspect the SHA-256 Authenticated "VVMS" Snapshot
Click VVMS Snapshot in the top navigation bar after executing any module to open the binary continuation inspector. The modal displays the "VVMS" v1 wire header (56 56 4D 53 01), total serialized payload size, dirty 4 KiB CoW sub-pages, WasmGC arena state, and trailing 32-byte SHA-256 integrity status:
Recipe 5: Run W3C .wast Specification & Regression Scripts
vvm includes a built-in .wast specification runner supporting (module ...), (invoke ...), (assert_return ...), (assert_trap ...), and (assert_invalid ...).
# CLI execution (exits 0 when all assertions pass, non-zero on any failure)
vvm wast arithmetic_checks.wast
# HTTP verification against a running vvm Studio daemon
curl -s -X POST http://127.0.0.1:8089/api/v1/wast/verify --data-binary "@arithmetic_checks.wast"
This guide walks application developers, language authors, and QA engineers through vvm's interactive Studio workspaces, WebAssembly 3.0 language features (WasmGC, Multi-Memory, Memory64, try_table, tail calls, and 128-bit SIMD), deterministic fuel metering, and Copy-on-Write (CoW) continuation snapshots.
1. Interactive vvm Studio Walkthrough
Launching vvm studio [port] (default port 8089) starts a zero-dependency HTTP server featuring a crisp Light-Mode default interface (#f8fafc slate canvas, #ffffff elevated cards) and instant one-click Dark-Mode switching persisted in localStorage.
The top bar organizes interactive workflows into four role-separated workspaces:
Workspace Route
Purpose
Key Controls & Telemetry
/ui/auth
Capability Gate
Mint HMAC-SHA256 Bearer capability tokens binding max_fuel, max_memory_pages, and allowed_imports.
/ui/portal
VM Debugger
Edit WebAssembly 3.0 .wat live, inspect B1+B3 IR, execute exports, single-step 16-byte IrInst traces, and monitor CoW + WasmGC counters.
/ui/delegated
Ecosystem Switchboard
Review multi-module Linker integration profiles across vprevail, vgate, vkbm, vllm, vsight, and vwarden.
/ui/admin
Telemetry & Audit
Trigger live static complexity (<= 12) and VVM-SEC-01..04 security verification across the runtime workspace.
When you click Step 16B IrInst, vvm Studio highlights the active destination slot row in frame[]u64 and updates the Program Counter badge with the instruction mnemonic, destination value, and exact remaining fuel.
2. Using WebAssembly 3.0 Features in vvm
2.1 Managed WasmGC (rec, struct, array, and Unboxed i31ref)
vvm implements the complete WebAssembly 3.0 Garbage Collection specification (Option D1 per-Store typed arenas) with iso-recursive (rec ...) type groups, sub / sub final subtyping, mutable/immutable structs and arrays, bulk segment initializers (array.new_data, array.init_data, array.new_elem, array.init_elem), and zero-allocation 31-bit tagged scalar references (ref.i31, i31.get_s, i31.get_u).
try_table Exception Handling: Declare typed exception tags with (tag $err (param i32)), raise exceptions via (throw $err ...), and catch them cleanly with (try_table (catch $err $label) ...) (catch, catch_ref, catch_all, catch_all_ref) without legacy stack-frame probing overhead on the non-throwing path.
Guaranteed O(1) Tail Calls: Both direct (return_call $fn ...) and indirect/typed (return_call_indirect ...) / (return_call_ref ...) reuse the current call frame in place, enabling unbounded state-machine transitions and functional recursion within a constant call-stack depth of 1.
2.3 Multi-Memory, Memory64, and 4 KiB Copy-on-Write Rollbacks
Multi-Memory: A single module can declare or import multiple independent linear memories ((memory $scratch 1 4), (memory $ring 2 8)) and address them explicitly in load/store/bulk instructions (i32.load $ring, memory.copy $ring $scratch).
64-Bit Memory64: Declare 64-bit linear memories (i64 index space) while preserving strict host bounds ceilings (max_memory_pages).
4 KiB CoW Sub-Page Tracking & "VVMS" Snapshots: Each 64 KiB Wasm page is subdivided into sixteen 4 KiB CoW sub-pages. Only dirtied 4 KiB sub-pages are copied prior to first mutation, allowing instant rollback or serialization into an authenticated "VVMS" binary continuation envelope:
Untrusted guest code must never stall a host worker thread. vvm enforces deterministic execution budgets at two levels:
Scalar & Control Instructions (1 fuel per IrInst): Every arithmetic op, local copy, branch, call, WasmGC allocation, and SIMD instruction decrements store.fuel by 1.
Bulk Memory, Table & GC Array Instructions (1 + length / 64 fuel): Bulk operations (memory.fill, memory.copy, memory.init, table.fill, table.copy, table.init, array.fill, array.copy, array.init_data, array.init_elem) validate bounds first (preserving W3C OOB trap precedence) and then deduct fuel proportional to element/byte count (1 + n / 64) before writing—preventing multi-megabyte zero-fuel amplification attacks.
When fuel reaches 0, execution halts cleanly with an out of fuel trap and leaves the host process completely unaffected.
4. Profiling Your Own Modules with vvm bench-mod
Before deploying a plugin to production, measure its exact decode+validate+lower time, execution latency, instruction count, MIPS rate, and 4 KiB CoW snapshot/restore cost with vvm bench-mod:
This guide covers production deployment, multi-tenant resource governance, WASI capability isolation, HTTP Studio daemon security, and continuous runtime verification for platform operators and security administrators.
1. Installation & Release Package Layout
Official vvm release archives (vvm-windows-x64.zip, vvm-linux-x64.tar.gz, and vvm-macos-universal.tar.gz or vvm-macos-src.tar.gz with build-macos.sh when cross-packaged) are verified against SHA256SUMS.txt and extract cleanly with zero external shared libraries:
# Windows PowerShell
Get-FileHash .\vvm-windows-x64.zip -Algorithm SHA256
BASH
# Linux / macOS
sha256sum -c SHA256SUMS.txt
2. Multi-Tenant Sandbox Resource Governance
Every vvmStore and HostSandbox instance is completely isolated—sharing zero mutable globals, linear memories, tables, or WasmGC arenas with sibling tenants. Administrators govern untrusted tenants across six hard resource dimensions:
Resource Dimension
Default Engine Ceiling
Studio HTTP Ceiling
Protection Provided
Instruction & Bulk Fuel (max_fuel)
100,000,000 CLI (5,000,000 Studio default)
50,000,000 max
Terminates infinite loops and charges 1 + n / 64 fuel on bulk memory/table/GC copies.
Linear Memory (max_memory_pages)
16,384 pages (1 GiB)
512 pages (32 MiB)
Overrides guest-declared maximums and returns -1 on memory.grow attempts past the host quota.
WasmGC Live Heap (max_gc_objects)
Configurable per CapabilityPolicy (16,384 Studio default)
65,536 live objects
Triggers automatic tri-color mark-sweep GC at quota threshold; traps if live reachable objects still exceed quota.
Call-Stack Depth & Frame Slots
2,048 active frames / 1,048,576u64 slots
2,048 frames / 1,048,576 slots
Prevents host OS thread stack exhaustion on deep mutual recursion (call stack exhausted trap).
vvm enforces a strict default-deny capability model (CapabilityPolicy + WasiConfig):
Host Import Namespace Allowlisting (allowed_host_modules): A guest module importing "vgate.http", "vprevail.raft", or "wasi_snapshot_preview1" fails instantiation immediately unless that exact module namespace is present in the sandbox's allowlist.
Every path is normalized lexically; any .. parent-directory segment, null byte, or drive-letter escape is rejected before lookup.
Sibling prefix confusion is blocked at segment boundaries (for example, allowlisting /sandbox/tenant_a automatically denies /sandbox/tenant_a_evil/secret.txt).
Guest file writes mutate an in-memory Copy-on-Write VFS layer bounded by max_vfs_bytes (64 MiB default) and max_vfs_file_bytes (16 MiB default), preventing host disk filling.
max_random_bytes: 1 MiB per random_get / get-random-bytes call (backed by OS CSPRNG when deterministic_random: false, or SplitMix64 PRNG for deterministic replay).
Explicit Network Gate (allow_network: false by default): Two-Tier WasiNet outbound HTTP (vgate) and DNS (vnet) hooks remain disabled unless explicitly enabled and bound by the host administrator.
4. Administering the vvm Studio HTTP Daemon
4.1 Binding & Network Hardening
vvm studio [port] [--host <ip>] [--require-auth] binds strictly to loopback (127.0.0.1:<port>) by default so interactive debugging endpoints are never accidentally exposed on untrusted LAN/WAN interfaces. When publishing vvm Studio to remote engineering teams, set VVM_STUDIO_ADMIN_TOKEN (which automatically activates --require-auth) and place it behind an authenticating reverse proxy (such as vgate with vwarden OIDC/MFA) over TLS 1.3.
Built-in HTTP transport defenses enforced on every connection:
Bounded Concurrency & Graceful Shutdown: Handles TCP clients concurrently behind a 64-slot semaphore, logs structured [vvm-http] telemetry, and shuts down cleanly on SIGINT/SIGTERM.
Confined Static Asset Router (/docs/*, /benchmarks/*): Serves only allowlisted extensions (.html, .svg, .png, .json) under dist/docs/ and dist/benchmarks/ and returns 400 Bad Request on any .. or disallowed path character.
4.2 Ephemeral HMAC-SHA256 Session Governance
On startup, the Studio daemon generates a fresh 32-byte OS CSPRNG secret in memory (failing closed if OS entropy is unavailable). Capability tokens minted via /ui/auth or POST /api/v1/auth/session encode vvm1|<max_fuel>|<max_memory_pages>|<exp_unix>|<allowed_imports> (1-hour TTL) signed with HMAC-SHA256 and verified in constant time (hmac.equal). Restarting the daemon immediately invalidates all previously issued tokens.
4.3 Running Live Workspace & Security Audits
Administrators can verify runtime integrity either from the CLI (vvm audit) or interactively from /ui/admin (GET /api/v1/audit/status):
POWERSHELL
vvm audit .
Audit Gate
Rule Enforced
Expected Production Status
COMPLEXITY-12
Every function across all runtime subsystems maintains cyclomatic complexity <= 12.
PASS
VVM-SEC-01
Zero OS shell execution primitives anywhere in runtime, decoder, validator, VM, WASI, or HTTP modules.
PASS
VVM-SEC-02
Zero external C header inclusions in runtime subsystems (100% memory-safe native structures).
PASS
VVM-SEC-03
Zero blocking browser alert or prompt dialogs; strict JSON/HTML escaping and CSP headers.
PASS
VVM-SEC-04
Clean workspace governance with zero stray VCS metadata leaks.
PASS
vvm — Operations & Real-World Use Cases
vvm is engineered to embed directly inside latency-sensitive gateways, distributed consensus state machines, policy engines, AI agent tool sandboxes, and CI conformance pipelines without pulling in heavy C++ or LLVM JIT dependencies. This guide presents concrete production patterns using WebAssembly 3.0 .wat, .wast, CLI commands, and HTTP control-plane requests.
Use Case 1: Sub-Millisecond Serverless & API Gateway Edge Filters (vgate)
Modern API gateways allow tenants to upload custom header-routing, rate-limiting, or payload-scrubbing plugins. Native shared libraries risk crashing the proxy on a single null pointer, whereas multi-process containers add tens of milliseconds of cold-start overhead.
Why vvm Fits:
Microsecond Spin-Up: Decoding, validating, lowering to 16-byte B1+B3 Frame IR, and instantiating a filter takes 37–180 us.
return_call State Machines: Finite-state HTTP header parsers run in O(1) stack space via WebAssembly 3.0 tail calls.
Strict Per-Request Fuel: Setting --fuel 50000 guarantees every tenant filter completes in under half a millisecond or traps cleanly.
# 1. Mint a capability token allowing ONLY vgate.http with a 50,000-instruction fuel budget
curl -s -X POST http://127.0.0.1:8089/api/v1/auth/session `
-H "Content-Type: application/json" `
-d '{"max_fuel":50000,"max_memory_pages":2,"allowed_imports":"vgate.http"}'
# 2. Validate and inspect lowered 16-byte Frame IR via REST
curl -s -X POST http://127.0.0.1:8089/api/v1/wat/inspect `
-H "Content-Type: application/json" `
-d '{"wat":"(module (func (export \"ping\") (result i32) (i32.const 200)))"}'
Use Case 2: Deterministic Smart-Contract, Policy & Lease Evaluation (vwarden)
Zero-trust policy engines and distributed ledgers require bit-exact determinism: every node evaluating the same policy or contract against the same inputs must produce the exact same result and consume the exact same gas budget, with zero access to ambient host time, randomness, or network sockets.
Why vvm Fits:
Canonical IEEE 754 & Deterministic Relaxed SIMD: Floating-point and vector operations behave identically across x86_64 and ARM64.
Deterministic Clocks & SplitMix64 PRNG: Ambient OS entropy and wall-clock drift are isolated by default.
Use Case 3: Speculative Rollbacks & Durable Workflows (vprevail)
Stateful workflow engines, database stored procedures, and AI planning sandboxes frequently need to checkpoint a warmed guest VM, test multiple speculative branches, discard failed transactions in microseconds, or persist a continuation to durable storage.
Why vvm Fits:
4 KiB Sub-Page Copy-on-Write (CoW): Capturing and restoring linear memory + globals + tables takes 5.7–24.7 us on scalar/memory workloads because untouched 4 KiB sub-pages are never copied.
SHA-256 Authenticated "VVMS" Envelopes: Serialized snapshots include magic bytes 56 56 4D 53 01 and a trailing 32-byte SHA-256 digest verified in constant time before restore—preventing corrupted or tampered state injection.
###Host Embedding Pattern (Conceptual Flow)
TEXT
1. Instantiate module into Store and invoke initialization export
2. Enable 4 KiB sub-page CoW tracking on Store linear memories
3. Capture baseline VmSnapshot (or encode to SHA-256 "VVMS" binary bytes)
4. Invoke speculative transaction branch:
- On commit: keep mutated Store state (or persist updated "VVMS" checkpoint)
- On abort/trap: restore VmSnapshot in ~7 microseconds to exact pre-transaction state
Use Case 4: Managed DSLs, Graph Queries & Functional Closures (vkbm / vllm)
Compilers for garbage-collected DSLs, graph query engines, and typed functional languages traditionally had to bundle their own 100 KB+ linear-memory allocator and shadow-stack garbage collector inside every .wasm module.
Iso-Recursive Multi-Module Linking: Two separate modules declaring structurally identical (rec (type $Node ...)) definitions link together seamlessly across Linker boundaries while rejecting mismatched field layouts at link time.
Use Case 5: Automated W3C WAST Conformance Gating in CI/CD
Compiler teams generating WebAssembly 3.0 modules can gate every pull request or release artifact using vvm wast to test positive return values, expected runtime traps (division by zero, out-of-bounds memory, unreachable, fuel exhaustion), and negative static validation cases (assert_invalid):
vvm — Configuration, CLI, Sandbox Policy & API Reference
This reference documents all vvm and vwasm command-line subcommands and flags, sandbox policy schemas, WASI 0.3 and wasi_snapshot_preview1 host import namespaces, and the vvm Studio OpenAPI 3.1.0 HTTP endpoints.
1. vvm Command-Line Interface Reference
TEXT
Usage: vvm <command> [arguments]
Subcommand
Syntax
Description
Exit Codes
version
vvm version (--version, -v)
Prints vvm runtime version, WebAssembly 3.0 spec target, B1+B3 IR architecture, WasmGC heap mode, WASI 0.3 target, and 4 KiB CoW support.
0
inspect
vvm inspect <file.wasm|file.wat>
Decodes binary or text module and prints byte size, recursive type groups, imports, functions, tables, memories, tags, globals, exports, segments, and custom sections.
0 valid, 1 error
validate
vvm validate <file.wasm|file.wat>
Runs static WebAssembly 3.0 Chapter 3 validation (iso-recursive types, subtyping, stack polymorphism, non-null local initialization) and reports canonical type/function counts.
0 valid, 1 invalid
disasm
vvm disasm <file.wasm|file.wat>
Disassembles any binary .wasm or .wat module into canonical WebAssembly 3.0 .wat text format on stdout.
0 ok, 1 error
ir
vvm ir <file.wasm|file.wat>
Validates, lowers to 16-byte B1+B3 Frame IR, and prints per-function frame layouts (params, locals, max_stack, total_slots, v128_slots) and IrInst listings.
0 ok, 1 error
run
vvm run [--fuel <N|max>] [--real-clock] <file> [export] [args...]
Instantiates the module (auto-binding WASI 0.3 & Preview 1 when imported), invokes export (default _start), flushes WASI stdout, and prints return values + executed steps.
0 ok, 1 trap/error
bench-mod
vvm bench-mod <file> <export> [iters]
Profiles in-process decode+validate+lower microseconds, median/min/P95 execution milliseconds, step count, and 4 KiB CoW snapshot/restore latency over iters runs (default 5).
0 ok, 1 trap/error
wast
vvm wast <file.wast>
Executes a W3C .wast script (module, invoke, assert_return, assert_trap, assert_invalid) and prints pass/fail totals.
0 all pass, 1 any fail
studio
vvm studio [port] [--host <ip>] [--require-auth]
Starts the concurrent vvm Studio Web UI and OpenAPI 3.1.0 HTTP server (default 127.0.0.1:8089; configurable via VVM_STUDIO_HOST, VVM_STUDIO_PORT, VVM_STUDIO_REQUIRE_AUTH, and VVM_STUDIO_ADMIN_TOKEN).
Runs until stopped
audit
vvm audit [dir]
Scans dir (default .) for cyclomatic complexity (<= 12) and VVM-SEC-01..04 security invariants.
0 pass, 1 violation
docs
vvm docs [out_dir]
Synthesizes handbooks, compiles End-User (user/) and Technical (technical/) HTML documentation suites into out_dir (default dist/docs), and verifies documentation hygiene.
0 pass, 1 error
help
vvm help (--help, -h)
Displays CLI usage summary.
0
vvm run Flags
Flag
Default
Accepted Values
Behavior
--fuel <N|max>
100000000
Unsigned 64-bit integer, or max / unlimited / 0
Sets deterministic instruction and bulk-operation fuel budget for the invocation.
--real-clock
false (deterministic)
Boolean flag (presence enables)
Switches WASI monotonic and wall clocks from deterministic replay epoch (1.7e18 ns + 1 us/tick) to real host OS clocks.
2. vwasm Guest Compiler CLI Reference
vwasm compiles freestanding guest source modules directly into standard WebAssembly .wasm binaries (\0asm v1).
Uses seeded SplitMix64 PRNG (0x9e3779b97f4a7c15); set false for OS CSPRNG.
max_handles
16,384
Hard cap on active WASI descriptors, streams, futures, and waitable-sets.
max_vfs_bytes
67,108,864 (64 MiB)
Total in-memory Copy-on-Write virtual filesystem storage cap.
max_vfs_file_bytes
16,777,216 (16 MiB)
Maximum byte size of any single virtual file.
max_stream_bytes
1,048,576 (1 MiB)
Maximum buffered unread bytes per WasiStreamRing.
max_stdio_bytes
16,777,216 (16 MiB)
Maximum captured guest stdout + stderr output buffer.
max_random_bytes
1,048,576 (1 MiB)
Maximum bytes requested in a single random_get / get-random-bytes call.
4. Supported WASI Host Import Catalog
When wasi.module_needs_wasi detects WASI imports, vvm binds both WASI 0.3 (WASIp3) async primitives and the wasi_snapshot_preview1 compatibility bridge:
Generates interactive Light/Dark Benchmark Studio HTML and JSON telemetry
Every workload in the vvm benchmark suite is compiled into a standard .wasm binary, validated against the WebAssembly 3.0 specification, executed across vvm (-prod) and installed peer runtimes, and checked against a deterministic 32-bit mathematical checksum before any timing sample is accepted:
Host Environment: Windows x86_64 (AMD64 Family 26), 5 timed iterations per runtime after cache warmup, reporting median, min, and P95 latencies.
Two Architectural Runtime Tiers:
Tier 1 — Portable W^X Interpreters (vvm, WABT wasm-interp, WasmEdge Interpreter): Lower Wasm to compact internal bytecode in microseconds with zero RWX machine-code generation, minimal binary size (1.2–1.7 MB for WABT/vvm), deterministic instruction metering, and instant sandbox snapshotting.
Tier 2 — Native Machine-Code JITs (Wasmtime Winch/Cranelift, Wasmer Cranelift, Node.js V8): Embed 37–95 MB compiler backends that emit native x86_64/ARM64 machine instructions—trading binary footprint, JIT compile latency, and RWX/JIT memory pages for 5x–30x faster raw tight-loop arithmetic.
3.2 Cross-Runtime Net Execution Comparison (Median Milliseconds — Lower is Faster)
Workload
vvm (-prod In-Proc)
WABT Interp
WasmEdge Interp
Wasmtime Winch
Wasmtime Cranelift
Wasmer Cranelift
Node.js V8
01 Cold-Start / Spin-Up
0.037 ms (37 us)
25.43 ms CLI
38.61 ms CLI
18.92 ms CLI
19.85 ms CLI
42.10 ms CLI
0.185 ms V8 (54 ms CLI)
02 Recursive fib(31) (2.69M calls)
295.31 ms
484.13 ms
27,333.36 ms
12.44 ms
8.36 ms
9.18 ms
3.12 ms
03 CoreMark CPU Pipeline (CRC/Matrix/FSM)
162.72 ms
429.03 ms
21,883.68 ms
3.81 ms
1.94 ms
2.35 ms
1.48 ms
04 Prime Sieve (500 x 8,192 flags)
629.42 ms
1,422.29 ms
58,412.10 ms
9.62 ms
4.15 ms
4.89 ms
3.45 ms
05 PolyBench f64 Matrix Multiply (2.24M FMAs)
282.77 ms
567.37 ms
31,904.55 ms
5.14 ms
2.41 ms
2.76 ms
1.92 ms
06 ChaCha20 ARX / Hash Stream (vwasm)
227.24 ms
533.01 ms
29,110.42 ms
3.95 ms
1.72 ms
2.08 ms
1.39 ms
07 128-Bit SIMD f32x4 (5.12M lanes)
192.18 ms
225.94 ms
18,640.18 ms
1.89 ms
0.78 ms
0.94 ms
0.64 ms
08 Wasm 3.0 GC struct Trees (122,820 allocs)
49.85 ms
Unsupported
2,295.36 ms
Unsupported
3.86 ms
Unsupported
0.85 ms
4. Workload-by-Workload Engineering Analysis
Startup & Bytecode Lowering Latency (01_sightglass_noop, 37.0 us): Because vvm performs single-pass O(n) validation and B1+B3 Frame IR emission with zero machine-code register allocation or mprotect system calls, every .wasm module in the suite (61 B to 769 B) decodes, validates, lowers, and instantiates in 37 us to 285 us—supporting over 10,000 cold plugin instantiations per second per host core.
Branch-Dense Pipeline & Bitwise Hashing (03_coremark_pipeline at 162.6 MIPS, 06_vwasm_arx_crypto at 163.3 MIPS): Bitwise ARX rounds (add-rotate-XOR common to ChaCha20, BLAKE3, and SHA-256 compression schedules) and state-machine pipelines hit vvm's peak dispatch rate (163.3 MIPS) thanks to Option E3-A zero-copy local forwarding and fused compare-and-branch superinstructions (jump_if_i32_lt_s, jump_if_i32_ge_s, i32_add_imm).
Linear Memory Sieve & Bulk Fill (04_shootout_sieve, 139.5 MIPS): Executes 500 passes of memory.fill + byte-granular i32.load8_u/i32.store8 culling with single-comparison 64-bit bounds checks (offset + ea + size <= mem.data.len).
Floating-Point & Iterative Fractal / Mandelbrot Kernels (05_polybench_gemm_f64 at 138.0 MIPS, 07_simd_v128_f32x4 at 347M lane-ops/s): Dense IEEE 754 f64 matrix multiplication and iterative escape-time numeric kernels (such as Mandelbrot set evaluation and f32x4/f64x2 vector kernels) sustain 138 MIPS scalar and 347 millionf32 lane operations per second via the dedicated 16-byte aligned v128_stack side-array.
Managed WasmGC Struct Allocation (08_wasm30_gc_trees, 49.85 ms): Allocates and traverses 122,820TreeNode structs carrying unboxed 64-bit i31ref payloads (0 heap bytes for i31ref) and unwinds via a zero-cost try_table handler—running 46x faster than WasmEdge's interpreter (49.85 ms vs 2,295.36 ms).
vvm tracks linear memory mutations at 4 KiB sub-page granularity (16 sub-pages per 64 KiB Wasm page). Microsecond snapshot capture and time-travel restore latencies measured across the benchmark suite:
Workload Profile
Active Memory / Heap Footprint
CoW Snapshot Capture (us)
CoW Time-Travel Restore (us)
Max Sandbox Resets / Sec (1 Core)
01 Minimal Filter (1 page, 0 dirty sub-pages)
64 KiB (0 KiB dirty)
7.5 us
10.2 us
~98,000 / sec
02 Call-Intensive Kernel (0 dirty sub-pages)
64 KiB (0 KiB dirty)
15.5 us
5.7 us
~175,000 / sec
03 CoreMark State Buffers (1–2 dirty sub-pages)
64 KiB (8 KiB dirty)
11.4 us
7.2 us
~138,000 / sec
04 Prime Sieve (3 dirty 4 KiB sub-pages)
64 KiB (12 KiB dirty)
24.7 us
8.7 us
~114,000 / sec
05 Dense f64 Matrices (10 dirty sub-pages)
64 KiB (40 KiB dirty)
10.0 us
8.2 us
~121,000 / sec
08 Heavy WasmGC Arena (2,047+ live GC nodes)
Deep Option D1 struct arena
3,204.6 us
4,443.8 us
~225 / sec
6. Capacity Planning Guidelines
Memory Sizing per Concurrent Tenant Sandbox:
Base Store + frame[] + v128_stack overhead: ~640 KiB reserved virtual capacity (< 48 KiB resident for typical filters).
Linear memory ceiling: max_memory_pages * 64 KiB (for example, 16 pages = 1 MiB hard ceiling per tenant).
Recommended multi-tenant API filter profile (vgate / vwarden): max_fuel = 250,000, max_memory_pages = 16 (1 MiB), max_gc_objects = 4,096 -> supports 1,000+ concurrent isolated sandboxes per GiB of host RAM.
Unifies low-level byte buffers, garbage-collected object graphs, and 128-bit vector lanes inside each Store.
Core Functionality & Security Mechanics
Tracks 4 KiB Copy-on-Write dirty sub-pages for 5.7-10.2 us time-travel rollbacks
Stores structs/arrays via 32-bit ASLR-safe handles and unboxed 64-bit i31ref scalars
Executes all 256 0xFD fixed-width and deterministic Relaxed SIMD vector instructions
Host Control Plane
WASI 0.3 & Studio API
WASI 0.3 SandboxStudio Server
Component 6 of 6
Architectural Role & Purpose
Enforces zero-trust capability policies, WASI 0.3 stream/future rings, VVMS snapshots, and Studio HTTP UI.
Contextual Description & System Interaction
Connects sandboxed guest modules safely to vprevail, vgate, vwarden, vkbm, vllm, and vsight.
Core Functionality & Security Mechanics
Confines guest I/O via CapabilityPolicy, 64 MiB CoW VFS, and Preview 1 bridge
Seals VVMS v1 continuation snapshots with constant-time 32-byte SHA-256 digests
Serves 4-workspace Studio Web UI and HMAC-SHA256 authenticated OpenAPI 3.1.0 endpoints
Capability Pillar
What vvm Delivers
Primary Persona
WebAssembly 3.0 Core Engine
Full W3C Wasm 3.0 binary/text support: iso-recursive (rec ...) types, declared sub / sub final subtyping, WasmGC (struct, array, unboxed i31ref), try_table exceptions, return_call tail calls, Memory64, Multi-Memory, and 128-bit Fixed + Relaxed SIMD.
Guest Developers & Compiler Authors
16-Byte B1+B3 Frame IR
Single-pass lowering into 16-byte IrInst records (4 instructions per 64-byte CPU cache line) over unified frame[]u64 slots with 3-operand local forwarding and fused branch superinstructions (163.3 MIPS peak).
Sub-page 4 KiB Copy-on-Write dirty tracking (5.7–10.2 us restore) and "VVMS" v1 binary continuation envelopes protected by trailing 32-byte constant-time SHA-256 integrity digests.
Stateful Workflow & Edge Architects
Built-In vvm Studio & REST API
Light-Mode / Dark-Mode 4-workspace Web UI (/ui/auth, /ui/portal, /ui/delegated, /ui/admin) and OpenAPI 3.1.0 control plane for live .wat compilation, single-step IrInst debugging, and HMAC-SHA256 capability sessions.
Developers, Auditors & Operators
WAT / WAST & vwasm Toolchain
Folded and flat .wat parser/disassembler, B1+B3 IR disassembler, W3C .wast assertion runner (assert_return, assert_trap, assert_invalid), and vwasm guest compiler support.
QA & Toolchain Engineers
Visual Tour: vvm Studio & Cross-Runtime Benchmark Portal
Live WebAssembly 3.0 .wat Workbench & B1+B3 Frame IR Debugger
Cross-Runtime WebAssembly 3.0 Benchmark Studio (8 Standard Workloads)
Open http://127.0.0.1:8089/ui/portal in your browser to edit .wat modules live, mint HMAC-SHA256 capability sandbox tokens in /ui/auth, step individual 16-byte IrInst instructions, and inspect SHA-256 "VVMS" continuation snapshots.
Full 8-workload WebAssembly 3.0 benchmark results, B1+B3 dispatch throughput, CoW snapshot latency, and capacity sizing.
Part II: vvm — Step-by-Step How-To Guide
This guide provides task-oriented, copy-pasteable recipes for executing .wasm and .wat modules, configuring WASI capability sandboxes and fuel budgets, compiling guest programs with vwasm, running .wast conformance scripts, and debugging 16-byte B1+B3 Frame IR traces in vvm Studio.
Recipe 1: Inspect, Validate, and Execute .wasm and .wat Modules
vvm natively accepts both binary WebAssembly (.wasm, magic header \0asm) and folded or flat WebAssembly 3.0 Text Format (.wat) across all inspection and execution subcommands.
Step 1 — Author or Obtain a Module
Save the following Wasm 3.0 module with linear memory and exported functions as checksum.wat:
By default, vvm executes WASI modules inside a deterministic zero-trust capability sandbox:
Deterministic Clocks: Monotonic and wall clocks start at a fixed epoch (1,700,000,000,000,000,000 ns) and advance deterministically by 1,000 ns per clock read unless --real-clock is passed.
Deterministic Fuel Metering: Every executed IrInst deducts 1 fuel unit, and bulk memory/table/array operations deduct 1 + length / 64 fuel units before touching memory.
Bounded Copy-on-Write VFS: Preopened virtual paths live inside a quota-enforced in-memory Copy-on-Write filesystem (64 MiB total VFS ceiling, 16 MiB stdio cap, 16,384 max handles) with strict lexical .. traversal rejection.
Running a WASI Module with Strict Fuel vs Real Host Clocks
POWERSHELL
# Deterministic replay mode (fixed epoch clock + 2,500,000 instruction fuel ceiling)
vvm run --fuel 2500000 benchmarks/wasm/06_vwasm_arx_crypto.wasm bench
# Opt into real host wall/monotonic clock readings and unlimited fuel for trusted local CLI tools
vvm run --fuel max --real-clock benchmarks/wasm/04_shootout_sieve.wasm bench
Minting a Scoped Capability Policy Session via REST or Studio
Start vvm Studio on port 8089 and mint an HMAC-SHA256 capability token binding fuel, 64 KiB page ceilings, and allowed host import namespaces:
POWERSHELL
vvm studio 8089
Or mint the capability token directly from the command line:
Pass the returned token in Authorization: Bearer <token> on subsequent /api/v1/wat/execute calls to enforce those exact fuel, memory, and host import boundaries.
Recipe 3: Compile Guest Programs to WebAssembly with vwasm
The vwasm standalone WebAssembly guest compiler packaged alongside vvm in dist/bin/<os>/ compiles guest modules directly into compact, freestanding .wasm binaries with zero LLVM, Binaryen, or Emscripten dependencies.
Step 1 — Write a Freestanding Guest Kernel
Guest modules export functions using @[export: 'symbol_name'] so host sandboxes and CLI callers can invoke them directly by name:
Use -no-builtin for freestanding pure-compute kernels, and add -enable-globals when the guest module maintains stateful module-level globals across calls:
Recipe 4: Inspect B1+B3 IR Traces & "VVMS" Snapshots in vvm Studio
Step 1 — Launch Studio and Open /ui/portal
POWERSHELL
vvm studio 8089
Navigate to http://127.0.0.1:8089/ui/portal:
Paste any WebAssembly 3.0 .wat module into the WebAssembly 3.0 (.wat) Live Workbench editor.
Enter the target Export Function (for example, fib) and comma-separated Arguments (for example, 10, 0, 1).
Click Inspect IR to view the lowered 16-byte IrInst disassembly without executing, or click Compile & Execute to run the module inside a fresh capability sandbox.
Click Step 16B IrInst repeatedly to walk through the recorded instruction trace (step, PC, op, destination frame[rN] slot, 64-bit hex value, and remaining fuel).
Step 2 — Inspect the SHA-256 Authenticated "VVMS" Snapshot
Click VVMS Snapshot in the top navigation bar after executing any module to open the binary continuation inspector. The modal displays the "VVMS" v1 wire header (56 56 4D 53 01), total serialized payload size, dirty 4 KiB CoW sub-pages, WasmGC arena state, and trailing 32-byte SHA-256 integrity status:
Recipe 5: Run W3C .wast Specification & Regression Scripts
vvm includes a built-in .wast specification runner supporting (module ...), (invoke ...), (assert_return ...), (assert_trap ...), and (assert_invalid ...).
# CLI execution (exits 0 when all assertions pass, non-zero on any failure)
vvm wast arithmetic_checks.wast
# HTTP verification against a running vvm Studio daemon
curl -s -X POST http://127.0.0.1:8089/api/v1/wast/verify --data-binary "@arithmetic_checks.wast"
This guide walks application developers, language authors, and QA engineers through vvm's interactive Studio workspaces, WebAssembly 3.0 language features (WasmGC, Multi-Memory, Memory64, try_table, tail calls, and 128-bit SIMD), deterministic fuel metering, and Copy-on-Write (CoW) continuation snapshots.
1. Interactive vvm Studio Walkthrough
Launching vvm studio [port] (default port 8089) starts a zero-dependency HTTP server featuring a crisp Light-Mode default interface (#f8fafc slate canvas, #ffffff elevated cards) and instant one-click Dark-Mode switching persisted in localStorage.
The top bar organizes interactive workflows into four role-separated workspaces:
Workspace Route
Purpose
Key Controls & Telemetry
/ui/auth
Capability Gate
Mint HMAC-SHA256 Bearer capability tokens binding max_fuel, max_memory_pages, and allowed_imports.
/ui/portal
VM Debugger
Edit WebAssembly 3.0 .wat live, inspect B1+B3 IR, execute exports, single-step 16-byte IrInst traces, and monitor CoW + WasmGC counters.
/ui/delegated
Ecosystem Switchboard
Review multi-module Linker integration profiles across vprevail, vgate, vkbm, vllm, vsight, and vwarden.
/ui/admin
Telemetry & Audit
Trigger live static complexity (<= 12) and VVM-SEC-01..04 security verification across the runtime workspace.
When you click Step 16B IrInst, vvm Studio highlights the active destination slot row in frame[]u64 and updates the Program Counter badge with the instruction mnemonic, destination value, and exact remaining fuel.
2. Using WebAssembly 3.0 Features in vvm
2.1 Managed WasmGC (rec, struct, array, and Unboxed i31ref)
vvm implements the complete WebAssembly 3.0 Garbage Collection specification (Option D1 per-Store typed arenas) with iso-recursive (rec ...) type groups, sub / sub final subtyping, mutable/immutable structs and arrays, bulk segment initializers (array.new_data, array.init_data, array.new_elem, array.init_elem), and zero-allocation 31-bit tagged scalar references (ref.i31, i31.get_s, i31.get_u).
try_table Exception Handling: Declare typed exception tags with (tag $err (param i32)), raise exceptions via (throw $err ...), and catch them cleanly with (try_table (catch $err $label) ...) (catch, catch_ref, catch_all, catch_all_ref) without legacy stack-frame probing overhead on the non-throwing path.
Guaranteed O(1) Tail Calls: Both direct (return_call $fn ...) and indirect/typed (return_call_indirect ...) / (return_call_ref ...) reuse the current call frame in place, enabling unbounded state-machine transitions and functional recursion within a constant call-stack depth of 1.
2.3 Multi-Memory, Memory64, and 4 KiB Copy-on-Write Rollbacks
Multi-Memory: A single module can declare or import multiple independent linear memories ((memory $scratch 1 4), (memory $ring 2 8)) and address them explicitly in load/store/bulk instructions (i32.load $ring, memory.copy $ring $scratch).
64-Bit Memory64: Declare 64-bit linear memories (i64 index space) while preserving strict host bounds ceilings (max_memory_pages).
4 KiB CoW Sub-Page Tracking & "VVMS" Snapshots: Each 64 KiB Wasm page is subdivided into sixteen 4 KiB CoW sub-pages. Only dirtied 4 KiB sub-pages are copied prior to first mutation, allowing instant rollback or serialization into an authenticated "VVMS" binary continuation envelope:
Untrusted guest code must never stall a host worker thread. vvm enforces deterministic execution budgets at two levels:
Scalar & Control Instructions (1 fuel per IrInst): Every arithmetic op, local copy, branch, call, WasmGC allocation, and SIMD instruction decrements store.fuel by 1.
Bulk Memory, Table & GC Array Instructions (1 + length / 64 fuel): Bulk operations (memory.fill, memory.copy, memory.init, table.fill, table.copy, table.init, array.fill, array.copy, array.init_data, array.init_elem) validate bounds first (preserving W3C OOB trap precedence) and then deduct fuel proportional to element/byte count (1 + n / 64) before writing—preventing multi-megabyte zero-fuel amplification attacks.
When fuel reaches 0, execution halts cleanly with an out of fuel trap and leaves the host process completely unaffected.
4. Profiling Your Own Modules with vvm bench-mod
Before deploying a plugin to production, measure its exact decode+validate+lower time, execution latency, instruction count, MIPS rate, and 4 KiB CoW snapshot/restore cost with vvm bench-mod:
Part IV: vvm — Administrator & Sandbox Governance Guide
This guide covers production deployment, multi-tenant resource governance, WASI capability isolation, HTTP Studio daemon security, and continuous runtime verification for platform operators and security administrators.
1. Installation & Release Package Layout
Official vvm release archives (vvm-windows-x64.zip, vvm-linux-x64.tar.gz, and vvm-macos-universal.tar.gz or vvm-macos-src.tar.gz with build-macos.sh when cross-packaged) are verified against SHA256SUMS.txt and extract cleanly with zero external shared libraries:
# Windows PowerShell
Get-FileHash .\vvm-windows-x64.zip -Algorithm SHA256
BASH
# Linux / macOS
sha256sum -c SHA256SUMS.txt
2. Multi-Tenant Sandbox Resource Governance
Every vvmStore and HostSandbox instance is completely isolated—sharing zero mutable globals, linear memories, tables, or WasmGC arenas with sibling tenants. Administrators govern untrusted tenants across six hard resource dimensions:
Resource Dimension
Default Engine Ceiling
Studio HTTP Ceiling
Protection Provided
Instruction & Bulk Fuel (max_fuel)
100,000,000 CLI (5,000,000 Studio default)
50,000,000 max
Terminates infinite loops and charges 1 + n / 64 fuel on bulk memory/table/GC copies.
Linear Memory (max_memory_pages)
16,384 pages (1 GiB)
512 pages (32 MiB)
Overrides guest-declared maximums and returns -1 on memory.grow attempts past the host quota.
WasmGC Live Heap (max_gc_objects)
Configurable per CapabilityPolicy (16,384 Studio default)
65,536 live objects
Triggers automatic tri-color mark-sweep GC at quota threshold; traps if live reachable objects still exceed quota.
Call-Stack Depth & Frame Slots
2,048 active frames / 1,048,576u64 slots
2,048 frames / 1,048,576 slots
Prevents host OS thread stack exhaustion on deep mutual recursion (call stack exhausted trap).
vvm enforces a strict default-deny capability model (CapabilityPolicy + WasiConfig):
Host Import Namespace Allowlisting (allowed_host_modules): A guest module importing "vgate.http", "vprevail.raft", or "wasi_snapshot_preview1" fails instantiation immediately unless that exact module namespace is present in the sandbox's allowlist.
Every path is normalized lexically; any .. parent-directory segment, null byte, or drive-letter escape is rejected before lookup.
Sibling prefix confusion is blocked at segment boundaries (for example, allowlisting /sandbox/tenant_a automatically denies /sandbox/tenant_a_evil/secret.txt).
Guest file writes mutate an in-memory Copy-on-Write VFS layer bounded by max_vfs_bytes (64 MiB default) and max_vfs_file_bytes (16 MiB default), preventing host disk filling.
max_random_bytes: 1 MiB per random_get / get-random-bytes call (backed by OS CSPRNG when deterministic_random: false, or SplitMix64 PRNG for deterministic replay).
Explicit Network Gate (allow_network: false by default): Two-Tier WasiNet outbound HTTP (vgate) and DNS (vnet) hooks remain disabled unless explicitly enabled and bound by the host administrator.
4. Administering the vvm Studio HTTP Daemon
4.1 Binding & Network Hardening
vvm studio [port] [--host <ip>] [--require-auth] binds strictly to loopback (127.0.0.1:<port>) by default so interactive debugging endpoints are never accidentally exposed on untrusted LAN/WAN interfaces. When publishing vvm Studio to remote engineering teams, set VVM_STUDIO_ADMIN_TOKEN (which automatically activates --require-auth) and place it behind an authenticating reverse proxy (such as vgate with vwarden OIDC/MFA) over TLS 1.3.
Built-in HTTP transport defenses enforced on every connection:
Bounded Concurrency & Graceful Shutdown: Handles TCP clients concurrently behind a 64-slot semaphore, logs structured [vvm-http] telemetry, and shuts down cleanly on SIGINT/SIGTERM.
Confined Static Asset Router (/docs/*, /benchmarks/*): Serves only allowlisted extensions (.html, .svg, .png, .json) under dist/docs/ and dist/benchmarks/ and returns 400 Bad Request on any .. or disallowed path character.
4.2 Ephemeral HMAC-SHA256 Session Governance
On startup, the Studio daemon generates a fresh 32-byte OS CSPRNG secret in memory (failing closed if OS entropy is unavailable). Capability tokens minted via /ui/auth or POST /api/v1/auth/session encode vvm1|<max_fuel>|<max_memory_pages>|<exp_unix>|<allowed_imports> (1-hour TTL) signed with HMAC-SHA256 and verified in constant time (hmac.equal). Restarting the daemon immediately invalidates all previously issued tokens.
4.3 Running Live Workspace & Security Audits
Administrators can verify runtime integrity either from the CLI (vvm audit) or interactively from /ui/admin (GET /api/v1/audit/status):
POWERSHELL
vvm audit .
Audit Gate
Rule Enforced
Expected Production Status
COMPLEXITY-12
Every function across all runtime subsystems maintains cyclomatic complexity <= 12.
PASS
VVM-SEC-01
Zero OS shell execution primitives anywhere in runtime, decoder, validator, VM, WASI, or HTTP modules.
PASS
VVM-SEC-02
Zero external C header inclusions in runtime subsystems (100% memory-safe native structures).
PASS
VVM-SEC-03
Zero blocking browser alert or prompt dialogs; strict JSON/HTML escaping and CSP headers.
PASS
VVM-SEC-04
Clean workspace governance with zero stray VCS metadata leaks.
PASS
Part V: vvm — Operations & Real-World Use Cases
vvm is engineered to embed directly inside latency-sensitive gateways, distributed consensus state machines, policy engines, AI agent tool sandboxes, and CI conformance pipelines without pulling in heavy C++ or LLVM JIT dependencies. This guide presents concrete production patterns using WebAssembly 3.0 .wat, .wast, CLI commands, and HTTP control-plane requests.
Use Case 1: Sub-Millisecond Serverless & API Gateway Edge Filters (vgate)
Modern API gateways allow tenants to upload custom header-routing, rate-limiting, or payload-scrubbing plugins. Native shared libraries risk crashing the proxy on a single null pointer, whereas multi-process containers add tens of milliseconds of cold-start overhead.
Why vvm Fits:
Microsecond Spin-Up: Decoding, validating, lowering to 16-byte B1+B3 Frame IR, and instantiating a filter takes 37–180 us.
return_call State Machines: Finite-state HTTP header parsers run in O(1) stack space via WebAssembly 3.0 tail calls.
Strict Per-Request Fuel: Setting --fuel 50000 guarantees every tenant filter completes in under half a millisecond or traps cleanly.
# 1. Mint a capability token allowing ONLY vgate.http with a 50,000-instruction fuel budget
curl -s -X POST http://127.0.0.1:8089/api/v1/auth/session `
-H "Content-Type: application/json" `
-d '{"max_fuel":50000,"max_memory_pages":2,"allowed_imports":"vgate.http"}'
# 2. Validate and inspect lowered 16-byte Frame IR via REST
curl -s -X POST http://127.0.0.1:8089/api/v1/wat/inspect `
-H "Content-Type: application/json" `
-d '{"wat":"(module (func (export \"ping\") (result i32) (i32.const 200)))"}'
Use Case 2: Deterministic Smart-Contract, Policy & Lease Evaluation (vwarden)
Zero-trust policy engines and distributed ledgers require bit-exact determinism: every node evaluating the same policy or contract against the same inputs must produce the exact same result and consume the exact same gas budget, with zero access to ambient host time, randomness, or network sockets.
Why vvm Fits:
Canonical IEEE 754 & Deterministic Relaxed SIMD: Floating-point and vector operations behave identically across x86_64 and ARM64.
Deterministic Clocks & SplitMix64 PRNG: Ambient OS entropy and wall-clock drift are isolated by default.
Use Case 3: Speculative Rollbacks & Durable Workflows (vprevail)
Stateful workflow engines, database stored procedures, and AI planning sandboxes frequently need to checkpoint a warmed guest VM, test multiple speculative branches, discard failed transactions in microseconds, or persist a continuation to durable storage.
Why vvm Fits:
4 KiB Sub-Page Copy-on-Write (CoW): Capturing and restoring linear memory + globals + tables takes 5.7–24.7 us on scalar/memory workloads because untouched 4 KiB sub-pages are never copied.
SHA-256 Authenticated "VVMS" Envelopes: Serialized snapshots include magic bytes 56 56 4D 53 01 and a trailing 32-byte SHA-256 digest verified in constant time before restore—preventing corrupted or tampered state injection.
###Host Embedding Pattern (Conceptual Flow)
TEXT
1. Instantiate module into Store and invoke initialization export
2. Enable 4 KiB sub-page CoW tracking on Store linear memories
3. Capture baseline VmSnapshot (or encode to SHA-256 "VVMS" binary bytes)
4. Invoke speculative transaction branch:
- On commit: keep mutated Store state (or persist updated "VVMS" checkpoint)
- On abort/trap: restore VmSnapshot in ~7 microseconds to exact pre-transaction state
Use Case 4: Managed DSLs, Graph Queries & Functional Closures (vkbm / vllm)
Compilers for garbage-collected DSLs, graph query engines, and typed functional languages traditionally had to bundle their own 100 KB+ linear-memory allocator and shadow-stack garbage collector inside every .wasm module.
Iso-Recursive Multi-Module Linking: Two separate modules declaring structurally identical (rec (type $Node ...)) definitions link together seamlessly across Linker boundaries while rejecting mismatched field layouts at link time.
Use Case 5: Automated W3C WAST Conformance Gating in CI/CD
Compiler teams generating WebAssembly 3.0 modules can gate every pull request or release artifact using vvm wast to test positive return values, expected runtime traps (division by zero, out-of-bounds memory, unreachable, fuel exhaustion), and negative static validation cases (assert_invalid):
Part VI: vvm — Configuration, CLI, Sandbox Policy & API Reference
This reference documents all vvm and vwasm command-line subcommands and flags, sandbox policy schemas, WASI 0.3 and wasi_snapshot_preview1 host import namespaces, and the vvm Studio OpenAPI 3.1.0 HTTP endpoints.
1. vvm Command-Line Interface Reference
TEXT
Usage: vvm <command> [arguments]
Subcommand
Syntax
Description
Exit Codes
version
vvm version (--version, -v)
Prints vvm runtime version, WebAssembly 3.0 spec target, B1+B3 IR architecture, WasmGC heap mode, WASI 0.3 target, and 4 KiB CoW support.
0
inspect
vvm inspect <file.wasm|file.wat>
Decodes binary or text module and prints byte size, recursive type groups, imports, functions, tables, memories, tags, globals, exports, segments, and custom sections.
0 valid, 1 error
validate
vvm validate <file.wasm|file.wat>
Runs static WebAssembly 3.0 Chapter 3 validation (iso-recursive types, subtyping, stack polymorphism, non-null local initialization) and reports canonical type/function counts.
0 valid, 1 invalid
disasm
vvm disasm <file.wasm|file.wat>
Disassembles any binary .wasm or .wat module into canonical WebAssembly 3.0 .wat text format on stdout.
0 ok, 1 error
ir
vvm ir <file.wasm|file.wat>
Validates, lowers to 16-byte B1+B3 Frame IR, and prints per-function frame layouts (params, locals, max_stack, total_slots, v128_slots) and IrInst listings.
0 ok, 1 error
run
vvm run [--fuel <N|max>] [--real-clock] <file> [export] [args...]
Instantiates the module (auto-binding WASI 0.3 & Preview 1 when imported), invokes export (default _start), flushes WASI stdout, and prints return values + executed steps.
0 ok, 1 trap/error
bench-mod
vvm bench-mod <file> <export> [iters]
Profiles in-process decode+validate+lower microseconds, median/min/P95 execution milliseconds, step count, and 4 KiB CoW snapshot/restore latency over iters runs (default 5).
0 ok, 1 trap/error
wast
vvm wast <file.wast>
Executes a W3C .wast script (module, invoke, assert_return, assert_trap, assert_invalid) and prints pass/fail totals.
0 all pass, 1 any fail
studio
vvm studio [port] [--host <ip>] [--require-auth]
Starts the concurrent vvm Studio Web UI and OpenAPI 3.1.0 HTTP server (default 127.0.0.1:8089; configurable via VVM_STUDIO_HOST, VVM_STUDIO_PORT, VVM_STUDIO_REQUIRE_AUTH, and VVM_STUDIO_ADMIN_TOKEN).
Runs until stopped
audit
vvm audit [dir]
Scans dir (default .) for cyclomatic complexity (<= 12) and VVM-SEC-01..04 security invariants.
0 pass, 1 violation
docs
vvm docs [out_dir]
Synthesizes handbooks, compiles End-User (user/) and Technical (technical/) HTML documentation suites into out_dir (default dist/docs), and verifies documentation hygiene.
0 pass, 1 error
help
vvm help (--help, -h)
Displays CLI usage summary.
0
vvm run Flags
Flag
Default
Accepted Values
Behavior
--fuel <N|max>
100000000
Unsigned 64-bit integer, or max / unlimited / 0
Sets deterministic instruction and bulk-operation fuel budget for the invocation.
--real-clock
false (deterministic)
Boolean flag (presence enables)
Switches WASI monotonic and wall clocks from deterministic replay epoch (1.7e18 ns + 1 us/tick) to real host OS clocks.
2. vwasm Guest Compiler CLI Reference
vwasm compiles freestanding guest source modules directly into standard WebAssembly .wasm binaries (\0asm v1).
Uses seeded SplitMix64 PRNG (0x9e3779b97f4a7c15); set false for OS CSPRNG.
max_handles
16,384
Hard cap on active WASI descriptors, streams, futures, and waitable-sets.
max_vfs_bytes
67,108,864 (64 MiB)
Total in-memory Copy-on-Write virtual filesystem storage cap.
max_vfs_file_bytes
16,777,216 (16 MiB)
Maximum byte size of any single virtual file.
max_stream_bytes
1,048,576 (1 MiB)
Maximum buffered unread bytes per WasiStreamRing.
max_stdio_bytes
16,777,216 (16 MiB)
Maximum captured guest stdout + stderr output buffer.
max_random_bytes
1,048,576 (1 MiB)
Maximum bytes requested in a single random_get / get-random-bytes call.
4. Supported WASI Host Import Catalog
When wasi.module_needs_wasi detects WASI imports, vvm binds both WASI 0.3 (WASIp3) async primitives and the wasi_snapshot_preview1 compatibility bridge:
Generates interactive Light/Dark Benchmark Studio HTML and JSON telemetry
Every workload in the vvm benchmark suite is compiled into a standard .wasm binary, validated against the WebAssembly 3.0 specification, executed across vvm (-prod) and installed peer runtimes, and checked against a deterministic 32-bit mathematical checksum before any timing sample is accepted:
Host Environment: Windows x86_64 (AMD64 Family 26), 5 timed iterations per runtime after cache warmup, reporting median, min, and P95 latencies.
Two Architectural Runtime Tiers:
Tier 1 — Portable W^X Interpreters (vvm, WABT wasm-interp, WasmEdge Interpreter): Lower Wasm to compact internal bytecode in microseconds with zero RWX machine-code generation, minimal binary size (1.2–1.7 MB for WABT/vvm), deterministic instruction metering, and instant sandbox snapshotting.
Tier 2 — Native Machine-Code JITs (Wasmtime Winch/Cranelift, Wasmer Cranelift, Node.js V8): Embed 37–95 MB compiler backends that emit native x86_64/ARM64 machine instructions—trading binary footprint, JIT compile latency, and RWX/JIT memory pages for 5x–30x faster raw tight-loop arithmetic.
3.2 Cross-Runtime Net Execution Comparison (Median Milliseconds — Lower is Faster)
Workload
vvm (-prod In-Proc)
WABT Interp
WasmEdge Interp
Wasmtime Winch
Wasmtime Cranelift
Wasmer Cranelift
Node.js V8
01 Cold-Start / Spin-Up
0.037 ms (37 us)
25.43 ms CLI
38.61 ms CLI
18.92 ms CLI
19.85 ms CLI
42.10 ms CLI
0.185 ms V8 (54 ms CLI)
02 Recursive fib(31) (2.69M calls)
295.31 ms
484.13 ms
27,333.36 ms
12.44 ms
8.36 ms
9.18 ms
3.12 ms
03 CoreMark CPU Pipeline (CRC/Matrix/FSM)
162.72 ms
429.03 ms
21,883.68 ms
3.81 ms
1.94 ms
2.35 ms
1.48 ms
04 Prime Sieve (500 x 8,192 flags)
629.42 ms
1,422.29 ms
58,412.10 ms
9.62 ms
4.15 ms
4.89 ms
3.45 ms
05 PolyBench f64 Matrix Multiply (2.24M FMAs)
282.77 ms
567.37 ms
31,904.55 ms
5.14 ms
2.41 ms
2.76 ms
1.92 ms
06 ChaCha20 ARX / Hash Stream (vwasm)
227.24 ms
533.01 ms
29,110.42 ms
3.95 ms
1.72 ms
2.08 ms
1.39 ms
07 128-Bit SIMD f32x4 (5.12M lanes)
192.18 ms
225.94 ms
18,640.18 ms
1.89 ms
0.78 ms
0.94 ms
0.64 ms
08 Wasm 3.0 GC struct Trees (122,820 allocs)
49.85 ms
Unsupported
2,295.36 ms
Unsupported
3.86 ms
Unsupported
0.85 ms
4. Workload-by-Workload Engineering Analysis
Startup & Bytecode Lowering Latency (01_sightglass_noop, 37.0 us): Because vvm performs single-pass O(n) validation and B1+B3 Frame IR emission with zero machine-code register allocation or mprotect system calls, every .wasm module in the suite (61 B to 769 B) decodes, validates, lowers, and instantiates in 37 us to 285 us—supporting over 10,000 cold plugin instantiations per second per host core.
Branch-Dense Pipeline & Bitwise Hashing (03_coremark_pipeline at 162.6 MIPS, 06_vwasm_arx_crypto at 163.3 MIPS): Bitwise ARX rounds (add-rotate-XOR common to ChaCha20, BLAKE3, and SHA-256 compression schedules) and state-machine pipelines hit vvm's peak dispatch rate (163.3 MIPS) thanks to Option E3-A zero-copy local forwarding and fused compare-and-branch superinstructions (jump_if_i32_lt_s, jump_if_i32_ge_s, i32_add_imm).
Linear Memory Sieve & Bulk Fill (04_shootout_sieve, 139.5 MIPS): Executes 500 passes of memory.fill + byte-granular i32.load8_u/i32.store8 culling with single-comparison 64-bit bounds checks (offset + ea + size <= mem.data.len).
Floating-Point & Iterative Fractal / Mandelbrot Kernels (05_polybench_gemm_f64 at 138.0 MIPS, 07_simd_v128_f32x4 at 347M lane-ops/s): Dense IEEE 754 f64 matrix multiplication and iterative escape-time numeric kernels (such as Mandelbrot set evaluation and f32x4/f64x2 vector kernels) sustain 138 MIPS scalar and 347 millionf32 lane operations per second via the dedicated 16-byte aligned v128_stack side-array.
Managed WasmGC Struct Allocation (08_wasm30_gc_trees, 49.85 ms): Allocates and traverses 122,820TreeNode structs carrying unboxed 64-bit i31ref payloads (0 heap bytes for i31ref) and unwinds via a zero-cost try_table handler—running 46x faster than WasmEdge's interpreter (49.85 ms vs 2,295.36 ms).
vvm tracks linear memory mutations at 4 KiB sub-page granularity (16 sub-pages per 64 KiB Wasm page). Microsecond snapshot capture and time-travel restore latencies measured across the benchmark suite:
Workload Profile
Active Memory / Heap Footprint
CoW Snapshot Capture (us)
CoW Time-Travel Restore (us)
Max Sandbox Resets / Sec (1 Core)
01 Minimal Filter (1 page, 0 dirty sub-pages)
64 KiB (0 KiB dirty)
7.5 us
10.2 us
~98,000 / sec
02 Call-Intensive Kernel (0 dirty sub-pages)
64 KiB (0 KiB dirty)
15.5 us
5.7 us
~175,000 / sec
03 CoreMark State Buffers (1–2 dirty sub-pages)
64 KiB (8 KiB dirty)
11.4 us
7.2 us
~138,000 / sec
04 Prime Sieve (3 dirty 4 KiB sub-pages)
64 KiB (12 KiB dirty)
24.7 us
8.7 us
~114,000 / sec
05 Dense f64 Matrices (10 dirty sub-pages)
64 KiB (40 KiB dirty)
10.0 us
8.2 us
~121,000 / sec
08 Heavy WasmGC Arena (2,047+ live GC nodes)
Deep Option D1 struct arena
3,204.6 us
4,443.8 us
~225 / sec
6. Capacity Planning Guidelines
Memory Sizing per Concurrent Tenant Sandbox:
Base Store + frame[] + v128_stack overhead: ~640 KiB reserved virtual capacity (< 48 KiB resident for typical filters).
Linear memory ceiling: max_memory_pages * 64 KiB (for example, 16 pages = 1 MiB hard ceiling per tenant).
Recommended multi-tenant API filter profile (vgate / vwarden): max_fuel = 250,000, max_memory_pages = 16 (1 MiB), max_gc_objects = 4,096 -> supports 1,000+ concurrent isolated sandboxes per GiB of host RAM.