feat: add --run-as-service for background daemon mode

Adds a `service` module and wires `launcher.main()` to support running
Thoth detached from the terminal so closing the shell does not shut the
app down.

New flags:
  --run-as-service        POSIX double-fork; writes PID to
                          $THOTH_DATA_DIR/service.pid and redirects
                          stdout/stderr to $THOTH_DATA_DIR/service.log.
                          Forces --server --no-tray --no-open --no-splash.
  --service-stop          SIGTERM (then SIGKILL after 10s) the daemon.
  --service-status        Print running/stopped + PID.
  --service-restart       Stop existing daemon, then start a new one.
  --install-systemd-service
                          Write ~/.config/systemd/user/thoth.service
                          (Type=simple) for a cleaner long-term setup.
  --pid-file / --service-log
                          Override default paths.

Windows is not supported by --run-as-service; users get a message
pointing them to Task Scheduler / NSSM. The existing bin/thoth wrapper
already forwards extra args, so no installer change is needed.

Author: mforce

installer/thoth_setup.iss

@@ -69,6 +69,7 @@ Source: "..\voice.py";                 DestDir: "{app}\app"; Flags: ignoreversio
 Source: "..\tts.py";                   DestDir: "{app}\app"; Flags: ignoreversion
 Source: "..\vision.py";                DestDir: "{app}\app"; Flags: ignoreversion
 Source: "..\launcher.py";              DestDir: "{app}\app"; Flags: ignoreversion
+Source: "..\service.py";               DestDir: "{app}\app"; Flags: ignoreversion
 Source: "..\notifications.py";         DestDir: "{app}\app"; Flags: ignoreversion
 Source: "..\prompts.py";               DestDir: "{app}\app"; Flags: ignoreversion
 Source: "..\requirements.txt";         DestDir: "{app}\app"; Flags: ignoreversion

launcher.py

@@ -27,6 +27,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+import service
 from app_port import DEFAULT_APP_PORT, THOTH_HOST_ENV, THOTH_PORT_ENV, parse_app_port
 
 if TYPE_CHECKING:
@@ -1504,6 +1505,27 @@ def _build_arg_parser() -> argparse.ArgumentParser:
     parser.add_argument("--no-ollama", action="store_true", help="Do not try to auto-start Ollama")
     parser.add_argument("--port", type=int, default=_PORT, help=f"Preferred app port (default: {_PORT})")
     parser.add_argument("--host", default=None, help="Host/interface for the NiceGUI server")
+
+    svc = parser.add_argument_group("service mode (Linux/macOS)")
+    svc.add_argument(
+        "--run-as-service",
+        action="store_true",
+        help="Detach from the terminal and run Thoth in the background (writes PID and log files)",
+    )
+    svc.add_argument("--service-stop", action="store_true", help="Stop the running Thoth service")
+    svc.add_argument("--service-status", action="store_true", help="Print Thoth service status")
+    svc.add_argument(
+        "--service-restart",
+        action="store_true",
+        help="Stop the running Thoth service (if any) and start a new one as a daemon",
+    )
+    svc.add_argument(
+        "--install-systemd-service",
+        action="store_true",
+        help="Install a user-level systemd unit at ~/.config/systemd/user/thoth.service",
+    )
+    svc.add_argument("--pid-file", default=None, help="Override PID file path for service mode")
+    svc.add_argument("--service-log", default=None, help="Override log file path for service mode")
     return parser
 
 
@@ -1521,9 +1543,62 @@ def quit_for_update() -> None:
 
 # ── Main ─────────────────────────────────────────────────────────────────────
 
+def _resolve_service_paths(args: argparse.Namespace) -> tuple[Path, Path]:
+    pid_path = Path(args.pid_file) if args.pid_file else service.default_pid_path()
+    log_path = Path(args.service_log) if args.service_log else service.default_log_path()
+    return pid_path, log_path
+
+
+def _handle_service_management(args: argparse.Namespace) -> bool:
+    """Run a stop/status/install command if requested. Returns True if handled."""
+    pid_path, _log_path = _resolve_service_paths(args)
+
+    if args.service_status:
+        print(service.status_message(pid_path))
+        return True
+    if args.service_stop:
+        print(service.stop_service(pid_path))
+        return True
+    if args.install_systemd_service:
+        unit = service.install_systemd_unit()
+        print(f"Wrote {unit}")
+        print("Enable with:")
+        print("  systemctl --user daemon-reload")
+        print("  systemctl --user enable --now thoth.service")
+        print("View logs with: journalctl --user -u thoth.service -f")
+        return True
+    return False
+
+
+def _force_service_flags(args: argparse.Namespace) -> None:
+    """Apply the implicit options that ``--run-as-service`` requires."""
+    args.no_tray = True
+    args.no_open = True
+    args.no_splash = True
+    args.server = True
+
+
 def main(argv: list[str] | None = None) -> None:
     global _ACTIVE_TRAY
     args = _build_arg_parser().parse_args(argv)
