Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(agent-runtimes): status, install and update for Hermes and OpenClaw

rubenluetke10-beepa0ed045fc28f
diff --git a/jarvis/agent_runtimes/manager.py b/jarvis/agent_runtimes/manager.py
new file mode 100644
index 0000000000..8b1f5ddb6e
--- /dev/null
+++ b/jarvis/agent_runtimes/manager.py
@@ -0,0 +1,153 @@
+"""Install and update Hermes / OpenClaw with their own official tools.
+
+Only ever started by the person (a button in an agent's Brain settings): an
+install downloads and runs the project's own installer, an update runs the
+runtime's own updater. One job per runtime at a time; its output goes to a
+log file whose tail the UI shows. Before an update every running process of
+that runtime is stopped — on Windows a running Hermes venv or OpenClaw
+Gateway would hold files the updater must replace.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Final, Literal
+
+from jarvis.agent_runtimes import RUNTIME_NAMES, driver
+from jarvis.agent_runtimes.base import child_env, runtimes_root
+
+log = logging.getLogger(__name__)
+
+JobKind = Literal["install", "update"]
+JobState = Literal["running", "done", "failed"]
+
+#: An installer that has not finished in this long is stopped.
+_JOB_TIMEOUT_S: Final[float] = 30 * 60
+
+
+@dataclass(slots=True)
+class RuntimeJob:
+ runtime: str
+ kind: JobKind
+ state: JobState = "running"
+ started_ms: int = field(default_factory=lambda: int(time.time() * 1000))
+ finished_ms: int | None = None
+ exit_code: int | None = None
+ message: str = ""
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "runtime": self.runtime,
+ "kind": self.kind,
+ "state": self.state,
+ "started_ms": self.started_ms,
+ "finished_ms": self.finished_ms,
+ "exit_code": self.exit_code,
+ "message": self.message,
+ "log_tail": log_tail(self.runtime),
+ }
+
+
+_JOBS: dict[str, RuntimeJob] = {}
+_TASKS: dict[str, asyncio.Task[None]] = {}
+
+
+def _log_path(runtime: str) -> Any:
+ root = runtimes_root()
+ root.mkdir(parents=True, exist_ok=True)
+ return root / f"{runtime}-setup.log"
+
+
+def log_tail(runtime: str, lines: int = 12) -> list[str]:
+ try:
+ text = _log_path(runtime).read_text(encoding="utf-8", errors="replace")
+ except OSError:
+ return []
+ return [line for line in text.splitlines() if line.strip()][-lines:]
+
+
+def job(runtime: str) -> RuntimeJob | None:
+ return _JOBS.get(runtime)
+
+
+async def statuses(*, refresh: bool = False) -> list[dict[str, Any]]:
+ """Every runtime's status plus its running or last setup job."""
+ out: list[dict[str, Any]] = []
+ for name in RUNTIME_NAMES:
+ status = await asyncio.to_thread(driver(name).detect, refresh=refresh)
+ row = status.to_dict()
+ current = _JOBS.get(name)
+ row["job"] = current.to_dict() if current is not None else None
+ out.append(row)
+ return out
+
+
+def start(runtime: str, kind: JobKind) -> RuntimeJob:
+ """Start an install or update job; returns the running job if one exists."""
+ if runtime not in RUNTIME_NAMES:
+ raise KeyError(runtime)
+ current = _JOBS.get(runtime)
+ if current is not None and current.state == "running":
+ return current
+ target = driver(runtime)
+ argv = target.install_command() if kind == "install" else target.update_command()
+ if not argv:
+ failed = RuntimeJob(
+ runtime, kind, state="failed", message=f"{target.label} is not installed."
+ )
+ failed.finished_ms = failed.started_ms
+ _JOBS[runtime] = failed
+ return failed
+ new_job = RuntimeJob(runtime, kind)
+ _JOBS[runtime] = new_job
+ _TASKS[runtime] = asyncio.get_running_loop().create_task(_run(new_job, argv))
+ return new_job
+
+
+async def _run(current: RuntimeJob, argv: list[str]) -> None:
+ from jarvis.core.process_tree import make_process_tree
+ from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS
+
+ target = driver(current.runtime)
+ if current.kind == "update":
+ await target.stop()
+ path = _log_path(current.runtime)
+ tree = make_process_tree(f"{current.runtime}-{current.kind}")
+ try:
+ with path.open("wb") as handle:
+ handle.write(f"$ {' '.join(argv)}\n".encode())
+ handle.flush()
+ proc = await asyncio.create_subprocess_exec(
+ *argv,
+ stdin=asyncio.subprocess.DEVNULL,
+ stdout=handle,
+ stderr=handle,
+ env=child_env(),
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ start_new_session=True,
+ )
+ tree.assign(proc.pid)
+ try:
+ code = await asyncio.wait_for(proc.wait(), timeout=_JOB_TIMEOUT_S)
+ except TimeoutError:
+ with contextlib.suppress(ProcessLookupError, OSError):
+ proc.kill()
+ code = -1
+ current.message = "Stopped after 30 minutes."
+ current.exit_code = code
+ current.state = "done" if code == 0 else "failed"
+ if code != 0 and not current.message:
+ current.message = f"{target.label} {current.kind} failed (exit {code})."
+ except OSError as exc:
+ current.state = "failed"
+ current.message = f"Could not start the {current.kind}: {exc}"
+ log.warning("agent runtimes: %s %s could not start: %s", current.runtime, current.kind, exc)
+ finally:
+ tree.close()
+ current.finished_ms = int(time.time() * 1000)
+ target.detect(refresh=True)
+ _TASKS.pop(current.runtime, None)
diff --git a/jarvis/setup/dependencies.py b/jarvis/setup/dependencies.py
index c1e7bf4c0c..fef1cac944 100644
--- a/jarvis/setup/dependencies.py
+++ b/jarvis/setup/dependencies.py
@@ -197,9 +197,10 @@ def check_openclaw() -> DependencyStatus:
name="openclaw",
present=False,
install_hint=(
- "Optional. Only needed if you switch the worker "
- "provider away from claude-api. Install with "
- "`npm i -g openclaw` (pin 2026.5.7, see AD-21)."
+ "Optional. Needed for OpenClaw society agents "
+ "(docs/agent-runtimes.md). Install it from the agent's "
+ "Brain settings, or with the official installer; "
+ "2026.9.8 or newer."
),
)
version = _probe_version(path, "--version")
diff --git a/jarvis/setup/wizard.py b/jarvis/setup/wizard.py
index ff3db7f2dd..35baf3905f 100644
--- a/jarvis/setup/wizard.py
+++ b/jarvis/setup/wizard.py
@@ -1144,7 +1144,7 @@ def step_jarvis_agent_harness_check() -> None:
_println(f"✓ Worker-harness binary found: {binary}")
else:
_println("– 'openclaw' harness binary not on PATH (optional).")
- _println(" Install: npm i -g openclaw (pin: 2026.5.7, see AD-21)")
+ _println(" Install it from an agent's Brain settings (OpenClaw 2026.9.8 or newer).")
_println(" The harness stays inactive until the binary is available — no crash.")
# 2. Show the provider mapping (lazy import — the wizard should also run
diff --git a/jarvis/ui/web/agent_runtime_routes.py b/jarvis/ui/web/agent_runtime_routes.py
new file mode 100644
index 0000000000..3f28b5d9a8
--- /dev/null
+++ b/jarvis/ui/web/agent_runtime_routes.py
@@ -0,0 +1,42 @@
+"""``/api/agent-runtimes`` — Hermes / OpenClaw status, install and update.
+
+The society UI reads these to offer the runtime switch on an agent's Brain
+settings: installed or not, version, whether that version is new enough, and
+a running setup job with its log tail. Install and update run the runtimes'
+own official tools and only when the person presses the button.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from fastapi import APIRouter, HTTPException
+
+from jarvis.agent_runtimes import RUNTIME_NAMES, manager
+
+router = APIRouter(prefix="/api/agent-runtimes", tags=["agent-runtimes"])
+
+
+async def list_agent_runtimes(refresh: bool = False) -> dict[str, Any]:
+ """Every external runtime: installed, version, ready, problem, setup job."""
+ return {"runtimes": await manager.statuses(refresh=refresh)}
+
+
[email protected]("/{runtime}/{action}")
+async def run_agent_runtime_setup(
+ runtime: str, action: Literal["install", "update"]
+) -> dict[str, Any]:
+ """Start the runtime's official installer or updater (person-started only)."""
+ if runtime not in RUNTIME_NAMES:
+ raise HTTPException(404, f"unknown runtime {runtime!r}")
+ return {"job": manager.start(runtime, action).to_dict()}
+
+
[email protected]("/{runtime}/job")
+async def agent_runtime_job(runtime: str) -> dict[str, Any]:
+ """The running or last setup job of one runtime (``null`` when none)."""
+ if runtime not in RUNTIME_NAMES:
+ raise HTTPException(404, f"unknown runtime {runtime!r}")
+ current = manager.job(runtime)
+ return {"job": current.to_dict() if current is not None else None}
diff --git a/jarvis/ui/web/server.py b/jarvis/ui/web/server.py
index 5c2612b8df..dc7edb38f9 100644
--- a/jarvis/ui/web/server.py
+++ b/jarvis/ui/web/server.py
@@ -469,12 +469,12 @@ class WebServer:
from .agent_accounts_routes import router as agent_accounts_router
from .agent_chat_routes import router as agent_chat_router
from .agent_mcp_routes import router as agent_mcp_router
+ from .agent_runtime_routes import router as agent_runtime_router
from .agentic_ide_git_routes import router as agentic_ide_git_router
from .agentic_ide_routes import router as agentic_ide_router
from .antigravity_routes import router as antigravity_router
from .app_actions_routes import router as app_actions_router
from .appshot_routes import router as appshot_router
- from .jarvisx_routes import router as jarvisx_router
from .board_routes import (
board_router as board_meta_router,
)
@@ -506,6 +506,7 @@ class WebServer:
from .friends_routes import router as friends_router
from .frontier_routes import router as frontier_router
from .grok_build_routes import router as grok_build_router
+ from .jarvisx_routes import router as jarvisx_router
from .live_routes import router as live_router
from .local_models_assistant_routes import (
router as local_models_assistant_router,
@@ -752,6 +753,7 @@ class WebServer:
set_society_factory(self._build_society_runtime)
app.include_router(society_router)
+ app.include_router(agent_runtime_router)
from .mars_routes import router as mars_router
app.include_router(mars_router)
diff --git a/tests/unit/agent_runtimes/test_runtime_manager.py b/tests/unit/agent_runtimes/test_runtime_manager.py
new file mode 100644
index 0000000000..e59228e207
--- /dev/null
+++ b/tests/unit/agent_runtimes/test_runtime_manager.py
@@ -0,0 +1,97 @@
+"""Runtime status, install and update jobs, and their routes."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+import jarvis.agent_runtimes as runtimes
+from jarvis.agent_runtimes import base, manager
+from jarvis.agent_runtimes.base import RuntimeStatus
+from jarvis.ui.web.agent_runtime_routes import router
+
+
+class FakeDriver:
+ def __init__(self, name: str, *, exit_code: int = 0) -> None:
+ self.name = name
+ self.label = name.title()
+ self.exit_code = exit_code
+ self.stopped = 0
+ self.refreshed = 0
+
+ def detect(self, *, refresh: bool = False) -> RuntimeStatus:
+ self.refreshed += int(refresh)
+ return RuntimeStatus(self.name, self.label, installed=True, version="1.0.0", ready=True)
+
+ def _script(self, word: str) -> list[str]:
+ return [sys.executable, "-c", f"print('{word}'); raise SystemExit({self.exit_code})"]
+
+ def install_command(self) -> list[str]:
+ return self._script("installing")
+
+ def update_command(self) -> list[str]:
+ return self._script("updating")
+
+ async def stop(self, agent_id: str | None = None) -> None:
+ self.stopped += 1
+
+
+def fakes(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setattr(base, "runtimes_root", lambda: tmp_path)
+ drivers = {"hermes": FakeDriver("hermes"), "openclaw": FakeDriver("openclaw", exit_code=3)}
+ monkeypatch.setattr(runtimes, "_DRIVERS", drivers)
+ monkeypatch.setattr(manager, "_JOBS", {})
+ return drivers
+
+
+async def _finish(name: str) -> manager.RuntimeJob:
+ for _ in range(200):
+ current = manager.job(name)
+ assert current is not None
+ if current.state != "running":
+ return current
+ await asyncio.sleep(0.05)
+ raise AssertionError("job did not finish")
+
+
+async def test_an_install_runs_the_official_command_and_logs_it(fakes):
+ started = manager.start("hermes", "install")
+ assert started.state == "running"
+ assert manager.start("hermes", "install") is started # one job at a time
+ done = await _finish("hermes")
+ assert done.state == "done" and done.exit_code == 0
+ assert any("installing" in line for line in done.to_dict()["log_tail"])
+ assert fakes["hermes"].refreshed >= 1
+
+
+async def test_an_update_stops_the_runtime_first_and_reports_a_failure(fakes):
+ manager.start("openclaw", "update")
+ done = await _finish("openclaw")
+ assert fakes["openclaw"].stopped == 1
+ assert done.state == "failed" and done.exit_code == 3
+ assert "failed" in done.message
+
+
+async def test_unknown_runtimes_are_refused(fakes):
+ with pytest.raises(KeyError):
+ manager.start("skynet", "install")
+
+
+def test_routes_list_status_and_start_jobs(fakes):
+ app = FastAPI()
+ app.include_router(router)
+ client = TestClient(app)
+ rows = client.get("/api/agent-runtimes").json()["runtimes"]
+ assert [row["runtime"] for row in rows] == ["hermes", "openclaw"]
+ assert rows[0]["ready"] is True and rows[0]["job"] is None
+ assert client.post("/api/agent-runtimes/skynet/install").status_code == 404
+ assert client.post("/api/agent-runtimes/hermes/delete").status_code == 422
+ job = client.post("/api/agent-runtimes/hermes/install").json()["job"]
+ assert job["kind"] == "install" and job["runtime"] == "hermes"
+ assert client.get("/api/agent-runtimes/hermes/job").json()["job"]["kind"] == "install"