Handbook

Amiga Imager v0.90

Current handbook for Amiga Imager v0.90. This guide was checked against the shipped 0.90 / 260711 build and is the current public handbook until a newer revision is published.

Download v0.90 Back to downloads
  • Verified against build 260711
  • English reference guide
  • Current until the next handbook revision
Back to downloads

What this handbook covers

This is the public day-to-day guide for Amiga Imager v0.90. It is meant to match the current app build. It covers the two main workflows, the current build screen, platform-specific notes, and the settings panes introduced in the newer releases.

What the app does

Amiga Imager is a native macOS app that builds ready-to-use Amiga systems from one workflow.

  • PiStorm / Emu68 and Classic Amiga builds are written as .img files.
  • MiSTer / Minimig builds are written as .hdf files.
  • Finished images can be written directly to SD, CF, or USB media from the app.
  • The app supports both Simple and Advanced build flows.
  • Optional community software can be added during the build.
  • v0.90 introduces a native disk engine (AmigaDiskKit) that handles RDB and FFS operations internally, improving reliability on real Amiga hardware and eliminating a class of disk image corruption issues.

Before you start

For a normal build you should have these items ready:

  • a Mac running macOS 14 Sonoma or later
  • a valid Kickstart ROM
  • matching AmigaOS installation media
  • a destination SD, CF, or USB device if you plan to write the image immediately
  • internet access for optional package downloads

Media expectations depend on the AmigaOS version you select:

  • AmigaOS 3.1 / 3.1.4: ADF source folder
  • AmigaOS 3.2.x: ADF source folder or 3.2 CD ISO
  • AmigaOS 3.9: CD ISO plus Boing Bag 1 and Boing Bag 2

Optional but often useful for current v0.90 builds:

  • a paid Picasso96 archive from Individual Computers for the broadest Classic RTG compatibility
  • a valid Roadshow.lha if you want Roadshow Full instead of the demo path
  • registration files for IBrowse or IMP3 if you want licensed features

The two workflows

Build bootable image

This is the main mode and the one most users will spend their time in. It lets you select a target platform, point the app at your install media and ROM, choose optional software, review a Build Summary, and generate a ready-to-use disk image.

Flash existing image

This mode writes an already built image to removable media. The UI is simple: choose the image file, choose the target disk, optionally keep Only show external disks enabled, then click Write to Disk.

Writing to physical media may ask for your administrator password. On macOS you may also need to grant Full Disk Access to Amiga Imager if raw disk access is blocked.

How the current build workflow works

1. Choose the basic inputs

  • Select Target platform: PiStorm / Emu68, Classic Amiga, or MiSTer (Minimig).
  • Choose AmigaOS version. If possible, keep it on Auto and use Check Media to verify what the app found.
  • Provide an ADF source, an ISO, or both, depending on the OS version.
  • Select your Amiga ROM.
  • Choose the output image path.

2. Decide whether to stay in Simple or switch to Advanced

Simple is the fastest route. It applies safe defaults for a first build, including bundled assets, EN plus your system locale, Roadshow Demo, and the shareware Picasso96 path when RTG is needed.

Advanced is where the full app lives. Use it when you want custom hardware choices, manual Roadshow or Picasso96 archives, transfer folders, package-specific registration files, custom image sizing, or profile save/load.

3. Work through the build cards

Input

This card is where you set the platform, OS version, media, ROM, and output image. On Classic builds it also exposes the current hardware selectors for Machine, Accelerator, RTG Graphics Card, and Network Card.

Configuration

In Advanced mode this is where current v0.90 setup choices live:

  • Display: preset or custom screen mode, Workbench depth, backdrop, icon set
  • P96 iComp archive: optional commercial Picasso96 archive for Classic RTG
  • FrameThrower: PiStorm-only video settings such as mode, autostart, scaling, size, brightness, and contrast
  • Network: None, Roadshow (Demo), or Roadshow (Full), plus Wi-Fi where supported
  • Transfer Folder: copy a host folder into the chosen Amiga partition during the build

Optional Software

Simple mode offers a one-switch community package path. Advanced mode exposes grouped package selection with over 30 available packages across categories including Internet, Multimedia, Utilities, and System tools.

Some packages open extra fields only when needed, for example:

  • WHDLoad Kickstarts
  • IBrowse Key
  • IMP3 Reg

