# windows95 User Guide

`windows95` is Felix Rieseberg's Electron desktop app that runs Microsoft
Windows 95 inside a window on macOS, Windows, or Linux. It bundles the
[v86](https://github.com/copy/v86) x86 emulator, a SeaBIOS image, a vintage
copy of Windows 95, and a thin React shell that handles disks, files,
networking, and machine state — so you can launch a 30-year-old operating
system the same way you would launch any other modern desktop app.

This guide covers everyday use of the app: installing it, booting Windows 95,
mounting floppy and CD-ROM images, sharing a folder between your real computer
and the virtual one, recovering files from older versions of the app, and
working around the rough edges that come from emulating decade-old hardware.

For internal architecture, build pipeline, code-signing, and integration
points, see the companion **windows95 Administrator & Developer Guide**.

## 1. Quick Start

Get to the Windows 95 desktop in two minutes:

1. Download the installer for your platform from the
   [GitHub Releases page](https://github.com/felixrieseberg/windows95/releases).
2. Install it like any other desktop app (drag to `/Applications` on macOS,
   run the `.exe` setup on Windows, install the `.deb` / `.rpm` / `.flatpak`
   on Linux).
3. Launch **windows95** from your applications launcher.
4. On the welcome card, click **Start Windows 95**.
5. Wait ~30 seconds. SeaBIOS prints, then the splash screen appears,
   then the Windows 95 desktop.
6. Click anywhere inside the emulator to capture your mouse. Press **Esc**
   to release it back to the host.

> [!TIP]
> The emulator window resizes the Windows 95 desktop using a CSS scale of
> `2x` by default. Use **Window ▸ Zoom in / Zoom out / Reset zoom** in the
> menu bar to make the guest larger or smaller without changing its
> resolution. The keyboard accelerator that comes for free is the standard
> macOS / Windows menu shortcut on those items.

### What you get out of the box

- A bootable Windows 95 machine with 128 MB of RAM, an NE2000 network card,
  a Sound Blaster 16, a primary IDE hard disk (`C:`), a floppy drive (`A:`),
  and a CD-ROM drive (`D:`).
- A folder on your real computer, automatically shared with Windows 95 as
  drive `Z:` (default: your Downloads folder).
- Persistent state: Windows 95 boots back to where you left it on every
  launch, including any files you saved or programs you installed.
- Bidirectional text clipboard so Copy/Paste flows between Windows 95
  and your host OS.
- An offline mini-website (`http://windows95/`) browseable from inside
  Internet Explorer in the guest.
- Auto-updater (Squirrel on Windows / macOS) that pulls new releases
  hourly from GitHub once the app is packaged.

> [!NOTE]
> The very first launch unpacks the bundled disk image (`windows95.img`)
> and writes a saved-state file under your application data directory.
> Subsequent launches resume from that snapshot.

## 2. Installation

Pick the installer that matches your platform. All builds are signed
(macOS notarized, Windows Azure-signed) when produced by the upstream
release pipeline.

| Platform | Installer | Filename pattern |
|----------|-----------|------------------|
| macOS (Intel + Apple Silicon) | ZIP from GitHub Releases | `windows95-darwin-*.zip` |
| Windows | Squirrel installer (no MSI) | `windows95-{version}-setup-{arch}.exe` |
| Linux (Debian/Ubuntu) | `.deb` | `windows95_{version}_amd64.deb` |
| Linux (Fedora/RHEL) | `.rpm` | `windows95-{version}.x86_64.rpm` |
| Linux (Flatpak) | `.flatpak` | `windows95-{version}.flatpak` |

### System requirements

| Resource | Minimum | Recommended |
|----------|---------|-------------|
| OS | macOS 11+, Windows 10+, modern Linux desktop | Latest |
| Free RAM | 512 MB | 1 GB+ |
| Free disk | ~1.5 GB (disk image + state) | 3 GB |
| CPU | Any 64-bit x86_64 / arm64 | Modern multi-core |
| Internet | Optional (only for in-guest browsing + auto-updates) | Optional |

> [!IMPORTANT]
> The app embeds the v86 WebAssembly emulator and a 1 GB Windows 95 disk
> image. Once installed, the app runs entirely offline. Internet is only
> consulted for auto-updates and for HTTP traffic the guest itself initiates.

### macOS

=== "macOS"
    1. Download `windows95-darwin-*.zip` from the latest GitHub release.
    2. Unzip and drag **windows95.app** to `/Applications`.
    3. Right-click the app and choose **Open** the first time. macOS will
       verify the signature and remember your choice.
    4. Launch normally afterwards.

The bundle uses Felix Rieseberg's Apple Developer ID
(`Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)`), so Gatekeeper
should accept it without warnings on a current macOS.

### Windows

=== "Windows"
    1. Download `windows95-{version}-setup-{arch}.exe`.
    2. Run the installer. Squirrel installs into your user profile and
       creates Start Menu and Desktop shortcuts. No MSI is shipped — the
       installer is a single executable.
    3. Launch **windows95** from the Start menu.

> [!NOTE]
> If your release was built with `AZURE_TENANT_ID` and `SIGNTOOL_PATH`
> configured, the binary is Azure-signed and timestamped via
> `timestamp.acs.microsoft.com`. Otherwise SmartScreen may show an
> "unrecognized publisher" prompt — click **More info ▸ Run anyway**.

### Linux

=== "Debian/Ubuntu"
    ```bash
    sudo dpkg -i windows95_5.0.1_amd64.deb
    sudo apt -f install   # pull any missing dependencies
    windows95
    ```

=== "Fedora/RHEL"
    ```bash
    sudo rpm -i windows95-5.0.1-1.x86_64.rpm
    windows95
    ```

=== "Flatpak"
    ```bash
    flatpak install --user windows95-5.0.1.flatpak
    flatpak run com.felixrieseberg.windows95
    ```

> [!WARNING]
> Issue [#322](https://github.com/felixrieseberg/windows95/issues/322)
> reports that the RPM installer can fail on some Fedora releases.
> If `rpm -i` complains about missing libraries, install the Flatpak
> instead — it bundles every dependency.

There is no AppImage build at this time. Issue
[#114](https://github.com/felixrieseberg/windows95/issues/114) tracks
that request.

### Verify the install

After launching, check the **Help ▸ About** menu (Linux/macOS) — you
should see the app name `windows95`, your installed app version, and the
Electron runtime version (currently Electron 41 series). On Windows the
version is exposed in the executable's file properties because Electron
doesn't render an in-app About panel on that platform.

## 3. Configuration

windows95 puts its UI configuration on the **Settings** card you reach by
clicking the **Settings...** button on the welcome screen. Most users
never need to touch anything outside this card.

### Settings card overview

The Settings card has five tabs:

| Tab | What it controls |
|-----|------------------|
| **Floppy Drive** | Mount an `.img` / `.ima` / `.vfd` floppy image to drive `A:` for the next boot. |
| **CD-ROM** | Mount an `.iso` image to drive `D:` for the next boot. |
| **Shared Folder** | Choose which folder on your real computer becomes drive `Z:` inside Windows. |
| **Interface** | Toggle which live machine stats appear in the info bar (CPU, disk, network, sparklines). |
| **Machine State** | Reset the saved state, or boot a brand-new Windows 95 from scratch. |

> [!TIP]
> Pre-boot mounts (Floppy / CD-ROM tabs on the Settings card) attach the
> media before Windows 95 starts so the OS sees them at boot. To swap
> media while the machine is already running, use the **Machine** menu
> instead — see Section 4.

### Where settings live

| Setting | Location | Notes |
|---------|----------|-------|
| Shared folder path | `settings.json` in your app's userData dir | Set via the Shared Folder tab or Machine menu. |
| Info bar metrics | Browser `localStorage` | Per-install, not synced. |
| Saved machine state | `state-v5.bin` in userData | Auto-saved on quit, auto-restored on launch. |
| Recovered legacy files | `~/Downloads/Recovered C Drive/` | Created the first time the app rescues an older state. |

The userData directory follows Electron's convention:

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/windows95/` |
| Windows | `%APPDATA%\windows95\` |
| Linux | `~/.config/windows95/` |

### Environment variables (rarely needed)

Most users never set these. They are aimed at developers and the boot-probe
harness, but a few are occasionally useful for power users.

| Variable | What it does |
|----------|--------------|
| `WIN95_SMB_SHARE` | Override the host folder shared as drive `Z:` for one launch (path on the real computer). |
| `WIN95_SMB_LOG` | Write SMB protocol diagnostics to the file at this path. Useful when troubleshooting `\\HOST` access. |
| `WIN95_SMB_CAPTURE` | If set, log every parsed SMB request — much chattier than `WIN95_SMB_LOG`. |
| `WIN95_RECOVER_DIR` | Override the destination folder for legacy-state file recovery (defaults to `Downloads`). |
| `WIN95_DEBUG_PORT` | Renderer DevTools Protocol port when the app runs in dev mode. Defaults to `9222`. |

> [!IMPORTANT]
> The full set of `WIN95_PROBE_*` variables is the test harness. They are
> documented in the Admin Guide but are not part of the supported user
> surface; setting them by accident will cause the app to behave like an
> unattended test runner.

For everything else (Electron command-line switches, custom WASM paths,
build-time signing variables), see the Configuration Reference in the
Admin Guide.

## 4. Core Usage

This section walks through everything you can do once Windows 95 is
running. Tasks are grouped by what you are trying to accomplish.

### 4.1 Boot, stop, restart, reset

These four operations live on the **Machine** menu and on the Settings
card. They behave differently in important ways:

| Operation | Where | What happens |
|-----------|-------|--------------|
| **Start** | Machine ▸ Start, or **Start Windows 95** on the welcome card | Launches v86 with your saved state restored (if any), or boots fresh on first run. |
| **Start without state** | Machine ▸ Start without state, or **Boot from scratch** on the Machine State tab | Launches a brand-new Windows 95 even if a saved state exists. |
| **Restart** | Machine ▸ Restart | Soft reboots the running guest (equivalent to Windows ▸ Shut Down ▸ Restart). |
| **Reset** | Machine ▸ Reset | Deletes the saved state and reloads the renderer page — full forced reset. Confirmation dialog warns first. |
| **Stop** | Machine ▸ Stop | Pauses the emulator and saves state. The window keeps showing the last frame, dimmed. |

> [!CAUTION]
> **Reset** deletes the on-disk machine state. Anything you saved inside
> Windows 95 (Word documents, installed programs, registry tweaks) is
> lost. If you only want to fix a stuck machine, try **Restart** first.

### 4.2 Sending special key combinations

Some key chords are intercepted by your host OS and never reach Windows 95
(`Ctrl+Alt+Del` is the obvious example). The Machine menu exposes them
as menu items so you can send them deliberately:

| Menu item | Sends to guest | Why it exists |
|-----------|----------------|---------------|
| Send Ctrl+Alt+Del | Ctrl+Alt+Del | Open the Win95 Close Program dialog. |
| Send Alt+F4 | Alt+F4 | Close the active window inside Windows 95 without your host catching it. |
| Send Alt+Enter | Alt+Enter | Toggle DOS prompts between windowed and full-screen. |
| Send Esc | (Esc-equivalent) | Mostly for completeness — Esc inside the focused window already passes through. |

Everything else (typing, regular shortcuts, modifier keys) just works
when the emulator window has focus and the cursor is captured.

> [!TIP]
> Press **Esc** at any time to release or recapture your cursor. Once the
> cursor is captured, Esc inside Windows 95 still works — the host
> renderer reads the keystroke, toggles cursor-lock, and forwards it.

### 4.3 Mouse capture (and seamless mode)

There are two mouse modes:

- **Captured (default)**: click inside the emulator to lock your pointer
  to the guest. Press **Esc** to release.
- **Seamless / absolute**: when the guest's `VBMOUSE.DRV` driver is loaded
  (preinstalled on the bundled disk image) it requests *absolute* mouse
  positioning over the VMware backdoor. The app automatically drops
  pointer-lock and the host pointer becomes the guest pointer 1:1 — exactly
  like running a regular VM with guest additions installed.

You can tell the modes apart visually: in seamless mode you see your real
cursor passing over the guest, in captured mode it's hidden and the
guest's drawn cursor takes over.

### 4.4 Mounting a floppy or CD-ROM

There are two paths depending on whether you want the media at boot or
hot-swapped while running.

#### Pre-boot mount

Use the **Settings** card before clicking Start Windows 95:

1. Click **Settings...** on the welcome card.
2. Pick the **Floppy Drive** or **CD-ROM** tab.
3. Click **Mount image...** and pick an `.img`, `.ima`, `.vfd` (floppy)
   or `.iso` (CD-ROM) file from your real computer.
4. Click **OK** then **Start Windows 95**.

The disk shows up at `A:` (floppies) or `D:` (CD-ROM) inside Windows.

> [!NOTE]
> Floppy images are loaded fully into memory, so a 1.44 MB image becomes a
> 1.44 MB allocation. CD-ROM images are read on demand from disk via a
> synchronous file buffer — you can mount a 600 MB ISO without using
> 600 MB of RAM.

#### Runtime mount (hot-swap)

Use the **Machine** menu while Windows 95 is running:

1. **Machine ▸ Floppy Drive ▸ Insert Disk Image...** or
   **Machine ▸ CD-ROM Drive ▸ Insert Disc Image...**
2. Pick the file. Windows 95 sees the new media immediately.
3. To eject: **Machine ▸ Floppy Drive ▸ Eject** /
   **Machine ▸ CD-ROM Drive ▸ Eject**.

> [!WARNING]
> Inserting a CD while a Windows 95 program is mid-read can confuse
> applications. Eject from inside Windows 95 first (**My Computer ▸
> right-click D: ▸ Eject**) when possible.

### 4.5 Sharing files: the host folder as drive Z:

This is the highest-leverage feature of the app: a folder from your real
computer mounts as drive `Z:` inside Windows 95, with read access to every
file in it. You can drop any file in there on the host and copy it to
`C:` from inside Win95 with regular File Manager / Explorer drag-and-drop.

#### How it works (briefly)

The host runs a small SMB1 server on the renderer side. The guest's
NE2000 NIC routes traffic through v86's userspace TCP stack; the renderer
hooks the TCP-connection bus event for port 139 and answers NetBIOS / SMB1
requests out of the chosen folder. A guest-side agent (`W95TOOLS.EXE`)
auto-maps `\\HOST\HOST` to drive `Z:` at every login, so the share is just
*there* when you log in.

#### Picking a different folder

Either at boot from the Settings card, or while running from the Machine
menu:

| When | How |
|------|-----|
| Before booting | Settings ▸ Shared Folder ▸ **Choose folder...** |
| While running | Machine ▸ **Change Shared Folder...** |

The change is saved to `settings.json` and persists across launches.

> [!NOTE]
> The share is **read-only** from the guest's perspective: you can copy
> files out of `Z:` to `C:`, but Win95 can't write back to your host
> folder over the share. To move a file the other direction, the only
> built-in workaround is the host clipboard for text payloads.

#### Default share folder

If you never pick a folder, the app defaults to your operating system's
**Downloads** directory (whatever Electron's `app.getPath('downloads')`
returns — `~/Downloads` on macOS / Linux, `%USERPROFILE%\Downloads\` on
Windows).

#### Manually mapping the share inside Windows 95

`W95TOOLS.EXE` runs at login and maps `Z:` automatically, but if it fails
or you want a different drive letter:

1. Inside Windows 95: **Start ▸ Run...**
2. Type: `\\HOST\HOST` and press Enter — an Explorer window opens browsing
   the share.
3. Or, **Start ▸ Run...** and type a `NET USE` command:

```text
NET USE Y: \\HOST\HOST
```

The share named `HOST` is your chosen folder (renamed if its basename
contains characters that aren't LANMAN-safe); `\\HOST\TOOLS` is a small
synthetic share holding `_MAPZ.BAT` and a README — the things Windows
uses to map `Z:` automatically.

### 4.6 Copy and paste between host and guest

Text Copy/Paste is bidirectional and automatic, with a ~250 ms latency:

- Copy text inside Windows 95 → it appears in your host clipboard within
  half a second.
- Copy text on the host → next time you paste in Windows 95 (Edit ▸ Paste,
  Ctrl+V, Shift+Ins), the text is there.

Limits and behavior:

- Maximum 64 KB per clipboard event (anything larger is truncated).
- **Text only**: rich text, images, files, and other clipboard formats
  are not synced.
- Encoding is translated automatically (UTF-8 / LF on host ↔ Windows-1252
  / CRLF on guest). Non-Latin characters that don't have a cp1252
  representation are replaced with `?`.

> [!TIP]
> Clipboard sync is driven by `W95TOOLS.EXE` inside Windows. If you Quit
> Win95 and the agent isn't running on next boot (you launched a stripped
> guest), Copy/Paste won't work until you start it manually.

### 4.7 Browsing the offline mini-site

Internet Explorer inside Windows 95 has a built-in shortcut to
`http://windows95/`. Visiting it serves a small static site (home page,
apps catalog, credits, help) directly out of the app's bundle without ever
hitting the public internet.

| Page | URL |
|------|-----|
| Home | `http://windows95/` |
| Apps | `http://windows95/apps.htm` |
| Credits | `http://windows95/credits.htm` |
| Help | `http://windows95/help.htm` |

Type any of those into IE's address bar and it loads from the
`static/www/` directory in the app bundle.

### 4.8 Networking out to the real internet

The guest has a real-feeling network stack with several layers:

| Traffic type | Path |
|--------------|------|
| HTTP (port 80) | v86's "fetch" adapter rewrites the request and uses the host's `fetch()`. CORS headers are forced open by the app's session hook. |
| Other TCP ports | A raw TCP relay opens host sockets and bridges bytes both ways. Loopback, link-local, and the emulated 192.168.86/87 LAN are blocked for safety. |
| DNS | DNS-over-HTTPS via Cloudflare. The renderer intercepts magic names (`windows95`, `*.external`) and answers them locally with a placeholder IP. |

What this means in practice:

- Internet Explorer can browse real websites if your host has internet.
- A vintage IRC client, FTP client, or telnet to a real server works
  because the TCP relay forwards their traffic.
- `ping` does not work — the userspace TCP/IP stack v86 ships does not
  forward ICMP.
- Trying to reach `127.0.0.1`, `169.254.x.x`, or the private
  192.168.86.0/23 emulated LAN from the guest is silently dropped.

### 4.9 Watching live machine stats

By default, the top of the emulator window shows a small status bar:

```text
CPU: 245M/s | Disk: R 0.0B/s W 0.0B/s | Net: ↓0.0B/s ↑0.0B/s | Hide
```

| Metric | Meaning |
|--------|---------|
| CPU | Emulated instructions per second (M=million, G=billion). |
| Disk R/W | Bytes per second moving through the IDE controller. |
| Net ↓/↑ | Bytes per second through the NE2000 NIC. |

Click **Hide** to collapse it into a thin hot-zone at the top edge; hover
that zone to reveal it again, then click **Pin** to keep it visible. The
**Settings ▸ Interface** tab toggles individual metrics and turns
sparklines (the small inline trend graphs) on or off.

### 4.10 Recovering files from older app versions

When a release ships a new disk image or v86 build that breaks save-state
compatibility, the app increments its `STATE_VERSION`. On launch it looks
for an older state file (down to version 4) and offers a **Recover old C:\
drive...** button on the welcome card.

#### What recovery does

1. Spins up a throwaway, headless v86 instance (no keyboard, no mouse,
   no speaker).
2. Restores the legacy state into v86's block cache without booting
   Windows.
3. Walks the FAT32 file system on the recovered virtual disk, reading
   every sector as "overlay if present, base disk image otherwise".
4. Copies every file you ever wrote to or modified (skipping pristine OS
   binaries) into a host folder.

Default destination: `~/Downloads/Recovered C Drive/`. Override via the
`WIN95_RECOVER_DIR` environment variable.

#### When it works and when it doesn't

| Outcome | What happened |
|---------|---------------|
| **Files extracted** | The legacy state, the bundled `windows95.img`, and the geometry across releases were compatible. The button shows "Open folder" and lets you keep or discard the old snapshot. |
| **Recovery failed** | The error message is shown verbatim. The legacy snapshot is preserved on disk untouched; you can keep waiting for a fix or click **Discard old snapshot**. |

> [!WARNING]
> Recovery requires the partition table and FAT geometry to match across
> releases. If a future release reformats the disk image with different
> cluster parameters, recovery from earlier states will fail with
> `unexpected sector size` or similar — there is no fallback path.

## 5. Common Tasks

Goal-oriented recipes for typical workflows.

### 5.1 Install a vintage program from a CD

1. Mount the ISO before booting: **Settings ▸ CD-ROM ▸ Mount image...**.
2. Start Windows 95.
3. Open **My Computer ▸ D:**.
4. Run the installer (`SETUP.EXE`, `INSTALL.EXE`, or whatever the disc
   provides).
5. Follow the wizard. Windows 95 will save the install across reboots
   thanks to state persistence.

### 5.2 Install a program from a folder on your computer

1. Drop the installer files into your shared folder on the host
   (default: Downloads).
2. Boot Windows 95. The folder appears as drive `Z:`.
3. Open `Z:\` in Explorer, run the installer.
4. Programs install to `C:\` and persist across reboots.

> [!TIP]
> Issue [#140](https://github.com/felixrieseberg/windows95/issues/140)
> and [#282](https://github.com/felixrieseberg/windows95/issues/282)
> request clearer instructions for installing extra software. The folder
> route above is the most reliable: drop the installer in your host
> Downloads folder, copy to `C:`, run.

### 5.3 Save your work and quit cleanly

The app saves machine state automatically when you close the window:

1. Inside Windows 95: save your documents (just like real Win95).
2. Close the **windows95** window or quit the app.
3. The renderer pauses, calls `save_state()`, and writes the snapshot
   atomically. Wait until the window actually disappears — it can take
   a couple of seconds for a busy machine.

Next launch resumes from that exact moment, including running programs
and unsaved documents in memory.

### 5.4 Run an MS-DOS Prompt

1. Boot Windows 95.
2. **Start ▸ Programs ▸ MS-DOS Prompt**.
3. Use the DOS environment as you would on real hardware (FAT32 long
   filenames work, networking via the TCP relay does not — DOS programs
   that try to bind raw sockets won't reach the host).

> [!WARNING]
> Issue [#50](https://github.com/felixrieseberg/windows95/issues/50)
> documents that running **Command Prompt** can leave Windows with garbled
> blue pixels when you return to the GUI. If you hit this, pressing
> **Alt+Enter** to toggle the DOS box between windowed and full-screen
> often clears the corruption. A full **Machine ▸ Restart** also works.

### 5.5 Toggle full screen

- Mac: **View ▸ Toggle Full Screen** (Ctrl+Cmd+F).
- Windows / Linux: **View ▸ Toggle Full Screen** (F11).

This makes the *Electron window* full-screen. To resize the *Windows 95
desktop* itself, use **Window ▸ Zoom in / Zoom out / Reset zoom**.

### 5.6 Take a screenshot of the guest

The standard host screenshot tools (macOS Cmd+Shift+4, Windows Snipping
Tool) capture the emulator pixels just like any other window — Windows 95
is rendered into a regular HTML canvas. There is no built-in
"screenshot the guest" feature exposed in the menus.

### 5.7 Reset everything to a fresh Windows 95

Two ways:

1. **Settings ▸ Machine State ▸ Boot from scratch** while the welcome
   card is shown. Boots a fresh Win95 once but keeps the saved state
   alongside.
2. **Settings ▸ Machine State ▸ Reset state**. Deletes the saved state
   and the next launch starts from scratch. *All your changes are lost.*

For a hard reset that also wipes Electron caches and cookies (helpful
when the renderer itself misbehaves):

- **Help ▸ Troubleshooting ▸ Clear Cache and Restart**.

### 5.8 Find your machine state file

On any platform, the state path is determined by Electron's `userData`
location plus `state-v5.bin`. You don't need this for normal use, but
support requests sometimes ask for it.

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/windows95/state-v5.bin` |
| Windows | `%APPDATA%\windows95\state-v5.bin` |
| Linux | `~/.config/windows95/state-v5.bin` |

To open the underlying disk image (read-only — modifying it breaks state
restore): **Machine ▸ Go to Disk Image** opens its location in your
file manager.

### 5.9 Update the app

When packaged builds run, the auto-updater polls GitHub Releases hourly
(`update-electron-app` with `repo: 'felixrieseberg/windows95'`,
`updateInterval: '1 hour'`). New versions are downloaded in the
background and applied on the next restart of the app.

You can also manually grab the latest installer from the
[Releases page](https://github.com/felixrieseberg/windows95/releases).

## 6. Troubleshooting

### Diagnostic decision tree

If Windows 95 doesn't boot or behaves badly:

1. **Did the BIOS / SeaBIOS print appear at all?** No → the renderer hasn't
   started v86. Try **Help ▸ Troubleshooting ▸ Clear Cache and Restart**.
2. **Stuck on the cloud / splash screen for >70s with the CPU running?**
   Known instability that doesn't always reproduce. Try **Machine ▸
   Restart**, or **Reset** if that doesn't work.
3. **Blue screen with `KRNL386` / `VxD dynamic link` / `Initializing
   Device IOS`?** Your saved state may be corrupted. **Machine ▸ Reset**
   wipes it; you'll start a fresh machine but lose user data inside
   Windows.
4. **Garbled pixels after closing an MS-DOS Prompt?** See Section 5.4
   above (issue #50). Alt+Enter or restart.
5. **Drive Z: missing?** Check the Settings ▸ Shared Folder tab for the
   chosen path; if blank, **Choose folder...**, then **Machine ▸
   Restart**.

### Error: `unexpected sector size`

**Cause:** Legacy-state recovery couldn't read the disk image because
the geometry doesn't match what your installed app expects (cross-version
disk reformat).

**Solution:**
1. Click **Discard old snapshot** on the welcome warning panel.
2. **Machine ▸ Reset** or boot from scratch.
3. Manually re-create the work you had inside the old machine.

**Prevention:** Avoid downgrading the app across major versions; the
state format is forward-compatible only.

### Error: `hda block cache not reachable after restore`

**Cause:** The legacy state was loaded but v86's hard-disk async-buffer
cache wasn't where the recovery walker expected it. Usually means the
legacy state is from a v86 build the current renderer can't introspect.

**Solution:** Same as above — discard the old snapshot, boot fresh.

### Error: RPM installer fails on Fedora

**Cause:** Issue [#322](https://github.com/felixrieseberg/windows95/issues/322).
Some Fedora releases lack libraries the RPM expects, or refuse the
unsigned RPM because of policy.

**Solution:**
1. Try the Flatpak instead — it bundles every dependency.
2. As a last resort, use the `.zip` Linux build and run `windows95`
   manually.

### Error: Windows 95 doesn't start after a restart unless I reset

**Cause:** Issue [#299](https://github.com/felixrieseberg/windows95/issues/299).
A specific combination of machine activity at quit can leave the saved
state in a half-consistent place that Windows 95 can't resume from.

**Solution:** **Machine ▸ Reset state**, accept losing your progress.
There's no incremental recovery for this case.

**Prevention:** Cleanly shut down Windows 95 (**Start ▸ Shut Down ▸
Shut down the computer**) before quitting the app, instead of just
closing the window mid-run.

### Error: MS-DOS shows blank / black screen

**Cause:** Issue [#332](https://github.com/felixrieseberg/windows95/issues/332).
A corner case in v86's VGA emulation when DOS resets the display.

**Solution:** Press **Alt+Enter** twice to toggle full-screen on and
off; this often forces a VGA mode reset. Otherwise **Machine ▸ Restart**.

### Error: Windows 95 doesn't see drive Z: at boot

**Cause:** Either no host folder is configured, or the
`W95TOOLS.EXE` agent wasn't running on the previous boot to map the
drive at login.

**Solution:**
1. Confirm a folder is picked: **Settings ▸ Shared Folder** should show
   a path.
2. Inside Windows 95: **Start ▸ Run** ▸ `\\HOST\HOST`. If the share
   browses, your host side is fine.
3. Run `\\HOST\TOOLS\_MAPZ.BAT` (Start ▸ Run) to manually map drive `Z:`.
4. To make the mapping survive every boot, copy `_MAPZ.BAT` from the
   `\\HOST\TOOLS` share to `C:\WINDOWS\Start Menu\Programs\StartUp` —
   the file's own README explains this.

**Prevention:** Don't quit the app while Windows 95 is mid-login;
let the agent finish loading.

### Error: VMware backdoor not present

**Cause:** A `W95TOOLS.EXE` startup popup. The guest's clipboard agent
couldn't find the VMware backdoor I/O port, which v86 normally provides.

**Solution:** This shouldn't happen with the bundled v86 build. If it
does:
1. **Help ▸ Troubleshooting ▸ Clear Cache and Restart**.
2. If the message persists, you may have replaced `libv86.js` manually —
   reinstall the app from the official release.

### Error: Saving / loading state takes forever

**Cause:** Snapshots are uncompressed binary memory dumps + dirty-block
overlays. After a long session with lots of installed software,
state files can be hundreds of MB.

**Solution:** Wait it out. Quit-time saves block window-close until the
write completes (with `flush: true`).

**Prevention:** **Machine ▸ Reset state** every now and then, especially
after experimenting with software you don't want to keep. Smaller state
file = faster save/load.

### Error: CD-ROM doesn't show up as drive D:

**Cause:** Issue [#326](https://github.com/felixrieseberg/windows95/issues/326)
discusses CD-ROM support quirks. Sometimes Windows 95 needs to be told
the secondary IDE channel has new media.

**Solution:**
1. **Machine ▸ CD-ROM Drive ▸ Eject** then **Insert Disc Image...**
   again. The runtime hot-swap goes straight to the device, bypassing
   v86's async loader path that has a known BSY race.
2. If still missing, **Machine ▸ Restart** — the cold boot path is more
   reliable than the hot insert.

### Error: Imported game / app refuses to install

**Cause:** Many vintage installers depend on quirks of real hardware
(specific sound cards, MIDI, joystick ports). Issue
[#327](https://github.com/felixrieseberg/windows95/issues/327) tracks
the broader problem.

**Solution:** The emulator advertises an NE2000 NIC, Sound Blaster 16,
Pentium-class CPU, and a generic VGA. Software targeting other hardware
won't work. There's no fix from the app side — it's an emulation
limitation.

## 7. FAQ

**Q: Can I run Windows 98 / NT / XP / Linux instead?**

A: Not in this app. The bundled disk image, configuration, BIOS, and
v86 build are all tuned to Windows 95. v86 itself supports many other
OSes; if you want them, run v86 directly with a different disk image.

**Q: Where is the disk image stored on my computer?**

A: Inside the app bundle at `<app>/images/windows95.img`. **Machine ▸
Go to Disk Image** opens its containing folder. Don't edit it directly —
the saved state's overlay only matches a known disk image.

**Q: How do I move files from Windows 95 back to my real computer?**

A: This version only supports host → guest file transfer (the SMB share
is read-only from the guest). For text snippets, the bidirectional
clipboard works in both directions. For larger payloads, the only
built-in option is to host a real FTP / HTTP server on your computer
and use the TCP relay to ship files out.

**Q: Why is the emulator so much slower than real Win95 on a Pentium?**

A: v86 is a JavaScript+WebAssembly emulator running on a JIT compiler.
On modern hardware it's faster than a real 1995 Pentium, but heavy
graphics or 3D programs will still feel sluggish.

**Q: Can I install games like Doom, SimCity, Quake?**

A: 2D / vintage 3D programs that target Sound Blaster 16 + VGA generally
work. Anything needing a Voodoo / Glide / DirectX 7+ accelerator does
not. CD-ROM-based installers work via the CD-ROM mount.

**Q: Does it support multiple Windows 95 instances?**

A: Each Electron app runs one VM. You can launch multiple copies of the
app on macOS / Linux (e.g., from different user accounts or by duplicating
the bundle), but they share the same userData directory by default and
will fight over the saved state. Not supported.

**Q: Does it phone home / send telemetry?**

A: The app polls GitHub once an hour for new releases via
`update-electron-app`. There is no other built-in telemetry. The
Cloudflare DoH endpoint receives DNS queries the *guest* makes for real
hostnames; this is the guest browsing the web, not the app reporting on
you.

**Q: Where do log messages go?**

A: They print to the renderer DevTools console. Open it via **View ▸
Toggle Developer Tools** (Cmd+Opt+I on macOS, Ctrl+Shift+I elsewhere).

**Q: What's the difference between the welcome screen's "Settings" button
and the menu bar?**

A: The welcome screen's Settings card is the in-app, Win95-themed panel
for shared folder, mounted media, machine state, and info-bar metrics.
The OS-level menu bar (View, Window, Machine, Help) controls runtime
operations like full-screen, zoom, restart, and CD/floppy hot-swap. They
overlap intentionally — Settings is for pre-boot prep, the menu is for
during-run tweaks.

**Q: Can I move my Windows 95 install to another computer?**

A: Yes:
1. Copy the entire `windows95` userData folder (state file, settings) to
   the same path on the destination.
2. Install the same app version on the destination.
3. Launch — your saved Windows 95 should resume exactly.

The bundled disk image has to match version-to-version; mixing a state
from version 5 with an app from version 6 won't work (recovery handles
that case explicitly).

**Q: Does the recovery feature run on every launch?**

A: No. It only checks once per launch, and only if there's no current-
version state file. If recovery fails or you discard the snapshot, the
welcome card stops showing the recovery prompt.

**Q: Will it work with WinLinux 2000 / non-Win95 disk images?**

A: Issue [#336](https://github.com/felixrieseberg/windows95/issues/336)
asks this. Officially: no. The app hard-codes the bundled
`windows95.img`; you can't pick a different hard-disk image from the UI.
Power users running the app from source can swap the file, but it's not
supported and recovery will fail.

**Q: Why are my keystrokes not always reaching Windows?**

A: When the cursor is not captured, only some keys reach the guest.
Click into the emulator first (cursor lock), then type. The Machine menu
also exposes the most commonly stolen chords (Ctrl+Alt+Del, Alt+F4,
Alt+Enter).

**Q: I want to play videos inside Windows 95 — what works?**

A: Issue [#328](https://github.com/felixrieseberg/windows95/issues/328)
discusses this. Native Win95 codecs (MPEG-1 with the right player,
animated GIFs in Internet Explorer) work. Modern formats (MP4, H.264,
WebM) do not — the codecs simply don't exist for Win95 and the emulated
CPU isn't fast enough anyway.

**Q: Can I export my virtual hard disk to a regular `.img` file?**

A: Issue [#321](https://github.com/felixrieseberg/windows95/issues/321)
asks for this. The app does export a recoverable C: tree when state
versions change (described in Section 4.10), but there's no menu item
that exports the live disk to a stand-alone bootable `.img`. Power users
can find the live `windows95.img` via **Machine ▸ Go to Disk Image** and
copy it manually.

---

_Generated April 2026 from felixrieseberg/windows95 at d0090e5. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._