Handbook
The complete guide to Amiga Imager 1.0 beta — building ready-to-boot Amiga systems on your Mac. From your first Guided Build to PiStorm boards, USB, real floppy drives, your WHDLoad game collection in iGame on first boot, and the Amiga File Manager.
Appendix A: install media requirements by AmigaOS version
Appendix B: command-line (headless) builds
See also: UserFiles — automatic file discovery, your WHDLoad game collection, and ScummVM and the free adventure games (all in chapter 3).
Amiga Imager is a native macOS app that builds complete, ready-to-boot Amiga systems in one workflow: pick your hardware, point the app at your AmigaOS media and Kickstart ROM, choose optional software, and get a finished disk image — or write it straight to an SD/CF card. Everything runs in-process in native Swift; there are no external tools, scripts, or dependencies involved.
.img files (or write directly to a card)..hdf files; the UAE and Amiberry profiles also write companion .uae (WinUAE/Amiberry) and .fs-uae (FS-UAE) configs next to the image.
Optional, if you own them:
Amiga Imager does not bundle AmigaOS or Kickstart ROMs — you supply your own licensed copies (for example from an AmigaOS 3.2 purchase or Amiga Forever).
Amiga Imager checks for newer releases once a day (and on demand via Amiga Imager → Check for Updates…). The check reads a cryptographically signed version manifest — verified against a key built into the app, so the web server is never trusted — and shows a quiet banner with a Details button when a newer release exists. Nothing downloads or installs itself: updating is always your click on the download page. The automatic check can be switched off in Settings → Build → Check for app updates at launch.
New to Amiga Imager? Click Guided Build in the toolbar. It is 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 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 is still missing, and the tab strip lets you jump back to any earlier step.
Build bootable image is the main mode: select a platform, point the app at your media and ROM, choose software, review the Build Summary, and generate a ready-to-use image. Build blank image creates the same partitioned, formatted disk structure without installing an OS — and can pre-fill each partition from a folder on your Mac (see the power-user guide). Flash existing image writes an already-built image to removable media — choose the image, choose the disk, click Write to Disk (see chapter 7).
Simple is the fastest route. It applies safe defaults for a first
build: 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 — custom hardware, manual Roadshow
or Picasso96 archives, transfer folders, registration files, custom image sizing and
partition layout, and profile save/load.
PiStorm / Emu68, Classic Amiga, or Emulators (with a profile picker for MiSTer, UAE, and Amiberry).ADF/ folder) and additionally at a folder of 3.2.x update disks — the build combines them, with the folder's ADFs taking precedence. The media check reads the combined view, so it reports exactly what the build will use.classic_a1200_3.2.3_68060_rtg_64gb_150626.img — defaulting to Downloads. It updates as you change settings. In Save As, choosing only a folder keeps the automatic name; typing a name of your own fixes it, and Use automatic name under the field switches back.None, Roadshow (Demo), or Roadshow (Full), plus Wi-Fi where supported.
Simple mode offers a one-switch community package set. Advanced mode exposes grouped
selection with over 30 packages across Internet, Multimedia, Utilities, and System
categories — browsers, players, file managers, dock and desktop tools, and more. Some
packages reveal extra fields when selected (WHDLoad Kickstarts folder, IBrowse key,
IMP3 registration). You can also register your own LHA archives as
custom packages in Settings → Packages; they install to
SYS:Programs/<Name>.
IMP3 community tools (Settings → Packages, off by default, applies to every
platform) stages the prerequisite libraries and C: tools the Amiga Germany
IMP3 chat client needs — Triton (OpenTriton), ReqTools, RexxReqTools,
RexxTricks, TritonRexx, plus ActivateWindow, RawInsert,
Redit, Uptime, aget and utf8Decode —
all downloaded from Aminet at build time. The IMP3 client's own ARexx scripts are the
community's to distribute, so add those from the channel.
If you have a WHDLoad game library on your Mac — a folder of game archives
(.lha, as shipped by the usual retroplay-style collections),
already-extracted game drawers, or a mix of both — Amiga Imager can install it
during the build. In the WHDLoad Games section, set
Games collection to that folder; two further fields appear:
DH1:) so the
boot partition stays lean.WHDGames).
The build extracts every archive and copies every game drawer into
<partition>:<drawer>/, keeping your collection's own folder
structure. If your library is organized A–Z, keep it that way —
thousands of drawers in one flat directory make Amiga filesystem listings crawl, so the
A–Z layout is preserved deliberately.
Everything the games need comes along automatically:
One thing to add yourself: many WHDLoad games need Kickstart images
(kick 1.3 / 3.1) in DEVS:Kickstarts to run. Point the WHDLoad
Kickstarts folder field at your own licensed ROM image files — the Build Summary
warns you if a games collection is set without one. As with AmigaOS itself, Amiga Imager
does not bundle these.
WHDLoad games are skipped in blank-image mode (there is no OS to launch them from).
The ScummVM 2.5.1 RTG package (NovaCoder's 68060 port, which opens on a Picasso96 screen) comes with four classic point-and-click adventures that their creators have released as freeware, selectable individually in the Games group:
The game data is downloaded from scummvm.org during the build (and cached like all other
downloads), installed to SYS:Games/<Name>, and registered in ScummVM's
configuration with complete launcher entries — the games appear in the ScummVM launcher
immediately, correctly named, with no Add Game step. Two automatic upgrades:
ScummVM's 68060 build sets the hardware envelope: on PiStorm it is always available (Emu68 presents a 68060); on Classic Amiga it requires a 68060 accelerator (the packages are hidden otherwise); on UAE and Amiberry the companion configs request a 68060 automatically — enable RTG, since the interpreter opens on a Picasso96 screen; on MiSTer (a 68000 Minimig core) it is not available.
Everything a build downloads is cached in
~/Library/Application Support/AmigaImager and reused on every later build.
This covers both the community packages you select and the engine's own dependencies
(the Emu68 boot bundle, Emu68-tools, network/RTG/USB 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 a flaky connection never breaks a
build, and repeat builds are noticeably faster.
Caching is managed in Settings → Packages → Build Download Cache:
To prepare a fully offline machine, run one normal build online first to warm the cache.
If you build often, UserFiles saves you from picking your ADFs, ROM, and extras by hand every time. Turn it on in Settings → Build, point the app at one base folder, and it fills in the media automatically from a fixed folder layout.
The app seeds the structure for you (each folder holds a short "place files here" note):
AOS31, AOS3141, AOS32, AOS39 — the OS media and Kickstart ROM for that AmigaOS version (ADFs, or a CD ISO, plus a .rom).Install — optional extras, matched by filename: your Picasso96 (iComp) archive, Roadshow, and the IBrowse/GoVD keys.Kickstarts — extra Kickstart ROMs for WHDLoad.
Keeping several AmigaOS 3.2.x releases side by side. By default all
3.2.x point releases share the one AOS32 folder. If you own more than one
and want to keep them separate, create a per-version folder next to it — the app checks
the version folder first and falls back to AOS32:
AOS321AOS322AOS3221AOS323
If you only have one 3.2.x set, just use AOS32 — nothing else to do. The
build log shows exactly which folder and files were discovered.
PiStorm builds produce a complete SD card layout: a FAT32 boot partition with the Emu68
firmware, your Kickstart as kick.rom, and a generated
config.txt matched to your board — plus the Amiga RDB partitions with the
OS install. VideoCore RTG is always included; the machine boots straight into an RTG
Workbench.
Different PiStorm boards need different Emu68 boot configurations. Pick yours in the PiStorm section of the build screen:
Selecting the right board matters: each one receives a hardware-proven configuration, and a mismatched config can leave the machine stuck on the Emu68 splash screen — or not booting at all. In particular, a 40-pin A500/A2000 PiStorm must use PiStorm Classic, never PiStorm16. FrameThrower is its own option and works with any board (it requires Emu68 1.1 or newer, which the build picks automatically).
The build downloads the current Emu68 release automatically (and caches it). The PiStorm settings pane offers a prerelease opt-in for Emu68 test builds, plus a boot-bundle source override for advanced setups. PiStorm16, FrameThrower and USB builds need Emu68 1.1 and use it automatically — no opt-in needed. Auto-mount EMU68BOOT: (default on) makes the FAT boot partition appear as a drive on Workbench.
A newer Emu68 does not need a rebuild: Manage Amiga Software can update Emu68 in place on an existing PiStorm image or SD card — see Updating Emu68 on a PiStorm image or card in chapter 12.
FrameThrower digitizes the Amiga's native video output and shows it over the Pi's HDMI — one cable for both RTG and native screens. Enable it in the FrameThrower section and choose mode (integer or smooth scaling), size, offset, brightness, and contrast. Autostart brings the capture up at boot. FrameThrower requires Emu68 1.1, which the build uses automatically.
RGB2RTG gets native screens onto HDMI with no extra hardware: an unofficial Emu68 build that draws the Amiga's native display through the Pi itself, so games, the early startup menu and the boot menu appear on the same monitor as the RTG Workbench. It is your own download, chosen in Settings → PiStorm → RGB2RTG, and it is given to individual systems on a card with a boot menu — not to a single-system image. The card has to run Emu68 1.1, because RGB2RTG is built on it. Its author calls it experimental. Setting it up, and what a system on RGB2RTG gets, is described under RGB2RTG in chapter 8.
On a Raspberry Pi 4 or CM4, the build can include a full USB host stack: the Poseidon USB system plus the Emu68 xHCI controller driver. Enable it in the USB section of the build screen. USB storage devices (sticks, card readers) then work from Workbench.
PiStorm builds can include Roadshow networking with the Pi's own hardware: onboard Wi-Fi (enter your network name and password at build time; connect on the Amiga via the OnlineWifi tool) or wired Ethernet on the Pi 4/CM4. The WBDock gets a matching go-online entry.
You do not have to type the Wi-Fi password: From this Mac fills in the password this Mac already saved for that network (macOS asks for permission first), and the password field supports Password AutoFill from the Passwords app. A password used for a build is remembered for that network in the macOS Keychain and filled in the next time you enter the same network name. The same goes for the amiagent and Home Assistant tokens in Settings → Remote Access: they live in the Keychain, never in the app's preferences or in a saved profile.
A600/A1200-based PiStorm builds include the CFD133 compactflash.device
driver with an auto-mounting CF0 DOSDriver: insert a CF card in the PCMCIA
slot and it just appears. With no card present it is a silent no-op.
Classic builds produce a pure RDB image for CF/SD-to-IDE or SCSI solutions in real Amigas — no PiStorm content. The full hardware matrix is supported natively:
scsi.device modules, keymaps, and boot handling..device from DEVS:USBHardware, unit 0), click Online, then Save. From then on it's simply Trident → Online per session. (The build deliberately does not probe USB controllers during boot — a failed probe can freeze some machines, so this one manual step buys a reliable first boot on every setup.)MaxTransfer and Mask are settable under Settings → Classic for picky IDE/SCSI controllers; the defaults are safe for common setups.
AmigaOS 3.2 on a hard drive normally requires a V47 (3.2) Kickstart ROM.
Machines with an older 3.1 (V40) or 3.1.4 ROM can still boot it — the
hard-drive startup performs a soft-kick (LoadModule … ROMUPDATE)
that loads the V47 ROM modules from disk at boot. That soft-kick startup script ships
only on the 3.2.x Update disk (Update3.2.3.adf and
friends).
In practice:
PiStorm builds are not affected — Emu68 always provides a V47 ROM.
A600 and A1200 builds include the CFD133 compactflash.device driver with an
auto-mounting CF0 DOSDriver — a CF card in the PCMCIA slot just works.
The Vampire is handled as a Classic accelerator, not a separate platform.
Selection recipe (example: an Icedrake in an A1200): machine A1200, accelerator
Apollo 68080 / Vampire, RTG card Vampire SAGA, network card
Apollo V4Net (V4-family boards) or V2ExpEth (V2 cards) — the
network choice also tells the build which board generation you have. Support is hardware-validated on an Icedrake A1200. Everything
is sourced from the official Apollo SAGADriver.lha, so a matching set of drivers
and tools is installed automatically:
68040.library, 68060.library, or MMU libraries. On a 68080 those make SetPatch run the CPU/MMU setup for the wrong class and guru the machine on boot (#80000008), so they are stripped — you don't need to clean anything up by hand.v4net.device on V4 boards, v2expeth.device on V2 / A2000 boards. Board generation is inferred from your selections.SD0: (sagasd.device + fat95) — handy for moving files from the Mac. The second slot is available as SD1: via Storage/DOSDrivers. Toggle in Settings → Classic.freewaycpusb.device is installed. It is not Subway-compatible, so a generic Poseidon/Subway driver leaves it empty — Amiga Imager ships the correct one. Remember the one-time Trident setup described above (add the controller → Online → Save); on the Vampire especially, probing USB hardware during boot is exactly the kind of thing that can wedge a first boot, so the build leaves it to you.
The ROM caveat — read this before you build. Vampire boards usually ship with
the ApolloOS (AROS) ROM, and the V47 soft-kick trick described in the V47 rule
above does not work on it. So the build stages the Apollo tools —
C:ApolloMap, C:ApolloFlash, C:ApolloControl and your
Kickstart at SYS:Apollo/kick.rom — for you to map or flash a real 3.2 (V47) ROM yourself:
run ApolloMap SYS:Apollo/kick.rom to map it temporarily (lost on power-off), or
ApolloFlash SYS:Apollo/kick.rom to flash it permanently — for a dedicated AmigaOS
machine, flashing is the comfortable choice. Never interrupt ApolloFlash: a
broken flash needs a USB-Blaster recovery. There is deliberately no automatic boot
hook: ApolloMap reboots after mapping, which would loop forever if it ran from the
startup. Run it once by hand, then your 3.2 builds boot normally.
The Emulators target builds a pure-RDB .hdf with no PiStorm boot content.
Pick the profile — MiSTer (Minimig), UAE, or
Amiberry — next to the platform selector.
The MiSTer profile builds for one of two cores, chosen under Settings → Emulators → MiSTer Core: the official Minimig (the default) or BigMig.
RAM:Roadshow-PPP.log (and see Troubleshooting)./media/fat/Amiga/shared) and mouse wheel support.ZZ9000.card, bigmigAHI and the MHI library. In the OSD, System → Zorro Boards → ZZ9000 RTG must be ON.ZZ9000Net.device: switch ZZ9000 Network ON in the same OSD page. The Amiga takes an address by DHCP at boot.0.0.0.0 on the ZZ9000Net interface. Plug in a cable or a USB Ethernet adapter, or use the workaround below.
A WiFi connection can only carry the MiSTer's own address, so the Amiga cannot simply be
bridged onto it. The script bigmig-wifi.sh routes it instead — Amiga Imager writes
it next to the image on every BigMig build with networking: it puts a virtual eth0 in place of the real port, passes the
Amiga's traffic through the MiSTer onto the WiFi, and gives the Amiga one fixed address in your
LAN by DHCP. It writes nothing to the SD card, so a MiSTer restart undoes it — and loading a
core restarts the MiSTer, so run it again after every restart.
bigmig-wifi.sh from next to the image to /media/fat/Scripts/ on the MiSTer's SD card.root, password 1 unless you changed it) and runsh /media/fat/Scripts/bigmig-wifi.sh start.250 in your LAN. If that one is taken, or lies
inside your router's DHCP range, give another: … start 192.168.1.240.eth0 when the row switches on, and has to find the new one.ConfigureNetInterface ZZ9000Net CONFIGURE=DHCPShowNetStatus then shows the address.
… bigmig-wifi.sh status shows whether it is running and the last DHCP replies;
… bigmig-wifi.sh stop puts the real Ethernet port back. Don't run it with a cable
plugged in — then BigMig reaches the LAN directly, and the script refuses to start.
.uae for WinUAE/Amiberry and .fs-uae for FS-UAE. Both ship with an empty Kickstart path by design — set kickstart_rom_file (.uae) or kickstart_file (.fs-uae) 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 it reliably.MMULibs.adf, which SetPatch loads at boot — keep that disk in your ADF folder; the build warns if the libraries are missing. Only the library matching the chosen CPU is installed: the OS 3.2 CPU libraries refuse the wrong processor, so a 68060 image carrying 68040.library would alert whenever something opens it. Installing ScummVM raises the CPU to a 68060 automatically..fs-uae file. FS-UAE reads
none of the .uae keys — an HDF attached to a hand-rolled FS-UAE config
gets no RTG board, no bsdsocket networking, and only 8 MB of Zorro II Fast
RAM. The generated .fs-uae file configures all of this (including the
256 MB of Zorro III Fast RAM that memory-hungry AmiSSL 5.x needs). If
you build your own config instead, carry at least
zorro_iii_memory = 262144There are two ways to get an image onto a card:
Writing erases the card, so the app first shows a confirmation naming
the exact target — card name, size, and /dev node. Read it, then click
Erase and Write (the confirmation can be disabled in
Settings → Storage → Card Writing). The write skips empty space, so
only actual content is transferred, and verifies the result afterwards; a progress bar
under the toolbar shows both passes.
Card access goes through the signed Amiga Imager Disk Helper, so the authorization is branded rather than a generic system prompt — and silent once set up. One-time setup:
Contents/MacOS/AmigaImagerDiskHelper). macOS protects removable media, so this step is required for silent access.Until the helper is approved, the app falls back to the standard macOS authorization prompt — card access always works either way.
The other direction: File → Save Card as Image… (also a button in the Amiga File Manager's toolbar) reads an SD or CF card, or a hard disk in a USB adapter, into a file on the Mac. The card is only read, never written. Internal Mac disks are not offered.
Reading takes time, not space: a whole 256 GB card through a typical USB card reader takes about an hour, an HDF only as long as its partitions. Empty areas are skipped, so on the Mac the file takes only the space the card's data fills. Copied to a USB stick or an exFAT disk, it grows to its full size.
Both Save Card as Image and Add System from Card can read the disk of an Amiga that is running on your network, without taking its card or drive out. Switch the source from Card or disk to Amiga on the network, choose the machine and the disk.
amipkg upgrade amiagent brings it.scsi.device 0 · DH0, DH1). Floppies are not offered.One card can carry several complete systems — your own Workbench, Coffin, AGS, a games collection — and a boot menu asks at power-on which one to start. Amiga Imager builds such a card from images you already have: it copies their partitions onto the new card and adds the menu. The source images are only read, never changed.
.hdf, .img or .hda — or
From Card or Disk… for a card in the reader (see
Systems straight from a card below). A sheet lists the image's
partitions with their filesystem, size and content; tick the ones you want. Repeat
for every image.A normal build can carry other systems too: the card gets the AmigaOS this build installs, the systems you add, and the boot menu in front of them.
Without an added system there is no boot menu, and the build is the same as without the setting. The transfer folder and the WHDLoad games always go onto the build's own partitions, never into an added system. On first boot the new system restarts once to set the language; it then comes back through the menu, which starts it again by itself after ten seconds.
A system does not have to be an image file. Add System from Card… (next to Add System from Image…; in the partition editor From Card or Disk…) reads the Amiga partitions of an SD or CF card, or of a hard disk in a USB adapter: your old PiStorm card, a CF card out of an A1200, a drive that has been in an Amiga for thirty years.
Only the chosen partitions are read, and empty areas are skipped: the file is as big as the card on paper, but takes only the space those partitions fill. To keep a copy of the whole card, use Save Card as Image.
DOS\7 automatically, and the editor
says so.
Most images expect their own drive names: a system on DH0: whose games
live on DH1:. Partitions imported from one image therefore form a group.
On the card they wait under neutral names (MBA0, MBA1 …) and
are not mounted; when you pick that system, they get their own names back for as
long as it runs. The editor shows both names for each such row — for example
On the card MBA1, not mounted; DH1 while Coffin runs. Systems therefore
never see each other's partitions and cannot mix.
A system that comes as several image files — System One with its games in a second file, or AmiKit's AK0 and AK1 saved separately — is put together with Belongs to in the partition editor: choose the system for each extra partition, and it joins that system's group under its own drive name. A further partition from a system's own image already belongs to that system, and the picker shows it preselected; only a partition whose image has no system on the menu can be left at Every system (shared), and is then mounted in all of them.
Partitions that belong to no system — a data partition you added yourself — are
mounted in every system. Such a partition never takes a volume name one of the systems
uses: a second Work becomes Work2 on the card. On the
desktop, the card's own volumes sit in a second column — BootMenu (a hard
drive with the boing ball) at the top, then the shared partitions — and
EMU68BOOT keeps its usual place; each system keeps its own drive icons.
A PiStorm card starts with the Kickstart ROM you chose for the card. A system that needs another one — Coffin, for example, brings its own 3.9-based ROM — gets it under Kickstart for this system in the partition editor. The build puts every such ROM onto EMU68BOOT.
Emu68 loads the ROM only when the Raspberry Pi starts. When you choose a system whose
ROM differs from the one running, the menu switches the card over and asks you to
press Ctrl-Amiga-Amiga once: a keyboard reset restarts the Pi, and
the system comes up with its own ROM. Switching off and on works too. When that
system hands the card back to the menu, the card returns to its own ROM — so the
boot menu always comes up in the environment it was built for, and a system with
its own ROM asks for that keyboard reset every time you start it. Systems that run
on the card's own ROM switch without that step. For Coffin r65, take the ROM that
ships inside the image (DEVS:Kickstarts/coffin.rom) — an older Coffin
ROM does not fit r65.
A system made for an older Kickstart may not start on a newer one: Workbench 3.1 has
no icon.library on disk because Kickstart 3.1 carried it in ROM, so on a
3.2 ROM it stops at a requester. The import sheet and the editor warn about such a
system — give it its own ROM, or update it first.
A PiStorm card has one Emu68 for all its systems, and a system's drivers (Ethernet, VideoCore) are made for the Emu68 it was built with. When an imported system was built by Amiga Imager for Emu68 1.1, the card gets Emu68 1.1, and the build log says why. Otherwise the card stays on the stable 1.0 line.
Distributions made for Emu68 1.0 can stumble on a 1.1 card. Coffin r65 runs there with
the adjustments below; AmiKit (up to 12.8.3) does not. So each system can have
its own Emu68: when the card runs 1.1 and a system needs 1.0, the
build puts Emu68 1.0.7 into a folder of its own on EMU68BOOT
(Emu68-v1.0.7), and the boot menu switches between the two the way it
switches Kickstarts — one Ctrl-Amiga-Amiga. Amiga Imager recognises AmiKit and the
systems it built itself; for anything else, set Emu68 in the
partition editor (Automatic, 1.0 or 1.1). A card whose hardware needs 1.1
(PiStorm16, FrameThrower, USB) cannot run a 1.0 system; the build log says so.
RGB2RTG is an unofficial Emu68 build that draws the Amiga's native screen on
the Pi's HDMI output, so games, the early startup menu and the boot menu appear on the
same monitor as the RTG Workbench — no camera-port hardware needed. It is not bundled
with Amiga Imager: download it from its author and choose the .zip,
.lha or unpacked folder in Settings → PiStorm → RGB2RTG
(a .7z has to be unpacked in the Finder first). Version 0.78 is
recognised; its kernels for Pi 3 and Pi 4 both go on the card, and the Pi picks its own.
No system uses it unless you say so: choose RGB2RTG as a system's
Emu68 in the partition editor. Switching to it works like a Kickstart
switch — the menu asks for Ctrl-Amiga-Amiga once. RGB2RTG is built on Emu68 1.1, so
the card must run 1.1 too; on a 1.0 card the build log warns, and the system starts
with the card's Emu68. A system on RGB2RTG also gets
RGB2RTG's own programs: C:rgb2rtg, RGB2RTG-SoundMonitor
and RGB2RTG-Native in SYS:Utilities, the HDMI audio
driver for AHI (when the system has AHI), and a line in S:User-Startup
that applies your RGB2RTG settings at every start. For RGB2RTG's entries in the
Directory Opus menu, run C:rgb2rtg MENU once in a Shell. RGB2RTG's own
installer is not needed — and should not be run on a card with a boot menu, because
it rewrites config.txt, which belongs to the boot menu there.
Its author calls it experimental: it is built for the Amiga 1200 and optimised for CaffeineOS, and some demos and games come out in the wrong colours or do not run.
Some systems need small changes to run on the new card. When the import finds one, the
partition editor shows Adjust for this card with a switch for each
change. They are on by default; every file that is changed keeps its original beside
it (.orig, .old), and the build log lists each one.
bsdsocket.library goes in (for Coffin as
bsdsocket.library_full, which Coffin picks up itself).
Settings → PiStorm → Exchange Partition adds a FAT32 partition called
EXCHANGE at the end of the card (4 GB unless you choose another size).
Put the card in a Mac or PC and it shows up as an ordinary drive; on the Amiga it
appears as EXCHANGE: on the Workbench — for music, downloads or WHDLoad
archives. On a card with several systems, every system that has
fat95 mounts it. Its size comes off the Amiga partitions; the card size
stays. It works for single-system PiStorm images too.
BootMenu disk to choose the system for the next start — this is also
how you get the menu back after K. Choosing without K returns the
card to showing the menu at every start.
At power-on the menu opens on the Amiga's own video output. If your PiStorm is
connected only by HDMI, switch on PiStorm: show the boot
menu over HDMI in Settings → Build. The menu partition
then gets a small Picasso96 setup with VideoCore.card, and the menu opens on HDMI.
This needs your AmigaOS 3.2 ADF folder (for icon.library and
iffparse.library) and downloads Picasso96 and Emu68-tools — or uses your
iComp Picasso96 archive, if you chose one. Power-on takes a few seconds longer.
Without that option the countdown still runs on HDMI, unseen: after ten seconds the system chosen last starts and brings up its own RTG display. Either way, the Boot Menu icon opens the menu on the same display as the Workbench.
Next to Boot Menu, the BootMenu disk carries
Boot Menu Prefs. Double-click it in any running system to:
EMU68BOOT) and its own
Emu68 profile. Empty means the card's own.Changes take effect at the next start.
Page → Partitions lists every partition of the card with its size
and what it is for: the boot menu's own, a system's (a * marks the one
that system starts from), or - for one that belongs to nobody — a
shared data partition, or one that is still free.
DH0, DH1 …+ in front of the system name. Use it for a data partition that every system should see,
or to copy one system's data into another's from the running Workbench. In the
other system the partition keeps the name it has on the card, and only the system
it belongs to can start from it.Saving here also puts the card itself back in order, so a partition that has just become a system's cannot boot past the menu. Creating, resizing or filling partitions is not done here — that stays Amiga Imager's (or HDToolBox's) work.
Picking a system makes its partition the one that boots and restarts the Amiga.
Amiga Imager adds one line, AmiBootLoader RESET, to each system's
S:User-Startup (or before LoadWB when there is none); it
puts the card back so that the next power-on shows the menu again.
If a system hangs before it gets that far, the next start would run it again. To get out: switch the Amiga on while holding both mouse buttons, choose Boot Options, select BOOTMENU as the boot partition, and boot. The menu appears and you can choose another system. The menu itself shows this hint at the bottom of the screen.
Each menu run is written to BootMenu:S/AmiBootLoader.log, with the
Kickstart that was running — the first place to look when a choice does not do what
you expected.
Switch on Boot menu: rescue shell in Settings → Build
and the menu offers R: the Amiga restarts with every partition of the
card mounted under its card name (MBA0, MBB0 …) and opens a
Shell on the menu partition, with the usual commands from your AmigaOS 3.2 ADFs and a
short help text. That is the way into a system that no longer starts — for example
Copy MBB0:S/Startup-Sequence.orig MBB0:S/Startup-Sequence undoes an
adjustment. The next Ctrl-Amiga-Amiga shows the menu again. The rescue shell uses the
Amiga's own video output.
The Amiga File Manager is a built-in window for browsing and editing Amiga disks without booting an Amiga. It reads and writes real Amiga filesystems directly — drop files onto an image, pull a save-game off an SD card, or peek inside an archive, all from macOS. Open it with the Amiga File Manager button in the main window's top bar or with Shift-Cmd-M.
.hdf, .img) — 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 dual pane (two side-by-side panes, Directory Opus style — ideal for copying between two disks) and browser (a single Finder-like view with a sidebar of everything open). Your choice is remembered. In either view, pick a source, then a partition, then navigate; a breadcrumb shows where you are.
.lha/.lzh to descend into it like a drawer and drag files out (archives are read-only).There is no rename yet.
Physical media is treated carefully: a card always opens read-only first; writing is an explicit second step. While a build is running or a card is being written, the File Manager refuses to open that image or disk. Access uses the same silent Disk Helper as card writing (chapter 7). To keep a copy of a card as a file, or to turn it into an HDF for an emulator, use the toolbar's Save Card as Image (chapter 7).
With a supported USB floppy controller and a 3.5" drive, the File Manager reads and writes real Amiga floppies — no separate tools. Use the Floppy Drive menu in the File Manager toolbar.
.adf (DD 880K or HD 1.76M)..adf back to 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 and head-settle timing, default
density. If a read fails with noTrk0, try the other bus
type or drive unit 1 (PC drives on a twisted cable
usually answer as unit 1).
Amiga Imager previews Amiga files right in Finder (select a file, press Space) and inside the File Manager:
.iff/.ilbm pictures and Workbench .info icons render as images..hdf, .img, .adf, and .lha show an info card: partitions with volume name, size, and free space, plus an expandable tree of the contents.
To act on a file, use Finder's right-click → Open With → Amiga Imager:
.hdf/.img open in the File Manager;
.lha/.adf extract to a folder next to the file (a handy
replacement for The Unarchiver for these formats — use Get Info → Change All
to make double-click extract).
Enable the previews once under System Settings → General → Login Items & Extensions → Quick Look; the button in Settings → Build → Quick Look Previews takes you straight there.
Every image Amiga Imager builds ships with amipkg — a package manager
for AmigaOS 3.x, in the spirit of Homebrew or apt. It installs, updates and removes
software from AmigaPKG, a curated, cryptographically
signed catalog of 200+ freely distributable classics and tools — straight on
the running Amiga. It also works on any other 3.x system, from a stock A500
up: the standalone amipkg.lha is a free download at
github.com/thomas-luebker/amiga-pkg
(and on Aminet). Extract it into a drawer of your choice and run
Install (self-contained — everything stays in that
drawer, nothing else on the system is touched) or
Install-System (additionally adds the
AMIPKG: assign and Shell path to S:User-Startup as one
clearly marked, removable block).
amipkg lives in one home drawer —
SYS:Tools/AmigaImager on built images, published as the
AMIPKG: assign. CLI, both GUIs, the signed catalog, the
download cache and the receipt database all sit together there (like
MUI:), so amipkg’s self-update always lands on the binaries
actually in use:
AMIPKG:amipkg-mui — the MUI front-end (needs MUI 3.8+,
no extra custom classes): a toolbar with the catalog and package actions, a sidebar
with View (Installed/Available) and Categories panes for one-click
filtering, sortable list columns, a description pane, and a status bar with live
catalog counters. A failed operation pops the full error message in a requester.AMIPKG:amipkg-gui — the GadTools front-end: the same
features in a simpler dress, runs on any stock 3.x system with zero dependencies.amipkg — the CLI both GUIs drive; with the default
integrated setup it is on the Shell path, so it works from any Shell.
The essentials:
amipkg update (fetch the latest catalog), avail,
info <id>, install <id> (add
DRYRUN to preview the plan without changing anything),
check, upgrade, remove <id>,
adopt, doctor (audit installs against the receipts) and
dir (show or set the install drawer). Full documentation ships on the
image as an AmigaGuide (AMIPKG:amipkg.guide, also in the GUIs’
Documentation menu).On built images amipkg also appears in the WBDock (the MUI front-end when MUI is installed, GadTools otherwise), and GlowIcons builds get a proper colour amipkg icon.
Installing resolves dependencies automatically — an app needing MUI or
AmiSSL pulls it in first, with the right CPU build for the machine — and shows the
resolved plan (packages + download sizes) before anything happens. amipkg checks the
package’s hardware floors (CPU, Kickstart) and free disk space up front and
refuses clearly instead of installing something that cannot run; interrupted downloads
resume where they stopped. Each app lands in its own drawer inside the
install directory — and that directory can be any drawer on any drive,
not just the boot partition: default SYS:Programs, changeable with
amipkg dir (e.g. amipkg dir Work:Software). Archives without
a top-level drawer of their own are wrapped automatically, so loose files never pile up.
Everything is recorded in a receipt database: remove
deletes exactly what was installed, including its User-Startup lines, and
doctor audits the installed files against the receipts. Already have an
app installed somewhere? amipkg adopt <id> <drawer> takes over
managing it in place — updates then land in that drawer, not in
SYS:Programs. amipkg keeps itself current the same way:
amipkg upgrade amipkg updates the running installation in place.
Downloads need a TCP/IP stack (Roadshow, or an emulator’s bsdsocket); browsing the bundled catalog works offline. The catalog and almost all archives are reachable over plain HTTP, so no TLS stack is required; packages on https-only hosts additionally need AmiSSL 5.x (which amipkg can install for you).
Integrated, self-contained — or not at all. Both choices live in
Settings → Packages → Package Manager: Integrate into the
system at boot (default on) makes the boot scripts set the
AMIPKG: assign and put the drawer on the Shell path. Turned off, the
image gets a fully self-contained amipkg: nothing is wired at boot, the
programs find their data next to their binaries, and everything stays inside the
drawer. And amipkg itself is entirely optional — switch off
Install the package manager on built images and Amiga Imager builds
completely amipkg-free images, exactly as before this feature existed.
The catalog behind amipkg is an open project of its own:
github.com/thomas-luebker/amiga-pkg.
Every entry pins the exact archive (SHA-256, size, mirrors) with honest CPU/Kickstart
floors and dependencies, and the whole index is re-verified against the upstream
sources and re-signed automatically every night — new upstream
releases reach your Amiga without anyone lifting a finger. Missing a program? Package
submissions are simple pull requests (a single JSON file; the repo’s
PACKAGING.md explains every key in about five minutes).
The catalog is not a one-way street: since amipkg 0.6.x your Amiga can
author submissions itself. Both GUIs offer
Submit a Package… (a small form: package id, archive URL, category,
description), and the Shell equivalent is
amipkg submit <id> <archive-url> [CAT=<Category>] [description].
The submitting machine downloads the archive, computes the SHA-256 pin
on-device, and sends the draft in; a courier verifies the pin against an
independent download, validates the entry, and opens a review branch. A maintainer
still reviews the license and signs everything offline before it reaches any
catalog — the Amiga is the authoring tool, never a trust shortcut. Duplicate ids
are refused instantly on the Amiga (new versions of existing packages are picked
up automatically by the nightly refresh — no submission needed).
The catalog is signed with an Ed25519 key and verified on the Amiga against a built-in public key; every download must match the SHA-256 recorded inside that signed catalog. A tampered catalog or archive is refused — the download host is never trusted, which is exactly why plain HTTP is safe here.
The same package management, without booting the Amiga: click
Software in the main window's top bar (or Shift-Cmd-P) to open
Manage Amiga Software, open a built .hdf/.img,
and see every installed package with its version and update status. Search the catalog,
install (dependencies resolved, just like on the Amiga), update one or all, remove, or
change the install drawer — presets, one entry per drive of the image, or any custom
path like Work:Software via the Install Drawer menu. The window edits the
image’s receipt database directly, so the Amiga and the Mac always agree about
what is installed. The catalog
refreshes automatically from the signed online index.
When Emu68 moves on, a PiStorm system you have been using for months does not need a rebuild. Open its image — or the card itself — in Manage Amiga Software and an Emu68 bar appears above the package list. It shows:
config.txt. If the board cannot be told for sure, the bar asks you to
pick it instead of guessing;
Update to … replaces the Emu68 kernel, the Pi firmware and the
overlays on the EMU68BOOT partition (and, for Emu68 1.1, the matching
VideoCore.card). Everything is downloaded and checked before anything is
written. Never touched: your Kickstart ROM (kick.rom),
your Wi-Fi settings (wpa_supplicant.conf), and everything on the Amiga
partitions. config.txt is left alone too — it is regenerated
only when an update moves the system from Emu68 1.0 to 1.1, which
needs the new format; your HDMI mode, USB and FrameThrower settings are carried over.
The bar says so in words when an update is such a move.
Updates only go forward. Before every update the current Emu68 is
saved into one backup slot on the boot partition
(EMU68BOOT:Emu68Backup/), and the bar then offers
Restore … to put it back. Restoring uses up that backup, and the next
update replaces it — there is only ever one previous version to go back to. Going from
1.1 back to 1.0 is done with Restore, never with an update. Images that need Emu68 1.1
(PiStorm16, FrameThrower, USB) are never offered a 1.0 release.
SD and CF cards. Open Card… in the Manage Amiga Software toolbar lists the external cards connected to the Mac; pick yours and macOS asks for your password once. The card stays unmounted while it is open there. This also means a PiStorm card that no longer boots after an update can be fixed by putting it back in the Mac and choosing Restore.
Updating a real card is new in 0.99.12. Back up the card before you update it — for example by reading it into an image file with a disk-imaging tool — so nothing you care about depends on the update going right.
Amiga Fleet is a board of every Amiga on your network that runs amiagent, the small network daemon from the package list. Each machine gets a tile with its online status, response time, agent version, CPU, Kickstart and memory, and from the tile you open its live screen, a shell, and file transfer — without walking over to the machine. Open it with Shift-Cmd-L, the menu item Amiga Fleet…, or the Amiga Fleet button in the main window's top bar.
Scan LAN (or Scan my network on an empty board) sweeps the Mac's local network for agents on port 7846; enter the token your agents use and every machine that answers is added. Add… adds one machine by hand — name, host address, port and token. Right-click a tile to open its windows, Edit… its details or Remove it; Refresh updates the whole board.
RAM:). For the other direction, tick Files: a panel
lists the Amiga's drives and drawers, and you drag a file to the Finder or click
its save button. Large files are transferred in chunks with a progress readout.AMIAGENT port, which lets it drive programs that have no ARexx port of
their own. The one-click Unfreeze IMP button in the Report window
(for the IMP3 player) is one such script.amiagent creates its own TLS certificate the first time it runs, and the console uses an encrypted connection whenever the agent offers one. Because that certificate is self-signed, the console trusts it on first use: the first connection to a machine remembers its certificate fingerprint, and every later connection must present the same one. If it changes, the connection is refused — just like SSH's host-key check. If you reinstalled amiagent on purpose, that is expected; if you did not, find out why before going on. An agent without TLS is reached unencrypted.
amiagent exists to let another computer drive the Amiga: it runs any command it receives, reads and writes files, and controls the mouse and keyboard. Treat it accordingly:
S:User-Startup on the image and can travel unencrypted.AMIPKG: assign + Shell path at boot, or self-contained in its drawer), the Build Download Cache (cache on/off, offline mode, re-download, per-cache clear) and Custom Packages (register your own LHA archives as installable packages).SDH0/DH0-style device names).DEVS:a314.config, and Controller Compatibility (MaxTransfer, Mask).If you keep the defaults, you can ignore most of these — they matter when matching specific hardware or tuning repeated workflows.
Settings → PiStorm → Network → Bring the network up at boot, on by
default. It writes S:Network-Startup, which S:User-Startup
already runs at boot, so the Amiga is on the network without you typing anything.
The interface follows the build: the Pi's ethernet (genet), or WiFi
(wifipi) if you set an SSID. A WiFi build tries the ethernet port as
well, after WiFi is up, so a cable works there too.
The add is QUIET under FailAt 30, so if something else
raises the same interface later — Roadie, or PiStorm Online — the duplicate is
silent and cannot fail the script.
Turn it off if you would rather connect by hand. Be aware what that means: the
machine boots with no network at all, and anything that needs one fails
with it. amiagent is the common casualty — it needs
bsdsocket.library to bind its port and exits without one, so the
machine comes up unreachable and the agent looks broken when it is not. With the
setting off, the build log says so explicitly rather than skipping in silence.
(When amiagent starts at boot, it is tried again every 10 seconds for five minutes,
so a network that comes up late or a cable plugged in later still works.)
Settings → Build → Set the Amiga's clock from the internet, on by default. A PiStorm has no battery clock, and on many classic Amigas the battery is long gone, so without it the machine starts with an old date every time — wrong file dates, and secure web pages fail once the date falls outside a certificate's validity.
Every image with a network (PiStorm and Classic with Roadshow, MiSTer with PPP,
UAE and Amiberry) gets sntp from Aminet and S:NTPSync.rexx.
It sets the clock as soon as the network answers and every hour after, and on a
machine that has a clock it sets that too. The server is your choice under
Time server: the worldwide NTP Pool (pool.ntp.org,
the default), a regional pool, Cloudflare, Google, Apple, PTB or NIST — or
Custom… for your own, for example your router. A custom entry
must be a server name or IP address; anything else falls back to
pool.ntp.org. The time zone
is your Mac's, summer time included: the build writes the switch dates for the
next 25 years into the script. The log is in T:ntpsync.log; delete the
NTPSync lines in S:User-Startup to turn it off on the Amiga.
Simple mode and the Guided Build are the on-ramps; this chapter is the deep end — full control over partitions, filesystems, and repeatable builds. Everything here lives in Advanced mode unless noted.
In Advanced mode the Image & Build card exposes the complete partition layout: a proportional partition bar you can click to select, plus per-partition controls. For each partition you set:
SDH0/DH0-style
device names follow your naming scheme from Settings → Storage → Partition
Device Names; the label is the volume name on Workbench.The partition budget readout keeps the layout honest: usable RDB space, the fixed allocations, what remains — and on PiStorm the effective FAT boot partition alongside the Amiga space. Invalid layouts are flagged in place and in the Build Summary, with the reason spelled out.
pfs3aio handler (downloaded
automatically and cached), likewise embedded in the RDB. To use a newer one, choose
it — the handler itself or its .lha — under Settings → Build →
PFS3 handler. It is fast and robust for
big data partitions, with one hard limit: 101.6 GiB per
partition — the layout validator blocks anything larger and tells you to
cap the partition or use FFS.Build blank image (the mode picker next to the workflow tabs) builds the partitioned, formatted disk without installing AmigaOS — and optionally pre-fills it:
config.txt, your kick.rom — so a blank
PiStorm card boots Emu68 and presents the empty Amiga partitions.
Save Profile / Load Profile (bottom of the build
screen, Advanced mode) snapshot the entire configuration as a .json file
— hardware, media paths, packages, partition layout, everything. Load one to
reproduce a build exactly, keep one per machine you maintain, or drive unattended
builds from the command line with --build-profile
(Appendix B). Profiles also carry the build options from the
Settings window. Passwords and tokens are never written into a profile — loading
one keeps your own. Since v0.99.12 profiles are saved in a new format: older profiles
still load, but an older version of the app cannot open a profile saved by v0.99.12 or
later.
screenmode.prefs, and on PiStorm also into the HDMI timing in
config.txt.SYS:Programs/<Name> like any built-in package.The Build Summary lists the exact blocker. The most common causes: missing install media, missing Kickstart ROM, no output path — or, for AmigaOS 3.9, a missing Boing Bag; for 3.2.2+, a missing Update disk (see below).
Symptoms that look unrelated but share one cause: the package manager reports “Catalog update failed (rc 10) — no output”, AmiSSL-based programs insist “AmiSSL 5.x is required” although it is installed, or an application simply refuses to start. The machine has run out of Fast RAM.
First check: are you launching with the generated .fs-uae file? It requests
256 MB of Zorro III Fast RAM (plus the RTG board and bsdsocket networking).
FS-UAE reads none of the .uae keys, so a hand-rolled config
— or an image built by an older version, which wrote only the .uae —
leaves you on 8 MB of Zorro II Fast RAM. In that case add to your FS-UAE
configuration:
zorro_iii_memory = 262144On 8 MB, a loaded Workbench with MUI, the dock and a stats window leaves only a few megabytes. A program that cannot be started at all usually reports nothing rather than an error, which is why the message rarely mentions memory.
Your Amiga has a 3.1/3.1.4 ROM and the image was built without the 3.2.x
Update disk, so it has no soft-kick startup. Add
Update3.2.x.adf to your ADF folder and rebuild — see
the V47 rule in chapter 5. (Current versions block or warn about
this in the Build Summary before building.)
USB is started manually by design: open Trident (in the WBDock) and click Online. Auto-starting the USB stack during boot can hang the machine, so the app — like the wider Emu68 community — leaves the stack offline until you bring it up. Also note that on a CM4, enabling FrameThrower excludes USB from the build entirely (they share the one USB controller).
Set up the Amiga Imager Disk Helper with Full Disk Access (chapter 7), or grant Full Disk Access to Amiga Imager itself and retry. Replugging the target device can also help.
Writing erases the whole card. The confirmation names the exact target — card name,
size, /dev node. Read it and cancel if it isn't the card you expect.
(Settings → Storage → Card Writing controls the confirmation.)
Many WHDLoad games need Kickstart images (kick 1.3 / 3.1) in
DEVS:Kickstarts — if a game quits straight back to Workbench or asks for a
kickstart, that's usually it. Set the WHDLoad Kickstarts folder and
rebuild (see chapter 3) — or copy the kickstart files into
DEVS:Kickstarts on the finished image with the
Amiga File Manager, no rebuild needed.
Set the network stack to Roadshow Demo or Roadshow Full — A314 is not supported with None.
Reduce the preset, adjust the custom size, or increase the margin in Settings → Storage → SD Card Size Reduction. The app also compares image size against the card before writing, so a mismatch fails fast rather than hours in.
If the Roadshow PPP log shows Local IP address stuck at
0.0.0.0 with repeated IPCP configuration request reject messages,
the MiSTer's Linux side is not handing out an address. Edit
linux/ppp_options on the MiSTer SD card and:
192.168.1.1:192.168.1.254 (local:remote) — on many images the automatic assignment does not work. proxyarp (already enabled) then puts the Amiga on your LAN.-vj to disable Van Jacobson compression — this stops the Configure-Reject loop.ms-dns <your-router> for name resolution.
Keep crtscts active, confirm the OSD has UART = PPP at
115200, then re-up the Amiga's PPP interface. Always eject the card
cleanly from macOS before moving it back to the MiSTer.
Use Export Log after the failure and keep the Build Summary details —
that captures the exact configuration of the build. Every build writes its own
timestamped log file to ~/Library/Logs/Amiga-Imager/, so a failed build's
log survives even after you rebuild — the Previous Logs button next to
Export Log opens that folder in the Finder.
ADF/ folder).Update3.2.x.adf). Supply them in the ADF folder; when combined with a CD ISO, the folder's disks take precedence. The Update disk is required for machines with 3.1 ROMs (see the V47 rule)..lha).Amiga Imager can run a build from the command line — no window — driven by a saved build profile. This is handy for scripting, repeatable batches, or running the same build unattended.
First create the profile: set everything up on the build screen the way you want it,
then click Save Profile (in Image & Build,
Advanced mode) to write a .json file. Then invoke the app binary inside the
bundle with --build-profile:
/Applications/Amiga\ Imager.app/Contents/MacOS/Amiga\ Imager \
--build-profile ~/Builds/AmigaVision.json \
--output ~/Builds/AmigaVision.imgThe profile carries the whole configuration; these flags override individual paths so one profile can be reused:
--build-profile <path> — the saved profile (required).--output <path> — output image path.--assets <path> — Assets folder.--install-media <path> — install ISO.--kickstart <path> — Kickstart ROM.--adf-dir <path> — ADF source folder.--help — show usage.
Both Build bootable image and Build blank image profiles are supported;
Flash existing image is not (it needs an interactive card selection). The build
log is written to ~/Library/Logs/Amiga-Imager/, and the process exits with a
non-zero status if the build fails — so it fits cleanly in a shell script.
Tip: after upgrading the app, re-save older profiles once so any newly added path fields are stored.