feat(daemon): make --daemon boot-persistent by default (#2)

`--daemon` now installs a per-user autostart so the supervisor restarts
on login / system boot:

- macOS: LaunchAgent at ~/Library/LaunchAgents/com.lightning-mlx.<id>.plist
  (RunAtLoad=true, KeepAlive=true), loaded via `launchctl load -w`.
- Linux: user unit at ~/.config/systemd/user/lightning-mlx-<id>.service
  (Restart=always), enabled via `systemctl --user enable --now`.

Opt-out with `--daemon=non-persist` (or `=ephemeral`) to keep the original
in-session detached behavior.

`lightning-mlx kill` uninstalls the plist/unit before signaling so launchd
or systemd cannot restart the supervisor we are killing. Install failures
unlink the on-disk record and surface a clean DaemonError instead of a
traceback. `list_daemons()` shows persistent daemons whose supervisor pid
is not yet live as `pending` rather than `stale`.

Tests:
- tests/test_persistence.py (7): plist/unit content, install + uninstall
  on darwin/linux, idempotent uninstall, unsupported-platform error.
- tests/test_daemon.py: added persistent vs non-persist start paths,
  install-failure record cleanup, stop-uninstall ordering, list-pending
  for persistent dead-pid, CLI dispatch for `--daemon=non-persist`.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: samuelfaj

README.md

@@ -127,6 +127,10 @@ lightning-mlx serve mlx-community/Qwen3.5-4B-MLX-4bit --daemon
 
 Daemon mode starts a detached supervisor, writes logs under `~/.lightning-mlx/logs/`, and restarts the server if the model process exits unexpectedly.
 
+By default the daemon is **boot-persistent**: lightning-mlx installs a per-user autostart (a `~/Library/LaunchAgents/com.lightning-mlx.<id>.plist` on macOS, or a `~/.config/systemd/user/lightning-mlx-<id>.service` on Linux) so the supervisor restarts at login / system boot. `lightning-mlx kill` removes the autostart and stops the daemon. Use `--daemon=non-persist` to keep the original in-session detached behavior (process dies on reboot).
+
+On Linux, run `loginctl enable-linger $USER` once if you want user services to keep running after logout.
+
 ```bash
 lightning-mlx status
 lightning-mlx tui <PID-or-model-name>

tests/test_daemon.py

@@ -79,18 +79,29 @@ def fake_popen(cmd, **kwargs):
         port=8000,
     )
 
+    # Use non-persist to exercise the in-process Popen path; persistent mode is
+    # covered by a dedicated test that mocks install_autostart.
+    args.daemon = "non-persist"
     record = daemon.start_daemon(
         args,
-        ["serve", "mlx-community/Qwen3.5-4B-MLX-4bit", "--daemon", "--port", "8000"],
+        [
+            "serve",
+            "mlx-community/Qwen3.5-4B-MLX-4bit",
+            "--daemon=non-persist",
+            "--port",
+            "8000",
+        ],
     )
 
     assert record["supervisor_pid"] == 4321
     assert record["base_url"] == "http://127.0.0.1:8000"
     assert "--daemon" not in record["command"]
-    assert record["command"][-3:] == [
+    assert all(not c.startswith("--daemon=") for c in record["command"])
+    assert record["command"][-4:] == [
         "mlx-community/Qwen3.5-4B-MLX-4bit",
         "--port",
         "8000",
+        "--force",
     ]
     assert started["cmd"][:3] == [daemon.sys.executable, "-m", "vllm_mlx.daemon"]
     assert started["kwargs"]["start_new_session"] is True
@@ -157,6 +168,137 @@ def test_list_daemons_marks_dead_records_stale(daemon_dirs, monkeypatch):
     assert daemon._read_json(path)["state"] == "stale"
 
 
+def test_list_daemons_keeps_persistent_dead_as_pending(daemon_dirs, monkeypatch):
+    record = _record("one", supervisor_pid=100)
+    record["persistent"] = True
+    path = _write_record(record)
+    monkeypatch.setattr(daemon, "_pid_alive", lambda pid: False)
+
+    matches = daemon.list_daemons()
+    assert len(matches) == 1
+    assert matches[0].record["state"] == "pending"
+    assert daemon._read_json(path)["state"] == "pending"
+
+
+def test_start_daemon_persistent_installs_autostart_and_skips_popen(daemon_dirs, monkeypatch):
+    installed = {}
+    popen_calls = []
+
+    def fake_install(record):
+        installed["record"] = record
+
+    def fake_popen(*args, **kwargs):
+        popen_calls.append(args)
+        raise AssertionError("Popen must not be called for persistent daemons")
+
+    monkeypatch.setattr(daemon, "install_autostart", fake_install)
+    monkeypatch.setattr(daemon.subprocess, "Popen", fake_popen)
+
+    args = Namespace(
+        model="mlx-community/Qwen3.5-4B-MLX-4bit",
+        _original_alias=None,
+        served_model_name=None,
+        host="127.0.0.1",
+        port=8000,
+        daemon="persist",
+    )
+    record = daemon.start_daemon(
+        args,
+        ["serve", "mlx-community/Qwen3.5-4B-MLX-4bit", "--daemon"],
+    )
+
+    assert record["persistent"] is True
+    assert installed["record"]["id"] == record["id"]
+    assert popen_calls == []
+    assert record["supervisor_pid"] is None
+
+
+def test_start_daemon_non_persist_uses_popen_and_skips_install(daemon_dirs, monkeypatch):
+    install_calls = []
+
+    class FakePopen:
+        def __init__(self, cmd, **kwargs):
+            self.pid = 9999
+
+    def fake_popen(cmd, **kwargs):
+        return FakePopen(cmd, **kwargs)
+
+    monkeypatch.setattr(daemon, "install_autostart", lambda r: install_calls.append(r))
+    monkeypatch.setattr(daemon.subprocess, "Popen", fake_popen)
+
+    args = Namespace(
+        model="mlx-community/Qwen3.5-4B-MLX-4bit",
+        _original_alias=None,
+        served_model_name=None,
+        host="127.0.0.1",
+        port=8000,
+        daemon="non-persist",
+    )
+    record = daemon.start_daemon(
+        args,
+        ["serve", "mlx-community/Qwen3.5-4B-MLX-4bit", "--daemon=non-persist"],
+    )
+
+    assert record["persistent"] is False
+    assert record["supervisor_pid"] == 9999
+    assert install_calls == []
+
+
+def test_start_daemon_persistent_install_failure_removes_record_and_raises(daemon_dirs, monkeypatch):
+    def fake_install(record):
+        raise daemon.PersistenceError("launchctl not found")
+
+    def fail_popen(*args, **kwargs):
+        raise AssertionError("Popen must not be called when install fails")
+
+    monkeypatch.setattr(daemon, "install_autostart", fake_install)
+    monkeypatch.setattr(daemon.subprocess, "Popen", fail_popen)
+
+    args = Namespace(
+        model="mlx-community/Qwen3.5-4B-MLX-4bit",
+        _original_alias=None,
+        served_model_name=None,
+        host="127.0.0.1",
+        port=8000,
+        daemon="persist",
+    )
+
+    with pytest.raises(daemon.DaemonError, match="Failed to install autostart"):
+        daemon.start_daemon(
+            args,
+            ["serve", "mlx-community/Qwen3.5-4B-MLX-4bit", "--daemon"],
+        )
+
+    # No orphan record files left behind.
+    assert list(daemon.DAEMON_DIR.glob("*.json")) == []
+
+
+def test_stop_daemon_uninstalls_autostart_before_killing(daemon_dirs, tmp_path, monkeypatch):
+    alive = {100}
+    stop_path = tmp_path / "daemon.stop"
+    record = _record("one", supervisor_pid=100)
+    record["stop_path"] = str(stop_path)
+    record["persistent"] = True
+    _write_record(record)
+
+    order = []
+    monkeypatch.setattr(daemon, "_pid_alive", lambda pid: int(pid or 0) in alive)
+    monkeypatch.setattr(daemon, "uninstall_autostart", lambda did: order.append(("uninstall", did)))
+
+    def fake_signal(pid, sig):
+        order.append(("signal", int(pid)))
+        alive.discard(int(pid))
+        return True
+
+    monkeypatch.setattr(daemon, "_signal_pid", fake_signal)
+
+    daemon.stop_daemon("100")
+
+    # Uninstall must happen before any signal so launchd/systemd cannot restart.
+    assert order[0] == ("uninstall", "one")
+    assert ("signal", 100) in order
+
+
 def test_supervisor_restarts_failed_child_until_stop_marker(daemon_dirs, tmp_path, monkeypatch):
     record = _record("one", supervisor_pid=0)
     record["log_path"] = str(tmp_path / "daemon.log")
@@ -204,6 +346,7 @@ def fake_start_daemon(args, raw_args):
             "supervisor_pid": 1234,
             "base_url": "http://127.0.0.1:8000",
             "log_path": "/tmp/lightning.log",
+            "persistent": True,
         }
 
     monkeypatch.setattr(daemon, "start_daemon", fake_start_daemon)
@@ -221,11 +364,46 @@ def fake_start_daemon(args, raw_args):
     cli.main()
 
     out = capsys.readouterr().out
-    assert captured["args"].daemon is True
+    assert captured["args"].daemon  # truthy = enabled
     assert captured["raw_args"][-1] == "--daemon"
     assert "Started daemon mlx-community/Qwen3.5-4B-MLX-4bit (pid 1234)." in out
 
 
+def test_cli_serve_daemon_non_persist_dispatches(monkeypatch):
+    from vllm_mlx import cli
+
+    captured = {}
+
+    def fake_start_daemon(args, raw_args):
+        captured["args"] = args
+        captured["raw_args"] = raw_args
+        return {
+            "model": args.model,
+            "original_alias": None,
+            "supervisor_pid": 1234,
+            "base_url": "http://127.0.0.1:8000",
+            "log_path": "/tmp/lightning.log",
+            "persistent": False,
+        }
+
+    monkeypatch.setattr(daemon, "start_daemon", fake_start_daemon)
+    monkeypatch.setattr(
+        cli.sys,
+        "argv",
+        [
+            "lightning-mlx",
+            "serve",
+            "mlx-community/Qwen3.5-4B-MLX-4bit",
+            "--daemon=non-persist",
+        ],
+    )
+
+    cli.main()
+
+    assert captured["args"].daemon == "non-persist"
+    assert "--daemon=non-persist" in captured["raw_args"]
+
+
 def test_cli_dispatches_status_kill_and_tui(monkeypatch):
     from vllm_mlx import cli
 

tests/test_persistence.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for boot-persistent daemon autostart (launchd + systemd --user)."""
+
+from __future__ import annotations
+
+import plistlib
+import sys
+from pathlib import Path
+
+import pytest
+
+from vllm_mlx import persistence
+
+
+@pytest.fixture()
+def darwin_layout(tmp_path, monkeypatch):
+    monkeypatch.setattr(persistence, "PLATFORM", "darwin")
+    monkeypatch.setattr(persistence, "LAUNCHAGENTS_DIR", tmp_path / "LaunchAgents")
+    monkeypatch.setattr(persistence, "SYSTEMD_USER_DIR", tmp_path / "systemd_user_unused")
+    return tmp_path
+
+
+@pytest.fixture()
+def linux_layout(tmp_path, monkeypatch):
+    monkeypatch.setattr(persistence, "PLATFORM", "linux")
+    monkeypatch.setattr(persistence, "LAUNCHAGENTS_DIR", tmp_path / "LaunchAgents_unused")
+    monkeypatch.setattr(persistence, "SYSTEMD_USER_DIR", tmp_path / "systemd_user")
+    return tmp_path
+
+
+def _record(daemon_id: str = "abc123", record_path: str = "/tmp/r.json") -> dict:
+    return {
+        "id": daemon_id,
+        "model": "mlx-community/Qwen3.5-4B-MLX-4bit",
+        "record_path": record_path,
+        "log_path": "/tmp/abc123.log",
+    }
+
+
+def test_label_for_id_is_stable():
+    assert persistence.service_label("abc123") == "com.lightning-mlx.abc123"
+
+
+def test_install_darwin_writes_plist_and_loads_it(darwin_layout, monkeypatch):
+    calls = []
+
+    def fake_run(cmd, check=False, **kwargs):
+        calls.append(cmd)
+
+        class R:
+            returncode = 0
+
+        return R()
+
+    monkeypatch.setattr(persistence.subprocess, "run", fake_run)
+
+    record = _record(record_path="/tmp/abc.json")
+    persistence.install_autostart(record)
+
+    plist_path = darwin_layout / "LaunchAgents" / "com.lightning-mlx.abc123.plist"
+    assert plist_path.exists()
+    data = plistlib.loads(plist_path.read_bytes())
+    assert data["Label"] == "com.lightning-mlx.abc123"
+    assert data["RunAtLoad"] is True
+    assert data["KeepAlive"] is True
+    assert data["ProgramArguments"][:3] == [sys.executable, "-m", "vllm_mlx.daemon"]
+    assert data["ProgramArguments"][-2:] == ["supervise", "/tmp/abc.json"]
+
+    assert any(cmd[:2] == ["launchctl", "load"] for cmd in calls)
+    assert any(str(plist_path) in cmd for cmd in calls)
+
+
+def test_uninstall_darwin_unloads_and_removes_plist(darwin_layout, monkeypatch):
+    plist_path = darwin_layout / "LaunchAgents" / "com.lightning-mlx.abc123.plist"
+    plist_path.parent.mkdir(parents=True, exist_ok=True)
+    plist_path.write_bytes(b"<plist/>")
+
+    calls = []
+
+    def fake_run(cmd, check=False, **kwargs):
+        calls.append(cmd)
+
+        class R:
+            returncode = 0
+
+        return R()
+
+    monkeypatch.setattr(persistence.subprocess, "run", fake_run)
+
+    persistence.uninstall_autostart("abc123")
+
+    assert not plist_path.exists()
+    assert any(cmd[:2] == ["launchctl", "unload"] for cmd in calls)
+
+
+def test_uninstall_darwin_is_idempotent_when_plist_missing(darwin_layout, monkeypatch):
+    monkeypatch.setattr(persistence.subprocess, "run", lambda *a, **k: None)
+    persistence.uninstall_autostart("does-not-exist")
+
+
+def test_install_linux_writes_unit_and_enables_it(linux_layout, monkeypatch):
+    calls = []
+
+    def fake_run(cmd, check=False, **kwargs):
+        calls.append(cmd)
+
+        class R:
+            returncode = 0
+
+        return R()
+
+    monkeypatch.setattr(persistence.subprocess, "run", fake_run)
+
+    record = _record(record_path="/tmp/abc.json")
+    persistence.install_autostart(record)
+
+    unit_path = linux_layout / "systemd_user" / "lightning-mlx-abc123.service"
+    assert unit_path.exists()
+    text = unit_path.read_text(encoding="utf-8")
+    assert "[Service]" in text
+    assert f"{sys.executable} -m vllm_mlx.daemon supervise /tmp/abc.json" in text
+    assert "Restart=always" in text
+    assert "WantedBy=default.target" in text
+
+    cmds = [tuple(c) for c in calls]
+    assert ("systemctl", "--user", "daemon-reload") in cmds
+    assert ("systemctl", "--user", "enable", "--now", "lightning-mlx-abc123.service") in cmds
+
+
+def test_install_on_unsupported_platform_raises(tmp_path, monkeypatch):
+    monkeypatch.setattr(persistence, "PLATFORM", "win32")
+    with pytest.raises(persistence.PersistenceError, match="not supported"):
+        persistence.install_autostart(_record())
+
+
+def test_uninstall_linux_disables_and_removes_unit(linux_layout, monkeypatch):
+    unit_path = linux_layout / "systemd_user" / "lightning-mlx-abc123.service"
+    unit_path.parent.mkdir(parents=True, exist_ok=True)
+    unit_path.write_text("stub", encoding="utf-8")
+
+    calls = []
+
+    def fake_run(cmd, check=False, **kwargs):
+        calls.append(tuple(cmd))
+
+        class R:
+            returncode = 0
+
+        return R()
+
+    monkeypatch.setattr(persistence.subprocess, "run", fake_run)
+
+    persistence.uninstall_autostart("abc123")
+
+    assert not unit_path.exists()
+    assert ("systemctl", "--user", "disable", "--now", "lightning-mlx-abc123.service") in calls
+    assert ("systemctl", "--user", "daemon-reload") in calls