Handbook

Amiga Imager v0.91

Current handbook for Amiga Imager v0.91. This guide was checked against the shipped 0.91 / 260712 build and is the current public handbook for this release.

Download v0.91 Back to downloads
  • Verified against build 260712
  • English reference guide
  • Current for the v0.91 release
Back to downloads

What this handbook covers

This is the public day-to-day guide for Amiga Imager v0.91. It is meant to match the current app build. It covers the two main workflows, the current build screen, the package controls added in recent releases, and the settings panes that matter when building for real hardware.

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 and custom package archives can be added during the build.
  • v0.91 completes the fully native PiStorm path: RDB, FAT32, FFS, and PFS3 are now handled by the native disk engine.

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.91 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
  • direct download URLs for any custom packages you want the app to install during the build

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, custom packages by URL, WBDock item selection, 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.91 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 the current catalog 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

v0.91 adds two important package controls:

  • Custom Packages can be added in Settings -> Build with a package name and direct download URL. They appear under a dedicated Custom group during the build.
  • When WBDock is selected, the package area now shows a WBDock items selector so you can decide which installed apps should appear in the dock.

Current catalog highlights still include:

  • 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.
  • Export Log now writes the complete session log, including mid-build exports and sessions that only involved flashing.

Platform notes for v0.91

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.
  • v0.91 is the first release where the PiStorm image path is fully native end to end, including FAT32 boot partition setup, RDB partition resolution, FFS, and native PFS3 handling.
  • If you need to compare behavior, the legacy disk path is still available as a deprecated opt-in fallback in Settings -> Debug.

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 Ekstrom. Select it in the Network Card picker for clockport-equipped models.
  • v0.91 also improves shared package handling with faster direct downloads, safer filename extraction from archives, and more reliable script and binary protection-bit handling on first boot.

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.91)

v0.91 takes AmigaDiskKit beyond the RDB and FFS work introduced in v0.90. On the PiStorm path, the engine now handles RDB, FAT32, FFS, and PFS3 internally, including partition layout, FAT32 boot-volume creation, PFS3 formatting, file I/O, and handler registration.

That means PiStorm builds no longer require the old external imaging tool anywhere on the normal path. The legacy engine remains available only as a deprecated fallback under Settings -> Debug.

v0.91 also fixes the header layout used for long-filename DOS\7 volumes. If you built a DOS7-based image with v0.9 or v0.90, rebuild it with v0.91. That applies even if the older image looked fine at first.

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, and Custom Packages
  • 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 native engine now covers the main PiStorm disk path, but some supporting operations still rely on bundled helper tools or the optional legacy fallback.

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.

A custom package does not install

Check the package name and direct download URL in Settings -> Build -> Custom Packages. The file should be a valid archive the build pipeline can unpack, ideally an .lha package.

An older image behaves strangely on the Work partition

If the image was built with v0.9 or v0.90 and uses a DOS\7 partition, rebuild it with v0.91. The long-filename header layout was corrected in this release.

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. In v0.91 the exported log contains the full session output, which makes it much more useful for tracking down build or flash problems.