Wanix

Wanix is an embeddable runtime that brings a Unix-like environment to the browser. Declare a <wanix-system>, bind files and archives into a namespace, run Wasm and JavaScript tasks, boot Linux in an x86 emulator, and wire up terminals and a VS Code workbench, all from HTML.

<wanix-system>
  <wanix-bind type="file" dst="helloworld.wasm" src="./helloworld.wasm"></wanix-bind>
  <wanix-task cmd="helloworld.wasm" term start></wanix-task>
  <wanix-term path="#task/1/term"></wanix-term>
</wanix-system>

Everything is a file. Processes, terminals, VMs, browser APIs, and storage are exposed through a unified namespace you compose with binds. The same idea as Plan 9, with improvements, in the browser.
Composable environments. Layer tar archives, fetch remote files, write inline scripts, and union directories to build exactly the filesystem your app needs.
Pluggable compute. Run Go/TinyGo (gojs), WASI Wasm, JavaScript workers, and x86 Linux (via v86) as tasks in the same namespace.
Isolation by design. Each task gets its own namespace. VMs export a guest namespace. Import remote namespaces over 9P.
Browser-native integration. OPFS persistence, DOM control, web workers, service workers, and fetch are first-class via the #web namespace.
No backend required. The runtime (wanix.min.js + wanix.wasm) runs entirely client-side. Host static assets on any CDN.
Progressive complexity. Start with a single Wasm binary and terminal. Add Linux VMs, a full IDE workbench, or cross-origin federation when you need them.

Use Cases

In-browser dev environments: edit/run code without a remote container.
Interactive demos and tutorials: embed reproducible sandboxes in docs, blog posts, and courseware.
Local-first apps: persist user data in OPFS, run logic in workers, and build your own platform.
Agent sandboxes: utilize browser sandboxing to isolate an agent environment you construct.
Personal compute: build your own computing environment / operating system.

Quick Start (CDN)

<!DOCTYPE html>
<html>
<head>
  <script type="module"
    src="https://cdn.jsdelivr.net/npm/wanix@0.4.0-alpha8/dist/wanix.min.js">
  </script>
</head>
<body style="height: 100vh; margin: 0;">

  <wanix-system>
    <!-- bind alloc ramfs to namespace root -->
    <wanix-bind dst="." src="#ramfs/new"></wanix-bind>
    <!-- bind inline file into namespace -->
    <wanix-bind type="file" dst="hello.sh" perm="0755">
      echo "Hello from Wanix!"
    </wanix-bind>
    <!-- bind wasm executable from url -->
    <wanix-bind type="file" dst="rc.wasm"
      src="https://cdn.jsdelivr.net/npm/wanix-extras@0.4.0-rc1/dist/rc.wasm">
    </wanix-bind>
    <!-- declare a task that will autostart -->
    <wanix-task id="shell" cmd="rc.wasm -c hello.sh" term start></wanix-task>
    <!-- show a terminal wired up to the task -->
    <wanix-term path="#task/shell/term"></wanix-term>
  </wanix-system>

</body>
</html>

JavaScript API

After <wanix-system> fires a ready event, use the filesystem handle:

<script type="module">
  const sys = document.querySelector('wanix-system');
  sys.addEventListener('ready', async () => {
    console.log(await sys.root.readDir('.'));
    await sys.root.writeFile('note.txt', 'saved from JS');
  });
</script>

Full API: api/handle.js.

Elements Reference

Elements let you compose a Wanix system in HTML. The only visual elements are <wanix-term> and <wanix-workbench>.

`<wanix-system>`

The root namespace and Wasm kernel. All other elements live inside it (or reference it with for).

Attribute	Description
`wasm`	URL to the Wanix Wasm module. Defaults to `./wanix.wasm` next to the bundle.
`debug`	Enable DevTools helpers and verbose logging.
`id`	System identifier used for cross-origin import/export.
`allow-origins`	Space-separated origins allowed to import this system via `postMessage` (use `*` to allow all). Requires `id`.

Events: ready (namespace usable), error (load failure).

`<wanix-bind>`

Mount a source into the namespace at dst.

