Settings

Settings

Settings has a sidebar of sections, each with an icon tile: General · Appearance · Updates · Hosts and Fleet · Resources · Tags · Notifications · Greta, then Advanced and About below a line.

Settings is not a separate window. It opens inside the main window, from the gear at the right of the window bar or Flotilla ▸ Settings… (⌘,), so it works the same way after the window has been closed and reopened from the menu bar.

Flotilla's settings are a typed registry with three tiers of precedence:

locked  ▸  overrides everything and disables the control
user    ▸  what you chose
default ▸  the seed value, which an administrator may also supply

An administrator can ship sensible defaults you may still change, or lock a value so you cannot. A locked setting appears with a lock, its control disabled, and a note that your organisation manages it.

The rule this screen is held to

A control either works, or it is visibly disabled with the reason written in the row.

An independent audit once found 11 of 26 settings were read by nothing — they persisted, survived a relaunch, and changed nothing. That is worse than a missing feature, because it is a claim the feature exists. It is now enforced mechanically: Scripts/check-settings-consumers.sh fails the build if a setting marked available has no code reading it.

The Updates and Hosts and Fleet sections used to be rows of disabled controls saying "arrives in Phase 2". Both are live now, which is why they are documented below rather than listed as placeholders.

General

Setting	What it does
Launch at login	Registers Flotilla as a login item through SMAppService. Off by default. See Launch at login.
Show Dock icon	On by default. Off puts Flotilla in the menu bar only. Only two states, because macOS has only two activation policies that differ — an earlier version offered three and two of them did the same thing.
Confirm destructive actions	Governs single-item deletion of a container, image, volume, network or machine. Deleting several at once always asks, and this does not affect it.
Keep this Mac awake while containers run	Off by default. Holds off sleep while any container on this Mac is running, and never on battery.
Appearance	Auto, Light or Dark. First run asks for this; Auto follows macOS.
Light theme	Eight themes in two rows of four: Stripe, Flesh, Cantaloupe and Canary on cream, then the same four bars on the honeydew wash.
Dark theme	Four: Stripe, Flesh, Cantaloupe and Canary.
Refresh containers every	How often the container list and its state refresh. 5 seconds by default; 0 turns polling off.
Refresh stats every	CPU, memory and I/O sampling, on its own interval, 10 seconds by default — stats are more expensive than a list, so they are deliberately not tied together.

A theme changes two things only: the window bar and the content background. The honeydew row is light-only, and the dark list is a separate type rather than the same list with four options hidden — so a configuration profile cannot set a dark theme that has no dark form.

Notifications

The Notifications section has one switch per kind of notification. Errors is always on and its switch is locked. See Notifications for every category and what each one sends.

Resources

Defaults for new containers, so you are not retyping them in every run form.

Setting	What it does
CPUs	Default CPU allocation for a new container. 4 by default.
Memory	Default memory allocation. 1,024 MB by default.

The run form can override both for any one container.

Default registry used to live here. It is now set in the Registries section with Set as Default, beside the list of registries it can name — and it only completes bare names in Flotilla's own Pull form. It does not change what container does at the command line. See Registries.

Tags

Where you tidy up the tags you put on containers, machines, volumes, networks and hosts: New Tag…, rename and recolour a tag everywhere at once, see how many things it is on, and delete it. Deleting a tag asks first and says how many things it will come off; nothing else is deleted.

Tags are stored in Flotilla's own preferences on this Mac and never sent to the container runtime, so tagging something changes nothing about how it runs.

Deleting a container does not delete its tags. The runtime list comes from a poll that can fail, and a sweep on every refresh would throw your tags away the first time it did. Clean Up forgets tags on things that no longer exist, when you ask for it.

Hosts and Fleet

This section was called Host Mode.

Choose this Mac's role in Use this Mac as: Admin or Host. Both run their own containers — "host" only means another Mac may manage this one. The old combined role is retired; a stored or profile value of it is read as Admin. See Hosts for pairing.

The tab shows This Mac's fleet identity, and on a host:

Setting	Default	What it does
Port	7868	The port host mode listens on.
Let admin Macs on this network find it	On	Advertises the host over Bonjour. Adding a host by address works either way.
Keep this Mac awake for its admin	On	Holds off system sleep while host mode is on. The display can still sleep, and a laptop only on its power adapter.
Install and upgrade container by itself	On	Installs container and its kernel, and upgrades container when nothing is running. Needs the Flotilla Helper.
Install Flotilla updates from its admin	On	Only genuine, newer Flotilla is ever installed. See Updates.
Let its admin start and stop container	On	Off, the admin can see that container is stopped but cannot start it.

These switches are the host owner's. A paired admin cannot change them.

Below them: Show Code for pairing, the Admin Macs trusted by this Mac (with Remove and Allow Again), and the Fleet enrolment key — Create Key on an admin, or a pasted or profile-supplied key on a host. Replace… makes a new key; Macs given the old one can no longer ask to join, and Macs already enrolled stay.

The fleet DNS domain and names across Macs are set in DNS, not here.

Updates

On an admin Mac, the four Sparkle settings:

Setting	Default
Automatically check for updates	Asked once, then what you chose
Automatically download updates	Off
Check every	24 hours (at least one)
Update channel	Stable, or pre-releases too

These are handed to Sparkle only once you or a profile has set them. Flotilla promises no phone-home, and an automatic check reaches GitHub, so it is consent rather than a default: left alone, Sparkle asks once, on the second launch, whether to check by itself.

The Suggestions library group has Check for new suggestions daily, on by default, and says which library version you have. That daily check also fetches the vulnerability report. See Updates.

