Build locally, run locally

Run a machine on your own hardware — boot a kernel against a local root filesystem and get an interactive console in your terminal, with no round trip through brintos.io. Today this is a Node developer harness in the HardwareJS repo; a polished local platform is still coming.

Status: developer harness. HardwareJS — the host runtime that traps syscalls and emulates the devices the in-browser Linux kernel runs against — is the same code the website uses. The harness below (run-machine.mjs) is the command-line counterpart of the browser's launch surface: same kernel, same devices, same toolchain output. The full self-contained local platform (packaging, image management) is in progress.

Prerequisites

Node.js (we test on 22+).
The HardwareJS repo, brintos/hardwarejs.
A kernel image — build one in Build the Linux kernel, or reuse a machine's /boot/vmlinux.wasm.
A root filesystem directory to boot (see step 2).

1. Get the harness

Clone HardwareJS and build the library once:

git clone https://brintos.io/brintos/hardwarejs.git
cd hardwarejs
pnpm install
pnpm build        # emits dist/, which the harness imports

2. Get a root filesystem

The harness serves a host directory to the machine as its root filesystem over virtio-fs (read-write — changes land on the directory). The easiest way to get a real userland is to copy one out of a machine you own with the brintos-fs client:

brintos login
mkdir -p ~/mnt/brintos ./rootfs
brintos mount <you>/<repo> ~/mnt/brintos
cp -a ~/mnt/brintos/. ./rootfs/        # local copy you can boot
# (Ctrl-C the mount once the copy is done.)

Make sure a kernel image is reachable: either it already exists at ./rootfs/boot/vmlinux.wasm, or pass one explicitly with --kernel in the next step (e.g. the vmlinux.wasm you built in Build the Linux kernel).

3. Boot it

Point the harness at your root filesystem. Your terminal becomes the machine's serial console:

node src/cli/run-machine.mjs --fs ./rootfs
# or, equivalently:
pnpm machine --fs ./rootfs

Options:

-f, --fs <dir> — root filesystem directory to boot (required).
-k, --kernel <path> — kernel image (default <fs>/boot/vmlinux.wasm).
-i, --init <path> — init to exec as PID 1 (default /bin/sh).
--ram <MiB> / --user-ram <MiB> — kernel / per-process memory (default 256 / 64).
--cmdline <str> — extra kernel command line appended verbatim.

The harness boots the kernel in Node worker threads, mounts ./rootfs as / over virtio-fs, execs your init as PID 1, and bridges the guest console PTY to your terminal — exactly the path the browser's launch surface takes, minus the browser.

Press Ctrl-] to power the machine off and return to your shell. Everything else you type goes to the guest (so Ctrl-C reaches the program in the foreground, not the harness).

Running your own package

Build a package as in Build locally, run on brintOS, drop it into your root filesystem directory (e.g. ./rootfs/usr/local/bin/), and run it from the console — or pass --init /usr/local/bin/yourprog to have the kernel exec it as PID 1. The binary wasmcc produces is identical to the one that runs on brintos.io.

This is a developer harness today; the self-contained local platform is still being built. Building tooling for wasm-native Linux and want to compare notes? Get in touch.