Containers

Containers

Containers is a list of rows on the left and the selected container's page on the right. There is no table and no Cards. See Views and filtering for rows and the split view.

Once you have paired a host, the list is the fleet's: This Mac's containers and every paired host's, in one list, with the host as a chip on each row that is not This Mac's. The Host filter narrows it to one Mac. Groups are rows in the same list — see Groups below.

The toolbar

Every section shares the same toolbar shape and the same control order, so nothing moves as you change section. The split view, the filter, sorting, multi-select and bulk actions are all covered in Views and filtering. Search is the box in the window bar.

The filter here asks two independent questions — State, and Show: Groups and containers, Groups only or Containers only — plus Host once a host is paired. The search box takes is:running, image:, host: and tag: as well as plain words.

The + menu has Run Container…, New Group… and Suggestions…, which opens the Suggestions section. The same three are in the File menu, and the search box (⌘K) reaches them too.

Running a container

Run Container… opens an embedded form with a live command preview, validated by the same allowlist call that will run it, so the preview cannot show a command as accepted that container would then refuse.

• Run on — which Mac, once a host is paired. On another Mac, host folders cannot be mounted: only named volumes. The preview is checked against that host's rules, not This Mac's.
• Image reference, Name.
• Ports — a bare port is refused, because the CLI needs both halves. Without a host IP the port is reachable from your whole network, not just this Mac, and the form says so.
• Network — chosen now, because neither the CLI nor Flotilla can move a container onto a network after it exists. Without a DNS domain, names do not resolve between containers; see DNS.
• Environment variables — KEY=VALUE. The CLI also accepts a bare KEY to inherit that variable from this Mac; Flotilla refuses it, because it exports your shell environment into the container without saying which values went.
• Volumes — a named volume, or an absolute path on this Mac. The destination cannot be /.
• Command — left empty, the image runs its own entrypoint.
• Detach, Architecture, Rosetta inside the container, and Limit CPU and memory. Defaults come from Settings ▸ Resources.
• Restart and health — whether Flotilla starts the container again if it stops, and how it checks the container is working. It needs the container to have a name. See below.

Architecture is Automatic, arm64 or amd64. Automatic runs the arm64 build on Apple silicon; amd64 runs the Intel build under Rosetta. An image with only one build ignores the choice.

Rosetta inside the container is a different thing, and it is easy to confuse the two. It lets an arm64 container run Intel (x86-64) programs as well. It is not needed to run an amd64 image, and it needs Rosetta installed on the Mac the container runs on.

Row actions

While the pointer is over a row, or the row is selected, it shows Start or Stop — a group shows Stop while anything in it runs — and ⋮. Restart, Tags and Delete are in ⋮, in the right-click menu and in the page's header. They are the same menu.

Bulk deletion always asks and cannot be turned off. Single-item deletion asks only when Confirm destructive actions is on in Settings — turn it off and a single Delete goes straight through.

That rule lives in one place — DeletePolicy in the core, which is tested — rather than being reimplemented per screen. The reason is instructive: there used to be five private copies of the confirmation logic, and collapsing them into one exposed a context menu that deleted with no confirmation at all, two lines away from a button that always asked.

On a host

A paired host's container has the same lifecycle — Start, Stop, Restart, Force Kill, Delete… — plus tags and Copy, which adds the Host. Each is a bounded request over the fleet connection, checked by the host's own allowlist; none of them opens a shell there.

Items that open This Mac's own tools are not offered for a host's container: Terminal, Files and Run Again with Changes….

Container detail

Click a row. Its page opens in the right-hand pane, with ↑ ↓ buttons to step through the containers as currently filtered and sorted, and an expand button for more width.

Tabs: Overview · Processes · Logs · Inspect, then Terminal · Files after a divider.

Every page puts its tabs in the same order, so moving between a container and a machine does not move the tabs under you. The ways in — Terminal, Files — come after the divider. The tab you were on stays as you step from one container to the next.

• Overview — state, image, published ports, addresses, uptime, and the Restart and health card. Ports offer Copy as the primary action; see Views and filtering for why Open in browser is not.
• Processes — what is running inside.
• Logs — this container's output. The combined feed is in the sidebar's Logs section.
• Inspect — the full inspect payload, as a table or as JSON.
• Terminal — a real shell. See Terminal.
• Files — browse the filesystem, copy files in and out. See Files.

A host's container has Overview, Logs, Inspect and Processes only.

What you cannot edit, and why

A container has no editable settings. This is not an omission — container has no update subcommand, so there is nothing Flotilla could call. Rather than offer a settings screen that could never save, the overflow menu has Run Again with Changes…, which opens a prefilled create form. It does not delete the original; that stays a separate, confirmed decision.

That prefill does not carry environment variables or volume mounts, and the sheet says so. inspect returns the image's own environment mixed with what you set, with nothing distinguishing them — so carrying them over would silently reapply the image's defaults as if you had chosen them. Mounts are not modelled in what the runtime reports, and guessing would be inventing data.

The name gets a suffix, because the original still exists and container run --name web fails while web is there. A host port that something else already holds — almost always the original, still running — is dropped rather than prefilled, and the sheet names it. Copying 8080:80 verbatim produced a container that could not bind and stopped at once.

The overflow menu

