Test the beta

Flotilla is free. It comes from its GitHub release page, signed by its developer and checked by Apple.

1. 1 Find the download

   Do Open the release page and scroll down to Assets.

   Expect The release is marked Pre-release. Under Assets are files named Flotilla-1.5.0-beta.6 ending in .dmg, .pkg, .zip and .tar.gz. Download the .dmg (a disk image), unless you know you want the .pkg (an installer package).

2. 2 Install it

   Do Open the file you downloaded from your Downloads folder. For the .dmg: drag the Flotilla icon onto the Applications folder in the window that opens. For the .pkg: follow Apple’s Installer.

   Expect The disk image opens a window with Flotilla and a shortcut to Applications, and copying takes a few seconds. The package opens Apple’s Installer, asks for your password, and ends with “The installation was successful.” Either way, Flotilla is now in your Applications folder.

3. 3 Open it for the first time

   Do Open your Applications folder and double-click Flotilla.

   Expect macOS asks its usual question for an app from the internet: “Flotilla” is an app downloaded from the Internet. Are you sure you want to open it? Press Open. (After the package, it may open straight away without asking.) There is no warning about an “unidentified developer”, an app that “can’t be opened” or “is damaged”, or Apple being unable to check it.

The first time Flotilla opens, a short guide called the Setup Assistant asks a few questions. Two words it uses: an admin Mac is one you use to look after containers, on itself and on other Macs; a host is a Mac that an admin Mac looks after. With one Mac, choose Admin.

1. 4 Welcome

   Do Read the first page, choose Admin, and press Continue.

   Expect A window titled “Welcome to Flotilla”, with “Step 1 of 5” and the question “How will you use this Mac?”. Admin and Host each say in a line or two what they mean, and a note says you can change this later in Settings.

2. 5 Make It Yours

   Do Choose an appearance (Auto follows your Mac’s light or dark mode) and a look, then press Continue.

   Expect A small sketch of the window changes as you choose, so you can see the result before you go on.

3. 6 Meet Greta

   Do Read the page about Greta, decide whether to turn her on, and press Continue (or Not now).

   Expect Greta is Flotilla’s assistant. The page says she runs on this Mac with Apple’s on-device model, sends nothing away, and never runs anything herself. If Apple’s model isn’t available on this Mac, it says so and offers Not now.

4. 7 Prepare This Mac: nothing happens without you

   Do Read this page before clicking anything.

   Expect An item called “Apple’s container”. If container isn’t on this Mac, a checkbox reads “Download and install container 1.5.0 when I continue”, with a line saying it is Apple’s installer, about 118 MB, that Flotilla checks it is Apple’s, and that Apple’s Installer asks for your password. If it is already installed, it says “Installed. Flotilla runs your containers with it.” Nothing has been downloaded yet.

5. 8 Install Apple’s container

   Do If the checkbox is there, tick it and press Continue. Skip this step if container was already installed.

   Expect Flotilla shows each stage, such as “Downloading container 1.5.0…” and “Checking it is Apple’s…”. Then Apple’s Installer opens and asks for your password: finish it there. Flotilla carries on by itself when the Installer is done.

6. 9 Online Checks

   Do Read the page, leave both boxes ticked for this test, and press Continue.

   Expect It says Flotilla goes online by itself only for these, and each is separate: “Check for Flotilla updates automatically” and “Check daily for new suggestions”, both ticked, each naming the websites it contacts.

7. 10 You’re set up

   Do Look over the summary and press Start Using Flotilla.

   Expect A page titled “You’re Set Up” lists your choices (role, appearance, container, Greta, online checks) and says you can change any of it later in Settings. Then Flotilla’s main window opens.

8. 11 Approve the Flotilla Helper

   Do If macOS tells you Flotilla added a background item, or Flotilla asks you to switch it on, open System Settings ▸ General ▸ Login Items & Extensions and switch Flotilla on.

   Expect The Helper is a small background part of Flotilla for the few jobs that need administrator rights, such as installing container. macOS asks about it once. Afterwards, the ● Helper dot at the bottom of Flotilla’s window is green, and hovering it shows “Flotilla Helper — Running” with a version.

The main window has a sidebar of sections on the left, the section you chose on the right, a search box in the bar at the top, and a status bar along the bottom.

1. 12 Overview

   Do Look at the page that opens first.

   Expect Overview is selected in the sidebar. Across the top is a band that says “Nothing needs attention” (or shows a notice), with an All Notifications link. Under it, a Get started card offers Run a Container…, Pull Image…, Add Host… and Try a Suggested Stack…. Under that are tiles called widgets, such as Fleet at a glance, Hosts and Containers, with counts that are zero or close to it on a new Mac. If container still isn’t installed, a band at the top says so, with a button to install it.

2. 13 The status bar

   Do Look along the bottom of the window. Click ● Container.

   Expect On the left: ● Container, ● Helper, the version, “v1.5.0-beta.6”, and then when Flotilla last refreshed, such as “Updated just now”. With more than one Mac added, that line also says how many are connected, such as “2 of 3 Macs connected”. On the right: Tasks. Clicking ● Container opens a menu whose first line is “Running”. If it says Stopped instead, choose Start Container System and wait for the dot to turn green.

3. 14 Note your version

   Do Open Settings (Flotilla menu ▸ Settings…, or ⌘,) and choose About. Copy the version line into “Flotilla version and build” at the top of this page, so your reports carry it.

   Expect “Version 1.5.0-beta.6 (a build number) · Tested with container 1.5.0”.

4. 15 Find your way

   Do Click Containers, Images and Volumes in the sidebar, then Overview again.

   Expect Each opens on the right. An empty list says there is nothing there yet and offers a way to start. Looking changes nothing on your Mac.

A container is a program packaged with everything it needs, made from an image (the package) and run in its own small Linux virtual machine. Suggestions are ready-made recipes for ones worth trying. You’ll run Mailpit, a small tool developers use to catch test emails. It has a web page, needs no password, and is harmless to delete.

