pages / Browser API
Browser API
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 astls.json(caSubject,caKeyId,leafSpki,caKeyandleafKey, base64 DER), as an object or a URL. Without it, port 443 is plain TCP.fetchandWebSocket: replace the page's own.upgrade_https: ask forhttps://andwss://when the guest useshttp://andws://. This is the default on https pages.tunnels:[{ host, port, url }], guest TCP destinations carried over a WebSocket tourlas binary messages (websockify, websocat, Neon's wsproxy). Leave outhostto match any name on that port.urlcan 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).
consoleandserial: output bytes.ready: set up.progress({ file, loaded, total }): a snapshot or file loading.blob: a file being fetched.stop({ reason }) anderror.- In user mode,
consoleis what the program writes to its terminal;stopis{ reason: "exit", code }when it exits,{ reason: "fault", message }when it faults; andidlesays 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 thedebugoption).tcp-connection: aConnectionfrom 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_inputandconsole_resizego 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 withsave_state()'s asuser_statewithinitial_state(save both while stopped);user_statussays{ state: "running" | "idle" | "exited" | "fault", waiting_for_input, waiting_on_blobs, wake_ms, code }, andidlefires 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'sProcess::spawndoes; 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 (exitis 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 emitsspawn-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'sru_maxrss(self, and the children that ended) and the free memory of/proc/meminfoandsysinfo(RAM less the frames in use). A page counts once touched (a reservation withPROT_NONEorMAP_NORESERVEonly 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 } }(alsomemory_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. Withscan(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()anddestroy();vm.readyis a promise for the setup.