Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 38 ยท WASI and Beyond the Browser

What is WASI? The WebAssembly System Interface

Understand WASI, the WebAssembly System Interface - capabilities, preopened directories, fd_write, args and environment, preview1 vs preview2 - with runnable Node WASI and hand-written host examples.

A WebAssembly module on its own is completely sealed. It can compute, but it cannot print a line, read a file, ask for the time or open a socket, because the core specification contains no instructions for any of that. In a browser the surrounding JavaScript fills the gap by providing imports. But when you want to run a module outside a browser, as a command-line tool, a server plugin or a cloud function, you need a standard answer to the question: "what does the module import to talk to the operating system?"

That answer is WASI, the WebAssembly System Interface. It is a set of standardized imports that a module can call for files, clocks, random numbers, environment variables and (increasingly) sockets. If a host implements WASI, then any WASI-compiled module runs on it unchanged: on Linux, Windows, macOS, in an edge runtime or in a plugin host.

The idea in one picture

flowchart LR
  A["Your source: C, Rust, Go, ..."] --> B["Compiler with a wasi target"]
  B --> C["app.wasm (imports wasi functions)"]
  C --> D["Runtime: wasmtime, wasmer, Node, Deno"]
  D --> E["Host OS: files, clock, random, stdout"]

The module calls WASI functions; the runtime decides what each call is allowed to do on the real system.

WASI is the WebAssembly counterpart of the POSIX layer that C programs use. Programs call fd_write instead of write, and path_open instead of open. The standard library of the source language (Rust std, C libc through wasi-libc, Go's syscall) is ported to call these imports, so most of your ordinary code works after recompiling.

Capabilities: security by design

A native program normally inherits all the permissions of the user who runs it. WASI inverts this with a capability-based model: a module can only touch what the host explicitly hands it.

  • There is no global filesystem. The host preopens directories and gives the module descriptors for them. The module can open files inside those directories but cannot name /etc/passwd unless the host mounted /etc.
  • Network access, environment variables and clocks are also granted, not ambient.
  • Anything not granted simply fails with an error code (EBADF, ENOENT, ENOTCAPABLE).

WASI in four ideas

Imports A standard list of host functions.
Capabilities Only what the host grants.
Preopens Mounted folders, nothing else.
Portable Same .wasm on any runtime.

Sandbox first, features second.

1 / 2

Preview 1 and what comes next

The first widely deployed version is called WASI Preview 1 (wasi_snapshot_preview1, also called "wasip1"). It is a flat list of about 45 functions modelled on POSIX file descriptors. Nearly every runtime and toolchain supports it, so it is what you use today for command-line programs.

WASI Preview 2 (wasip2) rebuilt the interface on the component model (next lessons). Instead of flat integer-and-pointer functions it describes typed interfaces such as wasi:filesystem, wasi:cli, wasi:http and wasi:sockets in an interface language called WIT. Preview 2 is the base for new work, while Preview 1 remains important for existing tools.

A tiny WASI program

The module below is what a compiler produces for a "hello world" without any libraries. It imports fd_write from wasi_snapshot_preview1, exports its memory and an entry point named _start. In text format:

WAT
(module
  (import "wasi_snapshot_preview1" "fd_write"
    (func $fd_write (param i32 i32 i32 i32) (result i32)))
  (memory (export "memory") 1)
  (data (i32.const 8) "Hello from WASI!\n")
  (func (export "_start")
    ;; build an iovec at address 0: { buf = 8, len = 17 }
    (i32.store (i32.const 0) (i32.const 8))
    (i32.store (i32.const 4) (i32.const 17))
    ;; fd_write(fd=1, iovs=0, iovs_len=1, nwritten_ptr=40)
    (drop (call $fd_write (i32.const 1) (i32.const 0) (i32.const 1) (i32.const 40)))))

fd_write takes a file descriptor (1 is stdout, 2 is stderr), a pointer to an array of iovecs (each a buffer pointer and length, so several pieces can be written at once), the number of iovecs, and a pointer where the host stores how many bytes were written. It returns an error code, 0 for success.

Node.js ships a WASI implementation in the node:wasi module. Giving it the compiled module is all it takes:

Node.js Run a WASI module 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.

The text "Hello from WASI!" is written by the module through the host's fd_write, not by JavaScript.

What WASI really is: just imports

There is nothing magical about WASI. It is an agreement on names and signatures. To prove it, here is a host that supplies fd_write itself, written in a dozen lines. Because we control the implementation, we can capture the output into a string instead of letting it reach the terminal. This is exactly what makes WASI easy to sandbox and to test:

Node.js A hand-written fd_write: capture the module's output

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.

By returning ERRNO_BADF for every descriptor except 1 and 2, this host implements a tiny capability policy: the module can print, and nothing else. Real runtimes do the same at larger scale with preopened directories and permission flags.

What a WASI module can and cannot do

Can (when granted) Cannot
Read and write files in preopened directories Open arbitrary paths
Read command-line arguments and environment variables See the host's other processes
Get the time and random bytes Make syscalls directly
Write to stdout and stderr, read stdin Load native libraries (dlopen)
Exit with a code (proc_exit) Fork or exec (no processes)

Threads, sockets and HTTP are available through newer proposals and Preview 2 interfaces, with varying support between runtimes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is WASI?

    WASI standardizes the system interface (files, clocks, random, stdio) so modules run unchanged on any runtime that implements it.
  2. 2. What does capability-based security mean in WASI?

    There is no ambient authority. The host decides which directories, clocks and streams a module receives.
  3. 3. In fd_write(fd, iovs, iovs_len, nwritten), what is an iovec?

    iovecs let a single call write several buffers. Each is 8 bytes: a 4-byte pointer and a 4-byte length.
  4. 4. Which export does a WASI command-line module provide as its entry point?

    By convention a WASI command exports _start (and its memory). Runtimes call it to run the program.

Summary

  • WASI is a standard system interface of imports for files, clocks, random numbers, arguments, environment and stdio.
  • It is capability-based: the host grants directories and resources; everything else fails.
  • Preview 1 (wasi_snapshot_preview1) is a flat POSIX-like API; Preview 2 builds on the component model.
  • A command module exports _start and memory; Node, wasmtime, wasmer and others can run it.
  • Because WASI is only imports, hosts can implement, restrict or fake any call, which makes testing and sandboxing straightforward.

Next: Running WebAssembly Outside the Browser