1. 16 Open Suggestions

   Do Click Suggestions in the sidebar, just under Overview.

   Expect A row of tabs: All, Apps, Stacks, Volumes, Networks, Domains, Machines and Clusters, each with a count. The list is on the left, and a line under it reads “N suggestions · library” and a version.

2. 17 Find Mailpit

   Do Open the Apps tab, type mailpit in the search box at the top of the window, and select “Mailpit Email Testing Tool”.

   Expect Its details appear on the right of the list: what it is, its image (ghcr.io/axllent/mailpit), its ports and when it was tested. Nothing has been created. (If Mailpit isn’t listed, Flotilla hasn’t fetched its suggestions yet: click the version in the status bar, choose Check Now under Suggestions library, and search again.)

3. 18 Use it

   Do Press ▶ at the top of the details (its tooltip says “Use this suggestion…”).

   Expect The Run Container form opens across the window, already filled in: the image, the name mailpit, ports such as 127.0.0.1:8025:8025 (a different first number if 8025 is taken on this Mac), and a volume for its data. A preview shows the container run command it will use. There are no red errors. Nothing runs until you press ▶ on this form.

4. 19 Run it

   Do Hover the ▶ at the top right of the form (tooltip “Run”), then press it.

   Expect You are back on Containers at once. A Tasks panel rises on the right with one line for the job and its progress: Flotilla downloads the image first, which can take a minute. Then mailpit is in the list and running, and the panel tucks itself away.

5. 20 Open its web page

   Do In your web browser, go to http://localhost:8025 (use the first port number from the form if it was different).

   Expect Mailpit’s page, with an empty inbox.

6. 21 Its page

   Do Select mailpit in the Containers list.

   Expect Its page opens to the right of the list, starting on Overview, with its state, image and ports. Along the top is a row of tab icons, each with a tooltip when you hover: Overview, Processes, Logs, Inspect, Terminal and Files.

7. 22 Its logs

   Do Open the Logs tab.

   Expect The lines Mailpit printed as it started, including one saying where its web page is.

8. 23 Stop it

   Do In the page’s header, press Stop (a filled square; its tooltip says “Stop mailpit”).

   Expect Within a few seconds it shows as stopped, in the list and on its page, and its web page no longer loads.

9. 24 Delete it

   Do In the page’s header, press the trash can (tooltip “Delete mailpit”).

   Expect Flotilla asks first: “Delete “mailpit”?”, “This cannot be undone.”, with Delete and Cancel. After Delete, it is gone from the list. The volume made for its data stays in Volumes until you delete it there.

Downloading an image without running it is called pulling it. alpine is a very small Linux image.

1. 25 Pull an image

   Do Click Images in the sidebar and choose Pull Image… (also in the File menu). Type alpine:latest in Reference and press ▶ (tooltip “Pull”).

   Expect You are back on the Images list at once, and the Tasks panel shows the pull with a percentage. The window stays usable while it runs.

2. 26 It arrives

   Do Wait for the pull to finish.

   Expect alpine is in the Images list, beside Mailpit’s image. About two seconds after the pull ends, the panel tucks away, and the status bar shows “Tasks · Done” for a moment, then how many jobs finished.

Flotilla updates itself. Betas are offered only on the Pre-release channel, and a new Mac starts on Stable.

1. 27 Switch to the Pre-release channel

   Do Click the version (“v1.5.0-beta.6”) in the status bar. Choose Switch Channel ▸ Pre-release.

   Expect A menu with Check for Updates…, when it last checked, “Channel: Stable”, Switch Channel, Automatically check, Release Notes, and the suggestions library’s version with Check Now. Afterwards it reads “Channel: Pre-release”. (Settings ▸ Updates shows the same choice.)

2. 28 Check for updates

   Do Choose Check for Updates… from the same menu.

   Expect A short “Checking…”, then “Flotilla is up to date”, unless a newer beta has come out since, in which case it is offered with its release notes.

The box in the bar at the top of the window filters the list you are looking at, finds things by name, and runs commands. ⌘K puts you in it from anywhere.

1. 29 ⌘K opens it

   Do Press ⌘K on any page.

   Expect The search box takes focus at once and lists commands, then sections.

2. 30 It filters the page you are on

   Do On Containers or Images, type part of a name.

   Expect The list filters as you type, and the dropdown says “N on this page”.

3. 31 Look at one kind of thing

   Do Type image: and then part of an image’s name. Try Tab while a kind is suggested.

   Expect Only images are listed, and the page behind is not filtered. Tab accepts the suggested kind.

4. 32 Other kinds

   Do Try volume:, net:, suggestion: and host:.

   Expect Each lists only that kind of thing.

5. 33 Commands by name

   Do Type /run-container, then /settings, then /greta.

   Expect Each command is listed, and Return or Tab runs it.

6. 34 Commands only

   Do Type >.

   Expect Only commands are listed, and the page is not filtered.

7. 35 Esc in the box doesn’t close a form

   Do Open a form (Pull Image…, say), type in a field, press ⌘K, then Esc.

   Expect Esc closes the dropdown. The form stays open with what you typed.

8. 36 Search Docker Hub

   Do In Images, choose Browse Docker Hub…, type a name in the box and press Return.

   Expect Results from Docker Hub, a public catalogue of images.

Every list in Flotilla works the same way, like Mail: rows on the left, the selected row’s page on the right. Running a few containers first (from Suggestions) gives you more to look at.

1. 37 Rows everywhere

   Do Look at the list in each of Containers, Machines, Images, Volumes, Networks, Hosts, Registries, DNS and Kubernetes.

   Expect Each is a list of rows with a checkbox at the start of each row and a Sort menu.

2. 38 The bar above a list

   Do Open Containers and look at the bar above the list, then at the checkboxes at the start of the rows.

   Expect The first thing in the bar is a checkbox, directly above the rows’ own checkboxes. Next to it are two buttons on one rounded bar, one with lines (list only) and one with two panes. The one in use is lit. After them come the Sort menu and, when there is something to choose between, Filter.

   Do Tick the checkbox in the bar, then untick it. Hover each of the two buttons.

   Expect Every row is ticked, then none. The tooltips say “Show List Only” and “Show Two Panes”.

