cyclo_manager CLI

PyPI package: cyclo-manager
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:

1. Runs docker compose against a bundled 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).
3. Can pip install -U itself and bring the Docker stack back up.

Implementation: cyclo_manager_cli/cli.py, cyclo_host_agent/.

For the full monorepo (API source, UI source, dev compose), see the repository root README.

Table of contents

• Prerequisites
• Install
• Commands
• What cyclo_manager up does
• Host agent (cyclo_host_agent)
• Compose services
• Configuration
• Agent sockets on the host
• Environment variables
• URLs (packaged stack)
• Custom config and development
• Dependencies
• License

Prerequisites

• Docker with Compose v2 (docker compose — the legacy docker-compose binary alone is not enough)
• Python 3.10+
• 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
• Root shell handling — root is rejected 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/.

Install

From PyPI:

pip install cyclo-manager

If cyclo_manager is not on PATH, add the user script directory:

export PATH="$HOME/.local/bin:$PATH"
cyclo_manager up

If the entry point is missing:

python3 -m cyclo_manager_cli.cli --help
python3 -m cyclo_manager_cli.cli up

Commands

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.

What cyclo_manager up does

Three phases:

[1/3] Setting up host agent     → systemd unit, socket ownership, sudoers
[2/3] Starting containers       → cyclo_manager (API) + ui
[3/3] Creating (not starting)   → zenoh_daemon + novnc-server

Open http://127.0.0.1:3000 (UI) and http://127.0.0.1:8081/docs (API).

Host agent (cyclo_host_agent)

The pip package installs a small FastAPI server that listens on a Unix domain socket on the host:

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)

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.

Compose services

Defined in cyclo_manager_cli/docker/docker-compose.yml. All services use network_mode: host.

Start optional containers from the UI or manually, e.g. docker start zenoh_daemon.

Configuration

The CLI always mounts the bundled config into the API container. There is no -c / --config flag on the pip CLI.

Bundled path: cyclo_manager_cli/config/config.yml

The API reads it as CONFIG_FILE=/app/config.yml inside the container.

Schema

s6 service names are not listed in config; each in-container agent reports them at runtime.

Example (bundled default)

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"

To use a different config layout, mounts, or local source builds, use the repository’s docker-compose.dev.yml — see Custom config and development.

Agent sockets on the host

On the host, sockets typically live under:

/var/run/robotis/agent_sockets/
├── ai_worker/s6_agent.sock
├── cyclo_intelligence/s6_agent.sock
└── host/host_agent.sock          ← created by cyclo_manager up

The bundled compose file mounts the parent directory:

- /var/run/robotis/agent_sockets:/agents

So /agents/ai_worker/s6_agent.sock in config corresponds to the host path above.

Environment variables

URLs (packaged stack)

With network_mode: host and default ports:

Custom config and development

The pip workflow is intended for production robots with pre-built images.

For development (local API/UI source, custom config.yml, hot reload):

# From repository root
docker compose -f docker-compose.dev.yml up

See the root README.

Dependencies

Python dependencies declared in pyproject.toml:

The cyclo_manager CLI itself uses only the Python standard library plus subprocess calls to docker compose, pip, systemctl, and sudo.

Runtime outside Python:

• Docker + Compose v2
• systemd (host agent service)
• Pre-built Docker images referenced in the bundled compose file

License

SPDX: Apache-2.0 (see pyproject.toml and the repository LICENSE).