Getting started

Emu198x is 30 emulators, one binary per machine. The thing that catches people first: there is no emu198x command. You run the machine — emu198x-spectrum, emu198x-c64, emu198x-nes — and each one has its own download and Homebrew formula.

One binary is one machine

A binary carries the hardware and nothing else. The binary called emu198x-spectrum is a ZX Spectrum: its Z80, its ULA, its tape port, its timing. There is no Spectrum ROM inside it and no software, and it will not run a C64 disk. Point it at firmware and media you supply, and it boots.

Each binary starts in one of three modes.

• A window. The default, and what a bare start gives you on 20 of the 30 machines: run the binary and it boots into a native window. The other 10 want media first — the Atari, Sega and Nintendo consoles, the Dragon 32 and the BBC Micro — and starting one without it exits with an error naming what is missing.
• A headless run. Either --headless or --script. The machine runs with no window and follows a list of steps: run frames, load media, press keys, read or patch memory, save a screenshot or an audio capture.
• An MCP server. --mcp. The same controls over stdio, plus per-chip queries, for an agent or another tool to drive.

All 30 machines have all three modes. What they do not share is their flags. The Spectrum takes --rom and --tape, the Atari 2600 takes --cart, the MSX takes --bios, the C64 takes --rom-dir. Run any binary with --help and it prints that machine's own set, along with its keyboard controls.

Binary names are shortened, and they do not always match the name a machine goes by here: the NES ships from emu198x-nes, the MSX1 from emu198x-msx, the Oric from emu198x-oric-atmos. Every machine page in the system matrix names the binary that machine ships from.

What works today

Each release publishes an archive per machine per desktop platform — macOS on Apple silicon and Intel, Linux on ARM64 and x86-64, and Windows on x86-64. Start at the downloads page, which links the current release. Building from a source checkout gets you the same binaries and needs a current stable Rust toolchain.

What differs between machines is boot depth: how far real firmware and real software get. Some boot to a prompt and load from tape; some paint nothing until you give them media. The system matrix carries a boot capture for each machine that has one, and the accuracy progress page carries the evidence behind it.

Install with Homebrew

On macOS or Linux, Homebrew installs the binary for your processor. Install just the machines you want:

brew install emu198x/tap/emu198x-spectrum
emu198x-spectrum --rom /path/to/your/48.rom

The downloads page lists every machine's Homebrew command and its archives. With Homebrew, run the command by name; with an extracted archive, use ./ from its folder. On Windows, extract the ZIP and run the .exe.

Running a machine

Take the ZX Spectrum. From an unpacked release archive:

tar xf emu198x-spectrum-aarch64-apple-darwin.tar.gz
cd emu198x-spectrum-aarch64-apple-darwin
./emu198x-spectrum --rom /path/to/your/48.rom

The same run from a source checkout:

git clone https://github.com/emu198x/emu198x.git
cd emu198x
cargo run --release -p emu198x-spectrum -- --rom /path/to/your/48.rom

Both open a Spectrum window sitting on the copyright line, which is where a 48K machine starts with nothing loaded. To load something, hand it a tape and let the machine's own ROM loader run:

./emu198x-spectrum --rom /path/to/your/48.rom --tape /path/to/your/game.tap --autoload-tape

The --autoload-tape flag waits for the boot to finish, types LOAD "", and starts the tape motor. That is the real loading path rather than an instant-load trap, so the border stripes you get are the ones the hardware produced.

Where the firmware goes

Passing --rom on every run wears thin. Each binary also looks under ~/.emu198x/roms/ for the firmware its machine needs, in a directory named for that machine:

mkdir -p ~/.emu198x/roms/sinclair-zx-spectrum-48k
cp /path/to/your/48.rom ~/.emu198x/roms/sinclair-zx-spectrum-48k/48.rom
./emu198x-spectrum

Nothing here has to be guessed. Start a binary before its firmware is in place and the error names the exact file it went looking for:

error: ROM not found at /Users/you/.emu198x/roms/sinclair-zx-spectrum-48k/48.rom

What you need that we cannot give you

Firmware and software. Emu198x ships no ROMs, no BIOS images, and no disks, tapes or cartridges; the downloads page sets out the position on that. What you have to find depends on the machine: a Spectrum, an MSX or a PET needs its firmware before it will boot at all, while a NES or a Master System has no system ROM and starts from the cartridge image you supply.

What does not work yet

• No unified command. A wrapper that reads a file's type and starts the machine that matches is a design, not a release. You pick the binary yourself.
• No launcher screen. Starting a binary boots its machine immediately, and every option is a command-line flag. Per-machine launchers with model, memory and expansion pickers are planned and not built.
• No browser build. Releases target macOS, Linux and Windows. A WASM build is intended and does not exist.
• The windows are verifier shells. They exist to check the hardware against real firmware and real software, and they show it: file handling, input configuration and on-screen media controls are thin or absent.
• Boot depth is uneven. A machine having a binary is not a promise that it reaches a usable prompt with your firmware. The Sord M5, for one, paints a blank screen from its own monitor ROM and needs a cartridge before there is anything to see. Check the machine you care about on the system matrix before assuming.