3. 39 The divider is remembered

   Do Drag the divider between the list and the page, switch to another section, then come back.

   Expect The width is remembered for each section. A section you have never changed starts with the divider in the middle.

4. 40 Rows fit their width

   Do Make the list wide, then narrow.

   Expect Rows become one line when there is room, and two or three when narrow. The small labels (chips) drop before the name is ever cut short.

5. 41 Row actions on hover

   Do Hover a row, then select one. Open the ⋮ menu at its end, then right-click a row.

   Expect The row’s main action (Start or Stop, for a container) and ⋮ appear at its end. Delete is in ⋮, the right-click menu and the page header, never as a button on the row, and it asks first.

6. 42 Step through the list

   Do With a page open, use ↑ ↓ in its header, then ⌘[ and ⌘]. Then press the expand button beside them.

   Expect The selection moves through the list in the order shown. Expand widens the page over the list.

7. 43 Several at once

   Do Tick two rows. Then hover a checkbox that can’t be ticked (This Mac in Hosts, or a built-in network).

   Expect The right side shows a summary with actions for both. A checkbox that can’t be ticked says why.

8. 44 List only

   Do Press the list-only button (the one with lines) in the bar above the list, or press ⌥⌘L. Click a row, then press ✕ or Esc. Press the two-panes button to bring the page back.

   Expect The list fills the window, a click on a row slides its page in, and ✕ or Esc closes it, also while a row has keyboard focus. The two-panes button puts the list and the page side by side again, and the button that is lit follows.

9. 45 Filtering keeps the page open

   Do With an item’s page open, filter the list so that item is hidden.

   Expect Its page stays open.

10. 46 Logs and Activity

    Do Open Logs and click a line. Then open Activity and click a line.

    Expect The line’s full text, time, source and Mac on the right. Activity is a record, so it has no bulk actions.

11. 47 Notifications and Suggestions

    Do Look at Notifications and Suggestions. Dismiss several notices at once.

    Expect The same rows as the other lists. Error notices can’t be ticked.

12. 48 The smallest window

    Do Make the window as small as it goes.

    Expect No pane is cut off, the theme grid in Settings reflows to two columns, and the version in the status bar is still readable.

The Overview is the page Flotilla opens on. Under the band along the top, it is made of widgets: tiles that each show one thing, such as your containers or your Macs. You choose which ones, how big, what they show and where they go, and Flotilla remembers for next time. A few containers running first (from Suggestions) gives the widgets something to show.

1. 49 The top of the Overview

   Do Open Overview. Look at the band along the top, under the title bar. Try to drag it or remove it.

   Expect The band says “Nothing needs attention”, or shows one notice at a time with arrows and Dismiss, and always has an All Notifications link. It stays where it is: it can’t be moved or removed. The Get started card and the widgets are under it.

2. 50 Four shapes

   Do Find the Containers widget and click the ⋯ at its top right. Under Size, choose Small, then Wide, Tall and Large in turn.

   Expect The widget changes shape each time, and shows a different layout of the same information: a single figure when Small, the figure with a few rows when Wide, a list of one-line rows when Tall, and a list of rows with more detail when Large. Nothing overlaps and the other widgets move to make room.

3. 51 Choose what a widget shows

   Do Open the ⋯ menu of the Containers widget again and under Show choose Running, then Stopped, then All. Do the same on Hosts and Images.

   Expect The list changes each time. The widget’s title names a choice other than its usual one, such as “Containers · Stopped”. Hosts offers All and Problems, and Images offers Newest, Largest and With Vulnerabilities. Storage has no choice, because it shows this Mac’s disk and nothing else.

4. 52 Click a widget

   Do Set Containers to Stopped, then click the widget. Go back to Overview and click Machines.

   Expect Containers opens already filtered to stopped containers, and Machines opens its section. Clicking a widget takes you to the part of Flotilla it comes from, set to what the widget showed.

5. 53 Add and remove widgets

   Do Press Add Widget in the bar at the top of the Overview, above the widgets. Tick a widget that has no tick, such as Images or Tasks. Then open the menu again and untick it.

   Expect Every kind of widget is listed with an icon, and those on the page have a tick. Ticking adds the widget, and unticking takes it away. There is only ever one of each kind: ticking one that is already there changes nothing.

6. 54 Move a widget

   Do Hover over a widget and look at its top left. Drag the grip of dots to another place, and let go.

   Expect A grip of six dots appears, and its tooltip says “Drag to move”. The widget lifts as you drag, the others slide out of the way, and it settles into the place where you let go. You don’t need Edit mode for this. Clicking anywhere else on the widget opens its section instead.

7. 55 Edit Widgets

   Do Press Edit Widgets. On one widget, press ✕. On another, press the S, W, T and L buttons, then drag the small handle at its bottom right corner. Look at the panel on the right. Then press Done.

   Expect Each widget gets a ✕, buttons for its size (S small, W wide, T tall, L large) and a resize handle. The panel lists every kind of widget with a checkbox and a line about it, and ticking or unticking works as in the Add Widget menu. At the top are Reset to Recommended and Done. Done, the panel and the sidebar all stay whole in the window, even a narrow one.

8. 56 Your layout is kept

   Do Arrange the widgets the way you like, quit Flotilla (⌘Q) and open it again.

   Expect The same widgets, order, sizes and choices come back. The layout belongs to this Mac: another Mac that you manage keeps its own.

9. 57 Start again

   Do Press Edit Widgets, then Reset to Recommended. Then remove every widget with ✕.

   Expect Reset puts back Fleet at a glance, Hosts, Containers, Vulnerabilities, Activity, Machines and Kubernetes at their usual sizes. With no widgets, the page says “Make the Overview yours”, with buttons to add widgets one at a time and “Use the recommended layout”. The band and the Get started card never go.

Every job you start, such as a pull or a run, becomes a task, shown in the Tasks panel on the right. A larger image, such as postgres:17, gives you time to look while it pulls.

