First Run

First run

The first time Flotilla opens, it opens the Setup Assistant in a window of its own, with five steps and a Finish. Flotilla also runs a preflight on container before it trusts any number.

Every step has a default, so pressing Continue all the way through gives a sensible setup. The steps are listed down the left, with Step 2 of 5 at the top. Return continues and Esc goes back. Back keeps what you did. A tick in the list means a step was answered, not only seen.

If you close the assistant part way, it is offered again next time. Run it again whenever you like from Help ▸ Setup Assistant….

1. Welcome

How will you use this Mac? Admin or Host:

• Admin — the Mac you sit at. It manages its own containers and, once you pair them, other Macs'. It listens on nothing.
• Host — a Mac that runs containers for an admin, such as a Mac mini in a cupboard. It listens on the local network for its paired admins.

Whether a Mac listens on the network at all is not something anybody should find out about later, so it is asked here. Admin is pre-selected because it listens on nothing. A host also gets a box, ticked, to open Flotilla at login so its admin can reach it after a restart.

You can change the role later in Settings ▸ Hosts and Fleet. If your organisation's profile sets it, the step says so instead of asking. See Hosts.

2. Make It Yours

Auto, Light or Dark, and the themes for light and dark. Auto is pre-selected: it follows macOS, with the light theme by day and the dark one after sunset if macOS switches. "Follow the system" is a choice rather than an absence of one, which is why it is asked. All of it is in Settings ▸ General too. See Settings.

3. Greta

Meet Greta, Flotilla's assistant. She runs on this Mac with Apple's on-device model and sends nothing away. She answers questions and drafts things, and she never runs anything. You review every draft.

The step says whether she is ready. If Apple Intelligence is off, or Apple's model is not ready, it says so and offers to open System Settings. The box to turn on Greta is ticked, and if she can't run yet it reads so she's ready when Apple's model is. Your organisation can lock it.

4. Prepare This Mac

What this Mac needs to run containers. Nothing here installs or asks for anything without a button.

On an admin, a checkbox, ticked, offers to download and install container 1.5.0 when you continue. It is Apple's installer, about 118 MB from Apple's releases on GitHub. Flotilla checks the package is Apple's, then Apple's Installer asks for your password. Flotilla never performs a privileged install silently. After that it offers the kernel containers run on. Flotilla asks for Local Network access when you first add a host, not before.

On a host, nobody may be at the keyboard, so there are three things:

• container. Flotilla installs it and its kernel itself once the Flotilla Helper is on.
• The Flotilla Helper. Its background service does the jobs that need administrator rights: DNS names across Macs, installing container, and installing Flotilla updates. macOS asks you to approve it once, in System Settings ▸ General ▸ Login Items & Extensions, or your organisation's profile does. See Flotilla Helper.
• Local Network. Needed so an admin Mac can find and manage the host. macOS asks once. Choose Request Access, then Allow. A configuration profile cannot grant this.

Not now is offered where the step is optional: installing container on an admin, the Helper on a host, and Greta when she can't run yet. There is never a global Skip. On a host, Not now on this step still saves the role, because a host that isn't listening isn't a host.

5. Online Checks

Flotilla reaches the internet by itself for two things, and nothing else. Each is a separate box, ticked, and each says exactly what it contacts.

• Check for Flotilla updates automatically. Reads the update feed at melonfleet.github.io once a day. An update you choose to install downloads from Flotilla's releases on github.com. The request names Flotilla's version and nothing about this Mac.
• Check daily for new suggestions. Fetches the suggestions library from raw.githubusercontent.com once a day. The request carries nothing about this Mac, and a library is used only if its signature verifies.

A host has no update check of its own, because its admin updates it. Your organisation can lock either box.

Finish

A summary of where this Mac stands: role, appearance, container, Greta, online checks, and on a host the Helper and Local Network. You can change any of it later in Settings. Overview then shows a Get started list for your role.

The preflight

Before it trusts any number, Flotilla checks container. It distinguishes the cases carefully, because "not installed" and "installed but not running" want completely different responses from you. Each gets a banner at the top of Overview and This Mac's page saying what is wrong, with the one button that fixes it, and the status bar's container dot says the same.