Packages new in v0.90:

  • Solas — clockport RGB LED strip controller for clockport-equipped Amigas
  • LumiWeather — weather widget (Roadshow required)
  • LumiPass — password manager
  • LumiReg — registration and license key manager

Image & Build

Use this card to choose the image size and start the build. Simple mode stays on the preset path. Advanced mode exposes the full image size controls, partition layout, profile save/load, and the final build actions.

  • Build Image is used for PiStorm and Classic targets.
  • Build HDF is used for MiSTer.
  • Before the script runs, the app opens a Build Summary so you can review the current settings and warnings.
  • After a successful build you can click Use Built Image and switch straight into the write flow.
  • When the build finishes, macOS sends a notification. You can keep working in another app and come back when the build is done.

Platform notes for v0.90

PiStorm / Emu68

  • Builds use an .img output file.
  • Wi-Fi settings and FrameThrower are PiStorm-specific.
  • The PiStorm settings pane controls boot-bundle source and prerelease firmware opt-in.

Classic Amiga

  • Current RTG card choices include VA2000, P-Vision, Vampire SAGA, and ZZ9000.
  • Current network choices include A314, ZZ9000Net, PicoWiFy, and other Classic NICs.
  • A314 requires Roadshow. The app will flag that mismatch in the build summary if you choose A314 without a Roadshow stack.
  • PicoWiFy is a clockport-based Wi-Fi adapter by Niklas Ekström. Select it in the Network Card picker for clockport-equipped models.
  • v0.90 improves Classic reliability around boot module protection bits (ROMUPDATE), DOS7 partition handling, and package matching.

MiSTer / Minimig

  • Builds use an .hdf output file.
  • Optional RTG uses UAEGFX.
  • If you enable networking, MiSTer must be set to UART Mode = PPP and Baud = 115200.

Native disk engine (v0.90)

v0.90 introduces AmigaDiskKit, a native Swift implementation of all RDB and FFS disk operations. It is the default engine for new installs and handles partition layout, FFS formatting, and file copy/extract internally without requiring an external tool for those steps.

The native engine fixes a class of reliability problems caused by incorrect FFS root-block layout that previously caused "Not a DOS disk" errors on real Amiga hardware after imaging. These failures were silent — the image appeared valid but would not mount on hardware.

If you need to switch back to the legacy path for any reason, a Disk Engine toggle is available in Settings → Debug.

Settings window (Cmd+,)

The current app has a dedicated Settings window with five panes:

  • Build: build behavior, Aminet exposure, UserFiles auto-discovery, asset folder override
  • Storage: SD-card size reduction presets so generated images still fit real media
  • PiStorm: floppy buffers, boot-bundle source, prerelease toggle, optional firmware URL override
  • Classic: A314 auto-mount behavior and optional DEVS:a314.config output
  • Debug: diagnostic output, Disk Engine toggle (native AmigaDiskKit vs. legacy hst-imager), and other developer-oriented behavior

If you keep the default setup, you can ignore most of these. They are mainly useful when matching specific hardware or refining repeated build workflows.

Troubleshooting

Helper tools do not install

Use Install / Retry. The app bundles helper tools for operations such as FAT32 partition creation (PiStorm) and legacy disk operations. The native engine (default) handles RDB and FFS steps internally, but some operations still rely on bundled tools.

The build cannot start

The most common causes are missing install media, missing Kickstart ROM, or no output image path. For AmigaOS 3.9, also check that both Boing Bag updates are present.

Writing to disk fails on macOS

Enable Full Disk Access for Amiga Imager in System Settings → Privacy & Security → Full Disk Access, then retry. Replugging the target device can also help.

A314 does not work

Make sure the network stack is set to Roadshow Demo or Roadshow Full. A314 is not supported with None.

The image boots on a Mac/emulator but not on real hardware

This was the most common symptom of the FFS root-block bug fixed in v0.90. If you are seeing it with an older image, rebuild the image with v0.90. The native disk engine writes a correct root-block layout by default. If you have Disk Engine set to Legacy in Settings → Debug, switch it back to Native and rebuild.

The image is too large for the card

Reduce the preset, adjust the custom size, or use the storage size-reduction settings to leave more headroom for real SD media.

You need help diagnosing a problem

Use Export Log after the failure and keep the build summary details. That is the fastest way to capture the exact configuration used by the current build.