1. 58 A task in detail

   Do Start a larger pull. Hover its line in Tasks, then open its caret (the small arrow). Then put the panel away with its chevron or Esc.

   Expect The tooltip says where it runs, its state and step. The caret shows its steps and live output. Put away, the status bar shows “Tasks · 1 · N%” with a spinner.

2. 59 Show and hide

   Do Press ⌥⌘T twice.

   Expect Tasks opens, then closes.

3. 60 Two jobs are two tasks

   Do Start a second pull while the first is running.

   Expect Two lines in Tasks, and Images stays usable.

4. 61 Stop a pull

   Do Start a larger pull and click its Stop (a circle with a square).

   Expect The task ends as Cancelled, with no failure notice.

5. 62 A job that fails says so

   Do Pull an image that doesn’t exist, such as flotilla-beta/no-such-image:0.

   Expect The task is marked failed with one red line saying why. The status bar shows “Tasks · Failed” in red, and a notice “… failed: …” offers Show Task, which opens Tasks on that line. If Flotilla is in the background, a macOS notification too.

6. 63 Retry a failed job

   Do On that failed task, click Retry (the circular arrow), twice.

   Expect A new line starts and the old one is marked retried. The second click starts nothing more.

7. 64 Stop a container from its task

   Do Run a container from Suggestions, show Tasks (⌥⌘T), and hover the Stop button (a filled square) on its Run task. Click it.

   Expect The tooltip names the container, such as “Stop mailpit”. The button shows a small spinner while it works, and the container stops in Containers.

8. 65 A run can’t be retried

   Do Look at a Run task.

   Expect No stop-circle and no Retry on it: running the same container twice could do harm, so Flotilla doesn’t offer it.

9. 66 Stop never reaches the wrong container

   Do Run a container, delete it, run another with the same name, and look at the first one’s task.

   Expect The old task has no Stop button. The new task’s Stop stops only the new container.

10. 67 Finished jobs fold away

    Do Let several jobs finish, one of them failing. Then use Clear on one line, and Clear finished (✕ in a circle) in the header.

    Expect They fold into one line, “N finished”, that opens on click, with the failure named on it in red (“· 1 failed”). Clear removes them.

11. 68 A failure keeps the panel up

    Do Start two jobs, one of which fails.

    Expect The panel stays up after the good one ends, until you put it away.

12. 69 An open line keeps the panel up

    Do Open a line’s caret, then let a job finish.

    Expect The panel does not tuck away while a line is open.

13. 70 Tasks and Greta

    Do Open Greta (the sidebar, or ⌘G) and start a pull.

    Expect The Tasks panel and Greta don’t overlap.

14. 71 Every icon has a tooltip

    Do Hover each icon button in the panel.

    Expect Stop, Retry, Clear and Clear finished each have a tooltip.

15. 72 A switch for failed jobs

    Do Open Settings ▸ Notifications.

    Expect A switch for “A job you started failed”, on by default.

Anything you create starts with a form across the window. Every form has its buttons together at the top right, and none at the bottom.

1. 73 One cluster of buttons

   Do Open Run Container (File ▸ Run Container…), New Volume, New Network and Pull Image.

   Expect At the top right of each, on one rounded strip: ✕ to close, then the main action in your Mac’s accent colour. No row of buttons at the bottom.

2. 74 The command preview

   Do In Run Container, type the image nginx:latest, the name web and the port 127.0.0.1:8080:80. Watch the preview while you type.

   Expect No red errors before you have typed anything. The preview shows the whole container run … command, the same command you could type in Terminal, and changes as you type.

3. 75 ▶ starts a job, ✓ keeps changes

   Do Hover the main action on each form, and on Tag Image, a group, a registry, a new DNS domain and Add Host.

   Expect A tooltip with its full name, such as “Pull” or “Create…”. It is ▶ on a form that starts a job (which then shows in Tasks) and ✓ on a form that keeps your changes.

4. 76 Return and Esc

   Do Press Return in a filled-in form, and Esc in an untouched one.

   Expect Return uses the main action. Esc closes the form.

5. 77 Unsaved changes are asked about

   Do Change a field, then press ✕. Choose Keep Editing, then try Esc, then Back.

   Expect The same question each time, “Discard your changes?”, with Discard and Keep Editing.

6. 78 Every way out asks

   Do With a half-filled form, click another section in the sidebar, choose something from ⌘K, press ⌘Q, and use the menu-bar icon.

   Expect One question, “Discard your changes to …?”, each time. An untouched form leaves at once.

7. 79 Rare extras are in ⋯

   Do Open a group and a DNS domain.

   Expect ⋯ to the left of ✕, with Save to File… (the group) and Delete… (the domain). Forms with no extras show no ⋯.

8. 80 Close alone

   Do Open a registry you aren’t signed in to, or a DNS domain you are only looking at.

   Expect ✕ alone, with no main action.

9. 81 Export

   Do Choose File ▸ Export Configuration….

   Expect A list of what can be exported, with one select-all checkbox at the top.

10. 82 A host’s page isn’t a form

    Do Open This Mac in Hosts.

    Expect Its own page header, not a form’s buttons.

You used one suggestion on the core path. Apps are single containers and stacks are several that work together; the other tabs suggest volumes (storage), networks, DNS domains (names for containers), machines and Kubernetes clusters. Nothing is created until you press a form’s main action.

1. 83 Search changes the counts

   Do Type postgres, then clear it. Then try database and licence.

   Expect Every tab’s count changes, All showing the total, and the box prompts “Search all suggestions”. database finds the Databases category, licence finds entries with a licence note. Clearing brings the counts back.

2. 84 All

   Do Open All.

   Expect Apps, stacks and the others together, each row with its kind, and a logo for apps and stacks or a symbol for the rest. A Category menu narrows apps and stacks only.

3. 85 An app’s details

   Do Open Apps and select one.

   Expect Its details on the right: image, ports, where it keeps data, any passwords it will generate, any licence note and when it was tested. Use (▶) is in the header, with ↑ ↓ to step.

4. 86 A stack’s details

   Do Open Stacks and select one.

   Expect Its services with their images, and notes under “Once it’s running”.

