armless
pages / Browser API

Browser API

on this page

Options#

option meaning
wasm, wasm_smp the wasm to load (a URL, bytes or a WebAssembly.Module). With cpus > 1, wasm_smp, or else wasm with armless.wasm replaced by armless-smp.wasm
memory_mb the guest's RAM (default 512). A restored snapshot only commits the pages it holds
cpus number of CPUs (default 1)
smp_policy with several CPUs, how a CPU waits for another: "adaptive" (the default: spin briefly, then give up the thread now and then, and learn when the host has fewer cores free than it says) or "spin-count" (armless 0.12's). See set_smp_policy()
filesystem { json, baseurl }: the 9p root's tree and where its blobs are fetched from
fs_cache_mb cap on decompressed file contents kept in the page (256 by default); the guest's page cache keeps what it uses often
predecode_mb cap on the pre-decoded instructions each CPU keeps (24 by default), held for the life of the machine
initial_state a snapshot to restore (URL or bytes, zstd or not)
boot for a cold boot: { kernel, initrd, cmdline } (cmdline defaults to console=ttyS0), or { raw, addr } for a bare-metal binary; without kernel, the kernel and initrd under /boot in the filesystem
user user mode, instead of boot: { argv, env, cwd, cols, rows }, a program started from the filesystem as execve would (by PATH in env when argv[0] has no slash; cwd / and 80x24 by default). One CPU only
user_state user mode from a snapshot: the process (URL or bytes) saved with the machine initial_state restores, by save_process() or natively by Process::save (snowglobe's system/user.bin). The machine must be made as the one saved was: memory_mb, filesystem, and console, network on or off
network turns on virtio-net; see below
console virtio-console on or off (default on)
free_page_reporting a virtio-balloon that zeroes the memory the guest's kernel reports free, so snapshots leave it out (default off; a snapshot restores only onto the devices it was saved with; the kernel needs CONFIG_VIRTIO_BALLOON and CONFIG_PAGE_REPORTING)
mac the NIC's MAC address, "aa:bb:cc:dd:ee:ff"
jit, jit_threshold the wasm JIT on or off (default on) and how often a block runs before it is compiled
autostart run as soon as it is set up (default true); otherwise call run()
debug off by default. On, the machine samples its memory every few seconds and where it moves (loaded, restored, a save), keeps the last 400 in vm.debug.samples and emits them as memory events; see memory_report()

network options:

  • tls: the CA as tls.json (caSubject, caKeyId, leafSpki, caKey and leafKey, base64 DER), as an object or a URL. Without it, port 443 is plain TCP.
  • fetch and WebSocket: replace the page's own.
  • upgrade_https: ask for https:// and wss:// when the guest uses http:// and ws://. This is the default on https pages.
  • tunnels: [{ host, port, url }], guest TCP destinations carried over a WebSocket to url as binary messages (websockify, websocat, Neon's wsproxy). Leave out host to match any name on that port. url can be a function of { host, port } returning a URL or a promise of one, called for each connection (to add a fresh access token, say); if it throws or rejects, the guest's connection is refused. The destination is the guest's choice: a function should check { host, port } before it hands out a credential.
  • allow_private: let the guest's requests and WebSockets reach private, loopback and link-local addresses (localhost, 10/8, 192.168/16, 169.254/16, fc00::/7 and the IPv6 forms that carry them). Off by default; the page's own origin is always reachable. Under Node, Bun or Deno a name is also refused if it resolves to such an address (fetch() looks it up again, so for a guarantee use the native host, which dials only what it checked).
  • allow: ({ url, host, port, kind }) → true or false (or a promise of one), deciding alone which requests (kind "http") and WebSockets ("websocket") go out. Armless.private_host(host) is the default's test, to build on.

The guest's requests never carry the visitor's cookies, HTTP authentication or referrer (credentials: "omit", referrerPolicy: "no-referrer"). Under Node, Bun and Deno a redirect goes back to the guest, whose next request is checked again; a browser follows redirects itself, under CORS.

Events#

Subscribe with vm.on(name, fn) (off removes).

  • console and serial: output bytes.
  • ready: set up. progress ({ file, loaded, total }): a snapshot or file loading.
  • blob: a file being fetched. stop ({ reason }) and error.
  • In user mode, console is what the program writes to its terminal; stop is { reason: "exit", code } when it exits, { reason: "fault", message } when it faults; and idle says it has gone quiet waiting for input (every thread waits, none on a file being fetched), once until it prints or gets input again.
  • memory: a sample of the memory (with the debug option).
  • tcp-connection: a Connection from the guest to a port nothing else handles.

The guest's data for a connection counts as taken once its data listeners had it, and a tunnel's once its WebSocket sent it: the guest waits for room rather than the page buffering what a slow far end can't take.

A Connection has host (the name the guest resolved) and port, and supports accept(), refuse(), hold() (decide later), write(), close() and drain(), plus the data, end, connect and close events. A page can't make raw TCP connections, so connections nobody accepts, and no tunnel takes, are refused.

Calls#

  • Input: console_input(data), console_resize(cols, rows), serial_input(data).
  • Files: provide_blob(name, data) to preload a blob, has_blob(name).
  • connect(port): a connection into a server in the guest.
  • Snapshots: save_state() returns the snapshot as one buffer; save_state_pieces() returns it in pieces of about 1 MiB, to write or compress as they come; restore_state(src, { user_state }) replaces the machine's state (and in user mode the process).
  • User mode: console_input and console_resize go to the program's terminal; close_input() ends its input (reads past what is left return 0), kill(sig = 2) sends it a signal; save_process() returns the process's state, which goes with save_state()'s as user_state with initial_state (save both while stopped); user_status says { state: "running" | "idle" | "exited" | "fault", waiting_for_input, waiting_on_blobs, wake_ms, code }, and idle fires when the program waits for input (not when it only sleeps or waits for files). An idle program costs nothing: it runs again at its next deadline (wake_ms), on input, or when a file it waits on arrives.
  • User mode, jobs beside the program: const job = await vm.spawn({ argv: ["/bin/sh", "-s"], env: ["PATH=..."], cwd: "/root" }) starts a process of its own (root, a session of its own, no parent) while the machine runs, as a native host's Process::spawn does; it throws when the machine isn't in user mode or the build has no spawn, and fetches the program's files first. job.pid; job.write(bytesOrString) (false once its stdin is gone); job.closeInput(); job.poll() returns { stdout, stderr: Uint8Array, exit } of what it did since the last poll (exit is null while it runs, then 0 to 255, 128 + the signal for one a signal ended; it throws once the job is released; the machine emits spawn-output { pid } once when a job has something to poll, until it is polled); job.kill(sig = 15) signals its process group; job.release() lets go of it. save_process() fails while a job is held (not released): a snapshot keeps no host end of a job's pipes.
  • User mode, memory: a program reads its own, as on Linux, from the frames its page tables map: /proc/<pid>/status (VmPeak, VmSize, VmHWM, VmRSS, RssAnon, RssFile, RssShmem, VmData, VmStk, VmExe), /proc/<pid>/statm, fields 23 and 24 of /proc/<pid>/stat, getrusage's ru_maxrss (self, and the children that ended) and the free memory of /proc/meminfo and sysinfo (RAM less the frames in use). A page counts once touched (a reservation with PROT_NONE or MAP_NORESERVE only raises the size), and a copy-on-write page after a fork counts in each process.
  • smp_report(): with several CPUs, what they did and what their waits for one another cost: { cpus, host_cores, policy, oversubscribed, slow_waits, tlbi, ic_invals, kicks, insns: [per CPU], waits: { tlb, wfe, lock: { waits, spins, yields, ms, max_ms } }, workers: [{ run_ms, idle_ms, yield_ms, slices, idle_waits, events, yields, compiles }], event_delay: { count, ms, max_ms } } (also memory_report().smp); null with one CPU. set_smp_policy(name) changes the policy while it runs and returns the one before.
  • memory_report({ scan }): what the page's memory holds, split into the pieces armless can tell apart: the whole linear memory (which never shrinks), the guest's RAM, the host's heap (live, peak, big blocks, freed blocks kept to be reused), the file system (blobs fetched, files the guest wrote) and the JIT. With scan (the default) it also counts the 4 KiB pages that hold a non-zero byte before, in and after the RAM: the memory in use, as opposed to how far it has grown. It is what to read when a page is bigger than the guest's RAM explains.
  • Lifecycle: run(), stop() and destroy(); vm.ready is a promise for the setup.

this page's source