Attribute	Description
`dst`	Destination path. `.` is the namespace root. Paths do not start with `/`.
`src`	Source path or URL. System paths use `#` prefix (e.g. `#ramfs`, `#web/opfs`).
`type`	Bind type (see below). Default: `ns`.
`perm`	File permission mode for `file` binds. Default: `0644`.
`union`	Union mode when binding to an existing directory. Default: `after`.

Bind types

Type	Behavior
`ns`	Bind another namespace path (default).
`file`	Write element text content (or fetched URL if `src` is set) to `dst`.
`archive`	Fetch a `.tar` or `.tar.gz` and mount as a directory tree.
`import`	Import a remote Wanix namespace via WebSocket (`ws://` / `wss://`) or iframe + 9P (`src` URL with `#system-id`).

`<wanix-task>`

Allocate and run a task, which is shaped like a process (args, env, stdio, ...) and executed by a task driver. Tasks run in their own namespace, by default inheriting the current/root namespace.

Attribute	Description
`cmd`	Command line to run.
`type`	Task driver: `auto`, `gojs`, `wasi`, `js`, etc. Default: `auto`.
`role`	Semantic role. Use `shell` for workbench shell templates.
`id` / `alias`	Optional name for referencing the task at `#task/<id>/…`.
`env`	Environment variables, space-separated `KEY=VALUE` pairs (use quotes for values with spaces).
`wd`	Working directory within the task namespace.
`fsys`	Base filesystem path for the task namespace.
`stdin` / `stdout` / `stderr`	Namespace paths for I/O redirection.
`term`	Allocate a terminal device for this task.
`start`	Start the task automatically when the system is ready.
`for`	ID of a `<wanix-system>` to attach to (instead of being a direct child).

Terminal path after allocation: #task/<id>/term (or #task/<rid>/term without alias).

Task drivers

Type	Behavior
`auto`	Determine automatically (default).
`js`	Run plain JavaScript as a task.
`gojs`	Run Wasm compiled by Go using `GOOS=js GOARCH=wasm`.
`wasi`	Run any Wasm compiled using `wasi`/`wasip1`.

`<wanix-vm>`

Allocate and run a virtual machine.

Attribute	Description
`type`	VM backend. Default: `v86`.
`id` / `alias`	Optional name. Terminal at `#vm/<id>/term`.
`fsys`	Root filesystem path in the namespace.
`term`	Allocate a terminal for serial console I/O.
`start`	Boot automatically when ready.
`append`	Kernel command line additions.
`export`	Host-export device (e.g. `ttyS0`, `hvc1`) for guest ↔ host bridging.
`mem`	RAM size (e.g. `512M`, `1G`).
`boot`, `bios`, `netdev`, …	Additional QEMU-style flags mapped from attribute names.

Using <wanix-vm> requires a VM backend to be loaded using bind to #vm/<type>:

<wanix-bind dst="#vm/v86" type="archive" src="https://cdn.jsdelivr.net/npm/wanix-extras@0.4.0-rc1/dist/v86.tgz"></wanix-bind>

`<wanix-term>`

Render an xterm.js terminal connected to a Wanix terminal device.

Attribute	Description
`path`	Terminal device path (e.g. `#term/1`, `#task/shell/term`, `#vm/1/term`).
`raw`	Raw mode — no local line editing; bytes pass through directly. Use for VM serial consoles.
`for`	ID of a `<wanix-system>` to attach to.

Style the element with height: 100% (and flex layout on parents) for full-page terminals.

`<wanix-workbench>`

Embed a VS Code web workbench backed by the Wanix filesystem.

Attribute	Description
`assets`	URL prefix for workbench static assets (built with `make -C workbench`).
`wd`	Workspace folder path in the namespace (e.g. `root`, `.`).
`open`	Space-separated file paths to open on startup.
`term`	Enable integrated terminal panel.
`raw`	Raw terminal mode for integrated terminal.
`sidebar`	Initial sidebar state: `default`, `hidden`, or `never` (hidden even if user previously opened).
`welcome`	Show welcome page on startup.
`debug`	Verbose workbench logging.
`task-ns`, `term-ns`	Override task/terminal namespace paths (e.g. for VM guest shells).