5. 87 Volumes, networks, domains and clusters

   Do Select one suggestion in each of Volumes, Networks, Domains and Clusters.

   Expect A summary, its details, and “Opens the existing create form. Review or change its values before creating.”

6. 88 Machines are for this Mac

   Do Select a machine suggestion. If you have a second Mac paired, choose it in “Create on”, then This Mac again.

   Expect On another Mac: “Machines can only be created on This Mac…” and Use is off. Back on This Mac, it is on again.

7. 89 No match

   Do In one tab, type zzzz. Then type something that matches only in another tab.

   Expect “No matching suggestions”, and Show all matches when another tab has one, which opens All.

8. 90 Two at once

   Do Tick two apps. Then tick an app and a volume.

   Expect Two apps or stacks offer “Use 2 Suggestions…”. An app with a volume says “Use apps and stacks together, or choose one resource.” and the button is off.

9. 91 Leaving a form you haven’t changed

   Do Select an app and press Use. Press ✕ at once. Use it again, change the name, then press ✕.

   Expect The first ✕ closes with no question: the filled-in values aren’t your changes. After your change, “Discard your changes?”.

10. 92 Use a stack

    Do Use a stack, with the same two ✕ checks.

    Expect The stack form, with a suggested name and free web ports. No question untouched, a question after a change.

11. 93 Use the others

    Do Use a volume, a network, a domain, a machine and a cluster, with the same ✕ checks each time.

    Expect New Volume (with a name that isn’t taken), New Network, New DNS Domain, New Machine and New Cluster, each filled in. No question untouched, a question after a change.

12. 94 Use only opens a form

    Do After a Use, before pressing the main action, look at the matching section.

    Expect Nothing has been created.

13. 95 Coming back to the same place

    Do On Volumes, search data, select a row, press Use, then ✕.

    Expect The Volumes tab, the search, the selection and the divider exactly as you left them.

14. 96 Coming back after creating

    Do Use something and press the form’s main action.

    Expect You come back to the same tab and selection, with the job in Tasks.

15. 97 Kept while you go elsewhere

    Do Pick a category, go to Containers and come back. Then quit Flotilla and reopen it.

    Expect The same tab, search, category and selection after the visit. After reopening, the divider is where you left it (the tab and search start afresh).

16. 98 Find suggestions from any page

    Do From Containers, press ⌘K and type redis. Choose a volume suggestion, then try an app and a stack.

    Expect Suggestions of several kinds, each with its kind under its name. Choosing one opens Suggestions on its tab with that row selected; no form opens and nothing is created.

17. 99 Only suggestions

    Do Type suggestion: database, then suggestion: alone.

    Expect Only suggestions, from every tab.

18. 100 From Containers

    Do In Containers, choose Suggestions… from the Add menu (also on a right-click in empty space).

    Expect Suggestions on the Apps tab.

19. 101 From an empty list

    Do In an empty list (an empty Volumes, Networks, DNS, Machines or Clusters, or Containers filtered to nothing), choose a suggestion named under “Or start from a suggestion”, then More….

    Expect The named one, selected in its tab with its details and no form; then the whole tab.

20. 102 From the other sections

    Do Choose Suggestions… from the Add menu of Volumes, Networks, DNS, Machines and Clusters.

    Expect The matching tab each time (Machines opens with This Mac).

21. 103 From the menus

    Do Open File ▸ Suggestions. Then try Overview’s “Try a Suggested Stack…”.

    Expect All, Apps, Stacks, Volumes, Networks, Machines, Kubernetes Clusters and DNS Domains, each opening its tab. The Overview button opens Stacks.

22. 104 Using several in turn

    Do Tick several apps or stacks and press “Use N Suggestions…”. Include two that use the same port. Look in ⋯.

    Expect Each form in turn, with “1 of N”, and Skip in ⋯. The later of the two gets a free port, or says “No free port near N — choose one”.

23. 105 Logos

    Do Look at Apps and Stacks, then run something from a suggestion and look at its row and page. Then try dark mode.

    Expect Each entry’s logo on a light tile, or its category’s symbol. The container’s row and page header show the same logo, and so does its image. In dark mode, a thin line round the tile.

24. 106 Machine and registry logos

    Do Open Machines and Registries.

    Expect The Linux distribution’s or registry’s logo, where the library has one.

25. 107 A logo that needs a credit

    Do Open Suggestions and look for Redis. If it shows only a symbol and not a logo, the library that carries it isn’t out yet: mark this step Skip. If it shows the logo, scroll to the foot of the list. Then open a group, choose Add Service, and look at the foot of the picker. Then open Settings ▸ About.

    Expect Redis’s logo on its tile, and a short credit line that Redis asks for at the foot of Suggestions, at the foot of the Add Service picker, and in About. The credit is there whatever you search for or whichever tab you are on.

26. 108 The library in Settings

    Do Open Settings ▸ Updates, quit and reopen Flotilla, and look again.

    Expect The suggestions library’s version, when it last checked (kept after reopening), and Check Now.

Suggestions come from a library that Flotilla fetches and checks. These steps need library 2026.10.20.1 or newer. Its images are scanned every day for known security problems (vulnerabilities), and Flotilla matches that report against the images on your Mac; nothing about your Mac is sent. Some apps don’t run as the administrator inside their container, so Flotilla prepares a fresh volume (storage) for them to write to.

1. 109 The library version

   Do Click the version in the status bar and choose Check Now under Suggestions library.

   Expect It shows version 2026.10.20.1 or newer.

2. 110 Findings for an image

   Do Use an app from Suggestions and run it, so its image is on this Mac (Grafana works well). Then open that image in Images.

   Expect A Vulnerabilities card, with counts for Critical, High, Medium and Low. It says the findings are in the image, that updating packages inside a container doesn’t change them, and that a newer image fixes them, with “Check for a newer image…”, which opens Pull Image. A footnote says when and by what it was scanned, and that it is advisory only.

3. 111 In the lists

   Do Look at the rows in Images, then at the same app in Suggestions.

   Expect An image with critical findings has a chip such as “2 critical” on its row. The suggestion has a line such as “Its image has 2 critical issues (fixed in a newer version)”. An image with nothing reported shows nothing.

