86BoxControl

Small, reusable helpers collected while setting up a Windows 98 and DOS software VM in 86Box on macOS.

This folder intentionally contains only automation and documentation. It does not contain commercial software, registration details, VM disks, extracted installers, floppy images, or generated ISOs.

What is here

• host/ — prepare ISO and FAT-floppy media on macOS.
• codex/ — reusable @oai/sky helpers for controlling the 86Box macOS UI from a Codex node_repl session.
• guest/windows98/ — VBScript and Autorun examples for launching installers and creating verified desktop shortcuts inside Windows 98.
• guest/dos/ — simple DOS batch launchers used by the VM.
• docs/OPERATING-NOTES.md — the practical lessons that mattered during the setup.
• host/retrobridge/ and guest/windows98/retrobridge98/ — RetroBridge98, a native Windows 98 browser window rendered by an isolated Chrome session on the Mac. See docs/RETROBRIDGE.md for its safety boundary and staged setup.

Typical workflow

1. Extract each original floppy into its own directory:

   host/extract-floppies.sh work/extracted disk01.img disk02.img disk03.img

2. If an installer can read all files from one directory, merge the directories. The merge fails on conflicting files by default, which prevents a later disk's unrelated INSTALL.EXE from silently replacing disk 1's installer:

   host/merge-disk-directories.sh work/merged work/extracted/disk01 work/extracted/disk02

3. Add an appropriate guest launcher, then build an ISO:

   host/build-iso.sh work/merged output/installer.iso

4. Mount the ISO in 86Box. The Codex helper can drive the macOS file picker by exact path; see codex/sky-86box.mjs and docs/OPERATING-NOTES.md.

To organise an established guest without relocating fragile DOS/Windows 9x install directories, build a small ISO containing guest/windows98/ORGANIZE-SHORTCUTS.VBS as ORGANIZE.VBS and guest/windows98/ORGANIZE-AUTORUN.INF as AUTORUN.INF. The script creates C:\GAMES, C:\APPS, C:\TOOLS, C:\DEV, and C:\MEDIA, writes launchers for the known DOS installation paths, and groups recognised shortcuts on the desktop and Start Menu. Installed programs remain in their original locations.

For the reusable multi-disc MP3 copy flow, the collection verifier, and the writable-floppy result channel used when the guest display cannot be inspected, see docs/MP3-COLLECTION.md.

Requirements

• macOS (hdiutil, shasum)
• mtools for floppy extraction/rebuilding (brew install mtools)
• Codex Desktop with Computer Use for the optional @oai/sky helpers
• Docker Desktop, uv, and Google Chrome for building and running RetroBridge98

The guest scripts target Windows 98's Windows Script Host and DOS/Windows command interpreter. Keep their CRLF line endings when placing them on vintage media.

License

The automation and documentation in this repository are available under the MIT License. No third-party software or installation media are included.