Metadata-Version: 2.4
Name: clawd
Version: 0.5.1
Summary: LocalClaw: a local multi-agent lifecycle manager for OpenClaw and Hermes
Author-email: Michael He <heguangzhu@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/heguangzhu/clawd
Project-URL: Repository, https://github.com/heguangzhu/clawd
Project-URL: Changelog, https://github.com/heguangzhu/clawd/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/heguangzhu/clawd/issues
Keywords: docker,openclaw,hermes,agent,cli,lifecycle
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9.0,>=8.0
Requires-Dist: PyYAML<7.0,>=6.0
Requires-Dist: rich<14.0.0,>=13.7.0
Requires-Dist: typer<1.0.0,>=0.12.3
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.2.0; extra == "dev"
Dynamic: license-file

# LocalClaw

🌐 Language:
[English](README.md) | [中文](README.zh-CN.md)

[![PyPI](https://img.shields.io/pypi/v/clawd.svg)](https://pypi.org/project/clawd/)
[![Python](https://img.shields.io/pypi/pyversions/clawd.svg)](https://pypi.org/project/clawd/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![CI](https://github.com/heguangzhu/clawd/actions/workflows/ci.yml/badge.svg)](https://github.com/heguangzhu/clawd/actions/workflows/ci.yml)

`LocalClaw` is a local-first lifecycle manager for running multiple AI agent runtimes on one machine. It currently supports [OpenClaw](https://github.com/openclaw/openclaw) and [Hermes Agent](https://github.com/NousResearch/hermes-agent).

<details>
<summary>Contents</summary>

- [Highlights](#highlights)
- [Install](#install)
- [Quick Start](#quick-start)
- [Safe Upgrade Workflow](#safe-upgrade-workflow)
- [Model Configuration](#model-configuration)
- [Environment and Access](#environment-and-access)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Uninstall](#uninstall)
- [License](#license)

</details>

## 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
- **Available versions with cache-aware refresh** — `clawd list --versions` shows upgrade candidates from the configured registries, served from a day-cache by default. Add `--no-cache` to force a fresh registry read when you want the latest tags now.

```text
$ clawd 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  │
└─────────────────┴──────────┴───────────┴───────┴─────────┴─────────────────┘
```

Pass `--versions` to see available upgrade candidates (cached per day):

```text
$ clawd list --versions
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ 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.

```bash
pip install clawd
```

or, for isolated CLI installs:

```bash
pipx install clawd
# or
uv tool install clawd
```

## Quick Start

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

```bash
clawd setup
```

Spin up an OpenClaw instance and open the TUI:

```bash
clawd create openclaw --name writer --version 2026.4.1
clawd tui writer
```

If you maintain a custom runtime image, keep the logical service version explicit and override only the runtime image:

```bash
clawd create openclaw \
  --name writer-tools \
  --version 2026.4.1 \
  --image registry.example.com/openclaw:2026.4.1-tools
```

Or spin up a Hermes instance with the same shape:

```bash
clawd create hermes --name analyst --version 2026.4.13
clawd tui analyst
```

Configure providers / models inside an instance via its service-native flow (OpenClaw's `configure`, Hermes's `setup`):

```bash
clawd config writer
```

Open the web dashboard to see all instances, providers, and upgrade candidates at a glance (runs as a persistent Docker container):

```bash
clawd dashboard
```

![Dashboard](docs/images/en.png)

See what versions are available for upgrade (cached per day; add `--no-cache` to force a fresh fetch):

```bash
clawd list --versions
clawd list --versions --no-cache
```

For the full command reference (`list` / `inspect` / `exec` / `upgrade` / `provider` …), see [USAGE_latest.md](release/USAGE_latest.md).

## Safe Upgrade Workflow

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

```bash
clawd clone writer --name writer-upgrade-test
clawd upgrade writer-upgrade-test --version 2026.4.10
clawd rollback writer-upgrade-test    # if the new version misbehaves
```

`upgrade` also accepts `--image` when you want to keep the target version label explicit but run a custom image:

```bash
clawd upgrade writer-upgrade-test \
  --version 2026.4.10 \
  --image registry.example.com/openclaw:2026.4.10-tools
```

Every `upgrade` snapshots the instance datadir and the matching env file (`~/.localclaw/instances/<instance>.env` for OpenClaw, `<datadir>/.env` for Hermes) before replacing the container. If the upgrade fails, LocalClaw restores both automatically. When `--image` is used, the chosen runtime image is persisted as part of the instance state, so later `recreate`, orphan recovery, and `rollback` continue using the same recorded image chain.

## Model Configuration

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

```bash
clawd provider collect --all
clawd provider list
clawd 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: `~/.localclaw/instances/<instance>.env`
- Hermes: `<datadir>/.env`

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

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history. Latest release notes: [RELEASE_latest.md](release/RELEASE_latest.md).

## Contributing

Issues and PRs welcome at [github.com/heguangzhu/clawd/issues](https://github.com/heguangzhu/clawd/issues).

Local development:

```bash
git clone https://github.com/heguangzhu/clawd.git
cd localclaw
uv sync --all-extras
uv run pytest -q
```

## Uninstall

```bash
pip uninstall clawd
# or
pipx uninstall clawd
# or
uv tool uninstall clawd
```

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

## License

MIT — see [LICENSE](LICENSE).
