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 git 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 — entirely inside your browser tab (see Linux in the browser for how).

brintOS hosts two repository types: machine images (this page) and ordinary git repositories. Only image repos can be launched.

Creating a machine

Go to brintos.io/new and pick the machine image type. Three starting points:

• From a template — fork one of our ready-to-boot template images.
• Fork an existing machine — any machine your account can read.
• From scratch — an empty drive you populate yourself.

You can also fork directly from any machine's page. A fork is a full writable copy under your account — content addressing means it shares storage with its parent rather than duplicating it.

The machine spec

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

Launching

Launch machine on the repo page opens the launch surface; Power on boots it. The machine's drive is mounted as the root filesystem over virtio-fs — your browser serves file blobs out of cloud storage on demand, verified by hash on read — and the spec's kernel boots against it in a dedicated worker. 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.

Persistence and snapshots

Writes made by the running machine go back to its cloud drive — power off, reload, boot again, and your files are there. Owners manage point-in-time copies under Settings → Snapshots:

• Each snapshot is a complete drive state. live is the working drive and always exists; the machine boots from whichever snapshot is marked active.
• Capture from active makes a new snapshot of the current active state; snapshots can be renamed, deleted, or made active (booting an older snapshot is how you roll back).

Working with the drive from your computer

brintos-fs mounts a machine's drive as a local directory over FUSE:

brintos login
brintos mount <owner>/<repo> /tmp/mymachine
# --snapshot NAME mounts a specific snapshot instead of the active one

Mounts are read-write when your account has write access to the repo, read-only otherwise. Writes are write-back — they complete at local speed and drain to the server in the background; sync/fsync or unmounting are the durable barriers. The end-to-end developer loop (build a binary locally, drop it onto a machine, run it in the browser) is Build locally, run on brintOS.

Sharing

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

Current limitations

• No network interface in the guest yet. Machines today boot without an eth0 — programs inside the machine can't open sockets to the outside world. Network-as-a-service describes the virtual NIC this is building toward.
• Machines are single-operator. A running machine lives in one browser tab; there is no shared live session — sharing a machine shares the filesystem, and each visitor boots their own instance.
• 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.