# Test Interplanetary with an emulator

Use ROMs and disc images you are authorized to access. Interplanetary contains
no games. An emulator and its required BIOS files are installed separately.

## Windows 11 / Windows 10 1809 or later, x64

Extract the entire ZIP to a local NTFS disk, then double-click **Start
Interplanetary.cmd**. Keep its window open. Paste an IPFS collection link,
an Internet Archive item link, or an HTTP JSON manifest URL. Type `open`
to open the drive in Explorer. The default drive folder is
`%LOCALAPPDATA%\Interplanetary\Drive`.

For a Start menu shortcut, right-click `install.ps1` and run with PowerShell,
or use `powershell -ExecutionPolicy Bypass -File install.ps1` from the extracted
folder. Installation is per-user and does not require administrator rights.
No scheduled tasks or services are installed. Windows binaries are unsigned
unless the distributor signs them; verify the archive checksum from its publisher.

## Linux, x64 or ARM64

Install FUSE 3 with your distribution's package manager (for example,
`sudo apt install fuse3` on Ubuntu/Debian). `/dev/fuse` must be available.
Extract the archive, open a terminal in its folder, and run
`./interplanetary-desktop`. Paste your collection link. The drive appears at
`~/Interplanetary`. `./install.sh` optionally installs a per-user desktop shortcut.
Flatpak/Snap emulators need permission to read that folder.

## macOS 14 or later, Apple Silicon or Intel

Copy Interplanetary.app from the disk image into Applications and open it.
Add a collection in Sources. Enable its File Provider extension if macOS asks.
Use **Interplanetary** in Finder's Locations sidebar as the emulator's ROM folder.
The Sources window shows preparation and acquisition progress.

Choose the collection with the emulator's **Choose folder** or library-import
dialog. That grants access to the selected folder. Selecting just one ROM in
an Open dialog grants access to that file; an emulator that also examines its
parent folder may still wait for access. Merely pasting a path into a
configuration file does not establish consent. See Apple's
[File Provider access rules](https://developer.apple.com/documentation/bundleresources/information-property-list/nsfileproviderdomainusagedescription).

For mGBA, first use **File → Add folder to library** and choose the collection,
then load a ROM from it. If a previous file-only attempt is already waiting,
restart the emulator after selecting the folder. Keep saves and save states
in a writable local folder outside Interplanetary.

## Load and cache a collection

1. Add an `ipfs://<CID>` collection (matching files and subfolders can be served
   by peers with different parent roots), an Archive.org item URL, or a JSON
   manifest. Ordinary website directory pages are not supported.
2. Wait for the collection folders to appear. Metadata is prepared without
   downloading every ROM. Large catalogs appear progressively.
3. Set the emulator's ROM/content directory to the mounted collection. Open a
   game normally. Save states, memory cards, patches and scraped artwork should
   go outside the imported drive.
4. Leave Interplanetary running while using files that have not been cached.
   For offline use, select **Keep Local** in the Mac app or use the CLI:
   `interplanetary root`, `interplanetary ls <entry-id>`, then
   `interplanetary keep-folder <folder-entry-id>` or
   `interplanetary keep <file-entry-id>`. Wait for acquisition to finish.
5. To contribute a local ROM set, run
   `interplanetary copy-link /path/to/ROMs --share`, then
   `interplanetary sharing on`. On Windows use `.\interplanetary.exe` and a
   quoted Windows path. Files are imported with the same canonical IPFS profile
   used by the app; a different import profile can produce different CIDs.

The examples use `interplanetary` as shorthand. From an extracted Linux package,
use `./interplanetary`; on Windows use `.\interplanetary.exe`. On Mac the CLI is
`/Applications/Interplanetary.app/Contents/MacOS/interplanetary-cli`.

The Windows/Linux launcher accepts `sources`, `status`, `open`, and `quit`.
Advanced operations use the bundled `interplanetary` CLI and MCP bridge.
Quitting stops the processes the launcher owns. Cached Windows files remain
on disk; uncached reads require the provider. The Linux mount is removed.

## Storage and performance

Small files (up to 8 MiB) are acquired and verified whole. Large files use
version-bound ranges. IPFS ranges use a 32 MiB memory cache and up to 512 MiB
of disk blocks, independent of whole-file residency. The bundled IPFS node
also caches blocks and uses automatic garbage collection with a 10 GB target;
kept/shared content can exceed that target. `interplanetary storage` reports
managed cache use; `free-up-space` clears eligible engine copies/ranges.
Native Windows/macOS copies and IPFS storage are separate disk usage.

Windows uses progressive Cloud Files hydration: the first requested bytes
can be returned before the whole file, but Windows may fetch the rest in the
background while the file is open. Emulator scans or whole-file checksums can
also read an entire collection. macOS may hydrate a complete file for memory
mapping, even after earlier reads used ranges. Internet throughput depends on available peers,
the origin, NAT/relay routing and your connection; local correctness tests are
not Internet performance measurements.

## Troubleshooting

Windows/Linux write startup errors to `desktop.log` in the app data directory.
Windows uses `%LOCALAPPDATA%\Interplanetary`; Linux uses
`${XDG_DATA_HOME:-~/.local/share}/interplanetary`. The native Mac app uses
`~/Library/Application Support/Interplanetary`. Do not share `engine.json` or
the IPFS config file: they contain local authentication/identity material.

Use `interplanetary peers` and `connect-peer <multiaddr>` for direct peer
connections. Do not replace missing nodes with a public gateway URL and expect
it to become a peer. A file that changes while open is rejected as stale;
close it and reopen after the drive refreshes.