Include a child <wanix-task role="shell" …> as the shell template.

System Namespace

These # paths are provided by the kernel and can be bound into your namespace:

Path	Description
`#task`	Process control and task namespaces.
`#term`	Terminal devices.
`#vm`	Virtual machine control.
`#ramfs`	In-memory filesystem (cloned per bind).
`#pipe`	Pipe pairs (cloned per bind).
`#signal`	Signal devices (cloned per bind).
`#web`	Browser integration — OPFS (`#web/opfs`), DOM, workers, caches, etc.
`#wanix`	Internal Wanix devices.

Recipes

Minimal Wasm terminal

Run a Go/TinyGo Wasm binary with a terminal:

<wanix-system>
  <wanix-bind type="file" dst="app.wasm" src="https://example.com/app.wasm"></wanix-bind>
  <wanix-task id="app" cmd="app.wasm" term start></wanix-task>
  <wanix-term path="#task/app/term"></wanix-term>
</wanix-system>

See examples/basic-terminal.html.

Writable namespace with inline files

Create a virtual filesystem to use via JS:

<wanix-system>
  <wanix-bind dst="." src="#ramfs/new"></wanix-bind>
  <wanix-bind dst="greeting.txt" type="file" perm="0644">
    Hello, world!
  </wanix-bind>
</wanix-system>

See examples/basic-namespace.html.

JavaScript worker task

Run inline JS in a Wanix task:

<wanix-system>
  <wanix-bind dst="." src="#ramfs/new"></wanix-bind>
  <wanix-bind dst="task.js" type="file" perm="0766">
    console.log("JS task running!");
  </wanix-bind>
  <wanix-task cmd="task.js" start></wanix-task>
</wanix-system>

See examples/task-js.html.

Layered root filesystem

Stack archives and overlay individual files — later binds win:

<wanix-system>
  <wanix-bind type="archive" dst="root"
    src="https://example.com/base-rootfs.tar.gz"></wanix-bind>
  <wanix-bind type="archive" dst="root"
    src="https://example.com/overlay.tar.gz"></wanix-bind>
  <wanix-bind type="file" dst="root/boot/bzImage"
    src="https://example.com/custom-kernel"></wanix-bind>
</wanix-system>

See examples/bind-types.html.

Boot Linux in v86

<wanix-system>
  <wanix-bind dst="." type="archive"
    src="https://cdn.jsdelivr.net/npm/wanix-extras@0.4.0-rc1/dist/wanix-linux.tgz">
  </wanix-bind>
  <wanix-bind dst="#vm/v86" type="archive"
    src="https://cdn.jsdelivr.net/npm/wanix-extras@0.4.0-rc1/dist/v86.tgz">
  </wanix-bind>
  <wanix-vm export="ttyS0" mem="1G" term start></wanix-vm>
  <wanix-term path="#vm/1/term" raw></wanix-term>
</wanix-system>

See examples/basic-vm.html.

VS Code workbench with rc shell

Host workbench assets locally (make -C workbench), then:

<wanix-system debug>
  <wanix-bind type="archive" dst="root"
    src="https://cdn.jsdelivr.net/npm/wanix-extras@0.4.0-rc1/dist/wanix-linux.tgz">
  </wanix-bind>
  <wanix-bind type="fetch" dst="rc.wasm"
    src="https://cdn.jsdelivr.net/npm/wanix-extras@0.4.0-rc1/dist/rc.wasm">
  </wanix-bind>
  <wanix-workbench assets="/workbench" term>
    <wanix-task role="shell" cmd="rc.wasm"></wanix-task>
  </wanix-workbench>
</wanix-system>

See examples/basic-workbench.html.

Workbench with VM guest shell

Edit files on the host namespace while running shells inside a Linux VM:

<wanix-system debug>
  <wanix-bind dst="." type="archive" src="/assets/wanix-linux.tgz"></wanix-bind>
  <wanix-bind dst="#vm/v86" type="archive" src="/assets/v86.tgz"></wanix-bind>
  <wanix-vm export="ttyS0" start></wanix-vm>
  <wanix-workbench assets="/workbench"
    task-ns="#vm/1/guest/#task"
    term-ns="#vm/1/guest/#term"
    raw term>
    <wanix-task role="shell" cmd="bin/sh"></wanix-task>
  </wanix-workbench>
