Flotilla Helper

Flotilla Helper

The Flotilla Helper is Flotilla's one background service that runs as root, for the few jobs macOS lets only an administrator do. It is optional on the Mac you sit at, where those jobs can ask for your password instead. On a host, where nobody is there to type a password, it is what makes those jobs possible at all.

What it does — the whole list

1. Create and delete container's local DNS domains, which writes /etc/resolver. See DNS.
2. Keep the fleet's resolver files — one /etc/resolver/flotilla.<zone> file for each other Mac's zone, for names across Macs — and remove them all when that is turned off.
3. Install Apple's container package on a host.
4. Install a Flotilla update over a copy of Flotilla that is owned by root, as a package installs it. See Updates.

Nothing else. It does not run commands you type, and it cannot be asked to.

Why it is safe to approve

Typed requests, never a command line. The app says "create test" or "install this package as version 1.5.0"; the Helper builds the command itself and checks it with the same allowlist the app uses. So even a caller that somehow got past the signature check could not choose what runs.

It checks everything again, as root. The app is the caller, not the authority:

• Only Flotilla may connect, signed with an Apple Developer ID from the same team as the Helper. Each side checks the other. Nothing is hard-coded, and an ad-hoc development build can never pass — it has no team to match.
• DNS names are checked, and .local and other reserved names are refused. It runs only /usr/local/bin/container, and only while that file and its folder are owned by root and writable by no one else.
• Resolver files are the only files it writes itself. Each is named flotilla.<zone>, holds four fixed lines pointing at Flotilla on 127.0.0.1, port 7869, and is for a zone under a private fleet domain — .internal, .test or .home.arpa. It reads, writes or removes nothing not named flotilla.. So it can never redirect a real website.
• A container package must be Apple's: signed by Apple's Containerization team, notarised, exactly the version Flotilla asked for, and never older than what is installed. The Helper copies the file into a folder only root can write, and checks and installs that copy, so swapping the file after the check changes nothing.
• A Flotilla update must be Flotilla, signed by the Helper's own team with every binary inside it valid, and a newer build. It replaces only the app the Helper itself lives in — the destination is never given to it.

It runs tools directly, never through a shell, and one request at a time.

One helper, not several. Each job could have had a daemon of its own, but each would still be root, each would need its own approval in Login Items, and each would be one more connection to secure. The limit that matters is the short, typed list above, not the number of daemons.

Turning it on

The Helper is a background service. A signed copy of Flotilla registers it by itself at launch, so there is nothing to install. macOS then asks you to approve it once, in System Settings ▸ General ▸ Login Items & Extensions, where you switch Flotilla on. Approval happens in System Settings, which tells Flotilla nothing, so the status is read again whenever you come back to Flotilla.

Remove it and Flotilla leaves it removed. It does not register again until you press Install. An unsigned copy of Flotilla, such as a development build, never registers it.

Its state

The Helper item in the status bar shows the real state with a dot. Click it for the state and the buttons. The same state, with the same buttons, is in Settings ▸ Advanced ▸ Flotilla Helper.

State	What it means	Buttons
Not installed	DNS changes on this Mac ask for an administrator password. A host cannot do the Helper's jobs.	Install
Needs your approval	Registered, but macOS runs nothing as root until you switch it on.	Open Login Items…, Remove
Checking…	Asking the Helper for its version.	—
Approved but not answering	macOS has it switched on, but it is not replying.	Restart, Reinstall, Remove
Out of date	The running copy is older than this Flotilla needs.	Restart, Remove
Running (version N)	Working. DNS changes no longer ask for a password; Flotilla asks you to confirm each one instead.	Restart, Remove
Not available in this build	Only a Developer ID signed copy of Flotilla can use the Helper. The item is hidden.	—

Restart starts a fresh copy. Reinstall removes the registration and makes it again, and macOS may ask you to approve it again. Remove unregisters it, and DNS changes go back to the password prompt.

On a host, its owner approves it there, once. After that the admin can make DNS changes and container installs on that host, and the host's Install and upgrade container by itself setting can do its work. An admin trying to change a host whose Helper is off is told why — not installed, waiting for approval, or an unsigned copy — rather than shown a password prompt nobody is there to answer.

Without anyone at the keyboard

A configuration profile can pre-approve the Helper through managed Login Items, using its label dev.melonfleet.Flotilla.helper, and turn automatic setup on. A newly installed host then needs no clicks for the Helper. It still needs one click on macOS's local network prompt, which no profile can grant.

Approval is not permission for everything

Approving the Helper once does not mean Flotilla stops asking:

• On This Mac, every DNS change it makes is confirmed in Flotilla first, since there is no password prompt to serve as the confirmation.
• On a host, a DNS change or a container upgrade is confirmed on the admin, with what it will stop.
• Automatic work on a host — installing container, or upgrading it with nothing running — happens only when that host's owner, or a profile, has turned Install and upgrade container by itself on.

After an update

A running Helper keeps the binary it started with. When Flotilla is updated, the Helper notices the app it lives in has changed and quits once it is idle; macOS starts the new copy on the next request. Before every request Flotilla first asks the Helper's version, which is harmless to repeat, and if it cannot confirm a current Helper it does not send the request at all, so nothing is ever done twice.

If an early build installed the Helper under its old, DNS-only name, …dns-helper, Flotilla moves it to the new name once, keeping your approval.