Handbook
Current handbook for Amiga Imager v0.97 — fully native in Swift. Every build runs in-process with no external tools. It covers the build workflows plus the newer tools — the Amiga File Manager, Greaseweazle floppy support, building straight to a card, the Guided Build wizard, and the offline build cache — and is the current public handbook until a newer revision is published.
This is the public day-to-day guide for Amiga Imager v0.97. 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.
Amiga Imager is a native macOS app that builds ready-to-use Amiga systems from one workflow.
.img files..hdf files. The UAE and Amiberry profiles also write a companion .uae config next to the image.For a normal build you should have these items ready:
Media expectations depend on the AmigaOS version you select:
Optional but often useful for current builds:
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.
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.
Because writing erases the target, the app first shows a confirmation naming the card (turn it off in Settings → Storage → Card Writing if you prefer). Card access is authorized through the signed Amiga Imager Disk Helper — silent once it is approved and has Full Disk Access, otherwise via the standard macOS prompt. See Prompt-free card access in Troubleshooting for the one-time setup.
New to Amiga Imager? Click Guided Build in the toolbar for a full-screen wizard that walks you through one decision at a time, with a plain-language tip on every screen. It drives the same build engine as the normal form, so the result is identical — it just makes the choices easier to find. The Simple and Advanced modes remain available for everyone else.
The wizard adapts to your platform and covers, in order:
Transfer drawer on the image.Networking is chosen for you from the Licensed files step: supply your Roadshow archive for the full stack, otherwise the bundled demo is used. A disabled Next always explains what's still missing, and the tab strip lets you jump back to any earlier step.
PiStorm / Emu68, Classic Amiga, or Emulators. The Emulators target offers a profile picker for MiSTer (Minimig), UAE, and Amiberry.ADF/ folder) instead of loose ADF files. You can also supply both — the CD ISO for the
3.2 base plus a separate ADF folder of 3.2.x update disks, which the build overlays on top (the folder's
ADFs take precedence). AmigaOS 3.9 uses the CD ISO plus the Boing Bag updates as before.classic_a1200_3.2.3_68060_rtg_64gb_150626.img
(platform/machine, AmigaOS version, CPU, an rtg marker when
RTG is selected, image size, and the date). It updates automatically as
you change those settings, defaulting to your Downloads
folder. Pick your own path with Save As at any time; once
you do, the app keeps your choice instead of auto-naming.If this is your first build, consider Guided Build (see above) instead — it walks you through everything below. Otherwise:
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.
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.
In Advanced mode this is where the current setup choices live:
None, Roadshow (Demo), or Roadshow (Full), plus Wi-Fi where supportedLocale and keyboard. The keyboard layout follows the locale you select: the first selected locale sets the matching Amiga keymap at boot, so a German build comes up with a German keyboard rather than US.
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:
Packages new in v0.90:
Everything a build downloads is cached in ~/Library/Application Support/AmigaImager and reused on every later build — so repeat builds need no downloads. This covers both the community packages you select and the engine's own dependencies (the Emu68 boot bundle, Emu68-tools, network/RTG drivers, fat95, the CompactFlash driver, and so on). If a download can't reach the internet, the app automatically falls back to the cached copy, so builds keep working offline.
Caching is managed in Settings → Packages → Build Download Cache:
To prepare for a fully offline build, run one normal build online first to warm the cache, then turn on Offline mode.
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.
.img output file.VA2000, P-Vision, Vampire SAGA, and ZZ9000.A314, ZZ9000Net, PicoWiFy, and other Classic NICs..hdf output file with no PiStorm/Emu68 boot content. Pick the profile in the Emulators settings pane..254 via PPP. If it does not connect, check RAM:Roadshow-PPP.log for the negotiation trace..uae config is written next to the image. It ships with an empty Kickstart path by design — set kickstart_rom_file to a Kickstart 3.2 (47.x) ROM before launching. (AmigaOS 3.2 needs a 47.x ROM; a 3.1/40.x ROM will not boot reliably.)v0.90 introduced AmigaDiskKit, a native Swift implementation of all RDB and FFS disk operations. It is the default engine 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.
As of v0.96 the build is now fully native in Swift. The whole pipeline runs in-process for
all three platforms — OS install from your ADFs or ISO, package installation, RTG and network setup, and
the final boot-tuning steps — with no external tools involved. The legacy build scripts and the old
hst-imager helper have been removed entirely; there is no fallback path and no Disk Engine
toggle anymore. This is faster, simpler, and more consistent, and native builds have been validated on
real hardware across every platform and emulator profile.
The Amiga File Manager is a built-in window for browsing and editing the contents of Amiga disks without booting an Amiga. It reads and writes real Amiga filesystems directly, so you can drop a few files onto an image, pull a save-game off an SD card, or peek inside an archive — all from macOS.
Open it from the toolbar button in the main window or with Shift-Cmd-M. It opens as its own window, so you can keep it next to the build screen.
.hdf, .img) — Amiga RDB
partitions formatted as FFS or PFS3, and the
FAT32 boot partition of a PiStorm image..adf) — OFS and FFS..lha, .lzh) — browsed read-only, like a drawer.A toolbar toggle switches between two layouts; your choice is remembered:
In either view you pick a source and then a partition inside it, then navigate folders. A breadcrumb shows where you are; double-click a drawer to go in.
Drag and drop works between the two panes, between the sidebar and a pane, and to and from the Finder. There is no rename yet.
Double-click an .lha or .lzh file to descend into it as if it
were a drawer. You can browse the contents and drag files out. Archives are read-only — you
can extract from them but not add to them. Use the breadcrumb (or navigate up) to come back
out.
Physical media is treated carefully. A card is always opened read-only first, so browsing can never accidentally change it. To make changes you explicitly choose to open it for writing. Always double-check you picked the right card before enabling writing.
Raw disk access goes through a small signed Amiga Imager Disk Helper so the
authorization is branded as Amiga Imager rather than a generic system prompt. The first time
it is needed, macOS asks you to approve it once under
System Settings → General → Login Items & Extensions, and you grant the
helper Full Disk Access (see Prompt-free card access below). After
that, opening and writing cards is silent. Until the helper is approved, the app falls back to
the standard macOS authopen prompt, so card access always works either way.
While a build is running or an image is being written to a card, the File Manager will not open that image or disk, to avoid touching something mid-write.
Amiga Imager can preview Amiga files right in Finder with Quick Look, and inside the File Manager — no need to open or mount anything first.
.iff/.ilbm pictures
and Workbench .info icons render as images..hdf, .img,
.adf and .lha show an info card: the partitions (with volume
name, size and free space), a count of files, and an expandable tree
of the contents you can click through.In Finder, select a file and press Space. Inside the File Manager, select a file in a volume and press Space to preview it without extracting.
Opening and extracting. Quick Look previews are view-only, so to act on a file use Finder's right-click → Open With → Amiga Imager:
.hdf / .img — opens the image in the File
Manager to browse it..lha / .adf — extracts the contents to a
folder next to the file (a handy replacement for The Unarchiver for these formats).
Tip: choose Get Info → Open with → Change All to make double-click extract.The first time, enable the previews under System Settings → General → Login Items & Extensions → Quick Look (Amiga Imager). The button in Settings → General → Quick Look Previews takes you straight there.
If you have a supported USB floppy controller with a 3.5" drive, the File Manager can read and write real Amiga floppies — no separate tools required. Use the Floppy menu in the File Manager toolbar.
cu.usbmodem…
port); the last one is remembered..adf
file (Double Density 880K or High Density 1.76M)..adf back to a disk
(verified by default)..scp file, or write one back, for copy-protected or non-AmigaDOS disks.
(IPF is not supported.)Drive options live in Settings → Floppy: bus type, drive unit, read revolutions and retries, verify-after-write, motor spin-up and head-settle timing, and default density.
If a read fails with noTrk0, the drive isn't being selected — try the other
bus type or drive unit 1 (PC drives on a twisted
cable usually answer as unit 1).
You can build an image and write it to an SD/CF card in one step, without producing a separate file first. On the build screen, in Image & Build, set Build destination to SD/CF card and pick the target card. The build button changes to Build & Write to Card.
When the build finishes it writes straight to the card. Because writing erases the
card, the app shows a confirmation naming the exact target (card name, size and
/dev node) before it writes anything — click Erase and Write to
proceed or Cancel to leave the card untouched. (You can turn this
confirmation off in Settings → Storage → Card Writing.) It then writes —
skipping empty space, so only the actual content is written, not the whole card — and verifies
the result. A progress bar under the toolbar shows the write and verify passes.
Once the disk helper is approved and has Full Disk Access, the write is silent (no separate authorization prompt). See Prompt-free card access in Troubleshooting.
This destination is available for PiStorm and Classic builds. Emulator (HDF) builds always produce a file, since those images are meant for use in an emulator.
The current app has a dedicated Settings window with these panes:
DEVS:a314.config outputIf you keep the default setup, you can ignore most of these. They are mainly useful when matching specific hardware or refining repeated build workflows.
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 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.
Enable Full Disk Access for Amiga Imager in System Settings → Privacy & Security → Full Disk Access, then retry. Replugging the target device can also help.
By default, opening or writing an SD/CF card asks macOS for authorization through the generic
authopen prompt each time. To make card access branded and silent, Amiga Imager
includes a small signed background helper. Set it up once:
Contents/MacOS/AmigaImagerDiskHelper), then switch it on. This is required because macOS protects removable volumes (SD/CF/USB) — even an authorized helper cannot read or write them without Full Disk Access.
After that, opening and writing cards is silent. If a card open is ever denied for lack of Full
Disk Access, the app shows a banner with an Open Settings button and keeps
working through the standard authopen prompt in the meantime, so nothing breaks.
Writing erases the whole card. The app shows a confirmation naming the exact target before any
write — read the card name, size and /dev node and cancel if it is not the one you
expect. You can turn this confirmation off (or back on) in
Settings → Storage → Card Writing.
Make sure the network stack is set to Roadshow Demo or Roadshow Full. A314 is not supported with None.
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.
Reduce the preset, adjust the custom size, or use the storage size-reduction settings to leave more headroom for real SD media.
When an Amiga image with Roadshow runs on MiSTer, it reaches the network over PPP across the
FPGA serial line to pppd on the MiSTer's Linux side. If the Roadshow PPP log shows the
Local IP address stuck at 0.0.0.0 together with repeated
IPCP configuration request reject messages, the Linux side is not handing the Amiga an address.
Edit linux/ppp_options on the MiSTer SD card (it mounts as a FAT volume on macOS) and make sure of three things:
192.168.1.1:192.168.1.254 (local:remote). The stock comment claims newer MiSTer releases assign this automatically, but on many images it does not work — set it explicitly. proxyarp (already enabled) then puts the Amiga on your LAN.-vj to disable Van Jacobson header compression, which stops the IPCP Configure-Reject loop.ms-dns <your-router> so the Amiga can resolve names, not just route packets.
Keep crtscts active (it matches Roadshow's Hardware-Handshaking = ON), confirm the MiSTer OSD
has UART = PPP at 115200, then re-up the Amiga's PPP interface. The log should now show the
assigned Local IP address and IPCP reaching opened. Always eject the card from macOS
(diskutil unmount) before moving it back to the MiSTer.
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.