Host API

NanoVM keeps the boundary between guest and host deliberately small: five WASM imports and around thirty exports.

Imports (host → guest)

The module asks the host for very little — primarily a way to signal pending filesystem work and to read wall-clock time and entropy.

Exports (guest → host)

• Lifecycle — create, reset and step the VM.
• Memory — read and write guest memory regions.
• Execution — run until the next syscall boundary or trap.
• FS protocol — inspect and complete a pending FS request.

The FS_PENDING protocol

Rather than a callback per file operation, the guest writes a request into a shared memory region and raises fs_pending. The host reads the request, performs the I/O against MemFS, writes the result back, and resumes execution. This keeps the hot path free of host round-trips.

// host side, simplified
while (vm.run() === FS_PENDING) {
  const req = vm.readFsRequest();
  const res = memfs.handle(req);
  vm.writeFsResult(res);
}