Skip to content
OxideVM64-bitSDK documentation

host.kit.wasi

host.kit.wasi runs a compiled wasm32-wasip1 program (Rust, C, Zig, TinyGo) as the module’s own Linux process. It implements WASI Preview1 over the process’s real descriptors and the VM’s live files, clocks and entropy, and serves the oxidevm_bridge_v1 imports for process identity, native children and VM sockets. Every call is synchronous for the program: the module worker waits on its Linux mailbox, so no WebAssembly JSPI and no Asyncify are needed.

For a walkthrough, see Run Rust programs.

Functions

Section titled “Functions”
Member What it does
compile(bytes) Checks the bytes (admitShape), compiles, then checks the imports and exports (admit). Resolves with a WebAssembly.Module; a refused program throws AdmissionError or WebAssembly.CompileError and none of its code runs.
run(host, program, io, options) Runs the program once with fresh state and resolves with the module’s exit status.
readProgram(host, path) Reads a program file from the VM through one descriptor, at most limits.programBytes. Throws a LinuxError, or ProgramTooLarge (errno 27).
admitShape(bytes) Only the byte-level checks: a WebAssembly 1.0 core module, one unshared 32-bit memory with a declared maximum, no imported memory or table, at most one bounded function table, no start section.
admit(module) Only the import and export checks: function imports from wasi_snapshot_preview1 and oxidevm_bridge_v1 by name, and exports _start and memory.
AdmissionError The error the checks throw; its message names the first offending part.
limits The profile’s limits (below).
rootPreopen { guest: "/", host: "/", readOnly: false }, the default grant.

run(host, program, io, options)

Section titled “run(host, program, io, options)”

  • host: the adapter’s host. run uses whichever of these members it has:

    Member Capability Serves
    fs, fail files.sync Standard streams, failure lines (required)
    at files.at Preopens and every path and descriptor function
    clock clock clock_time_get, clock_res_get, poll_oneoff deadlines
    random random random_get
    process.info process.info process_info
    process.runSync process.sync command_run and the result_* functions
    net net.vm or net.internet net_*

    A function whose member is absent returns NOSYS. It never guesses or falls back.

  • io: a command’s io, or any object with env, cwd, stdin, stdout, stderr and optional terminals.

  • options.argv: the program’s argv, argv[0] included. Diagnostics name the program by argv[0].

  • options.preopens: the directories the program may use, each { guest, host, readOnly }. The default is [rootPreopen], the whole VM tree under the process’s own credentials. Any other directory is confined by the engine: paths beneath it resolve with RESOLVE_BENEATH on a held directory, so .., absolute symlinks and a concurrent symlink swap cannot escape (EXDEV). A read-only preopen refuses every mutation with ROFS.

run resolves with the program’s own exit status from 0 to 119. A larger status is reported as 1 with a line naming the original. A signal ends the process before run resolves.

Files and descriptors

Section titled “Files and descriptors”

Each run has its own descriptor table of at most 256 entries, standard streams and preopens included. A guest descriptor names a real Linux descriptor. Rights only ever shrink, and a stale or guessed number is BADF. Positional reads and writes do not move a shared offset, and fd_readdir resumes from the directory’s own d_off cookies on the held descriptor. Paths are raw bytes: at most 4,095 bytes, no NUL.

Imports

Section titled “Imports”
Group Functions Behaviour
Launch args_*, environ_* Exact values, 64 KiB each
Streams fd_read, fd_write, fd_pread, fd_pwrite 64 KiB host transfers, at most 128 buffers and 1 MiB per call, partial counts as Linux returns them
Descriptors fd_close, fd_renumber, fd_seek, fd_tell, fd_fdstat_*, fd_filestat_*, fd_sync, fd_datasync Linux status flags; nanosecond times; fd_fdstat_set_flags changes only APPEND and NONBLOCK
Preopens, directories fd_prestat_*, fd_readdir
Paths path_open, path_create_directory, path_filestat_*, path_link, path_readlink, path_remove_directory, path_rename, path_symlink, path_unlink_file Descriptor-relative, in the engine
Time, randomness clock_time_get, clock_res_get, poll_oneoff, random_get REALTIME and MONOTONIC only (CPU-time clocks are INVAL); 1 to 16 subscriptions per poll
Process proc_exit, sched_yield
Not provided fd_advise, fd_allocate (NOTSUP), proc_raise (NOSYS), sock_* (BADF: there are no socket preopens; use the bridge)

Linux errors become WASI errno values, never raw Linux numbers. A Linux error without a WASI name becomes IO.

Limits

Section titled “Limits”
limits. Value
programBytes 33,554,432 (32 MiB)
memoryPages 4,096 (256 MiB)
tableEntries 65,536
launchBytes 65,536 for argv and for the environment
pathBytes 4,095
descriptors 256, shared with bridge handles
iovecs, ioBytes, ioChunk 128, 1 MiB, 64 KiB