Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 38 ยท WASI and Beyond the Browser

Running WebAssembly Outside the Browser

Learn how to run WebAssembly on servers and the command line - Wasmtime, Wasmer, WasmEdge, wazero, Node.js and Deno - with args, environment, preopens, exit codes and embedding examples.

Browsers made WebAssembly famous, but the qualities that suit it to the web (small, fast to start, safe to run untrusted code, portable across CPUs) are just as valuable on servers. Today you can run .wasm files straight from a terminal, embed an engine inside your own application to run plugins, or use WebAssembly as a lightweight alternative to containers.

This lesson surveys the runtimes, shows the commands you will actually type, and demonstrates the host side of the story: passing arguments and environment variables, collecting exit codes, and giving a module access to directories.

The runtimes

A runtime (or engine) loads a module, validates it, compiles or interprets it and provides the imports. Several mature ones exist:

Runtime Written in Notes
Wasmtime Rust Reference-quality WASI and component model support; from the Bytecode Alliance
Wasmer Rust Several compiler backends; package registry; embeddable in many languages
WasmEdge C++ Cloud and edge focus; extensions for networking and AI
wazero Go Zero-dependency runtime for embedding in Go programs
wasm3, WAMR C Interpreters and small engines for constrained devices
Node.js, Deno, Bun C++ / Rust / Zig JavaScript runtimes with the full WebAssembly API and WASI support

Most of them compile code ahead of time or just in time to native machine code. Interpreters trade speed for tiny size and easy porting, which matters on microcontrollers.

Ways to run a module

Command line wasmtime app.wasm, one command.
Embedded A library inside your own app.
JS runtimes Node, Deno and Bun.
Edge platforms Functions at CDN locations.

Same module, many hosts.

1 / 2

Command-line use

With a WASI-compiled program, running looks like running any other executable. The commands below are read-only here; they show what you would do on your own machine.

Terminal
# Wasmtime: run a command-style module
wasmtime run app.wasm

# Pass program arguments after the module name
wasmtime run app.wasm -- --verbose input.txt

# Give it environment variables
wasmtime run --env GREETING=hello app.wasm

# Map a host directory into the sandbox (host::guest)
wasmtime run --dir ./data::/data app.wasm

# Call one exported function of a library module
wasmtime run --invoke add add.wasm 20 22

# Wasmer
wasmer run app.wasm -- arg1 arg2

# Node.js (WASI is built in, behind a stable-ish module)
node run-wasi.mjs

# Deno
deno run --allow-read app.js

The --dir host::guest option is the preopen from the last lesson. Without it the program sees no filesystem at all, even if the host machine has plenty. That is the sandbox working as intended.

Passing arguments, environment and exit codes

A WASI program learns its arguments through args_sizes_get and args_get, its environment through environ_sizes_get and environ_get, and ends with proc_exit(code). The module below does the minimal useful thing: it asks how many arguments it received and exits with that number as its exit code. That lets us watch the host side with no printing at all:

Node.js Arguments and exit codes with node:wasi

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice returnOnExit: true. Without it, a call to proc_exit ends the whole Node process, exactly as exit() would in a native program. A plugin host must set it so one misbehaving module cannot terminate the application.

What the host supplies

Node's WASI object implements the whole Preview 1 import list. You can ask the object what it provides, which is a handy way to learn the API surface:

Node.js The WASI Preview 1 functions Node implements

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

You will see the families: fd_* operate on open file descriptors, path_* take a descriptor plus a relative path (the capability model in action: you cannot name a path without a directory handle), clock_*, random_get, args_*, environ_*, poll_oneoff, proc_exit, and sock_* for already-open sockets.

Embedding an engine in your own program

The command line is only one use. Every major runtime is also a library, so your application can host modules:

Rust
// Rust, with the wasmtime crate
use wasmtime::*;

fn main() -> Result<()> {
    let engine = Engine::default();
    let module = Module::from_file(&engine, "add.wasm")?;
    let mut store = Store::new(&engine, ());
    let instance = Instance::new(&mut store, &module, &[])?;
    let add = instance.get_typed_func::<(i32, i32), i32>(&mut store, "add")?;
    println!("{}", add.call(&mut store, (20, 22))?);
    Ok(())
}
Go
// Go, with wazero (no cgo, no dependencies)
ctx := context.Background()
r := wazero.NewRuntime(ctx)
defer r.Close(ctx)
mod, _ := r.Instantiate(ctx, wasmBytes)
results, _ := mod.ExportedFunction("add").Call(ctx, 20, 22)
fmt.Println(results[0])

Python (wasmtime package), .NET, Ruby, PHP, Java and others have equivalent embeddings. This is how products add safe plugins: the host defines the allowed imports, the plugin runs in its own memory, and a bug or an attack in the plugin cannot read the host's data. See Plugin Systems with WebAssembly.

Resource limits

A runtime can bound what a module consumes, something the browser handles for you but servers must configure:

  • Memory: cap the maximum pages a module may grow to.
  • Time (fuel or epoch interruption): Wasmtime can count instructions ("fuel") or interrupt after a deadline, so an infinite loop cannot hang a request.
  • Stack depth: deep recursion traps instead of crashing the host.
  • Imports: simply do not provide dangerous functions.

Ahead-of-time compilation

For fast startup in serverless settings, runtimes can precompile a module to a native artifact (wasmtime compile app.wasm -o app.cwasm) and load that later, skipping compilation. Instantiating a precompiled module takes microseconds, which is why Wasm is attractive for per-request isolation.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a preopened directory do?

    The host maps a directory into the sandbox. Paths outside it cannot be named by the module.
  2. 2. Why set returnOnExit: true when hosting modules in Node?

    By default proc_exit terminates the process. A host that runs untrusted plugins must keep control.
  3. 3. Which runtime is a zero-dependency WebAssembly runtime written in Go?

    wazero is pure Go, so Go programs can embed it without cgo.
  4. 4. How can a host stop a plugin stuck in an infinite loop?

    Runtimes like Wasmtime count instructions or check deadlines so runaway code is interrupted with a trap.

Summary

  • Runtimes such as Wasmtime, Wasmer, WasmEdge, wazero, Node, Deno and Bun run .wasm outside browsers, from the command line or embedded as libraries.
  • The host controls arguments, environment, preopened directories, limits and the exit code.
  • returnOnExit (or its equivalent) keeps a plugin host in charge when a module exits.
  • Ahead-of-time compilation makes startup nearly instant for per-request sandboxes.
  • Hosts can cap memory, time and imports, which is the foundation for safe plugin systems.

Next: The Component Model and WIT