feat: Docker/Podman-install awareness - honest service messaging, --mycroft-conf override

Investigated how this tool behaves on a Docker/Podman-based OVOS
install (ovos-installer's "containers" method, or ovos-docker
directly) - researched ovos-docker's own documentation and compose
files, then confirmed the service-detection piece empirically against
a real locally-run podman container (not just inferred from docs).

Two confirmed, real gaps addressed:

1. Services: systemctl --user genuinely has nothing to find on a
   Docker/Podman install - OVOS runs as containers, not systemd units,
   in that mode. Previously this just showed a bare "Services: none
   found", indistinguishable from an actual problem. Added
   detect_container_runtime() (tries `docker ps` then `podman ps`,
   looking for OVOS/hivemind-named containers) - when systemd finds
   nothing but this does, the boot sequence now says so explicitly and
   lists the containers, rather than a silent, unexplained empty
   result. Does NOT attempt container start/stop/restart - that's
   separate, larger work (different commands, different confirmation
   semantics, potentially needing the Docker/Podman socket mounted)
   tracked as its own follow-up rather than bolted on here.

2. Pipeline: confirmed via ovos-docker's own compose files
   (volumes: ${CONFIG_FOLDER}:/home/${OVOS_USER}/.config/mycroft) that
   the real, live mycroft.conf commonly lives at a host path like
   ~/ovos/config/mycroft.conf (configurable per-install), not the
   standard ~/.config/mycroft/mycroft.conf ovos-config's own XDG-based
   lookup checks by default on the host. Since ovos-tui-client runs on
   the host, not inside the same containers, it had no way to find the
   right file. Added --mycroft-conf to point at a specific file
   directly (bypassing ovos-config's lookup for that one file read),
   using the same load_commented_json() helper ovos-config itself uses
   internally so real mycroft.conf files' JSON5-style '//' comments
   don't break it.

Logs were also investigated but NOT changed: ~/.local/state/mycroft
(already this tool's first candidate) matches both ovos-docker's
common volume-mount convention and the official ovos-logs tool's own
assumption, so this likely already works - genuinely unconfirmed
without a full running Docker OVOS stack though (a much heavier setup
than the lightweight container-naming test used for the services
piece), tracked as a follow-up rather than assumed correct.

192 tests passing (11 new, including detect_container_runtime tested
against a mocked subprocess AND confirmed once against a real local
podman container during development, and --mycroft-conf tested against
a real file with genuine JSON5 comments); verified sdist->wheel build.
Not tagging yet - commit+push freely, tag once we're both happy.

Author: andlo

README.md

@@ -180,13 +180,52 @@ ovos-tui
 Connects to `127.0.0.1:8181` by default. Options:
 
 ```bash
-ovos-tui --host 192.168.1.50 --port 8181 --lang da-dk --log-dir ~/.local/state/mycroft
+ovos-tui --host 192.168.1.50 --port 8181 --lang da-dk --log-dir ~/.local/state/mycroft --mycroft-conf ~/ovos/config/mycroft.conf
 ```
 
 - `--log-dir`: the log directory is auto-detected against a list of
   known candidate paths (which vary by OVOS install method). If nothing
   is found, the logs pane says so - pass this to point at the right
   directory explicitly.
+- `--mycroft-conf`: path to a specific `mycroft.conf` for the `Pipeline: `
+  palette entries to read. Only needed on Docker/Podman installs
+  (`ovos-installer`'s "containers" method, or `ovos-docker` directly) -
+  confirmed via `ovos-docker`'s own compose files that the real, live
+  config commonly lives at a host path like `~/ovos/config/mycroft.conf`
+  (configurable per-install), not the standard
+  `~/.config/mycroft/mycroft.conf` `ovos-config` looks for by default.
+  Without this, `Pipeline: ` may read the wrong file or find nothing on
+  a Docker install - it won't crash, but it won't be accurate either.
+  This direct-read path tolerates the same JSON5-style `//` comments a
+  real `mycroft.conf` has, but skips `ovos-config`'s own config-layering
+  (system/user/web-cache merge) - a reasonable trade-off for a quick
+  lookup.
+
+### Docker/Podman installs
+
+`ovos-tui-client` itself runs on the host, not inside the same
+containers, so a few things behave differently on a Docker/Podman
+install (confirmed against `ovos-docker`'s own documentation and a
+locally-run container, not just inferred):
+
+- **Logs**: usually fine without any extra flags - `ovos-docker`
+  installs commonly volume-mount the same conventional
+  `~/.local/state/mycroft` path this tool already checks first, and
+  the official `ovos-logs` debugging tool relies on that same
+  assumption. If the install was configured with `"logs": {"path":
+  "stdout"}` (a documented `ovos-docker` recommendation for
+  container-log-based debugging) instead, there are no log FILES at
+  all - this tool will correctly report "no logs found", and
+  `docker compose logs` / `docker logs <container>` are the right
+  tools for that case instead.
+- **Services**: `systemctl --user` genuinely has nothing to find,
+  since OVOS runs as containers, not systemd units, in this mode. The
+  boot sequence detects this (checking `docker ps` / `podman ps` for
+  OVOS-named containers) and says so explicitly rather than showing a
+  bare, unexplained "none found" - but starting/stopping/restarting a
+  container from here isn't supported yet (see the open issue for
+  this).
+- **Pipeline**: see `--mycroft-conf` above.
 
 ## Why not just fix ovos-cli-client / neon-cli-client?
 

ovos_tui_client/app.py

@@ -66,7 +66,7 @@
     find_log_dir, discover_log_sources, line_matches_filter, strip_log_prefix,
     extract_log_level, extract_skill_id, KNOWN_LOG_NAMES, KNOWN_LOG_LEVELS,
 )
-from ovos_tui_client.services import discover_services_with_state, restart_service, stop_service, start_service
+from ovos_tui_client.services import discover_services_with_state, restart_service, stop_service, start_service, detect_container_runtime
 from ovos_tui_client.state import load_filter_state, save_filter_state
 
 LOG_POLL_INTERVAL = 0.5  # seconds
@@ -190,7 +190,27 @@ class PipelineCommandProvider(Provider):
     reading mycroft.conf is fast/local, and pipeline order essentially
     never changes without an OVOS restart, so there's no staleness
     concern worth caching against. Uses ovos_config (respects OVOS's
-    own config layering) rather than parsing the raw file.
+    own config layering) by default - rather than parsing the raw file
+    - UNLESS --mycroft-conf was given (see build_arg_parser()), in
+    which case that specific file is read directly instead (still
+    tolerating JSON5-style '//' comments via the same
+    load_commented_json() helper ovos_config itself uses internally,
+    not a plain json.load()).
+
+    The override exists because ovos_config's own XDG-based lookup
+    doesn't know about Docker/Podman installs: confirmed via
+    ovos-docker's own compose files that the real, live mycroft.conf
+    commonly lives at a host path like ~/ovos/config/mycroft.conf
+    (configurable per-install via the compose stack's CONFIG_FOLDER
+    variable) rather than the standard ~/.config/mycroft/mycroft.conf
+    ovos_config looks for on the host by default - since
+    ovos-tui-client itself typically runs on the host, not inside the
+    same containers, it has no way to know that non-standard path
+    without being told. The direct-read fallback doesn't get
+    ovos_config's config-layering (system/user/web-cache merge) - a
+    reasonable trade-off for a quick lookup, and clearly indicated in
+    the resulting message so it's never mistaken for the full,
+    layered picture.
 
     Read-only - toggling stages on/off would mean writing to
     mycroft.conf itself, which needs its own careful design pass (see
@@ -203,8 +223,13 @@ class PipelineCommandProvider(Provider):
     async def search(self, query: str) -> Hits:
         matcher = self.matcher(query)
         try:
-            from ovos_config.config import Configuration
-            pipeline = Configuration().get("intents", {}).get("pipeline", [])
+            if self.app.mycroft_conf_override:
+                from json_database.utils import load_commented_json
+                conf = load_commented_json(self.app.mycroft_conf_override)
+                pipeline = (conf or {}).get("intents", {}).get("pipeline", [])
+            else:
+                from ovos_config.config import Configuration
+                pipeline = Configuration().get("intents", {}).get("pipeline", [])
         except Exception:
             return
         for i, stage in enumerate(pipeline, start=1):
@@ -433,13 +458,14 @@ class OVOSTUIApp(App):
 
     COMMANDS = App.COMMANDS | {ServiceCommandProvider, SkillCommandProvider, SkillFilterCommandProvider, PipelineCommandProvider}
 
-    def __init__(self, host="127.0.0.1", port=8181, lang="en-us", log_dir_override=None):
+    def __init__(self, host="127.0.0.1", port=8181, lang="en-us", log_dir_override=None, mycroft_conf_override=None):
         super().__init__()
         self.host = host
         self.port = port
         self.bus = OVOSBusConnection(host=host, port=port, lang=lang)
         self.log_dir = find_log_dir(override=log_dir_override)
         self.log_sources = discover_log_sources(self.log_dir)
+        self.mycroft_conf_override = mycroft_conf_override
         self.utterance_history = []
         self.history_index = None
         self.log_buffer = deque(maxlen=LOG_BUFFER_SIZE)
@@ -583,7 +609,17 @@ def _check_services_worker(self) -> None:
         call_from_thread() only guarantees THIS call finishes before
         returning, not that no other thread's call can be scheduled in
         between two of THIS thread's separate calls. One call = one
-        atomic write, no other thread's output can land inside it."""
+        atomic write, no other thread's output can land inside it.
+
+        When systemd finds nothing, this checks for a Docker/Podman
+        install before settling on a bare "none found" - a confirmed
+        real gap: OVOS installed via ovos-docker runs everything as
+        containers, not systemd --user units, so systemctl genuinely
+        has nothing to report there, and "none found" alone reads like
+        something's broken rather than "this is a different kind of
+        install". Only detection + an honest message, not container
+        start/stop/restart - see detect_container_runtime()'s own
+        docstring for why that's separate, larger, tracked work."""
         services = discover_services_with_state()
         if services:
             lines = ["Services:"]
@@ -592,7 +628,15 @@ def _check_services_worker(self) -> None:
                 lines.append(f"    {name} {state}")
             self.call_from_thread(self._write_status, "\n".join(lines))
         else:
-            self.call_from_thread(self._write_status, "Services: none found")
+            containers = detect_container_runtime()
+            if containers:
+                lines = ["Services: not managed via systemd - looks like a Docker/Podman install:"]
+                for name in containers:
+                    lines.append(f"    {name}")
+                lines.append("    (start/stop/restart from here isn't supported yet for containers - see `docker/podman ps`)")
+                self.call_from_thread(self._write_status, "\n".join(lines))
+            else:
+                self.call_from_thread(self._write_status, "Services: none found")
         self.call_from_thread(self._finish_startup)
 
     def _write_to_log(self, widget: RichLog, content) -> None:
@@ -1053,12 +1097,13 @@ def build_arg_parser():
     parser.add_argument("--port", type=int, default=8181, help="messagebus port (default: 8181)")
     parser.add_argument("--lang", default="en-us", help="BCP-47 language code for typed utterances (default: en-us)")
     parser.add_argument("--log-dir", default=None, help="override log directory auto-detection")
+    parser.add_argument("--mycroft-conf", default=None, help="path to a specific mycroft.conf to read for 'Pipeline: ' (bypasses ovos-config's own XDG-based lookup - needed on Docker/Podman installs, where the real config commonly lives at a host path like ~/ovos/config/mycroft.conf rather than the standard ~/.config/mycroft/mycroft.conf ovos-config looks for by default)")
     return parser
 
 
 def run():
     args = build_arg_parser().parse_args()
-    app = OVOSTUIApp(host=args.host, port=args.port, lang=args.lang, log_dir_override=args.log_dir)
+    app = OVOSTUIApp(host=args.host, port=args.port, lang=args.lang, log_dir_override=args.log_dir, mycroft_conf_override=args.mycroft_conf)
     app.run()
 
 

ovos_tui_client/services.py

@@ -96,3 +96,45 @@ def start_service(unit_name):
     """Starts a single systemd --user unit. Same (success, message)
     contract as restart_service()."""
     return _systemctl_action("start", unit_name)
+
+
+def detect_container_runtime():
+    """Best-effort detection of OVOS running under Docker/Podman
+    instead of systemd - meant to be checked when
+    discover_services_with_state() finds nothing, so the boot sequence
+    can give an honest, specific explanation ("looks like a
+    Docker/Podman install") instead of a bare "none found" that reads
+    like something's broken.
+
+    Confirmed via ovos-docker's own documentation
+    (openvoiceos.github.io/ovos-docker) that OVOS services run as
+    containers, not systemd units, when installed this way -
+    `systemctl --user` genuinely has nothing to find in that case, so
+    there's no bug to fix there, just a UI message worth improving.
+    This function does NOT attempt to replace systemctl's start/stop/
+    restart functionality for containers - that's real, separate work
+    (different commands, different confirmation semantics, potentially
+    needing the Docker/Podman socket mounted if ovos-tui-client itself
+    ever runs containerized) tracked as its own follow-up rather than
+    bolted on here as an afterthought.
+
+    Tries `docker` first, then `podman` (whichever is actually
+    installed) - returns a sorted list of container names that look
+    OVOS-related (containing 'ovos' or 'hivemind', case-insensitive,
+    matching ovos-docker's own naming convention), or [] if neither
+    runtime is available or neither has any matching containers."""
+    for binary in ("docker", "podman"):
+        try:
+            result = subprocess.run(
+                [binary, "ps", "--format", "{{.Names}}"],
+                capture_output=True, text=True, timeout=5,
+            )
+        except (subprocess.SubprocessError, FileNotFoundError, OSError):
+            continue
+        if result.returncode != 0:
+            continue
+        names = [n.strip() for n in result.stdout.splitlines() if n.strip()]
+        matching = [n for n in names if "ovos" in n.lower() or "hivemind" in n.lower()]
+        if matching:
+            return sorted(matching)
+    return []

tests/test_command_palette.py

@@ -402,6 +402,64 @@ async def test_pipeline_search_handles_empty_pipeline_gracefully(tmp_path):
         assert hits == []
 
 
+# --- PipelineCommandProvider: --mycroft-conf override (Docker/Podman
+# installs, where ovos_config's own XDG lookup finds the wrong file or
+# nothing - see build_arg_parser()'s help text and this Provider's
+# docstring for why) ---
+
+@pytest.mark.asyncio
+async def test_pipeline_uses_mycroft_conf_override_when_set(tmp_path):
+    """A real file on disk, with JSON5-style '//' comments (as real
+    mycroft.conf files commonly have) - confirms load_commented_json()
+    is actually used, not a plain json.load() that would choke on
+    them."""
+    conf_path = tmp_path / "mycroft.conf"
+    conf_path.write_text('''{
+        // this is a real mycroft.conf-style comment
+        "intents": {
+            "pipeline": ["stop_high", "ocp_high"]
+        }
+    }''')
+    app = _app_with_fake_bus(tmp_path)
+    app.mycroft_conf_override = str(conf_path)
+    async with app.run_test() as pilot:
+        provider = PipelineCommandProvider(app.screen)
+        hits = await _collect_hits(provider, "pipeline")
+
+    texts = [str(h.match_display) for h in hits]
+    assert "Pipeline: 1. stop_high" in texts
+    assert "Pipeline: 2. ocp_high" in texts
+
+
+@pytest.mark.asyncio
+async def test_pipeline_override_takes_priority_over_ovos_config(tmp_path):
+    """When set, the override is used INSTEAD of ovos_config's own
+    lookup, not merged with it - confirms Configuration() is never
+    even called in that case."""
+    conf_path = tmp_path / "mycroft.conf"
+    conf_path.write_text('{"intents": {"pipeline": ["from_override"]}}')
+    app = _app_with_fake_bus(tmp_path)
+    app.mycroft_conf_override = str(conf_path)
+    async with app.run_test() as pilot:
+        with patch("ovos_config.config.Configuration") as mock_config:
+            provider = PipelineCommandProvider(app.screen)
+            hits = await _collect_hits(provider, "pipeline")
+            mock_config.assert_not_called()
+
+    assert "Pipeline: 1. from_override" in [str(h.match_display) for h in hits]
+
+
+@pytest.mark.asyncio
+async def test_pipeline_override_handles_missing_file_gracefully(tmp_path):
+    app = _app_with_fake_bus(tmp_path)
+    app.mycroft_conf_override = str(tmp_path / "does-not-exist.conf")
+    async with app.run_test() as pilot:
+        provider = PipelineCommandProvider(app.screen)
+        hits = await _collect_hits(provider, "pipeline")  # must not raise
+
+    assert hits == []
+
+
 # --- SkillFilterCommandProvider: log-display skill filter, in the palette ---
 
 @pytest.mark.asyncio

tests/test_services.py

@@ -2,7 +2,7 @@
 real service management is exercised here."""
 from unittest.mock import MagicMock, patch
 
-from ovos_tui_client.services import discover_services, discover_services_with_state, restart_service, stop_service, start_service
+from ovos_tui_client.services import discover_services, discover_services_with_state, restart_service, stop_service, start_service, detect_container_runtime
 
 
 def _fake_completed(stdout="", stderr="", returncode=0):
@@ -139,3 +139,39 @@ def test_discover_services_still_returns_name_only_list():
     fake_output = "ovos-core.service loaded active running X\n"
     with patch("subprocess.run", return_value=_fake_completed(stdout=fake_output)):
         assert discover_services() == ["ovos-core.service"]
+
+
+# --- detect_container_runtime() (confirmed against a real podman container during development) ---
+
+def test_detect_container_runtime_finds_ovos_named_containers():
+    fake_output = "ovos-core-test\nsome-other-container\nhivemind-relay\n"
+    with patch("subprocess.run", return_value=_fake_completed(stdout=fake_output)):
+        assert detect_container_runtime() == ["hivemind-relay", "ovos-core-test"]
+
+
+def test_detect_container_runtime_returns_empty_when_no_matching_containers():
+    fake_output = "some-other-container\nanother-one\n"
+    with patch("subprocess.run", return_value=_fake_completed(stdout=fake_output)):
+        assert detect_container_runtime() == []
+
+
+def test_detect_container_runtime_returns_empty_when_neither_binary_available():
+    with patch("subprocess.run", side_effect=FileNotFoundError()):
+        assert detect_container_runtime() == []
+
+
+def test_detect_container_runtime_falls_back_from_docker_to_podman():
+    """docker not installed (FileNotFoundError) but podman is and has a
+    match - confirms the fallback actually tries the second binary
+    rather than giving up after the first failure."""
+    call_count = {"n": 0}
+
+    def fake_run(cmd, **kwargs):
+        call_count["n"] += 1
+        if cmd[0] == "docker":
+            raise FileNotFoundError()
+        return _fake_completed(stdout="ovos-messagebus\n")
+
+    with patch("subprocess.run", side_effect=fake_run):
+        assert detect_container_runtime() == ["ovos-messagebus"]
+    assert call_count["n"] == 2