clawcu 0.2.9

ClawCU: a local multi-agent lifecycle manager for OpenClaw and Hermes

ClawCU

🌐 Language: English | 中文

ClawCU is a local-first lifecycle manager for running multiple AI agent runtimes on one machine. It currently supports OpenClaw and Hermes Agent.

Contents

• Highlights
• Install
• Quick Start
• Safe Upgrade Workflow
• Model Configuration
• Environment and Access
• Changelog
• Contributing
• Uninstall
• License

Highlights

• One CLI, two runtimes — OpenClaw and Hermes through the same lifecycle commands
• Snapshots before every upgrade — datadir and env both captured; rollback restores from real backups
• Clone-first experiments — copy an instance, upgrade the copy, leave the original running

$ clawcu list
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ NAME            ┃ SERVICE  ┃ VERSION   ┃ PORT  ┃ STATUS  ┃ ACCESS          ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ writer          │ openclaw │ 2026.4.1  │ 18799 │ running │ 127.0.0.1:18799 │
│ analyst         │ hermes   │ 2026.4.13 │ 9129  │ running │ 127.0.0.1:9129  │
└─────────────────┴──────────┴───────────┴───────┴─────────┴─────────────────┘

Available versions (top 10 by semver, newest first)
  openclaw  2026.4.15, 2026.4.14, 2026.4.12, 2026.4.11, 2026.4.10, 2026.4.9,
            2026.4.8, 2026.4.7, 2026.4.5, 2026.4.2
  hermes    2026.4.16, 2026.4.13, 2026.4.8, 2026.4.3, 2026.3.30

Install

Requires Python 3.11+ and a running Docker daemon.

pip install clawcu

or, for isolated CLI installs:

pipx install clawcu
# or
uv tool install clawcu

Quick Start

First-time setup — checks Docker access and configures defaults:

clawcu setup

Spin up an OpenClaw instance and open the TUI:

clawcu pull openclaw --version 2026.4.1
clawcu create openclaw --name writer --version 2026.4.1
clawcu tui writer

Or spin up a Hermes instance with the same shape:

clawcu pull hermes --version 2026.4.13
clawcu create hermes --name analyst --version 2026.4.13
clawcu tui analyst

For the full command reference (list / inspect / exec / upgrade / provider …), see the USAGE reference.

Safe Upgrade Workflow

Upgrade on a clone first; promote only if the clone holds:

clawcu clone writer --name writer-upgrade-test
clawcu upgrade writer-upgrade-test --version 2026.4.10
clawcu rollback writer-upgrade-test    # if the new version misbehaves

Every upgrade snapshots the instance datadir and the matching env file (~/.clawcu/instances/<instance>.env for OpenClaw, <datadir>/.env for Hermes) before replacing the container. If the upgrade fails, ClawCU restores both automatically.

Model Configuration

Collect API keys and model lists from any managed instance or local home, and apply them elsewhere:

clawcu provider collect --all
clawcu provider list
clawcu provider apply openclaw:minimax writer --agent main --primary minimax/MiniMax-M2.7

Service identity is stored with each collected bundle, so OpenClaw and Hermes configs with the same logical name do not silently collide.

Environment and Access

Env files live per service (not unified):

• OpenClaw: ~/.clawcu/instances/<instance>.env
• Hermes: <datadir>/.env

Manage them with clawcu setenv / getenv / unsetenv (pass --apply to recreate the container immediately). Service-specific access: clawcu token <instance> and clawcu approve <instance> are OpenClaw-only (dashboard token + pairing model); Hermes uses clawcu tui / config / exec as its operational entrypoints. Full command reference: release/.

Changelog

See CHANGELOG.md for release history. Per-version release notes live in release/.

Contributing

Issues and PRs welcome at github.com/heguangzhu/clawcu/issues.

Local development:

git clone https://github.com/heguangzhu/clawcu.git
cd clawcu
uv sync --all-extras
uv run pytest -q

Uninstall

pip uninstall clawcu
# or
pipx uninstall clawcu
# or
uv tool uninstall clawcu

Uninstalling the CLI leaves every datadir under ~/.clawcu intact. Remove instance data explicitly with clawcu remove <name> --delete-data before uninstalling if you want it gone.

License

MIT — see LICENSE.