</wanix-system>

See examples/vm-workbench.html.

OPFS-backed persistent editor

Persist files in the browser with Origin Private File System:

<wanix-system>
  <wanix-bind dst="." src="#web/opfs"></wanix-bind>
  <wanix-bind dst="main.js" type="file" perm="0644">
    export default function() { return 42; }
  </wanix-bind>
  <wanix-workbench open="main.js" assets="/workbench"></wanix-workbench>
</wanix-system>

Export and import namespaces

Export a namespace from one page:

<wanix-system id="main" allow-origins="*">
  <wanix-bind dst="." src="#ramfs/new"></wanix-bind>
  <wanix-bind dst="shared.txt" type="file">shared data</wanix-bind>
</wanix-system>

Import it from another page:

<wanix-system>
  <wanix-bind type="import" dst="remote"
    src="https://other.example/app.html#main"></wanix-bind>
  <wanix-task id="repl" cmd="rc.wasm" term start></wanix-task>
  <wanix-term path="#task/repl/term"></wanix-term>
</wanix-system>

Import over WebSocket 9P:

<wanix-bind type="import" dst="home" src="wss://example.com/9p"></wanix-bind>

See examples/example-export.html and examples/bind-import.html.

Remote VM in a local workbench

Import a VM running on another origin and attach a workbench to its guest namespace:

<wanix-system debug>
  <wanix-bind type="import" dst="remote"
    src="https://vm-host.example/linux.html#linux"></wanix-bind>
  <wanix-workbench assets="/workbench"
    task-ns="remote/vm/1/guest/#task"
    term-ns="remote/vm/1/guest/#term"
    raw term>
    <wanix-task role="shell" cmd="bin/sh"></wanix-task>
  </wanix-workbench>
</wanix-system>

See examples/import-workbench.html.

More examples

See all examples.

Local Development

make build          # build runtime + wanix CLI
make examples       # serve examples at http://localhost:7070/examples
make                # show all make tasks

Using make examples will build extras the first time, and will need Docker running to succeed. Podman users will need to set DOCKER_CMD=podman.

See CONTRIBUTING.md for the full build guide.

Contributing

We'd love your contributions! Take a look at our issues to see how you can help out. You can also ask questions and participate in discussions, however right now most discussion takes place in our Discord.

Be sure to read our CONTRIBUTING.md doc to get started.

AI Disclosure

There are components of Wanix that have been written with AI assistance. However, we will not accept "vibe coded" PRs, which is to say a human needs to know how the PR works and be responsible for it.

Older Demos

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 745 Commits
.github		.github
api		api
cmd/wanix		cmd/wanix
docs		docs
elements		elements
examples		examples
extras		extras
fs		fs
gojs		gojs
misc		misc
native		native
rc		rc
site		site
term		term
test		test
v86		v86
vm		vm
wasi		wasi
wasm		wasm
web		web
workbench		workbench
.dockerignore		.dockerignore
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
buildjs.go		buildjs.go
go.mod		go.mod
go.sum		go.sum
index.ts		index.ts
package-lock.json		package-lock.json
package.json		package.json
task.go		task.go
wanix.go		wanix.go

Uh oh!

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Wanix

Use Cases

Quick Start (CDN)

JavaScript API

Elements Reference

<wanix-system>

<wanix-bind>

Bind types

<wanix-task>

Task drivers

<wanix-vm>

<wanix-term>

<wanix-workbench>

System Namespace

Recipes

Minimal Wasm terminal

Writable namespace with inline files

JavaScript worker task

Layered root filesystem

Boot Linux in v86

VS Code workbench with rc shell

Workbench with VM guest shell

OPFS-backed persistent editor

Export and import namespaces

Remote VM in a local workbench

More examples

Local Development

Contributing

AI Disclosure

Older Demos

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 4

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`<wanix-system>`

`<wanix-bind>`

`<wanix-task>`

`<wanix-vm>`

`<wanix-term>`

`<wanix-workbench>`

Packages