4. 112 In a container

   Do Open the page of the container you ran from that image.

   Expect The same findings. Nothing is stopped or restarted because of them.

5. 113 An image from elsewhere

   Do Open alpine in Images (from the core path, or pull alpine:latest).

   Expect No vulnerability information: the report covers the library’s images only.

6. 114 Offline

   Do Turn Wi-Fi off, quit Flotilla and open it again. Look at the image from before.

   Expect The findings still show, from Flotilla’s saved copy. Turn Wi-Fi back on.

7. 115 A volume set up for its app

   Do In Suggestions, Use Grafana and press ▶. Open Tasks while it runs. When it is running, open http://localhost:3000 (or the port the form chose).

   Expect The task shows a line “Setting up … for …” before the container starts. Grafana’s sign-in page opens, and its Logs show no “permission denied”.

8. 116 Interrupted half way

   Do Delete that container and its volume. Use Grafana again, quit Flotilla while the task says “Setting up …”, then open Flotilla, delete the half-made container if there is one, and run it again.

   Expect The setup runs again and finishes, and Grafana starts with no permission error.

9. 117 A volume that already has data

   Do Run Grafana again with the volume name of the one that is already in use and has data (keep the name the form shows if it matches, or type it).

   Expect Flotilla doesn’t touch that volume’s contents or owner. Nothing in it is lost.

10. 118 In a group

    Do Make a group (File ▸ New Group…), choose Add Service, pick Grafana, save the group and press Start.

    Expect Grafana’s new volume is set up the same way, and Grafana writes to it with no permission error.

A group is a saved set of containers that start together, such as an app and its database. Each container in a group is a service. Make one with File ▸ New Group….

1. 119 The Add Service picker

   Do In a new group’s form, choose Add Service.

   Expect A picker with Suggestions and the images on this Mac, a search field, a select-all row at the top of the checkboxes, and a way to start blank.

2. 120 One suggestion

   Do Tick one suggestion and press the main action (tooltip “Review Service”).

   Expect The service form opens, filled in with the recipe’s image, ports, settings and volumes.

3. 121 An image on this Mac

   Do Tick an image on this Mac that matches a suggestion, then one that doesn’t (such as alpine).

   Expect The first fills in like the suggestion. The second gives a form with just the image.

4. 122 Recipes match the major version

   Do With postgres:17 and postgres:latest both pulled, look at their rows in the picker.

   Expect The 17 image says “Starts from PostgreSQL’s ports, variables and volumes” only if the library’s recipe is for 17. The latest one says “Just the image”.

5. 123 Several at once

   Do Tick three and press “Add 3 Services”.

   Expect All three are added to the group straight away, with different names, each with a free port on this Mac.

6. 124 Two that want the same port

   Do Tick two that both use port 80.

   Expect The second is given a different port on this Mac.

7. 125 Each gets its own password

   Do Tick a service that needs a password. Remove another one before saving.

   Expect The service has its own generated password, and none is saved for the one you removed.

8. 126 A double click adds once

   Do Press the main action twice quickly.

   Expect The picks are added once.

9. 127 A port mapping needs a port on this Mac

   Do Edit a service and change its port to 127.0.0.1::80 (no port before the last colon).

   Expect It is marked in the form and refused on save, with “needs a host port”.

10. 128 Leaving the picker

    Do Tick some rows in the picker and press Back.

    Expect It leaves without asking: nothing has been added yet.

11. 129 Leaving cancels a pending add

    Do Tick several, press Add, then Back before it finishes. Try again and choose Blank Service instead of waiting.

    Expect Nothing is added afterwards, and the blank form is unchanged when the pending add would have finished.

12. 130 The question names the service

    Do In a service’s form inside a group, change something and press Back or ✕.

    Expect The question names only that service.

13. 131 A group’s overview

    Do Save the group, then select it in Containers and press Start.

    Expect An overview: “n of m services running”, the services, a link to each container, and Edit….

Use a running container you don’t mind changing, such as Mailpit or nginx run from Suggestions or the Run form.

1. 132 A terminal inside the container

   Do On the container’s page, open the Terminal tab, type ls / and press Return.

   Expect A working command line inside the container lists its folders. Typing, Return and colours behave as in Terminal.

2. 133 A small Finder

   Do Open the Files tab.

   Expect Back and forward, Icons / List / Columns, Group By, Share, Download, ⋯ and search. The path is at the bottom beside the item count.

3. 134 Group By

   Do Try each Group By option.

   Expect Name, Kind, Date Modified and Size work. Created, Last Opened, Added and Application are greyed out, because a container doesn’t record them. There is no Tags.

4. 135 Make, rename and move

   Do In /tmp, use New Folder, Rename and Move to….

   Expect Each works.

5. 136 Moving onto an existing name

   Do Move a file onto a name that already exists there.

   Expect A question about replacing it, not a silent loss.

6. 137 Delete asks

   Do Delete a file you made.

   Expect A confirmation, every time.

7. 138 Search

   Do Search inside the container.

   Expect Results, with a limit on how many.

A machine is a whole Linux virtual machine you can log in to, rather than one program. Try a small Alpine one.

1. 139 Create a machine

   Do Choose File ▸ New Machine…, pick Alpine, keep the suggested size and press ▶.

   Expect The form returns to Machines at once, the job is in Tasks, and the machine appears in the list.

2. 140 Its shell

   Do Start the machine and open its Shell tab.

   Expect A working command line inside the machine.

3. 141 Check an Alpine machine for updates

   Do On the running Alpine machine’s page, press Check for Updates.

   Expect A spinner, then “Up to date” or “N updates available” listing each package’s installed and available versions, and “Last checked”. No error text in the list. The page says to run apk upgrade in the Terminal tab to install them.

4. 142 Check an AlmaLinux machine

   Do If you make a running AlmaLinux machine, press Check for Updates on it.

   Expect The same, with versions that read normally (no \t or \n in them), and a suggestion to run dnf upgrade.