What it finds	The banner	The fix
No binary	container isn't installed	Download and Install container 1.5.0
Older than 1.0.0	container isn't installed, saying which version is too old	the same download
Service stopped	The container runtime isn't running	Start
Upgraded, but the service is still the old build	The container runtime is not available, naming both builds	Restart Container System in the status bar's container menu
No kernel	No kernel is installed	Download Kernel
Anything else	The container runtime is not available, with the reason	Retry

A stopped service, a missing kernel and a missing container are not faults, and are not dressed as them: amber, plain wording and a button, with the red triangle kept for states where something really is wrong. In those states every number below the banner is stale, which is why it sits above everything.

The oldest container Flotilla accepts is 1.0.0. Beta 5 is built and tested against 1.5.0, and a host older than that gets an Upgrade offer — see Updates.

Is the container CLI there?

Flotilla resolves the binary by looking along PATH and then in /usr/local/bin.

That second step is not redundant. A GUI-launched app does not inherit your shell's PATH. The environment LaunchServices hands a bundled app is exactly /usr/bin:/bin:/usr/sbin:/sbin — and container installs to /usr/local/bin, which is not in it. Early builds reported "the CLI isn't installed" on a machine where it was installed and running, and the bug was invisible during development because an app launched from a terminal inherits the terminal's rich PATH.

If the binary genuinely cannot be found, Flotilla says so and does not pretend to have an empty container list. The message names every directory it looked in:

Apple's container CLI wasn't found in: /usr/bin, /bin, /usr/sbin, /sbin, /usr/local/bin

A diagnosis you can check is worth more than a shorter one. Apple's releases are at apple/container if you would rather install by hand, and you can point Flotilla at the binary yourself — see Binary path in Settings.

Is the runtime service running?

container system status reports a stopped service by exiting non-zero while printing valid status JSON. Flotilla reads what the command printed rather than discarding it because the exit code was not zero, so it can tell "the service is stopped" apart from "something is actually wrong".

Starting the service is a normal, unprivileged operation. The service is always stopped after a Mac restarts, so by default Flotilla starts it once after this Mac starts up — and never again that boot, so a stop you made stays a stop. Settings ▸ Advanced ▸ Start container by itself also offers Ask and Never. Otherwise the banner's Start does it, with a spinner, because container system start takes several seconds.

Is it the build that is running?

Upgrading container without restarting its service leaves a skew that looks healthy: system status says running, and every container run fails with no available interface strategy for network default. Flotilla compares the CLI's build with the service's and names both — "upgraded to 1.5.0 but the running service is still 1.4.1" — because without them the symptom is inexplicable. One restart fixes it, and Restart Container System runs it without asking first: nothing useful is running in that state anyway.

Is there a kernel?

A fresh install looks running and cannot start anything until a kernel is downloaded. Flotilla checks for the file and offers Download Kernel — the one Apple's container recommends. The download reports in the banner, and a failure stays there beside Try Again, in the CLI's own words, because a failed download is most often the network.

What you see first

Flotilla opens on Overview, on an admin and on a host alike. The sidebar is one list in four blocks, and the blocks are the mental model:

  Overview           the fleet at a glance

  Containers         what containers are made of and run on
  Images
  Registries
  Volumes
  Networks
  DNS
  Machines
  Kubernetes

  Hosts              This Mac and every paired Mac

  Activity           what happened
  Logs

Settings is not in the sidebar: it is the gear at the right of the window bar, because the sidebar lists the things you manage, not the application's own preferences.

Machines are listed with containers but are not containers, and they are not where containers run either — each container gets its own VM. A machine is a persistent Linux VM you create and shell into, and you can ignore the section entirely. See Machines and containers for the measurement behind that.

Overview's Get started card offers the first things to do — run a container, pull an image, add a host, try a suggested stack. Close it with its X when you no longer need it. See Overview.

If the container list is empty

An empty list means empty, and Flotilla says which kind of empty it is: no containers exist, or none match your current filter and search. Those are different, and an app that draws the same blank pane for both makes you doubt the filter you just set.