Me and my homies Claude and Gemini present:
An SGI Indy / Indigo2 emulator, vibed into existence with Rust and AI assistance. Boots IRIX 6.5 and 5.3. Has networking. Has a framebuffer.
Status snapshot:
- Indy IP24 — primary daily-driver; IRIX desktop, X11, networking all work. R4400 (default) or R5000, picked at runtime.
- Indigo2 IP22 — embedded PROM fallback, two SCSI controllers, and the fullhouse interrupt layout. Choose Newport XL, GR2 XZ/Extreme, or IMPACT graphics; GR2 and IMPACT use command interpreters and software rasterizers (see Indigo2 IP22).
- Indigo2 IMPACT IP28 — R10000 CPU and IMPACT graphics, with IRIX 6.5 booting to the desktop, with an embedded IP28 PROM fallback. Two 512 MB banks provide 1 GB of RAM (see Indigo2 IP28).
Prebuilt releases are available in irix7/iris GitHub Releases.
This repository (irix7/iris) is a fork of
techomancer/iris — the upstream SGI
Indy / Indigo2 emulator.
Upstream remains the canonical project. The fork is maintained by Jupiter
Belic; anyone reusing its work elsewhere should follow the attribution rules
in AGENTS.md.
This fork is a working tree for two things: performance (allocator, PGO and
target-cpu build defaults; interpreter/JIT dispatch; idle-parking and
device-thread polling; RAM access, SCSI/DMA and NAT hot paths) and running
IRIS as several parallel per-task instances for development. The first
upstream-facing change of the latter kind is the CI copy-on-write overlay
relocation (IRIS_COW_OVERLAY_DIR). Changes are kept in the shape of upstream
commits so they can be offered back rather than diverging.
Instance mode is landing in stages under the epic
Parallel instance fleet (tickets
#2–#21). The --instance flags and the two isolation seams are in; see
docs/parallel-instances.md for the model, the
derivation table, and what is still open.
To pull upstream changes:
git remote add upstream https://github.com/techomancer/iris # once
git fetch upstream
git merge upstream/mainQ: What is it?
A: An SGI Indy / Indigo2 emulator with runtime-selectable R4400, R5000, or R10000 CPUs. Emulates enough hardware that IRIX boots to a usable system: shell, networking, X11, the works.
Q: But why?
A: Wanted to see how far vibe coding could go, and to learn some Rust along the way.
Q: You could have improved MAME.
A: Didn't seem like fun.
Q: So did you learn Rust?
A: LOL, my brain hurts. Let's not get ahead of ourselves.
Q: What LLMs did you use?
A: Mostly Claude, some Gemini. They wrote a lot of the hard parts. (This was written by Claude, the humble AI assistant).
Q: Can I contribute?
A: Yes, bug reports and merge requests are welcome.
Q: Regrets?
A: Yes.
- IRIX 6.5 boots to multiuser, networking works (ping, telnet, ftp, rsh, NFS, XDMCP)
- IRIX 5.3 works too
- Indy IP24: X11 / Newport (REX3) graphics works, with mouse and keyboard input (IntelliMouse wheel included), HAL2 audio, and IndyCam video-in through VINO
- Indigo2 IP22: Newport, GR2 XZ/Extreme, and IMPACT graphics; two SCSI controllers
- Indigo2 IP28: R10000, IMPACT graphics, and up to 1 GB with two 512 MB banks
- R4400, R5000, or R10000 CPU, selected per machine at runtime
- Cranelift JIT compiler for MIPS to host code (
jitv2, optional, experimental), plus a REX3 draw pipeline of 400+ precompiled specialised draw functions and an optional REX3 shader JIT (rex-jit), an IMPACT raster pipeline JIT (gr4-jit) and a GR2 (XZ / Extreme) span JIT (gr2-jit);gpujitturns on all three - Copy-on-write disk overlay, and CHD images with MAME-style
.diff.chdsidecars. Crash all day, base image stays clean - Hot-swappable CD-ROM with runtime disc switching
- Snapshots: save, restore, in-memory rollback, content-addressed dedup, HTTP push/pull
- Built-in NAT gateway with DHCP, host-DNS forwarding, port forwarding, an in-process NFSv2/v3 server, TFTP for PROM network boot, and FTP/XDMCP helpers; or PCAP bridging onto a real LAN
- Headless mode and a CI control socket (
iris-ci) for automation - Optional egui front-end (
iris-gui) with machine management and a benchmark tab; machines use the CLI TOML schema in isolated folders with relative paths - DaynaPort SCSI/Link Ethernet and the N64 development board (Ultra64), both enabled per machine in the config
- Other guests: Linux (Debian 7, Gentoo), NetBSD and OpenBSD have had SCSI, interrupt and timer fixes land for them. They are not regularly tested, so expect rough edges
Download Windows, macOS, and Linux builds from irix7/iris releases. The CLI and iris-gui are developed in this repository. Dani Sarfati contributed the GUI and its Mac App Store distribution support.
You need:
- A hard-disk image with IRIX 6.5.22 (or 5.3) for Indy. To produce one, follow clanker/irix/irix-install.md (install from the original media CDs into an empty CHD/raw disk).
- An external PROM image (optional):
070-9101-011.binfor Indy,070-1367-012.binfor Indigo2 IP22, or070-1477-002.binfor Indigo2 IP28. Each machine has its own embedded fallback.
Now, if you feel like typing some commands in console. Sync the project and:
cargo run --release
The project pins a nightly toolchain (rust-toolchain.toml); rustup picks it up
automatically.
On a Nix host flake.nix is the build environment. nix develop also installs
a launcher at target/launcher/bin/iris that carries the shell's library search
path, so automated runs and the test scripts need no LD_LIBRARY_PATH of their
own; the cargo-built binary stays available for gdb and friends. A plain cargo
build is all that is needed anywhere else, and iris reads no environment
variable to find its libraries. Details:
HELP.md.
For the complete core/GUI build-feature lists, configuration keys, CLI options, defaults, conflicts, and environment controls, see FEATURES.md. It also contains build examples, CPU details, and JIT implementation notes. The GUI tour is in iris-gui-README.md; Windows/WSL launch guidance is in wsl/README.md.
See CHANGELOG.md for dated changes and clanker/TODO.md for the feature-completion backlog.
Start with FEATURES.md for the complete build-feature and
configuration inventory for both iris and iris-gui.
| Guide | Contents |
|---|---|
| HELP.md | CLI usage, TOML examples, serial access, and guest setup. |
| debug.md | The monitor console's full command reference, the GDB stub, the MCP server, traces and other introspection. |
| HACKING.md | How the emulator is built: bus and device traits, threads and locks, the GFIFO, jitv2. |
| iris-gui-README.md | GUI build, machine management, input, disks, networking, benchmarks, and distribution. |
| FEATURES.md | All build features, profiles, configuration keys, CLI switches, GUI settings, diagnostic environment controls, CPU specifications, and JIT behavior. |
| NETWORKING.md | PCAP bridging and DaynaPort setup; DaynaPort protocol and XDMCP provide implementation and remote-display detail. |
| STORAGE.md | CHD, overlays, snapshots, CI automation, and scratch-volume file transfer. |
| docs/parallel-instances.md | Running several VMs side by side: the --instance flags, the StatePaths / derive_instance seam, and the epic #1 ticket map. |
| TESTING.md | Rust and guest tests, benchmark commands, CPU matrices, and performance methodology. |
| docs/ci.md | GitHub Actions: the setup-iris action, release and source installs, caching, and a media-free ROM smoke workflow. |
| CHANGELOG.md | Dated repository changes. |
| clanker/TODO.md | Current feature-completion backlog. |
| wsl/README.md | Windows/WSL build, launch, and troubleshooting. |
| PRIVACY.md | Privacy policy; App Store review notes describe distribution constraints. |
Hardware, testing, and development references:
CHD hard disks and CD-ROMs mount directly. Compressed parents stay untouched; writes use MAME-style diff sidecars. See STORAGE.md for the backend/licensing details and HELP.md for disk preparation.
PCAP places the guest on a physical LAN through a host capture interface. Library/driver requirements, permissions, licensing, setup, and caveats are in NETWORKING.md.
The SCSI Ethernet adapter is built in and attached per machine. See NETWORKING.md for its configuration, driver links, and network isolation requirements.
R4400, R5000, and R10000 are selected at runtime. The specifications, configuration examples, performance context, and snapshot compatibility rules are in FEATURES.md.
Optional jitv2 compiles MIPS code; rex-jit compiles Newport draw shaders
alongside the precompiled drawing routines; gr4-jit compiles IMPACT raster
pipelines; gr2-jit compiles GR2 RE3 span pipelines. gpujit turns on all
the graphics JITs and is the recommended
build (--features lightning,gpujit). See
FEATURES.md for their behavior, defaults,
limitations, persistent caches, and corpus-measurement tools.
Overlay modes keep base images clean while the guest writes. Configuration, commit/discard behavior, and CHD sidecar rules are in STORAGE.md.
Save/restore, rollback, deduplication, and HTTP snapshot transfer are documented in STORAGE.md. GR2/IMPACT snapshot coverage is incomplete; that guide states the limits.
Use STORAGE.md for Unix/TCP setup,
commands, serial capture, and scripts. --ci keeps offscreen graphics alive
unless --headless is explicitly selected.
Run several VMs from one host with --instance N (ids are 0-based). Each id
derives a private state directory (iris-instance-{N}, overridable with
--state-dir), a port block from --port-base (default 9000 + N*10, clear
of the legacy 8880/8881/8888 defaults), a CI socket, a stable guest MAC and a
distinct NAT /24:
iris --instance 0 --ci & # first VM, CI socket under ./iris-instance-0
iris --instance 1 --ci & # second VM, no port or socket clash
iris --instance 2 --print-instance # print the derived endpoints and exitEach state directory is owned by one live process through a locked
iris.lock. A second start there fails with the owner's PID instead of
silently sharing NVRAM or a CI socket; --replace stops that recorded owner
(cleanly over its CI socket when it can) before starting. See
HELP.md for signal and stale-file
behaviour.
Today the derivation applies NVRAM/EEPROM paths, the monitor/serial/CI ports, the CI socket, the MAC and the NAT subnet. Wiring the remaining artefacts (snapshot store, COW/CHD overlays, JIT cache, logs and the test dump) under the state directory, plus a fleet launcher and serial session isolation, are the open tickets in docs/parallel-instances.md. With no instance flag nothing changes, and there is deliberately one VM per process.
Host-to-guest file transfer through a raw scratch disk is described in STORAGE.md.
Click the window to grab mouse and keyboard. In the iris window Right Ctrl
releases the grab (on macOS Right Cmd does too, since Mac keyboards have no
Right Ctrl); in iris-gui it is Ctrl+Alt (Option+Command on macOS), with
Ctrl+Alt+Esc as a fallback. When the window loses focus, keys and mouse
buttons still held in the guest are released. Mouse and keyboard use standard PS/2 emulation
through the IOC, including an IntelliMouse scroll wheel. Keys are sent by
physical position, so set IRIX's keybd to your layout.
Note: Alt-tabbing away from the window can garble keyboard input in IRIX
terminal apps. Use telnet 127.0.0.1 2323 (with port forwarding configured)
for a clean terminal instead.
See TESTING.md for Rust tests, bare-metal CPU/benchmark suites, matrix runs, reference hardware, and performance methodology.
The clanker/ folder holds working notes written mainly
for AI coding agents: debugging lessons, subsystem gotchas, investigation
logs, plans, the backlog, agent skills and the MCP server. They are terse and
dated, but often the fastest way to learn why something is the way it is.
clanker/INDEX.md lists them by subsystem.
CLAUDE.md and AGENTS.md link to the agent
instructions, clanker/CLANKER.md; rules/ links to clanker/ for old
references.
BSD 3-Clause (LICENSE).
IRIS links libchdman-rs (>= 0.288.8), which — along with the MAME CHD core
it vendors — is also BSD 3-Clause, so the whole binary stays BSD 3-Clause. See LICENSE-libchdman-rs.txt for that third-party
notice.
Dominik Behr and contributors
We have no problems with LLM generated code. In fact most of IRIS is made with LLMs. But that doesn't mean we don't do proper software engineering. So lets keep PRs small and reasonable to review. One issue/fix per PR, preferably in one commit, since LLM code churn doesn't help with clarity. Lets keep this bisectable too.
On this host the JIT (jitv2) runs the R4400 guest at 644 MIPS versus 126 MIPS interpreted (5.1x speedup).
See BENCHMARKS.md for the full benchmark suite documentation: bare-metal kernels, IRIX workloads, CI workflows, data pipeline, and generated charts.
Latest run (4 cells):
| cell | CPU | accuracy | MIPS | DMIPS | LINPACK MFLOPS | Whetstone k/s |
|---|---|---|---|---|---|---|
r4400-interp |
R4400 | 100.0% | 126.4 | 168.8 | 20.6 | 6001.0 |
r4400-jitv2 |
R4400 | 100.0% | 644.2 | 531.2 | 36.9 | 1308.0 |
r5000-interp |
R5000 | 100.0% | 61.7 | 92.3 | 10.9 | 2919.0 |
r5000-jitv2 |
R5000 | 100.0% | 405.1 | 881.0 | 57.9 | 9295.0 |
Charts (auto-regenerated from CI history):
- Raw MIPS history — log scale, host-break lines
- Normalised efficiency — % of native host speed
- JIT speedup — JIT/interp ratio over time
- Efficiency by group — int/fpu/mem/img/vid/codec/sys
- Group heatmap — 80 commits × 7 groups
- Full history table — with inline sparklines
Profile artifacts (Rust flamegraphs): see bench-profile.yml workflow, uploaded per commit.