+
+    if _handle_service_management(args):
+        return
+
+    if args.service_restart:
+        pid_path, _ = _resolve_service_paths(args)
+        print(service.stop_service(pid_path))
+        args.run_as_service = True
+
+    if args.run_as_service:
+        pid_path, log_path = _resolve_service_paths(args)
+        print(f"Starting Thoth as a service (logs: {log_path}). Stop with: thoth --service-stop")
+        sys.stdout.flush()
+        service.daemonize(pid_path, log_path)
+        _force_service_flags(args)
+        service.install_signal_handlers(lambda: service.remove_pid(pid_path))
+        atexit.register(service.remove_pid, pid_path)
+
     preferred_mode = "browser" if args.browser else "native" if args.native else None
     linux_default_direct = sys.platform.startswith("linux") and not args.tray
     direct = args.server or args.no_tray or linux_default_direct

service.py

@@ -0,0 +1,230 @@
+"""Background-service helpers for Thoth.
+
+Provides POSIX daemonization, PID-file management, status/stop helpers, and a
+generator for a user-level systemd unit. Used by ``launcher.py`` to implement
+``--run-as-service`` and the related management flags.
+
+Windows is intentionally not supported here; on Windows ``--run-as-service``
+prints guidance to use Task Scheduler or NSSM instead of attempting a fragile
+detach.
+"""
+
+from __future__ import annotations
+
+import errno
+import logging
+import os
+import signal
+import sys
+import time
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def _data_dir() -> Path:
+    return Path(os.environ.get("THOTH_DATA_DIR", Path.home() / ".thoth"))
+
+
+def default_pid_path() -> Path:
+    return _data_dir() / "service.pid"
+
+
+def default_log_path() -> Path:
+    return _data_dir() / "service.log"
+
+
+def read_pid(pid_path: Path) -> int | None:
+    try:
+        text = pid_path.read_text().strip()
+    except FileNotFoundError:
+        return None
+    except OSError:
+        return None
+    try:
+        return int(text)
+    except ValueError:
+        return None
+
+
+def is_alive(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # Process exists but is owned by someone else — treat as alive.
+        return True
+    return True
+
+
+def write_pid(pid_path: Path, pid: int) -> None:
+    pid_path.parent.mkdir(parents=True, exist_ok=True)
+    pid_path.write_text(f"{pid}\n", encoding="utf-8")
+
+
+def remove_pid(pid_path: Path) -> None:
+    try:
+        pid_path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def daemonize(pid_path: Path, log_path: Path) -> None:
+    """Detach from the controlling terminal using the standard double-fork.
+
+    On return, the calling process is the daemon child: it has no controlling
+    terminal, ``stdin`` is ``/dev/null``, and ``stdout``/``stderr`` are
+    appended to ``log_path``. The PID of the daemon is written to ``pid_path``.
+
+    Refuses to start a second daemon if ``pid_path`` already references a live
+    process; raises :class:`SystemExit` with a friendly message in that case.
+    """
+    if os.name != "posix":
+        raise SystemExit(
+            "--run-as-service is only supported on Linux/macOS. "
+            "On Windows, use Task Scheduler or NSSM to run thoth in the background."
+        )
+
+    existing = read_pid(pid_path)
+    if existing is not None and is_alive(existing):
+        raise SystemExit(f"Thoth service is already running (PID {existing}).")
+
+    pid_path.parent.mkdir(parents=True, exist_ok=True)
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # First fork — let the parent return so the shell prompt comes back.
+    if os.fork() > 0:
+        os._exit(0)
+
+    # New session, no controlling TTY.
+    os.setsid()
+
+    # Second fork — guarantees we cannot re-acquire a TTY.
+    if os.fork() > 0:
+        os._exit(0)
+
+    os.chdir("/")
+    os.umask(0o022)
+
+    # Redirect standard fds.
+    sys.stdout.flush()
+    sys.stderr.flush()
+
+    with open(os.devnull, "rb") as devnull_in:
+        os.dup2(devnull_in.fileno(), sys.stdin.fileno())
+
+    log_fd = os.open(
+        str(log_path),
+        os.O_WRONLY | os.O_CREAT | os.O_APPEND,
+        0o644,
+    )
+    os.dup2(log_fd, sys.stdout.fileno())
+    os.dup2(log_fd, sys.stderr.fileno())
+    os.close(log_fd)
+
+    write_pid(pid_path, os.getpid())
+
+
+def install_signal_handlers(on_term) -> None:
+    """Install SIGTERM/SIGINT handlers that delegate to ``on_term``.
+
+    ``on_term`` is invoked with no arguments and should perform a graceful
+    shutdown. The handler raises :class:`KeyboardInterrupt` afterwards so that
+    existing ``except KeyboardInterrupt`` blocks still trigger.
+    """
+    def _handler(signum, _frame):  # pragma: no cover - exercised via signals
+        logger.info("Received signal %s; shutting down", signum)
+        try:
+            on_term()
+        finally:
+            raise KeyboardInterrupt
+
+    if hasattr(signal, "SIGTERM"):
+        signal.signal(signal.SIGTERM, _handler)
+
+
+def stop_service(pid_path: Path, timeout: float = 10.0) -> str:
+    pid = read_pid(pid_path)
+    if pid is None:
+        return "Thoth service is not running (no PID file)."
+    if not is_alive(pid):
+        remove_pid(pid_path)
+        return f"Thoth service is not running (stale PID file removed; was PID {pid})."
+
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        remove_pid(pid_path)
+        return f"Thoth service was not running (PID {pid})."
+    except PermissionError as exc:
+        return f"Cannot signal PID {pid}: {exc}."
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if not is_alive(pid):
+            remove_pid(pid_path)
+            return f"Stopped Thoth service (PID {pid})."
+        time.sleep(0.2)
+
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    except OSError as exc:
+        if exc.errno != errno.ESRCH:
+            return f"Failed to force-kill PID {pid}: {exc}."
+
+    remove_pid(pid_path)
+    return f"Force-killed Thoth service (PID {pid}) after {timeout:.0f}s timeout."
+
+
+def status_message(pid_path: Path) -> str:
+    pid = read_pid(pid_path)
+    if pid is None:
+        return "Thoth service: stopped."
+    if is_alive(pid):
+        return f"Thoth service: running (PID {pid}, pidfile {pid_path})."
+    return f"Thoth service: stopped (stale PID file at {pid_path}, was PID {pid})."
+
+
+_SYSTEMD_UNIT_TEMPLATE = """[Unit]
+Description=Thoth — local-first AI assistant
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart={launch_cmd} --server --no-tray --no-open --no-splash
+Restart=on-failure
+RestartSec=5
+Environment=PYTHONUNBUFFERED=1
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def install_systemd_unit(
+    launch_cmd: str | None = None,
+    unit_path: Path | None = None,
+) -> Path:
+    """Write a user-level systemd unit for Thoth and return its path.
+
+    Caller-controlled ``launch_cmd`` is interpolated verbatim into ``ExecStart``;
+    if omitted, this resolves the absolute path to the ``thoth`` launcher
+    (``~/.local/bin/thoth`` if available, otherwise the value of ``sys.argv[0]``).
+    """
+    if sys.platform.startswith("win"):
+        raise SystemExit("Systemd is Linux-only. Use --run-as-service or Task Scheduler on other platforms.")
+
+    if launch_cmd is None:
+        candidate = Path.home() / ".local" / "bin" / "thoth"
+        launch_cmd = str(candidate) if candidate.exists() else os.path.abspath(sys.argv[0])
+
+    target = unit_path or (Path.home() / ".config" / "systemd" / "user" / "thoth.service")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(_SYSTEMD_UNIT_TEMPLATE.format(launch_cmd=launch_cmd), encoding="utf-8")
+    return target