5. 143 A stopped machine

   Do Stop the machine and open its page.

   Expect The button is off, with “Start this machine to check for updates.” On a running one, the page says a check starts the machine again if it has just stopped.

6. 144 Other distributions

   Do If you have a running machine of another Linux distribution, open its page.

   Expect The button is off, with “Package checks support Alpine and AlmaLinux.”

A restart policy starts a container again if it crashes; a health check keeps asking it whether it still works. Use a container with a web page, such as Mailpit.

1. 145 The Restart and health card

   Do Open a container’s page.

   Expect A Restart and health card, with a history and an editor.

2. 146 A check that goes healthy and unhealthy

   Do Set an HTTP or port check on the container’s port. Then break it (stop the container’s program from the Terminal tab, for example), then fix it.

   Expect The check goes healthy; then unhealthy, with a warning notice offering Restart; then healthy again.

3. 147 Checks that can’t work are refused

   Do Try a check on a port the container doesn’t publish, a UDP port, or one bound to another address.

   Expect Refused when you save, with a reason.

4. 148 Restart after a crash

   Do Set a restart policy and make the container crash.

   Expect It restarts at once, then after about 10, 30, 60 and 120 seconds, then gives up with an error notice offering Start.

5. 149 Stopping isn’t crashing

   Do Stop the container in Flotilla.

   Expect It is not restarted.

Greta is Flotilla’s experimental assistant. She needs Apple Intelligence on this Mac. Speech is recognised on this Mac only.

1. 150 Greta says she is experimental

   Do Open Greta.

   Expect A banner at the top of her panel says she is experimental: her answers can be wrong, so check anything she suggests before you run it.

2. 151 The microphone permission

   Do Click the microphone in Greta’s message field.

   Expect macOS asks for microphone access.

3. 152 If you deny it

   Do Deny access (you can allow it again later).

   Expect One line, and a button that opens System Settings ▸ Privacy & Security ▸ Microphone.

4. 153 The speech model

   Do Allow access. If the speech model for your language isn’t installed yet, read the message before clicking.

   Expect “macOS needs to download speech recognition for <your language> from Apple, once”, and a Download button. Nothing downloads before you click it.

5. 154 Stopping the download

   Do Click Download, then Stop while it downloads.

   Expect The download stops and no listening starts.

6. 155 After the download

   Do Download it fully.

   Expect Dictation starts by itself, with a chime as it opens and closes.

7. 156 Dictating, offline

   Do Turn Wi-Fi off and dictate a sentence.

   Expect Words appear live in the field. Nothing is sent until you press Send.

8. 157 Every way to stop listening

   Do Stop dictation with a second click, then with Esc, by typing, and by switching windows.

   Expect Listening stops each time, and the microphone isn’t used afterwards.

9. 158 The shortcut

   Do Press ⇧⌘D twice, and look in the menus.

   Expect Dictate to Greta and Stop Dictating, in turn.

10. 159 Conversations

    Do Look at Greta’s list of conversations.

    Expect Rows with Pin, Rename, Duplicate, Archive and Delete (which asks first), actions for several at once, and a rounded message field.

The status bar’s dots show the state of Apple’s container and of the Flotilla Helper; click either for a menu.

1. 160 Settings

   Do Open Settings.

   Expect A sidebar of sections with icon tiles, and grouped panes. On a Mac managed by an organisation, locked settings read “Set by your organisation”.

2. 161 About

   Do Open Settings ▸ About.

   Expect “Flotilla 1.5.0-beta.6” with “Tested with container 1.5.0”, a list of every website Flotilla can contact, where it keeps its data, and logo credits.

3. 162 About from the menus

   Do Choose About Flotilla from the Flotilla menu, and from the menu-bar icon’s menu (at the top right of the screen).

   Expect Both open Settings ▸ About.

4. 163 The Support Bundle

   Do Choose Help ▸ Create Support Bundle…. Click a file in its list to read it.

   Expect Every file listed with its size and a description, readable before you save. A Close button in every state, and Esc closes it. Nothing is uploaded.

5. 164 The Container menu

   Do Click ● Container in the status bar.

   Expect A menu whose first line says Running (or Stopped), then its actions.

6. 165 Stop and start container

   Do Only if nothing you need is running: choose Stop Container System… from that menu, then start it again.

   Expect A confirmation first. Then the dot changes, and changes back when it starts.

7. 166 Restart the Helper

   Do Click ● Helper in the status bar and choose Restart.

   Expect A short wait, then Running again. The menu never freezes.

8. 167 Reinstall, Remove, Install

   Do Use Reinstall, then Remove, then quit and reopen Flotilla, then Install.

   Expect The state changes each time. After Remove, it doesn’t come back by itself when Flotilla next opens.

9. 168 The Helper is explained once

   Do Look through Settings for the Helper.

   Expect It is explained in one place, not repeated in several.

1. 169 Every icon says what it does

   Do Hover every icon button on Containers, Images, a container’s page, the status bar and a form’s header.

   Expect A tooltip on each that says what it does. None is empty.

2. 170 Tab icons

   Do Hover each tab icon on a container’s page and a machine’s page.

   Expect Each tab has its own tooltip, in the same order on every page.

3. 171 Tabs from the keyboard

   Do On a container’s page, press ⌘1 through ⌘6.

   Expect Each switches to its tab.

4. 172 Buttons say exactly what they do

   Do Hover the ▶ on New Machine and New Cluster. Hover the close icon on a page.

   Expect Tooltips that name the action, such as “Create Machine…”, and “Close”.

5. 173 VoiceOver

   Do Turn on VoiceOver (⌘F5) and move through the Containers list.

   Expect Each row offers the same as the pointer: its title, chips, buttons and ⋮.

1. 174 Hosts, Registries, DNS and Kubernetes

   Do Open each of them.

   Expect Rows with Sort menus and checkboxes. Kubernetes has a Delete for several clusters at once that asks first.

2. 175 Quitting

   Do Quit Flotilla with ⌘Q, then from the menu-bar icon, then with osascript -e 'quit app "Flotilla"' in Terminal.

   Expect It quits at once every time.

