Advanced

This chapter collects the power-user surfaces — the ones you reach for occasionally, not every day. It covers rolling a machine's home folder back to an earlier boot with Rewind home…, the built-in ext4 file browser that opens a machine's disk images directly on your Mac without booting the VM, the native filesystem check, and a few low-level configuration defaults.

A machine (a workspace, in the settings editor) keeps its data in two Linux ext4 disk images: the system disk and the home image. Everything here assumes you are comfortable with the storage model described in Machines and Resources settings.

Rewinding a machine's home

Each time a machine starts successfully, Bromure takes a copy-on-write checkpoint of its home image — the /home/ubuntu that holds your project checkouts, dotfiles, .ssh, shell history and agent state. Checkpoints are kept on a tiered ladder: the last few boots, then one a day for a week, then one a week for a month. They cost real disk space only as the live home drifts away from them.

Rewind home… is the everyday way to use them:

1. In the sidebar, open Virtual Machines and click the ⋯ button on the machine's row.
2. Choose Rewind home…. A sheet titled Rewind “‹machine›”’s home opens: "Each point is the home folder as it was when that boot started. The next start boots from the one you pick; the home as it is now is kept as a new point, so this can be undone here."
3. Pick a point in the list. Each row shows the date and time, how long ago that was, and the checkpoint's size on disk.
4. Click Rewind.

When it is done the sheet reads "Done — the next start of “‹machine›” boots from its home of ‹date›." Nothing else changes: the system disk, the machine's settings, and its credentials stay as they are.

Things to know:

• The machine must be off. The home image is swapped whole, so it can't be in use. While the machine is running, the sheet says "The machine is running — its home can't be swapped while it's in use. Shut it down first." and offers a Shut down button; Rewind stays disabled until the machine is off.
• A rewind can be undone. Before swapping, the current home becomes a new rollback point at the top of the same list. To undo, open Rewind home… again and pick it.
• No points yet. A machine that has never booted, or was just created, shows "No rollback points yet — one is taken each time this machine starts."
• Older machines. A machine that still keeps its home in a folder on the Mac (the legacy shared-folder home) has no image to rewind; the sheet says "This machine keeps its home on the Mac, not in an image — nothing to rewind." Upgrade its storage from the Resources pane first.
• Remote machines. In a rich-client mirror window, Rewind home… works the same way, against the server's checkpoints.

The other storage actions

The machine's Resources pane (⋯ › Edit… › Resources) keeps the older, per-layer actions. They are disabled while the machine's window is open ("Close the session window first."):

The machine's ⋯ menu also has Reset disk, the same system-disk reset. See Resources settings for the full pane.

The ext4 file browser

macOS has no native ext4 support, so ordinarily the only way to see inside a machine's disk images is to boot the VM. Bromure avoids that with its own dependency-free ext4 reader and writer: it parses the on-disk format directly and shows you the tree.

Workspaces › Open ext4 file… opens any ext4 (also ext2 or ext3) .img — a raw filesystem or an MBR/GPT-partitioned disk — in a Finder-like window. Nothing is mounted, no VM boots, and no elevated privileges are needed.

Note: The image opens read-only by default — safe even if a VM still has the disk attached. Editing is a separate, explicitly gated step (see Editing an image).

What you can open

A machine lives under ~/Library/Application Support/BromureAC/profiles/<uuid>/. Two images there are worth browsing, plus their rollback checkpoints:

The home image behaves this way because the guest mounts it over /home/ubuntu on boot, so the image's own root directory is that home folder. Kubernetes nodes, registries and the messaging connector keep their disks under kube/<id>/nodes/<uuid>/ instead, and open the same way.

Opening an image

1. Choose Workspaces › Open ext4 file….
2. An open panel titled Open ext4 Disk Image appears — "Choose an ext4 .img disk image (raw or partitioned)." — starting in ~/Library/Application Support/BromureAC. Navigate into a machine's profiles/<uuid>/ folder and pick disk.img, home.img, or a file under checkpoints/.
3. The browser opens in a window titled ext4 — «filename», showing the filesystem root.

The toolbar's info line summarizes the volume: its label, total size, whether the filesystem was found raw or at a partition offset, and its state — clean, not cleanly unmounted, or journal needs recovery. There is one window per image; reopening an image that is already open just focuses its window.

Browsing, previewing, and extracting