Details…, then straight to Logs, Terminal (when it is running) or Inspect. Then the whole lifecycle — Start, Stop, Restart and Force Kill — always in that order, with the ones that do not apply greyed out rather than missing, so the item under the pointer does not depend on the row you opened. Force Kill is for the container that ignores its stop signal; the only alternative used to be deleting it.

Then Run Again with Changes…, Tags, and a Copy submenu with Name, Image, Ports, IP / Network and Port URL — the last a http://localhost: address you can paste into a browser, left out when nothing is published. Then Delete.

The Inspect tab has its own Copy JSON — the payload with secrets redacted — plus Reload, a Table / JSON toggle and a Filter keys field. Redaction there is narrower than in a support bundle: image digests and mount paths stay, because they are what you inspect for, while tokens, certificates, URL credentials and KEY=value secrets still go.

The Logs tab's own controls

Separate from the sidebar's combined feed. Left to right: Copy and Save…, then Reload and Live, then an Options button holding Boot Log and Timestamps, then the search field. Every button is an icon with its name in the tooltip, and the Inspect tab beside it is laid out the same way.

Lines always wrap, left-aligned, the way Console shows a log. There used to be a Wrap checkbox; with it off the text was centred and looked shrunken, which is not something anyone wanted, so the option went rather than being repaired.

Live is a real stream, not a faster refresh. Flotilla runs container logs --follow and appends each line as it is written, keeping the newest in view — the same thing Console does. Turn it off, leave the tab, or close the window and the stream stops with it. Only Live lines carry a true timestamp: the ones fetched in a batch share the moment you fetched them, because container logs has no --timestamps of its own. A host's container streams too, through that host's own follow.

The machine Logs tab is this same screen. They used to be two, and the machine's had none of it.

Restart policy and health checks

container has neither a restart policy nor a health check, and it does not report a container's exit code. A container that exits with code 3 shows only stopped. So Flotilla runs both itself, and it is honest about what it cannot tell.

The Mac that runs the container runs its policy. A host keeps restarting and checking its containers while its admin is away.

Set a policy in the Run form's Restart and health field, or later on the container's Overview, in the Restart and health card, with Edit…. The card shows the policy, the latest health result and when it was checked, and the five latest things Flotilla did and why. Flotilla keeps the last 50.

Restart

• Never is the default. Flotilla leaves the container alone.
• If it stops unexpectedly restarts it whenever it stops, unless the stop was made in Flotilla. A stop you or an admin make in Flotilla is deliberate and is respected. Any other stop is restarted, including after the Mac or container comes back.

There is no on failure choice. With no exit code, there is nothing to judge failure by. A stop typed in Terminal looks the same as a crash, so it is restarted too. The editor says so.

Restarts wait 0, 10, 30, 60, 120, then 300 seconds. After five restarts in ten minutes, Flotilla stops trying and raises an error notice with Start as the fix. The card says it gave up. Start the container yourself to try again. A container that stays up for ten minutes resets the count.

Health checks

Turn on Check its health, then pick one kind:

• Port answers. A connection to one of the container's published ports is accepted.
• HTTP returns OK. A GET of a path on one of the container's published ports returns 2xx or 3xx. The path starts with /.
• Command succeeds. A command runs in the container and exits 0. It is a list of words, up to eight, and not a shell line. Write sh -c … yourself if you want a shell.

Port and HTTP checks connect to 127.0.0.1 on the Mac running the container, and only to a TCP port that container publishes. That is checked when you save, and again before every check, because a container's ports can change. A check can't be pointed at another address, or at another service on the Mac.

Each check has four settings:

Setting	Range	Default
Every	5 seconds to an hour	30 s
Timeout	1 to 60 seconds, shorter than the interval	5 s
Unhealthy after	1 to 10 failures in a row	3
Grace after start	0 to 600 seconds	30 s

A failure inside the grace period does not count, because the service may still be starting.

Unhealthy raises a warning notice with Restart as the fix. Flotilla does not restart the container for you unless you turn on Restart it when unhealthy. It is off by default. Those restarts count towards the same five in ten minutes.

When Flotilla is not in front, the notice also goes to Notification Centre. That is the category A container is unhealthy, on by default. See Notifications.

On a host

An admin can set a restart policy, and port and HTTP checks, on a host's containers. A command check can only be set on the Mac itself, by its owner. A command check runs in the container with the host's local-owner permissions, and Flotilla's connection never runs a command on another Mac. The host refuses one if it is sent, and re-checks at every run, so nothing stored earlier can get past.

The card shows the host's last report and says which Mac keeps the policy. A host on an older Flotilla says it needs a newer one. Health-check and restart-policy actions need beta 5 on the host.

Groups

A group is a saved, ordered set of containers that start and stop together. It shows in this list as one row with a half dot and "2 of 3 running", and its members below it. A member the group has not created yet says Not created; starting the group creates it.

The group's menu has Edit…, Start, Stop, Restart, Save to File…, and two ways to delete: Delete Group… forgets the group and leaves its containers, and Delete Group and Containers… removes both. Groups run on This Mac.

A group is a sequence, not an orchestrator: the group itself watches nothing and restarts nothing. Each member can have its own restart policy and health check, set on that container's page. See Groups and suggestions for how start order, readiness ports and passwords work.