cyclo-manager 0.4.0.dev0__tar.gz → 1.0.0__tar.gz

{cyclo_manager-0.4.0.dev0 → cyclo_manager-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cyclo-manager
-Version: 0.4.0.dev0
+Version: 1.0.0
 Summary: cyclo_manager CLI: pip-installable launcher for cyclo_manager server and UI containers. Run 'cyclo_manager up' to start Docker stack.
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
@@ -18,7 +18,7 @@ Requires-Dist: ruff; extra == "dev"
 **Console commands:** `cyclo_manager` (underscore), `cyclo-manager` (hyphen)  
 **Host agent:** `cyclo_host_agent` (installed by the package, run via systemd)
 
-This package is the **pip-installable launcher** for the cyclo_manager stack on a robot host. It:
+This package is the **pip-installable launcher** for the cyclo_manager stack on a robot host. It is intended for production robots that run the pre-built Docker images. It:
 
 1. Runs **`docker compose`** against a **bundled** [`cyclo_manager_cli/docker/docker-compose.yml`](cyclo_manager_cli/docker/docker-compose.yml) to start the **API** and **web UI** containers.
 2. Installs and maintains **`cyclo_host_agent`** as a **systemd** service for host-level operations (git repo updates, `cyclo_manager` package update from the UI).
@@ -50,11 +50,12 @@ For the full monorepo (API source, UI source, dev compose), see the [repository
 
 ## Prerequisites
 
-- **Docker** with **Compose v2** (`docker compose` — the legacy `docker-compose` binary alone is not enough)
+- **Docker** with **Compose v2** (`docker compose`; the legacy `docker-compose` binary alone is not enough)
 - **Python 3.10+**
-- **`sudo`** — required to install the host agent systemd unit, socket directory permissions, and sudoers rules
+- **systemd**: required for the managed `cyclo_host_agent.service`
+- **`sudo`** — required on normal-user hosts to install the host agent systemd unit, socket directory permissions, and sudoers rules
 - For **`cyclo_manager update`:** **`pip`** or **`pip3`** on `PATH`
-- **Do not run as root** — the host agent runs as the invoking user (or `SUDO_USER` when using `sudo cyclo_manager up`). Running as root is rejected.
+- **Root shell handling** — `cyclo_manager up` rejects direct root execution when a normal login user exists. On root-only devices, the host agent is installed as root.
 - **Agent sockets** on the host under `/var/run/robotis/agent_sockets/` (robot containers and host agent). The bundled Compose file bind-mounts this tree into the API container as `/agents/`.
 
 ---
@@ -94,6 +95,8 @@ python3 -m cyclo_manager_cli.cli up
 | `cyclo_manager update --no-pull` | Same as `update`, but skip image pull (use locally cached images). |
 | `cyclo_manager --help` | Subcommand overview |
 
+The CLI also has an internal `refresh-host-agent` subcommand. It is used by the sudoers rule and should normally not be invoked by users directly.
+
 **`down` vs `update`:** `down` removes the host agent entirely. `update` only stops Docker containers, upgrades the pip package, restarts the stack, and refreshes the host agent — it does **not** call `cyclo_manager down`.
 
 ---
@@ -120,16 +123,21 @@ The pip package installs a small **FastAPI** server that listens on a **Unix dom
 |------|------|
 | Socket | `/var/run/robotis/agent_sockets/host/host_agent.sock` |
 | systemd unit | `cyclo_host_agent.service` |
-| sudoers | `/etc/sudoers.d/cyclo_manager` (`cp`, `udevadm` for container setup scripts) |
+| sudoers | `/etc/sudoers.d/cyclo_manager` (`cp`, `udevadm` for container setup scripts; `refresh-host-agent` CLI subcommand for package-update refresh; skipped on root-only devices) |
 
 The API container reaches it at `/agents/host/host_agent.sock` (see bundled `config.yml`).
 
 **Responsibilities:**
 
-- List and update **`~/ROBOTIS-GIT/*`** git repositories (Version Management in the UI)
-- Run **`cyclo_manager update`** when triggered from the UI (`POST /host/update`)
+- List managed **ROBOTIS-GIT** git repositories in the configured workspace.
+- Check update availability from remote tags and local `package.xml` versions.
+- Update repos on allowed branches (`main`, `jazzy`) using stash or reset workflows.
+- Stop/start a repo's `docker/container.sh` helper during an update when requested by the UI.
+- Run Cyclo Manager package updates from the UI by delegating to `cyclo_manager update`.
+
+`cyclo_manager up` installs the `refresh-host-agent` CLI subcommand into sudoers. It is registered as `sys.executable -m cyclo_manager_cli.cli refresh-host-agent` with `SETENV`, so UI-triggered updates can pass the current `PYTHONPATH` to sudo and do not depend on `PATH`. The command is idempotent and refreshes the socket directory, sudoers file, systemd unit, and service state after package upgrades.
 
-`cyclo_manager up` and `cyclo_manager update` both call `_ensure_host_agent()`, which is idempotent — safe to run after upgrades or user changes.
+Repository scanning uses `CYCLO_HOST_AGENT_WORKSPACE` when set. Otherwise it uses the service user's home directory, except root-only devices with `/data/docker`, where `/data/docker` is used automatically. Only repositories whose `origin` remote belongs to `ROBOTIS-GIT` are returned by the repo list/update endpoints.
 
 ---
 
@@ -139,8 +147,8 @@ Defined in [`cyclo_manager_cli/docker/docker-compose.yml`](cyclo_manager_cli/doc
 
 | Compose service | Container name | `cyclo_manager up` | Image (example) |
 |-----------------|----------------|--------------------|-----------------|
-| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:0.4.0` |
-| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:0.4.0` |
+| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:1.0.0` |
+| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:1.0.0` |
 | `rmw_zenoh` | `zenoh_daemon` | **Created only** | `robotis/zenoh-daemon:latest` |
 | `novnc-server` | `novnc-server` | **Created only** | `robotis/novnc-server:latest` |
 
@@ -160,7 +168,7 @@ The API reads it as `CONFIG_FILE=/app/config.yml` inside the container.
 
 | Key | Description |
 |-----|-------------|
-| **`robot_container`** | Primary robot Docker container name (e.g. `ai_worker`). Used by the UI System page and service bringup. Must be a key in `sockets` and cannot be `host_agent`. |
+| **`supported_robot_containers`** | Robot Docker container names that can open the System page (e.g. `ai_worker`, `open_manipulator`). Each must be a key in `sockets` and cannot be `host_agent`. |
 | **`sockets`** | Map of logical name → agent **Unix socket path as seen inside the API container** (under `/agents/...`). Include robot/service containers and `host_agent`. |
 
 s6 **service names** are not listed in config; each in-container agent reports them at runtime.
@@ -168,20 +176,17 @@ s6 **service names** are not listed in config; each in-container agent reports t
 ### Example (bundled default)
 
 ```yaml
-robot_container: ai_worker
+supported_robot_containers:
+  - ai_worker
+  - open_manipulator
 
 sockets:
   ai_worker: "/agents/ai_worker/s6_agent.sock"
+  open_manipulator: "/agents/open_manipulator/s6_agent.sock"
   cyclo_intelligence: "/agents/cyclo_intelligence/s6_agent.sock"
   host_agent: "/agents/host/host_agent.sock"
 ```
 
-### Validation (API startup)
-
-- At least one socket entry besides `host_agent`
-- `robot_container` must exist in `sockets`
-- All socket paths must be non-empty strings
-
 To use a different config layout, mounts, or local source builds, use the repository’s **`docker-compose.dev.yml`** — see [Custom config and development](#custom-config-and-development).
 
 ---
@@ -212,6 +217,7 @@ So `/agents/ai_worker/s6_agent.sock` in config corresponds to the host path abov
 | Variable | Set by | Purpose |
 |----------|--------|---------|
 | **`CYCLO_MANAGER_CONFIG_FILE`** | CLI (`up`, `down`, `update`) | Absolute path to bundled `config.yml` on the host; mounted into the API container |
+| **`CYCLO_HOST_AGENT_WORKSPACE`** | User or CLI-generated systemd unit | Workspace scanned by `cyclo_host_agent` for managed git repositories |
 | **`HOSTNAME`** | CLI (default: machine hostname) | Passed to API as `HOST_HOSTNAME` |
 | **`CONFIG_FILE`** | Compose (`/app/config.yml`) | Path inside the API container |
 | **`ROS_DOMAIN_ID`** | **Not** set by CLI | Set inside robot containers (e.g. `~/.bashrc`) so DDS matches your fleet |
@@ -253,7 +259,7 @@ Python dependencies declared in [`pyproject.toml`](pyproject.toml):
 |---------|---------|
 | **fastapi** | `cyclo_host_agent` HTTP API |
 | **uvicorn** | `cyclo_host_agent` server |
-| **psutil** | Host agent / system utilities |
+| **psutil** | Declared package dependency for host/system utility support |
 
 The **`cyclo_manager`** CLI itself uses only the Python standard library plus **`subprocess`** calls to **`docker compose`**, **`pip`**, **`systemctl`**, and **`sudo`**.
 

{cyclo_manager-0.4.0.dev0 → cyclo_manager-1.0.0}/README.md

@@ -4,7 +4,7 @@
 **Console commands:** `cyclo_manager` (underscore), `cyclo-manager` (hyphen)  
 **Host agent:** `cyclo_host_agent` (installed by the package, run via systemd)
 
-This package is the **pip-installable launcher** for the cyclo_manager stack on a robot host. It:
+This package is the **pip-installable launcher** for the cyclo_manager stack on a robot host. It is intended for production robots that run the pre-built Docker images. It:
 
 1. Runs **`docker compose`** against a **bundled** [`cyclo_manager_cli/docker/docker-compose.yml`](cyclo_manager_cli/docker/docker-compose.yml) to start the **API** and **web UI** containers.
 2. Installs and maintains **`cyclo_host_agent`** as a **systemd** service for host-level operations (git repo updates, `cyclo_manager` package update from the UI).
@@ -36,11 +36,12 @@ For the full monorepo (API source, UI source, dev compose), see the [repository
 
 ## Prerequisites
 
-- **Docker** with **Compose v2** (`docker compose` — the legacy `docker-compose` binary alone is not enough)
+- **Docker** with **Compose v2** (`docker compose`; the legacy `docker-compose` binary alone is not enough)
 - **Python 3.10+**
-- **`sudo`** — required to install the host agent systemd unit, socket directory permissions, and sudoers rules
+- **systemd**: required for the managed `cyclo_host_agent.service`
+- **`sudo`** — required on normal-user hosts to install the host agent systemd unit, socket directory permissions, and sudoers rules
 - For **`cyclo_manager update`:** **`pip`** or **`pip3`** on `PATH`
-- **Do not run as root** — the host agent runs as the invoking user (or `SUDO_USER` when using `sudo cyclo_manager up`). Running as root is rejected.
+- **Root shell handling** — `cyclo_manager up` rejects direct root execution when a normal login user exists. On root-only devices, the host agent is installed as root.
 - **Agent sockets** on the host under `/var/run/robotis/agent_sockets/` (robot containers and host agent). The bundled Compose file bind-mounts this tree into the API container as `/agents/`.
 
 ---
@@ -80,6 +81,8 @@ python3 -m cyclo_manager_cli.cli up
 | `cyclo_manager update --no-pull` | Same as `update`, but skip image pull (use locally cached images). |
 | `cyclo_manager --help` | Subcommand overview |
 
+The CLI also has an internal `refresh-host-agent` subcommand. It is used by the sudoers rule and should normally not be invoked by users directly.
+
 **`down` vs `update`:** `down` removes the host agent entirely. `update` only stops Docker containers, upgrades the pip package, restarts the stack, and refreshes the host agent — it does **not** call `cyclo_manager down`.
 
 ---
@@ -106,16 +109,21 @@ The pip package installs a small **FastAPI** server that listens on a **Unix dom
 |------|------|
 | Socket | `/var/run/robotis/agent_sockets/host/host_agent.sock` |
 | systemd unit | `cyclo_host_agent.service` |
-| sudoers | `/etc/sudoers.d/cyclo_manager` (`cp`, `udevadm` for container setup scripts) |
+| sudoers | `/etc/sudoers.d/cyclo_manager` (`cp`, `udevadm` for container setup scripts; `refresh-host-agent` CLI subcommand for package-update refresh; skipped on root-only devices) |
 
 The API container reaches it at `/agents/host/host_agent.sock` (see bundled `config.yml`).
 
 **Responsibilities:**
 
-- List and update **`~/ROBOTIS-GIT/*`** git repositories (Version Management in the UI)
-- Run **`cyclo_manager update`** when triggered from the UI (`POST /host/update`)
+- List managed **ROBOTIS-GIT** git repositories in the configured workspace.
+- Check update availability from remote tags and local `package.xml` versions.
+- Update repos on allowed branches (`main`, `jazzy`) using stash or reset workflows.
+- Stop/start a repo's `docker/container.sh` helper during an update when requested by the UI.
+- Run Cyclo Manager package updates from the UI by delegating to `cyclo_manager update`.
+
+`cyclo_manager up` installs the `refresh-host-agent` CLI subcommand into sudoers. It is registered as `sys.executable -m cyclo_manager_cli.cli refresh-host-agent` with `SETENV`, so UI-triggered updates can pass the current `PYTHONPATH` to sudo and do not depend on `PATH`. The command is idempotent and refreshes the socket directory, sudoers file, systemd unit, and service state after package upgrades.
 
-`cyclo_manager up` and `cyclo_manager update` both call `_ensure_host_agent()`, which is idempotent — safe to run after upgrades or user changes.
+Repository scanning uses `CYCLO_HOST_AGENT_WORKSPACE` when set. Otherwise it uses the service user's home directory, except root-only devices with `/data/docker`, where `/data/docker` is used automatically. Only repositories whose `origin` remote belongs to `ROBOTIS-GIT` are returned by the repo list/update endpoints.
 
 ---
 
@@ -125,8 +133,8 @@ Defined in [`cyclo_manager_cli/docker/docker-compose.yml`](cyclo_manager_cli/doc
 
 | Compose service | Container name | `cyclo_manager up` | Image (example) |
 |-----------------|----------------|--------------------|-----------------|
-| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:0.4.0` |
-| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:0.4.0` |
+| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:1.0.0` |
+| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:1.0.0` |
 | `rmw_zenoh` | `zenoh_daemon` | **Created only** | `robotis/zenoh-daemon:latest` |
 | `novnc-server` | `novnc-server` | **Created only** | `robotis/novnc-server:latest` |
 
@@ -146,7 +154,7 @@ The API reads it as `CONFIG_FILE=/app/config.yml` inside the container.
 
 | Key | Description |
 |-----|-------------|
-| **`robot_container`** | Primary robot Docker container name (e.g. `ai_worker`). Used by the UI System page and service bringup. Must be a key in `sockets` and cannot be `host_agent`. |
+| **`supported_robot_containers`** | Robot Docker container names that can open the System page (e.g. `ai_worker`, `open_manipulator`). Each must be a key in `sockets` and cannot be `host_agent`. |
 | **`sockets`** | Map of logical name → agent **Unix socket path as seen inside the API container** (under `/agents/...`). Include robot/service containers and `host_agent`. |
 
 s6 **service names** are not listed in config; each in-container agent reports them at runtime.
@@ -154,20 +162,17 @@ s6 **service names** are not listed in config; each in-container agent reports t
 ### Example (bundled default)
 
 ```yaml
-robot_container: ai_worker
+supported_robot_containers:
+  - ai_worker
+  - open_manipulator
 
 sockets:
   ai_worker: "/agents/ai_worker/s6_agent.sock"
+  open_manipulator: "/agents/open_manipulator/s6_agent.sock"
   cyclo_intelligence: "/agents/cyclo_intelligence/s6_agent.sock"
   host_agent: "/agents/host/host_agent.sock"
 ```
 
-### Validation (API startup)
-
-- At least one socket entry besides `host_agent`
-- `robot_container` must exist in `sockets`
-- All socket paths must be non-empty strings
-
 To use a different config layout, mounts, or local source builds, use the repository’s **`docker-compose.dev.yml`** — see [Custom config and development](#custom-config-and-development).
 
 ---
@@ -198,6 +203,7 @@ So `/agents/ai_worker/s6_agent.sock` in config corresponds to the host path abov
 | Variable | Set by | Purpose |
 |----------|--------|---------|
 | **`CYCLO_MANAGER_CONFIG_FILE`** | CLI (`up`, `down`, `update`) | Absolute path to bundled `config.yml` on the host; mounted into the API container |
+| **`CYCLO_HOST_AGENT_WORKSPACE`** | User or CLI-generated systemd unit | Workspace scanned by `cyclo_host_agent` for managed git repositories |
 | **`HOSTNAME`** | CLI (default: machine hostname) | Passed to API as `HOST_HOSTNAME` |
 | **`CONFIG_FILE`** | Compose (`/app/config.yml`) | Path inside the API container |
 | **`ROS_DOMAIN_ID`** | **Not** set by CLI | Set inside robot containers (e.g. `~/.bashrc`) so DDS matches your fleet |
@@ -239,7 +245,7 @@ Python dependencies declared in [`pyproject.toml`](pyproject.toml):
 |---------|---------|
 | **fastapi** | `cyclo_host_agent` HTTP API |
 | **uvicorn** | `cyclo_host_agent` server |
-| **psutil** | Host agent / system utilities |
+| **psutil** | Declared package dependency for host/system utility support |
 
 The **`cyclo_manager`** CLI itself uses only the Python standard library plus **`subprocess`** calls to **`docker compose`**, **`pip`**, **`systemctl`**, and **`sudo`**.
 

{cyclo_manager-0.4.0.dev0 → cyclo_manager-1.0.0}/cyclo_host_agent/routers/repos.py

@@ -41,16 +41,20 @@ from fastapi import APIRouter, HTTPException, status
 router = APIRouter(prefix='/repos', tags=['repos'])
 
 GIT_TIMEOUT = 120.0
+GIT_REMOTE_TIMEOUT = 5.0
 
 
-def _resolve_home() -> Path:
+def _resolve_workspace() -> Path:
+    configured_workspace = os.environ.get('CYCLO_HOST_AGENT_WORKSPACE')
+    if configured_workspace:
+        return Path(configured_workspace).expanduser()
     sudo_user = os.environ.get('SUDO_USER')
     if sudo_user:
         return Path(f'/home/{sudo_user}')
     return Path.home()
 
 
-WORKSPACE_PATH = _resolve_home()
+WORKSPACE_PATH = _resolve_workspace()
 MANAGED_GITHUB_ORG = 'ROBOTIS-GIT'
 ALLOWED_UPDATE_BRANCHES = frozenset({'main', 'jazzy'})
 
@@ -120,7 +124,11 @@ async def _ensure_allowed_branch(repo_path: Path) -> None:
     raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=detail)
 
 
-async def _git(args: list[str], cwd: Optional[Path] = None) -> tuple[int, str, str]:
+async def _git(
+    args: list[str],
+    cwd: Optional[Path] = None,
+    timeout: float = GIT_TIMEOUT,
+) -> tuple[int, str, str]:
     proc = await asyncio.create_subprocess_exec(
         'git', *args,
         cwd=str(cwd) if cwd else None,
@@ -128,7 +136,7 @@ async def _git(args: list[str], cwd: Optional[Path] = None) -> tuple[int, str, s
         stderr=asyncio.subprocess.PIPE,
     )
     try:
-        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=GIT_TIMEOUT)
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
     except asyncio.TimeoutError:
         proc.kill()
         await proc.wait()
@@ -192,7 +200,13 @@ def _read_package_xml_version(repo_path: Path) -> Optional[str]:
 
 
 async def _fetch_latest_tag(remote_url: str) -> Optional[str]:
-    rc, out, _ = await _git(['ls-remote', '--tags', remote_url])
+    try:
+        rc, out, _ = await _git(
+            ['ls-remote', '--tags', remote_url],
+            timeout=GIT_REMOTE_TIMEOUT,
+        )
+    except asyncio.TimeoutError:
+        return None
     if rc != 0:
         return None
     tags = []

{cyclo_manager-0.4.0.dev0 → cyclo_manager-1.0.0}/cyclo_host_agent/routers/update.py

@@ -19,28 +19,33 @@
 """System-level endpoints for the host agent."""
 
 import asyncio
-import logging
-import shutil
+import sys
 
 from fastapi import APIRouter, HTTPException, status
 
-logger = logging.getLogger(__name__)
-
 router = APIRouter(prefix='/system', tags=['system'])
 
 _update_status: dict = {'phase': 'idle', 'output': '', 'error': ''}
 
 
-async def _run_update(cyclo_exe: str) -> None:
+@router.get('/version')
+async def get_host_agent_version() -> dict:
+    """Return the running cyclo_host_agent package version."""
+    from cyclo_manager_cli import __version__
+
+    return {'version': __version__}
+
+
+async def _run_update() -> None:
     global _update_status
     try:
         proc = await asyncio.create_subprocess_exec(
-            cyclo_exe, 'update',
+            sys.executable, '-m', 'cyclo_manager_cli.cli', 'update',
             stdout=asyncio.subprocess.PIPE,
             stderr=asyncio.subprocess.PIPE,
         )
         stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=600)
-        out = (stdout.decode() + stderr.decode()).strip()
+        out = (stdout.decode(errors='replace') + stderr.decode(errors='replace')).strip()
         _update_status['output'] = out
         if proc.returncode != 0:
             _update_status['phase'] = 'error'
@@ -50,24 +55,22 @@ async def _run_update(cyclo_exe: str) -> None:
     except asyncio.TimeoutError:
         _update_status['phase'] = 'error'
         _update_status['error'] = 'cyclo_manager update timed out'
+    except Exception as e:
+        _update_status['phase'] = 'error'
+        _update_status['error'] = f'Failed to start cyclo_manager update: {e}'
 
 
 @router.post('/update')
 async def start_update() -> dict:
-    """Delegate update to cyclo_manager update, which handles containers and host agent restart."""
+    """Run cyclo_manager update in the background."""
     global _update_status
 
-    cyclo_exe = shutil.which('cyclo_manager')
-    if not cyclo_exe:
-        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-                            detail='cyclo_manager command not found')
-
     if _update_status.get('phase') == 'updating':
         raise HTTPException(status_code=status.HTTP_409_CONFLICT,
                             detail='Update already in progress')
 
     _update_status = {'phase': 'updating', 'output': '', 'error': ''}
-    asyncio.create_task(_run_update(cyclo_exe))
+    asyncio.create_task(_run_update())
     return {'status': 'update started'}
 
 

{cyclo_manager-0.4.0.dev0 → cyclo_manager-1.0.0}/cyclo_manager.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cyclo-manager
-Version: 0.4.0.dev0
+Version: 1.0.0
 Summary: cyclo_manager CLI: pip-installable launcher for cyclo_manager server and UI containers. Run 'cyclo_manager up' to start Docker stack.
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
@@ -18,7 +18,7 @@ Requires-Dist: ruff; extra == "dev"
 **Console commands:** `cyclo_manager` (underscore), `cyclo-manager` (hyphen)  
 **Host agent:** `cyclo_host_agent` (installed by the package, run via systemd)
 
-This package is the **pip-installable launcher** for the cyclo_manager stack on a robot host. It:
+This package is the **pip-installable launcher** for the cyclo_manager stack on a robot host. It is intended for production robots that run the pre-built Docker images. It:
 
 1. Runs **`docker compose`** against a **bundled** [`cyclo_manager_cli/docker/docker-compose.yml`](cyclo_manager_cli/docker/docker-compose.yml) to start the **API** and **web UI** containers.
 2. Installs and maintains **`cyclo_host_agent`** as a **systemd** service for host-level operations (git repo updates, `cyclo_manager` package update from the UI).
@@ -50,11 +50,12 @@ For the full monorepo (API source, UI source, dev compose), see the [repository
 
 ## Prerequisites
 
-- **Docker** with **Compose v2** (`docker compose` — the legacy `docker-compose` binary alone is not enough)
+- **Docker** with **Compose v2** (`docker compose`; the legacy `docker-compose` binary alone is not enough)
 - **Python 3.10+**
-- **`sudo`** — required to install the host agent systemd unit, socket directory permissions, and sudoers rules
+- **systemd**: required for the managed `cyclo_host_agent.service`
+- **`sudo`** — required on normal-user hosts to install the host agent systemd unit, socket directory permissions, and sudoers rules
 - For **`cyclo_manager update`:** **`pip`** or **`pip3`** on `PATH`
-- **Do not run as root** — the host agent runs as the invoking user (or `SUDO_USER` when using `sudo cyclo_manager up`). Running as root is rejected.
+- **Root shell handling** — `cyclo_manager up` rejects direct root execution when a normal login user exists. On root-only devices, the host agent is installed as root.
 - **Agent sockets** on the host under `/var/run/robotis/agent_sockets/` (robot containers and host agent). The bundled Compose file bind-mounts this tree into the API container as `/agents/`.
 
 ---
@@ -94,6 +95,8 @@ python3 -m cyclo_manager_cli.cli up
 | `cyclo_manager update --no-pull` | Same as `update`, but skip image pull (use locally cached images). |
 | `cyclo_manager --help` | Subcommand overview |
 
+The CLI also has an internal `refresh-host-agent` subcommand. It is used by the sudoers rule and should normally not be invoked by users directly.
+
 **`down` vs `update`:** `down` removes the host agent entirely. `update` only stops Docker containers, upgrades the pip package, restarts the stack, and refreshes the host agent — it does **not** call `cyclo_manager down`.
 
 ---
@@ -120,16 +123,21 @@ The pip package installs a small **FastAPI** server that listens on a **Unix dom
 |------|------|
 | Socket | `/var/run/robotis/agent_sockets/host/host_agent.sock` |
 | systemd unit | `cyclo_host_agent.service` |
-| sudoers | `/etc/sudoers.d/cyclo_manager` (`cp`, `udevadm` for container setup scripts) |
+| sudoers | `/etc/sudoers.d/cyclo_manager` (`cp`, `udevadm` for container setup scripts; `refresh-host-agent` CLI subcommand for package-update refresh; skipped on root-only devices) |
 
 The API container reaches it at `/agents/host/host_agent.sock` (see bundled `config.yml`).
 
 **Responsibilities:**
 
-- List and update **`~/ROBOTIS-GIT/*`** git repositories (Version Management in the UI)
-- Run **`cyclo_manager update`** when triggered from the UI (`POST /host/update`)
+- List managed **ROBOTIS-GIT** git repositories in the configured workspace.
+- Check update availability from remote tags and local `package.xml` versions.
+- Update repos on allowed branches (`main`, `jazzy`) using stash or reset workflows.
+- Stop/start a repo's `docker/container.sh` helper during an update when requested by the UI.
+- Run Cyclo Manager package updates from the UI by delegating to `cyclo_manager update`.
+
+`cyclo_manager up` installs the `refresh-host-agent` CLI subcommand into sudoers. It is registered as `sys.executable -m cyclo_manager_cli.cli refresh-host-agent` with `SETENV`, so UI-triggered updates can pass the current `PYTHONPATH` to sudo and do not depend on `PATH`. The command is idempotent and refreshes the socket directory, sudoers file, systemd unit, and service state after package upgrades.
 
-`cyclo_manager up` and `cyclo_manager update` both call `_ensure_host_agent()`, which is idempotent — safe to run after upgrades or user changes.
+Repository scanning uses `CYCLO_HOST_AGENT_WORKSPACE` when set. Otherwise it uses the service user's home directory, except root-only devices with `/data/docker`, where `/data/docker` is used automatically. Only repositories whose `origin` remote belongs to `ROBOTIS-GIT` are returned by the repo list/update endpoints.
 
 ---
 
@@ -139,8 +147,8 @@ Defined in [`cyclo_manager_cli/docker/docker-compose.yml`](cyclo_manager_cli/doc
 
 | Compose service | Container name | `cyclo_manager up` | Image (example) |
 |-----------------|----------------|--------------------|-----------------|
-| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:0.4.0` |
-| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:0.4.0` |
+| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:1.0.0` |
+| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:1.0.0` |
 | `rmw_zenoh` | `zenoh_daemon` | **Created only** | `robotis/zenoh-daemon:latest` |
 | `novnc-server` | `novnc-server` | **Created only** | `robotis/novnc-server:latest` |
 
@@ -160,7 +168,7 @@ The API reads it as `CONFIG_FILE=/app/config.yml` inside the container.
 
 | Key | Description |
 |-----|-------------|
-| **`robot_container`** | Primary robot Docker container name (e.g. `ai_worker`). Used by the UI System page and service bringup. Must be a key in `sockets` and cannot be `host_agent`. |
+| **`supported_robot_containers`** | Robot Docker container names that can open the System page (e.g. `ai_worker`, `open_manipulator`). Each must be a key in `sockets` and cannot be `host_agent`. |
 | **`sockets`** | Map of logical name → agent **Unix socket path as seen inside the API container** (under `/agents/...`). Include robot/service containers and `host_agent`. |
 
 s6 **service names** are not listed in config; each in-container agent reports them at runtime.
@@ -168,20 +176,17 @@ s6 **service names** are not listed in config; each in-container agent reports t
 ### Example (bundled default)
 
 ```yaml
-robot_container: ai_worker
+supported_robot_containers:
+  - ai_worker
+  - open_manipulator
 
 sockets:
   ai_worker: "/agents/ai_worker/s6_agent.sock"
+  open_manipulator: "/agents/open_manipulator/s6_agent.sock"
   cyclo_intelligence: "/agents/cyclo_intelligence/s6_agent.sock"
   host_agent: "/agents/host/host_agent.sock"
 ```
 
-### Validation (API startup)
-
-- At least one socket entry besides `host_agent`
-- `robot_container` must exist in `sockets`
-- All socket paths must be non-empty strings
-
 To use a different config layout, mounts, or local source builds, use the repository’s **`docker-compose.dev.yml`** — see [Custom config and development](#custom-config-and-development).
 
 ---
@@ -212,6 +217,7 @@ So `/agents/ai_worker/s6_agent.sock` in config corresponds to the host path abov
 | Variable | Set by | Purpose |
 |----------|--------|---------|
 | **`CYCLO_MANAGER_CONFIG_FILE`** | CLI (`up`, `down`, `update`) | Absolute path to bundled `config.yml` on the host; mounted into the API container |
+| **`CYCLO_HOST_AGENT_WORKSPACE`** | User or CLI-generated systemd unit | Workspace scanned by `cyclo_host_agent` for managed git repositories |
 | **`HOSTNAME`** | CLI (default: machine hostname) | Passed to API as `HOST_HOSTNAME` |
 | **`CONFIG_FILE`** | Compose (`/app/config.yml`) | Path inside the API container |
 | **`ROS_DOMAIN_ID`** | **Not** set by CLI | Set inside robot containers (e.g. `~/.bashrc`) so DDS matches your fleet |
@@ -253,7 +259,7 @@ Python dependencies declared in [`pyproject.toml`](pyproject.toml):
 |---------|---------|
 | **fastapi** | `cyclo_host_agent` HTTP API |
 | **uvicorn** | `cyclo_host_agent` server |
-| **psutil** | Host agent / system utilities |
+| **psutil** | Declared package dependency for host/system utility support |
 
 The **`cyclo_manager`** CLI itself uses only the Python standard library plus **`subprocess`** calls to **`docker compose`**, **`pip`**, **`systemctl`**, and **`sudo`**.
 

{cyclo_manager-0.4.0.dev0 → cyclo_manager-1.0.0}/cyclo_manager_cli/__init__.py

@@ -18,4 +18,4 @@
 
 """cyclo_manager CLI - pip-installable launcher for cyclo_manager server and UI containers."""
 
-__version__ = '0.4.0'
+__version__ = '1.0.0'

{cyclo_manager-0.4.0.dev0 → cyclo_manager-1.0.0}/cyclo_manager_cli/cli.py

@@ -26,6 +26,7 @@ Launches cyclo_manager server and UI via Docker.
 import argparse
 import os
 from pathlib import Path
+import pwd
 import shutil
 import socket
 import subprocess
@@ -36,10 +37,11 @@ HOST_AGENT_SERVICE = 'cyclo_host_agent'
 HOST_AGENT_SOCKET = '/var/run/robotis/agent_sockets/host/host_agent.sock'
 HOST_AGENT_SOCKET_DIR = '/var/run/robotis/agent_sockets/host'
 
-# `cyclo_manager up` starts these immediately.
+# `cyclo_manager up` starts these Containers immediately.
 COMPOSE_SERVICES_UP = ('cyclo_manager', 'ui')
 # These get `docker compose create` only (stopped); start from UI or `docker start`.
 COMPOSE_SERVICES_CREATE_ONLY = ('rmw_zenoh', 'novnc-server')
+DISABLED_LOGIN_SHELLS = {'', '/bin/false', '/sbin/nologin', '/usr/sbin/nologin'}
 
 
 def _docker_dir() -> Path:
@@ -55,6 +57,47 @@ def _packaged_config_path() -> Path:
     return _config_dir() / 'config.yml'
 
 
+def _sudo_cmd(args: list[str]) -> list[str]:
+    """Return args prefixed with sudo when the current process is not already root."""
+    if os.geteuid() == 0:
+        return args
+    return ['sudo', *args]
+
+
+def _user_home(user: str) -> Path:
+    """Return a user's home directory from passwd, with a conservative fallback."""
+    try:
+        return Path(pwd.getpwnam(user).pw_dir)
+    except KeyError:
+        if user == 'root':
+            return Path('/root')
+        return Path(f'/home/{user}')
+
+
+def _has_normal_login_user() -> bool:
+    """Return True when the host has a non-root login user."""
+    for account in pwd.getpwall():
+        if account.pw_name == 'root':
+            continue
+        if account.pw_uid < 1000 or account.pw_uid >= 65534:
+            continue
+        if account.pw_shell in DISABLED_LOGIN_SHELLS:
+            continue
+        return True
+    return False
+
+
+def _host_agent_workspace(user: str, user_home: Path) -> Path:
+    """Return the workspace path the host agent should scan for git repositories."""
+    configured_workspace = os.environ.get('CYCLO_HOST_AGENT_WORKSPACE')
+    if configured_workspace:
+        return Path(configured_workspace).expanduser()
+    data_docker = Path('/data/docker')
+    if user == 'root' and data_docker.is_dir():
+        return data_docker
+    return user_home
+
+
 def _resolve_service_user() -> tuple[str, Path] | None:
     """
     Return (username, home) for the host agent systemd service.
@@ -64,9 +107,15 @@ def _resolve_service_user() -> tuple[str, Path] | None:
     """
     sudo_user = os.environ.get('SUDO_USER')
     if sudo_user:
-        return sudo_user, Path(f'/home/{sudo_user}')
-    user = os.environ.get('USER') or os.getlogin()
+        return sudo_user, _user_home(sudo_user)
+    user = os.environ.get('USER') or pwd.getpwuid(os.getuid()).pw_name
     if user == 'root':
+        if not _has_normal_login_user():
+            print(
+                'Info: root-only device detected; cyclo_host_agent will run as root.',
+                file=sys.stderr,
+            )
+            return 'root', Path('/root')
         print(
             'Error: cyclo_manager up must run as a normal user (e.g. robotis), not root.',
             file=sys.stderr,
@@ -85,19 +134,19 @@ def _setup_socket_dir(user: str) -> bool:
     print(f'  [1/3] Creating socket directory {HOST_AGENT_SOCKET_DIR}...')
     try:
         subprocess.run(
-            ['sudo', 'mkdir', '-p', HOST_AGENT_SOCKET_DIR],
+            _sudo_cmd(['mkdir', '-p', HOST_AGENT_SOCKET_DIR]),
             check=True,
             capture_output=True,
         )
         print(f'  [2/3] Setting ownership to {user}:{user}...')
         subprocess.run(
-            ['sudo', 'chown', f'{user}:{user}', HOST_AGENT_SOCKET_DIR],
+            _sudo_cmd(['chown', f'{user}:{user}', HOST_AGENT_SOCKET_DIR]),
             check=True,
             capture_output=True,
         )
         print('  [3/3] Removing stale socket file (if any)...')
         subprocess.run(
-            ['sudo', 'rm', '-f', HOST_AGENT_SOCKET],
+            _sudo_cmd(['rm', '-f', HOST_AGENT_SOCKET]),
             check=True,
             capture_output=True,
         )
@@ -111,25 +160,34 @@ def _install_sudoers(user: str) -> bool:
     """
     Write sudoers rules for cyclo_manager.
 
-    Grant NOPASSWD for udev operations needed by container.sh
-    (cp to /etc/udev/rules.d/, udevadm control/trigger).
+    Grant NOPASSWD for udev operations and the root-only host-agent refresh command.
     """
-    print('  Installing sudoers rules (cp, udevadm)...')
+    if not sys.executable:
+        print(
+            'Python executable is unknown. '
+            'Run `pip install cyclo-manager` and retry.',
+            file=sys.stderr,
+        )
+        return False
+
+    print('  Installing sudoers rules (cp, udevadm, host-agent refresh command)...')
     sudoers_content = (
         f'{user} ALL=(ALL) NOPASSWD: /usr/bin/cp, '
         f'/usr/bin/udevadm control --reload-rules, '
-        f'/usr/bin/udevadm trigger\n'
+        f'/usr/bin/udevadm trigger, '
+        'SETENV: '
+        f'{sys.executable} -m cyclo_manager_cli.cli refresh-host-agent\n'
     )
     sudoers_file = '/etc/sudoers.d/cyclo_manager'
     try:
         subprocess.run(
-            ['sudo', 'tee', sudoers_file],
+            _sudo_cmd(['tee', sudoers_file]),
             input=sudoers_content.encode(),
             capture_output=True,
             check=True,
         )
         subprocess.run(
-            ['sudo', 'chmod', '440', sudoers_file],
+            _sudo_cmd(['chmod', '440', sudoers_file]),
             check=True,
             capture_output=True,
         )
@@ -139,7 +197,7 @@ def _install_sudoers(user: str) -> bool:
         return False
 
 
-def _ensure_host_agent() -> int:
+def _ensure_host_agent(restart_no_block: bool = False) -> int:
     """
     Install or refresh cyclo_host_agent: systemd unit, socket dir, and service start.
 
@@ -151,10 +209,11 @@ def _ensure_host_agent() -> int:
         return 1
 
     user, user_home = account
-    agent_exe = shutil.which('cyclo_host_agent')
-    if not agent_exe:
+    workspace_path = _host_agent_workspace(user, user_home)
+    agent_exec_start = f'{sys.executable} -m cyclo_host_agent.main' if sys.executable else None
+    if not agent_exec_start:
         print(
-            'Warning: cyclo_host_agent not found in PATH. '
+            'Warning: Python executable is unknown. '
             'Run `pip install cyclo-manager` and retry.',
             file=sys.stderr,
         )
@@ -163,7 +222,7 @@ def _ensure_host_agent() -> int:
     if not _setup_socket_dir(user):
         return 1
 
-    if not _install_sudoers(user):
+    if user != 'root' and not _install_sudoers(user):
         return 1
 
     service_content = f"""\
@@ -177,8 +236,9 @@ User={user}
 Group={user}
 RuntimeDirectory=robotis/agent_sockets/host
 RuntimeDirectoryMode=0755
-ExecStart={agent_exe}
+ExecStart={agent_exec_start}
 Environment=HOME={user_home}
+Environment=CYCLO_HOST_AGENT_WORKSPACE={workspace_path}
 Restart=always
 RestartSec=3
 
@@ -192,22 +252,29 @@ WantedBy=multi-user.target
     try:
         print(f'  Writing unit file to {service_file}...')
         subprocess.run(
-            ['sudo', 'tee', service_file],
+            _sudo_cmd(['tee', service_file]),
             input=service_content.encode(),
             capture_output=True,
             check=True,
         )
         print('  Running systemctl daemon-reload...')
-        subprocess.run(['sudo', 'systemctl', 'daemon-reload'], check=True, capture_output=True)
+        subprocess.run(
+            _sudo_cmd(['systemctl', 'daemon-reload']),
+            check=True,
+            capture_output=True,
+        )
         print(f'  Enabling {HOST_AGENT_SERVICE}...')
         subprocess.run(
-            ['sudo', 'systemctl', 'enable', f'{HOST_AGENT_SERVICE}.service'],
+            _sudo_cmd(['systemctl', 'enable', f'{HOST_AGENT_SERVICE}.service']),
             check=True,
             capture_output=True,
         )
         print(f'  Starting {HOST_AGENT_SERVICE}...')
+        restart_cmd = ['systemctl', 'restart', f'{HOST_AGENT_SERVICE}.service']
+        if restart_no_block:
+            restart_cmd.insert(1, '--no-block')
         subprocess.run(
-            ['sudo', 'systemctl', 'restart', f'{HOST_AGENT_SERVICE}.service'],
+            _sudo_cmd(restart_cmd),
             check=True,
             capture_output=True,
         )
@@ -217,10 +284,54 @@ WantedBy=multi-user.target
         print(f'Failed to install host agent service: {e}', file=sys.stderr)
         return 1
     except FileNotFoundError:
-        print('sudo not found. Install the host agent service manually.', file=sys.stderr)
+        print(
+            'Required command not found. Install the host agent service manually.',
+            file=sys.stderr,
+        )
         return 1
 
 
+def _refresh_host_agent_after_update() -> int:
+    """Refresh host agent with the sudoers-registered cyclo_manager command when possible."""
+    if os.geteuid() == 0:
+        return _ensure_host_agent(restart_no_block=True)
+    if not sys.executable:
+        print(
+            'Python executable is unknown; falling back to setup.',
+            file=sys.stderr,
+        )
+        return _ensure_host_agent() if sys.stdin.isatty() else 1
+
+    refresh_command = [sys.executable, '-m', 'cyclo_manager_cli.cli', 'refresh-host-agent']
+    print(f'Refreshing host agent with sudo command: {" ".join(refresh_command)}')
+    pythonpath = os.pathsep.join(dict.fromkeys(path for path in sys.path if path))
+    try:
+        subprocess.run(['sudo', '-n', f'PYTHONPATH={pythonpath}', *refresh_command], check=True)
+        return 0
+    except subprocess.CalledProcessError as e:
+        if sys.stdin.isatty():
+            print(
+                'Warning: sudo refresh command failed; falling back to interactive setup.',
+                file=sys.stderr,
+            )
+            return _ensure_host_agent()
+        print(f'Host-agent refresh command failed: {e}', file=sys.stderr)
+        return e.returncode
+    except FileNotFoundError:
+        if sys.stdin.isatty():
+            return _ensure_host_agent()
+        print('sudo not found; cannot refresh host agent service.', file=sys.stderr)
+        return 1
+
+
+def cmd_refresh_host_agent(args: argparse.Namespace) -> int:
+    """Refresh the host agent from sudoers after a package update."""
+    if os.geteuid() != 0:
+        print('cyclo_manager refresh-host-agent must run as root.', file=sys.stderr)
+        return 1
+    return _ensure_host_agent(restart_no_block=True)
+
+
 def cmd_up(args: argparse.Namespace) -> int:
     """Start API + UI; create zenoh and noVNC containers without starting them."""
     print('--- cyclo_manager up ---')
@@ -272,15 +383,21 @@ def _teardown_host_agent() -> None:
     """Stop and remove the host agent service, unit file, sudoers, and socket dir."""
     print(f'Tearing down {HOST_AGENT_SERVICE}...')
     steps = [
-        (['sudo', 'systemctl', 'stop', f'{HOST_AGENT_SERVICE}.service'], 'stop service'),
-        (['sudo', 'systemctl', 'disable', f'{HOST_AGENT_SERVICE}.service'], 'disable service'),
         (
-            ['sudo', 'rm', '-f', f'/etc/systemd/system/{HOST_AGENT_SERVICE}.service'],
+            _sudo_cmd(['systemctl', 'stop', f'{HOST_AGENT_SERVICE}.service']),
+            'stop service',
+        ),
+        (
+            _sudo_cmd(['systemctl', 'disable', f'{HOST_AGENT_SERVICE}.service']),
+            'disable service',
+        ),
+        (
+            _sudo_cmd(['rm', '-f', f'/etc/systemd/system/{HOST_AGENT_SERVICE}.service']),
             'remove unit file',
         ),
-        (['sudo', 'systemctl', 'daemon-reload'], 'daemon-reload'),
-        (['sudo', 'rm', '-f', '/etc/sudoers.d/cyclo_manager'], 'remove sudoers'),
-        (['sudo', 'rm', '-rf', HOST_AGENT_SOCKET_DIR], 'remove socket dir'),
+        (_sudo_cmd(['systemctl', 'daemon-reload']), 'daemon-reload'),
+        (_sudo_cmd(['rm', '-f', '/etc/sudoers.d/cyclo_manager']), 'remove sudoers'),
+        (_sudo_cmd(['rm', '-rf', HOST_AGENT_SOCKET_DIR]), 'remove socket dir'),
     ]
     for cmd, desc in steps:
         print(f'  {desc}...')
@@ -384,7 +501,7 @@ def cmd_update(args: argparse.Namespace) -> int:
         return e.returncode
 
     print('Refreshing host agent (unit, socket, sudoers)...')
-    if _ensure_host_agent() != 0:
+    if _refresh_host_agent_after_update() != 0:
         print('Warning: Failed to refresh host agent service.', file=sys.stderr)
         return 1
 
@@ -425,8 +542,18 @@ def main() -> int:
     )
     update_parser.set_defaults(func=cmd_update)
 
+    refresh_parser = sub.add_parser(
+        'refresh-host-agent',
+        help='Refresh cyclo_host_agent service after package update',
+    )
+    refresh_parser.set_defaults(func=cmd_refresh_host_agent)
+
     args = parser.parse_args()
     if not args.command:
         parser.print_help()
         return 0
     return args.func(args)
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

{cyclo_manager-0.4.0.dev0 → cyclo_manager-1.0.0}/cyclo_manager_cli/config/config.yml

@@ -1,8 +1,11 @@
 # cyclo_manager Configuration
 
-robot_container: ai_worker
+supported_robot_containers:
+  - ai_worker
+  - open_manipulator
 
 sockets:
   ai_worker: "/agents/ai_worker/s6_agent.sock"
+  open_manipulator: "/agents/open_manipulator/s6_agent.sock"
   cyclo_intelligence: "/agents/cyclo_intelligence/s6_agent.sock"
   host_agent: "/agents/host/host_agent.sock"

{cyclo_manager-0.4.0.dev0 → cyclo_manager-1.0.0}/cyclo_manager_cli/docker/docker-compose.yml

@@ -11,7 +11,7 @@ services:
 
   cyclo_manager:
     container_name: cyclo_manager
-    image: robotis/cyclo-manager:0.4.0
+    image: robotis/cyclo-manager:1.0.0
     restart: always
     network_mode: host
     volumes:
@@ -27,7 +27,7 @@ services:
 
   ui:
     container_name: cyclo_manager_ui
-    image: robotis/cyclo-manager-ui:0.4.0
+    image: robotis/cyclo-manager-ui:1.0.0
     restart: always
     network_mode: host
     environment:

{cyclo_manager-0.4.0.dev0 → cyclo_manager-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cyclo-manager"
-version = "0.4.0.dev0"
+version = "1.0.0"
 description = "cyclo_manager CLI: pip-installable launcher for cyclo_manager server and UI containers. Run 'cyclo_manager up' to start Docker stack."
 readme = "README.md"
 license = "Apache-2.0"