3. 176 Quitting with the search open

   Do Open the ⌘K dropdown and press ⌘Q.

   Expect It quits, with no crash.

Needs a second Apple silicon Mac with macOS 26 and Flotilla beta 6, on the same network or reachable by address. Set it up as a host in its Setup Assistant; your first Mac is the admin. Linking them is called pairing.

1. 177 The Add Host form

   Do On the admin Mac, choose Add Host… (on Overview, or in Hosts).

   Expect The form on the left and help on the right: finding Macs nearby versus typing an address, the kinds of address that work (names, IP addresses, Tailscale), the port, and where the host shows its pairing code.

2. 178 Pair a host

   Do Pair the second Mac, following the form.

   Expect macOS asks once for Local Network access. The host then appears in Hosts, and its containers in Containers.

3. 179 Host rows

   Do Look at the rows in Hosts.

   Expect Each Mac’s own model icon (a virtual Mac shows a plain display), and in the group headings an icon per category with a chevron.

4. 180 SSH, Screen Sharing and Files

   Do Open the host’s page.

   Expect SSH, Screen Sharing and Files tabs, each with a green, red or grey dot. This Mac’s own page has none.

5. 181 SSH

   Do In the SSH tab, press Start SSH Session.

   Expect Your own ssh runs in a terminal, with your keys and settings. There is no connection until you press the button.

6. 182 Flotilla’s own key

   Do If you have no key for this host, use Make a Key, then Copy Key, then Try It.

   Expect ssh-keygen runs in the tab and never overwrites an existing key. Copy Key asks for the host’s password once.

7. 183 Replace the key

   Do Use Regenerate Key….

   Expect The old key is renamed aside, a new one made and copied, and, if you ticked it, the old one removed from the host, checked with the new key alone. Other hosts that had the old key offer Copy to ….

8. 184 Remove the key

   Do Use Remove Key from This Host….

   Expect Only that host’s authorized_keys file changes.

9. 185 Screen Sharing and File Sharing

   Do Open the Screen Sharing and Files tabs, with each service on, then off, on the host (System Settings ▸ General ▸ Sharing).

   Expect With it on: Open Screen Sharing and Open in Finder. With it off: how to turn it on, with Apple’s guide.

10. 186 Run on the host

    Do Run a container on the host (choose it in the Run form), then press Stop on its task.

    Expect The task names the host. Stop’s tooltip names the host, and the container stops there, not on the admin.

11. 187 Other jobs on the host

    Do Pull an image to the host, or push a network to it.

    Expect A task naming the host.

12. 188 Same name, different Mac

    Do With a container of the same name on both Macs, open the host’s one’s Terminal.

    Expect The command line is in the host’s container, not the admin’s.

13. 189 Another Mac’s files are read-only

    Do Open Files on one of the host’s containers.

    Expect You can look but not change anything.

14. 190 Volume setup on the host

    Do In Suggestions, choose the host in “Create on”, Use Grafana and press ▶.

    Expect It works the same as on this Mac, with the volume set up on the host.

15. 191 Security advisories

    Do Open the host’s Updates tab.

    Expect macOS releases and fixed or actively exploited security problems (CVEs) that apply to its macOS version, and serious fixes for its Linux kernel. They match that Mac, not the admin.

16. 192 Policies keep running on the host

    Do From the admin, set a restart policy and an HTTP or port check on one of the host’s containers. Quit Flotilla on the admin.

    Expect The host keeps applying them while the admin is closed. Command checks aren’t offered for a host.

17. 193 Suggestions for the host

    Do In Suggestions, choose the host in “Create on”, then Use a volume and an app.

    Expect Each form opens set to that Mac.

18. 194 container on the host

    Do Open the host’s menu.

    Expect Install/Upgrade container… is offered.

19. 195 An unreachable host

    Do With the host asleep or offline, try New Cluster on it.

    Expect The form stays open, with the reason in a band under its header.

20. 196 Network changes

    Do On the admin, switch Wi-Fi networks, or turn Wi-Fi off and on.

    Expect Hosts reconnect within a short time and don’t stay red.

21. 197 A busy host

    Do Keep the host busy with a big pull and watch its status.

    Expect Amber (busy), not red, and its last information is kept.

22. 198 Quitting with a host asleep

    Do Sleep or unplug the host, switch sections ten times, then quit Flotilla on the admin.

    Expect It quits at once. Checks don’t pile up, and “Updated” keeps moving until then.

23. 199 Forget all hosts

    Do Only if you are ready to pair again: Settings ▸ Forget all hosts and trust.

    Expect The hosts disappear. Your containers and settings are untouched.

Only if you had beta 5 on this Mac or a host. Skip this section if this is your first time with Flotilla. How to go back to beta 5 is in BETA-TESTING.md.

1. 200 Update from beta 5

   Do In beta 5, open Settings ▸ Updates and set the update channel to Pre-release if it isn’t already. Then choose Flotilla ▸ Check for Updates….

   Expect Beta 6 is offered with its release notes, installs, and relaunches Flotilla. The version now reads “1.5.0-beta.6”, not “1.5.0-beta.5”.

2. 201 Your things are kept

   Do After the update, look at your groups, your theme and other settings, the section you had open, and any Macs you had paired under Hosts. Then open Overview.

   Expect All of it is kept. Paired Macs are still trusted, with no new pairing needed. The Overview shows the recommended widgets, because beta 5 had no widgets to keep.

3. 202 Update a host from the admin

   Do If a host is on beta 5: on the admin, open the version menu ▸ Your Macs and update Flotilla on it.

   Expect A confirmation first. The host updates when idle, one host at a time, and comes back on beta 6.

4. 203 Nothing left over

   Do After a host updates, open its page.

   Expect No “waiting on update” or failed notice left over. Its Helper shows Running at the new version.

5. 204 A host offline during an update

   Do Take a host offline while it is being updated.

   Expect “Waiting”, not failed. Failed only after two minutes on the old build.

6. 205 Mixed versions

   Do If one Mac is still on beta 5, open its page and its containers from the other.

   Expect Everything beta 5 could do still works, and nothing is refused. The two Macs keep their own Overview layouts.