feat(cli): keep lerd daemon alive so macOS can gracefully stop Podman

[retr0ripper]

lerd starts the Podman Machine and containers at macOS login through lerd-autostart, but the lerd start process exits as soon as startup finishes, leaving the VM running without a process that launchd can signal when macOS shuts down. The result is that the Podman Machine can be killed abruptly, and lerd-postgres-timescaledb sees an unclean PostgreSQL shutdown and spends several minutes in crash recovery and fsyncing data on the next boot.

It should run a long-lived lerd daemon instead. The daemon starts the same environment as lerd start, then stays alive waiting for SIGTERM or SIGINT. When the service manager asks it to stop, it runs the normal lerd stop flow and waits for that shutdown to finish before exiting, giving the containers and Podman Machine a chance to shut down cleanly. The daemon should reuse the existing start and stop implementation rather than spawning lerd start and lerd stop as child commands, so there is one lifecycle implementation and no recursive service behavior.

The autostart service should invoke lerd daemon instead of lerd start, with Restart=on-failure so an unexpected daemon failure is still recovered by the service manager. The command itself is an internal implementation detail, so it should be registered as hidden and not become another user-facing command in the normal lerd --help output.

The shutdown path needs to wait for lerd stop to complete before the daemon exits. Receiving SIGTERM, starting the stop operation and immediately exiting would leave the VM exposed to the same abrupt termination this change is intended to fix. The handler should also tolerate an already-stopped or partially stopped environment and avoid running shutdown concurrently if multiple signals arrive.

The existing lerd start and lerd stop commands keep their current behavior. Only the macOS autostart lifecycle changes from a fire-and-forget start process to a supervised daemon, so manually starting and stopping Lerd does not acquire a persistent background process.

The main files are internal/cli/daemon.go for the new hidden command, the command registration in cmd/lerd/main.go (or the existing command registry), and internal/systemd/units/lerd-autostart.service for the service change from lerd start to lerd daemon.

Verification should include running the daemon directly and confirming it remains alive after startup, sending it SIGTERM and checking that the normal stop sequence completes before it exits, then rebooting macOS through the actual autostart service. After the reboot, lerd-postgres-timescaledb should come up without the multi-minute PostgreSQL crash-recovery/fsync phase. Repeated reboot/shutdown cycles should produce the same clean result.

[retr0ripper]

@geodro , could you review the approach in this issue? The main idea is to keep lerd alive as a lightweight daemon under launchd, so it can receive SIGTERM during macOS shutdown and run the existing lerd stop flow before the Podman Machine is terminated.

I’m leaning toward reusing the existing internal start/stop logic rather than spawning lerd start / lerd stop as child commands. The main thing I’d like your feedback on is whether this fits cleanly with the current service lifecycle and whether there are any concerns around signal handling, shutdown ordering, or Restart=on-failure.

[geodro]

Hey @retr0ripper thanks for this. We have lerd watcher that is always on, can we use that?

[retr0ripper]

Yeah that works, went with the watcher. It is already always on under launchd with RunAtLoad so it gets the SIGTERM at logout for free, which means no new daemon and no new command, and lerd-autostart.service stays on lerd start. It also covers starting lerd by hand with autostart off, which a daemon wired only into autostart would have missed.

The start and stop logic still moved into internal/lifecycle, so the watcher and the CLI share one implementation instead of shelling out to lerd stop.

On the signal handling and ordering questions, two things only showed up on a real machine. launchd gives these jobs five seconds before SIGKILL, nowhere near enough for the teardown, so the watcher plist gets a sixty second ExitTimeOut and nothing else does. And a bare SIGTERM cannot tell a logout from lerd install restarting the watcher, so that tore the whole environment down mid install until every path that stops the watcher started marking it first. Ordering is containers, then the Podman Machine, then the remaining host units, and the watcher never stops its own unit because booting out the job you are running inside blocks until you exit.

Restart=on-failure did not end up mattering, the watcher plist already has KeepAlive with SuccessfulExit false, so a clean exit at logout does not respawn it.