Guides

Machines

What a machine is, how to create and configure one, what happens when you power it on, and what the platform can and can't do today.

What a machine is

A machine is a repository whose contents are a bootable root filesystem. Like a source repository it has an owner, a page, forks, and access control; unlike one, its data is a content-addressed drive — every file is stored and de-duplicated by hash, which is what makes forks cheap and history durable. Launching a machine boots a real Linux 6.12 kernel, compiled to WebAssembly, against that drive in your browser or a local Node process. See Launching for all the launch methods.

Creating a machine

Go to brintos.io/new. Four starting points:

• From a template — fork one of our ready-to-boot template images.
• Fork an existing machine — any machine your account can read.
• Upload an ext4 image — import a raw .img file from your computer.
• From scratch — an empty drive you populate yourself.

You can also fork directly from any machine's page. Choose a backup snapshot; the latest is the default, and live cannot be forked. Your fork has its own writable live version and initial backup, with file content shared in storage rather than duplicated.

Importing an ext4 image

Use Choose File under Upload an ext4 image on /new to create a machine from an image. New machines skip the before-import backup. To replace an existing machine’s live filesystem, use Image import on its Snapshots page. Existing backups are preserved, and capturing a before-import backup is enabled by default. Both workflows create a new read-only backup of the imported filesystem.

Keep the tab open until upload finishes. If upload is interrupted, select the same file to resume. Processing then continues on the server, and the machine page shows its progress or any failure. Live stays available during preparation; replacement waits for a running live machine to stop, then briefly locks live edits and launches. Reload or remount live clients after replacement.

Images must contain a clean raw ext4 filesystem starting at byte zero, without a partition table. Unmount the image before selecting it. The initial limits are 1 TiB and 250,000 entries. Import preserves supported filesystem metadata and does not add boot files: launching still requires a matching wasm32 kernel and an official HardwareJS release.

The machine spec

Every image repo carries a machine spec — the hardware the kernel sees at boot. Owners edit it under Settings → Machine spec:

Boot kernel and HardwareJS are read-only information in About and Machine spec. For the selected snapshot, the most recently modified regular vmlinux-*.wasm file directly in /boot is selected (filename order breaks ties). Its -hwjs-<version>.wasm suffix selects the official runtime. A prominent red notice flags an invalid version or files this website does not serve. The small edit icon beside Init in About takes repository admins to its setting.

Launching

Launch machine on the repo page opens the launch surface. Check the selected version and press Power on if it has not started automatically. Your browser loads the snapshot’s kernel and its matching official HardwareJS runtime, then serves the selected cloud filesystem to the guest over virtio-fs. The surface shows:

• The screen — a canvas displaying the machine's real framebuffer. Its mode is measured from the window at power-on and follows the window: resizing re-modes the guest display (up to your screen's pixel capacity, max 3840×2160) and the console reflows. Keyboard and pointer events over the screen are delivered to the guest as Linux input events.
• The serial console — a terminal bridged to the guest's console. Every kernel log line (dmesg) appears verbatim, so what you see during boot is the actual kernel trace, panic messages included.
• Telemetry — machine, storage, and network dials while it runs.

A repo setting can also mark a machine power-on-open, so it boots as soon as the launch page loads. For embeds, headless Node launches, and offline images, see Launching.

Persistence and snapshots

Writes made by a machine running writable live go back to its cloud drive. Backup launches are read-only. Owners manage point-in-time copies on the Snapshots tab:

• Every repository starts with live. A clean shutdown or successful image import publishes latest, which cannot be renamed or deleted. Only one engine may use live at a time, including a read-only live engine. Published snapshots support concurrent engines.
• Owners can save a named snapshot using the controls inside the latest entry, even while live is running. This preserves the published version, excluding unpublished live edits. Named snapshots can be renamed or deleted. Select a published snapshot at launch to run that version.
• Use Update from Live inside latest to replace it immediately with a copy of live. Live must be stopped. Live and named snapshots stay unchanged.
• Every published snapshot can carry notes: Markdown saying what it holds, such as the build it came from, the runtime it needs and what changed. They appear in the Snapshots list and on the snapshot's launch page, for everyone who can launch it. Owners set them when saving a snapshot or updating latest from live, and can edit them later. A named snapshot starts with latest's notes. A newly published latest starts with none unless you supply them, because the old notes described other contents. A fork's latest keeps the notes of the snapshot it was forked from. Scripts can do all of this with the MCP snapshot tools.
• Automatic launches choose live when you can write and it is idle; otherwise they choose the latest backup. See version selection.

Working with the drive from your computer

Run the machine through the Node launcher, upload individual files in the file browser, or transfer the whole filesystem with ext4 import/export. See Files & images and Build locally, run on brintOS.

Sharing

Make a machine public and send the URL — anyone who opens it can launch a read-only backup. Recipients who want to keep changes fork it; the running instance in each visitor's tab is their own.

Current limitations

• Networking depends on the image and launch permissions. The image needs a compatible network driver, and cloud networking requires an authorized network capability. See Network-as-a-service.
• Live allows one engine at a time. Sharing a backup lets each visitor boot their own instance; it does not share an interactive console session.
• Machine binaries must come from the brintOS toolchain. The kernel runs executables produced by hwjs-cc; Emscripten or WASI binaries won't run. See the developer guide.