A host is updated by its admin and never checks for itself. Update Hosts Automatically, in the Hosts section's update menu, is on by default and rolls updates out one host at a time. See Updates.

Advanced

Setting	What it does
Binary path	Where Flotilla found the container binary, with an explanation of how it looked. Set it yourself when the automatic lookup picks something unexpected — see Troubleshooting.
Start container by itself	After this Mac starts up (the default), Ask or Never.
Flotilla Helper	Install, approve or remove the helper. See Flotilla Helper.
Lines requested when opening logs	How many lines are asked for per source. 200 by default.
Log buffer cap per container	How many are retained in memory. 5,000 by default.
Show timestamps	Timestamps in the log feed. On by default.
Keep a local error log	Whether Flotilla records its own errors on disk, for the support bundle. Off by default.
Error log cap	How much of it is kept. 500 entries by default.

"After this Mac starts up" means exactly that. The container service is always stopped after a restart, and starting it then is Flotilla's job. A stop made while the Mac was up — by you, with the CLI, with Flotilla's Stop, or by a crash — is left for a person. It used to be undone at the next launch, and an update from the admin relaunches Flotilla, so a service stopped on purpose came back by itself. The option was called "Always" until that was noticed; the new name says what it does.

Settings file

Export Settings… writes only what you have changed from the defaults, as JSON. Nothing secret and no host trust is ever included. Import Settings… applies what this version knows and says what it did not: values your organisation locks, keys it does not recognise, values it cannot use, and anything that is never imported from a file.

This is separate from a .flotilla configuration file, which describes what to build rather than how Flotilla behaves. See Sharing and export.

Reset

Three resets, each on its own, because someone whose window is stranded on a display they no longer have should be able to recover it without losing every preference — and neither should cost re-pairing a fleet.

Reset	What goes	What stays
Reset preferences	Every setting returns to its default, including your appearance choice, so Flotilla asks about it again at next launch.	Window layout, containers, images and volumes.
Forget all hosts and trust	Every Mac you have paired with, this Mac's own fleet identity, and your fleet enrolment key.	Containers, images, volumes, settings and window layout.
Reset window layout	The window's size and position and the sidebar width. Takes effect at next launch, because an open window saves its position again when it closes.	Every preference and all data.

Each confirmation names what it will do and what it will not touch, because not knowing where a reset stops is what stops people using it. None of them can delete a container, an image or a volume — those belong to the container runtime, not to Flotilla.

Forget all hosts and trust is for starting a fleet again from nothing, or for handing a Mac on. This Mac gets a new identity, so every Mac has to pair again from scratch, and each one's owner has to let this Mac back in: the old fingerprint they trusted no longer exists. Its button is disabled, not hidden, when there is nothing to forget, so it is somewhere you have seen before you need it. See Hosts.

Launch at login

Registered through SMAppService. The row shows the real registration status, including awaiting approval — macOS can put a login item in that state, and a plain on/off toggle would lie about it. When it is waiting, the row says to approve it in System Settings ▸ General ▸ Login Items.

This can be refused for an ad-hoc-signed build, which is what Scripts/make-app.sh produces. See Troubleshooting.

Greta

Turn on Greta switches Greta on or off, and Greta's look picks her face. See Greta.

Support bundle and About

The Diagnostics group in Advanced has Create… for the support bundle. The bundle is also in the Help menu. It shows every file before you save it, and nothing is uploaded. See Logs and diagnostics.

About

Settings ▸ About is where About Flotilla lives. Flotilla ▸ About Flotilla and the menu-bar item open it. It is a pane, not a window with a red dot, so it needs no button to close. It shows:

• The version, the build, and the container version it was tested with: for example "Version 1.5.0-beta.5 (build number) · Tested with container 1.5.0".
• Links to Flotilla on GitHub, the releases, Apple's container and melonfleet.dev.
• Network destinations: every place Flotilla can reach on the network, and when. That is Sparkle (on an admin Mac), the suggestions library and vulnerability reports, Docker Hub search (only when you open it), the registries container pulls from, speech recognition's one download from Apple (only when you click Download), and Macs you have paired. There is no analytics, no account and no licence check.
• What is stored locally, the licences, and the logos' notices.

Where settings live

One key per setting, in dev.melonfleet.Flotilla:

defaults read dev.melonfleet.Flotilla                       # every choice you have made
defaults write dev.melonfleet.Flotilla pollIntervalSeconds -int 15

A key that is absent means "not chosen", so that listing is a list of decisions rather than a dump of the whole registry. A key of the wrong type is ignored and its built-in default applies.

Settings used to be one JSON blob under a single userSettings key. It worked, and it was invisible to defaults, plutil and every script an admin already has — so an existing blob is moved to individual keys the first time a newer build starts, and then deleted.

Configuration profiles were never affected by that, either way. MDM does not write an app's own preference domain; it writes /Library/Managed Preferences/dev.melonfleet.Flotilla.plist as two dictionaries, defaults (seeded, user may change) and locked (enforced), and those outrank anything above. ManagedPayload in the source is the payload shape. A profile can, for example, lock mode to host on a rack of minis, or carry the fleet enrolment key so a host can ask to join with no one at its keyboard.

Flotilla reads the profile; it is not an MDM policy tool itself. Not yet: Jamf and MDM policy support beyond these keys is planned for 2.0.

A note on persistence

FlotillaCore is Foundation-only and deliberately cannot write to disk, so persistence lives in the app layer. An early version therefore retired an obsolete key correctly in memory and re-derived it on every launch, leaving it in UserDefaults indefinitely. The migration is now written at load. An in-memory migration is not a migration.