Host boundary

Embed the real machine.

This page documents the browser-facing boundary that exists in this repository. The loader fetches checked artifacts, constructs WasmLinux, and returns a controller. The published agent libraries are a separate host-side layer described further below.

loader.js is shipped here @agent-wasm is published elsewhere

Your appterminal, UI, or worker

loader.jsfetch and integrity boundary

WasmLinuxvirt platform + guest

Linuxkernel and userland

Browser Linux controller

Import the loader from the built web directory. The default path is the public initramfs boot. The callback receives output in chunks, so a terminal adapter should decode each chunk and append it rather than assume one callback per character.

import { startLinuxBoot } from "./loader.js";

const terminal = document.querySelector("#terminal");
const decoder = new TextDecoder();

const controller = await startLinuxBoot({
  manifestUrl: "./artifacts.json",
  ramMib: 256,
  onState: (state) => console.log("boot:", state),
  onOutput: (bytes) => {
    terminal.textContent += decoder.decode(bytes, { stream: true });
  },
  onError: (error) => console.error("wasm-vm:", error),
});

// Queue host keystrokes with controller.sendInput(new Uint8Array(...)).
const finalState = await controller.whenDone;
console.log("guest finished:", finalState);

The controller also exposes stop(), sendInput(bytes), and whenDone. The loader's options include onState, onProgress, onOutput, onError, ramMib, quantum, and the storage/network controls described on the guest page.

Boot modes exposed by the loader

Mode	What it does	Availability
`initramfs`	Passes the manifest's initramfs to `new WasmLinux`.	Default public demo path.
`disk`	Downloads the manifest's rootfs and passes it to `WasmLinux.newDisk`.	Large disk assets are local-only in this checkout.
`chunked`	Uses a chunk manifest and fetches disk chunks on demand.	Use the local serving workflow; see the guest page.
`persist: true`	Enables the IndexedDB overlay for a chunked boot.	Only meaningful with `chunked`.

Low-level bare-metal wrapper

For an ELF rather than Linux, the generated wasm-bindgen module exports WasmMachine. This is a relative build artifact under web/pkg; it is not an npm package published by this repository.

import init, { WasmMachine } from "./pkg/wasm_vm_wasm.js";

await init();
const machine = new WasmMachine(64);
machine.setConsole((byte) => processByte(byte));
machine.loadElf(elfBytes);

const result = machine.run(100_000);
// result.kind is "exited", "trapped", or "max".
console.log(result, machine.stateDigest());

The generated type declarations also expose step, architectural registers, canonical tracing, stats, and JIT counters. Use the source declarations as the contract for the exact generated build you are consuming.

Published host-side agent libraries

These packages are published from BLamy/agent-wasm, not from this repository. The table is a registry snapshot checked on 2026-08-30. Versions and exports can change; the npm links are the release records.

Package	Version	Verified README-backed surface
`@agent-wasm/core`	0.4.0	Browser Node runtime: `createContainer`, runtime/sandbox workers, virtual filesystem, package manager, and Vite/Next dev-server bridges. Exports include the root, `./internal`, `./vite`, and `./next`.
`@agent-wasm/sdk`	0.1.0	Workspace lifecycle and agent harness APIs: `createWorkspace`, snapshots, `AgentAdapter`, `AgentSession`, templates, and plugins. Exports include the root, `./auth`, and `./plugins`.
`@agent-wasm/react`	0.1.0	React workbench, chat, and UI components: provider/hooks, editor/preview/terminal panes, and subpaths `./workbench`, `./chat`, and `./ui`.
`@agent-wasm/chat-core`	0.1.0	Dependency-free chat domain, tool-call, and session APIs. The README does not make it a React or VM package.
`@agent-wasm/code`	0.1.0	Claude Code incremental JSONL transcript integration, including `claudeToolUseToToolCall`.
`@agent-wasm/vscode`	0.1.0	VS Code-shaped shell and React integration: `createVSCodeShell`, `<VSCode>`, and `useVSCodeShell`.
`@agent-wasm/keychain`	0.1.0	WebAuthn-PRF-backed AES-GCM vault with `Keychain` and `CredentialMirror`; it is not the guest disk.
`@agent-wasm/codex`	0.1.0	Codex agent compiled to WebAssembly for the browser, with MessageChannel/worker subpaths.
`@agent-wasm/tailscale-connect`	1.39.98-t02582083d	Published Tailscale Connect browser package. Its current README is sparse, so this page makes no broader API claim.

npm install @agent-wasm/core@0.4.0 @agent-wasm/sdk@0.1.0

Do not copy this install line for the VM. There is no verified @wasm-vm/sdk npm release in this checkout. Build the wasm module locally with make web-build, or consume the generated relative assets from a deployed web build.

Useful source contracts

web/loader.js — actual browser loader and controller lifecycle.
crates/wasm/src/lib.rs — wasm-bindgen boundary.
docs/embedding-guide.md — source-side integration notes.