The main view is a three-column table — Name, Size, and Type — with directories listed first. Type distinguishes folders, files, and symlinks, as well as the special Unix node types (Char, Block, FIFO, Socket).

• Navigate — double-click a folder to enter it; click the toolbar Up arrow to go back. The breadcrumb shows the current path.
• Preview — double-click a file, or right-click it and choose Preview. Text files render as text; binary files render as a hex dump. Either way the preview is capped at the first 1 MiB, and the footer reports how many of the file's total bytes are shown. A symlink previews as its target path.
• Extract — right-click a file and choose Extract… to write its full contents to your Mac through a save panel. This is the read-only path you will use most often.

Editing an image

Editing is deliberately behind a gate. Click Enable Editing… in the toolbar; the alert Enable editing of this disk image? warns:

Only edit an image whose workspace VM is stopped. Writing to a disk that a running VM has open will corrupt it.

Click Enable Editing and the image reopens read-write, with an orange Editing badge in the toolbar. A file's context menu then gains Replace…: pick a host file whose contents overwrite the selected file in place. The editor recomputes the inode's checksum, so the result stays consistent.

Warning: Replacement is in-place only. The new contents must fit the file's already-allocated blocks — a larger file is refused with That file would need to grow (growing, creating, and deleting files is not enabled). Inline-data files cannot be edited. Writes are refused while the journal needs recovery — run fsck first (below). And never edit an image that a running VM has attached.

Checking and repairing a disk

Bromure checks and repairs ext4 images with its own built-in checker — there is nothing to install (macOS ships no e2fsprogs, and Bromure doesn't use it). You meet it in three places:

• Automatically, at boot. When a machine's boot stops on filesystem errors, its stage shows DISK ERROR — "The system disk failed its boot-time filesystem check, and the boot cannot continue." — with Repair Disk and Reset System Disk…. Repair Disk stops the VM, runs the checker on the system disk, and boots again; nothing is deleted. If the next boot fails again, reset is the way forward. See Troubleshooting.
• In the ext4 browser. The toolbar's Run fsck… button.
• From the command line. bromure-cli vm fsck <workspace> [--repair] [--home] — see CLI, API & MCP.

In the browser, Run fsck… asks Check this image? — "This replays the filesystem journal if it is dirty and verifies the metadata. The workspace VM must be stopped. It can modify the image." — with Run fsck and Cancel. The result appears in a sheet titled fsck.ext4, with a one-line summary above the full output:

The image is then reopened, so the browser shows the repaired state.

What the checker does, and doesn't:

• Repair replays the filesystem journal and clears the "needs recovery" flag. This is the whole story for nearly every broken Bromure disk: images become unclean when a VM is stopped mid-write or dies, not through bit rot.
• Verify always checks the superblock and group-descriptor checksums, then walks the tree from the root, validating every reachable inode's checksum and extent tree. It reports what it finds but doesn't patch it.
• For damage the checker can't repair, the honest fix is Linux's own e2fsck inside a VM. The guest already checks the home image on every boot, and Kubernetes nodes and registries fall back to a throwaway machine that runs e2fsck on their disks automatically. For a workspace's system disk, Reset to base… re-clones it and leaves the home untouched.

When to reach for these tools

• Undo damage to your home — an agent deleted the wrong folder, or a dotfile change broke your shell: Rewind home… to the last good boot.
• Recover a file from a machine you would rather not boot — pull out an uncommitted change or a log from home.img with Extract….
• Inspect a checkpoint before you rewind, to confirm it holds what you expect: open it from checkpoints/home/ in the ext4 browser.
• Rescue a machine that won't boot — let Repair Disk replay the journal; if a bad config file is the cause, replace it in place with the browser and run fsck. See Troubleshooting for boot-failure diagnosis.

Developer defaults

A few low-level knobs are read from the app's UserDefaults domain, io.bromure.agentic-coding. Set them with defaults write while the app is not running, then relaunch:

For example, to make future machines' home images appear as 128 GiB:

defaults write io.bromure.agentic-coding vm.homeImageGB -int 128

Note: vm.homeImageGB affects only home images created after the change; existing images keep their size. A home image can be grown later but not shrunk.

Tip: For genuinely throwaway work, bromure-cli vm run --rm boots a Docker-style disposable workspace whose disk is deleted when the VM stops — documented in CLI, API & MCP.

The full list of UserDefaults keys and environment variables is in the Appendix.