Metadata-Version: 2.4
Name: exolimbs
Version: 0.7.1
Summary: Run ClawHub skills, sandbox, Playwright browser & multi-language runtimes as Hermes hands/feet. Structured JSON, zero extra LLM tokens.
Author-email: seanyang1983 <yase19636404@163.com>
License: MIT
Project-URL: Homepage, https://github.com/seanyang1983/exolimbs
Project-URL: Issues, https://github.com/seanyang1983/exolimbs/issues
Project-URL: Store, https://your-store.example.com
Keywords: hermes,openclaw,clawhub,agent,sandbox,playwright,skills
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7,>=6
Provides-Extra: browser
Requires-Dist: playwright<2,>=1.44; extra == "browser"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Dynamic: license-file

# Exolimbs — Hermes plugin

> Give your Hermes agent OpenClaw / ClawHub's hands and feet.
> Run community skills, an isolated sandbox, a Playwright browser, and
> multi-language runtimes — through a tiny structured-JSON tool surface, with
> **zero extra LLM tokens** on the execution path.

Hermes is the brain. Exolimbs is the deterministic execution substrate. It
never calls a model itself, has no conversation/memory/UI, and exposes six tools.

> ℹ️ "Exolimbs" is the working title. **Rename before any commercial
> launch** — see `DESIGN.md` → *Naming & legal*. The package, plugin name, and
> entry point are all in one place each, so renaming is a 5-minute job.

## Tools

| Tool | What it does |
|------|--------------|
| `claw_skill_search` | Search the ClawHub registry |
| `claw_skill_install` | Install + verify a skill (slug / `git:owner/repo@ref` / local path) |
| `claw_skill_run` | Deterministically run a skill's script entrypoint |
| `claw_sandbox_exec` | Run a command in an isolated (Docker) sandbox with rollback |
| `claw_browser` | Playwright browser automation via a structured action list |
| `claw_runtime` | Quick snippet in python / node / bash / ruby / go |

## Multiple skill markets

Switch the skills marketplace with `openclaw_lite.market` (or `EXOLIMBS_MARKET`):

| Market | Source | Notes |
|--------|--------|-------|
| `clawhub` (default) | clawhub.ai | Official OpenClaw registry, HTTP API v1 |
| `skillhub` | api.skillhub.cn | China-focused market (75k+ skills); server-side keyword search, public zip download |

```yaml
openclaw_lite:
  market: skillhub            # or clawhub
  # registry_base_url: https://clawhub.ai      # clawhub override
  # skillhub_base_url: https://api.skillhub.cn # skillhub override
```

Adding another market = one adapter class in `exolimbs/registries.py`.

## Two interchangeable backends

Set `exolimbs.backend` in `~/.hermes/config.yaml` (or `EXOLIMBS_BACKEND`):

| Mode | Behaviour |
|------|-----------|
| `cli` | Bridges to the real `openclaw` / `clawhub` CLIs (`--non-interactive --json`). Best registry parity. Requires Node + OpenClaw installed. |
| `native` | Fully decoupled Python substrate. No Node needed. Handles sandbox/browser/runtime + `git:`/local skill installs natively. |
| `auto` (default) | `cli` if the `openclaw` binary is on PATH, else `native`. |

## Install

**As a directory plugin (simplest):**

```bash
# copy the package into your Hermes plugins dir
cp -r exolimbs ~/.hermes/plugins/exolimbs
hermes plugins enable exolimbs
```

**As a pip package (distribution):**

```bash
pip install exolimbs           # core
pip install "exolimbs[browser]" # + Playwright
playwright install chromium          # one-time browser download
hermes plugins enable exolimbs
```

Verify inside a session:

```
/exo doctor
```

## Configure (`~/.hermes/config.yaml`)

```yaml
exolimbs:
  backend: auto            # auto | cli | native
  sandbox_enabled: true
  sandbox_image: "python:3.12-slim"
  sandbox_network: false
  default_timeout_s: 120
  max_retries: 2
  rollback: true
  registry_base_url: "https://clawhub.ai"
  browser_headless: true
  # Pro:
  audit_log: false
  # license_key: "EXL1...."   # or set EXOLIMBS_LICENSE in .env
```

## Free vs Pro (open-core)

- **Free:** all six tools, both backends, retry/rollback, trust-envelope verify.
- **Pro:** JSONL audit log, curated/verified skill packs, auto-update, priority
  support. Unlock with `EXOLIMBS_LICENSE`. See `DESIGN.md` for pricing/channels.

Licenses are signed **Ed25519** tokens (`EXL1.<payload>.<signature>`), verified
fully **offline** against an embedded public key — no phone-home, air-gap safe.

**Issuing licenses (vendor-side only):**

```bash
python scripts/gen_keys.py                 # once: make keypair (seed -> .secrets/, git-ignored)
                                           # paste printed public key into exolimbs/_licensing.py
python scripts/issue_license.py --sub alice@example.com --tier pro --days 365
# -> prints EXL1.<...> ; customer sets EXOLIMBS_LICENSE to that token
```

Revoke an issued license by adding its `jti` to `_REVOKED` in `_licensing.py` and
shipping a release.

## Security

Third-party skills are untrusted code. Prefer `claw_sandbox_exec` with
`network: false` for anything you don't fully trust. Without Docker, sandbox
calls run locally and are flagged `"sandboxed": false`.

## Dashboard UI (optional)

A web UI ships in `dashboard/` for the Hermes dashboard (`hermes dashboard`).
Install the plugin into your Hermes home and restart the dashboard:

```bash
cp -r exolimbs "$HERMES_HOME/plugins/exolimbs"   # default HERMES_HOME = ~/.hermes
# restart: hermes dashboard
```

An **Exolimbs** tab appears (after Skills) with: status, skill search
(ClawHub/SkillHub toggle), curated packs, and a runtime tester. It follows the
active dashboard theme automatically (uses the host SDK components). Backend
routes are mounted at `/api/plugins/exolimbs/` on dashboard startup.

## Try it locally (no Hermes, no GUI — it's a headless engine)

Exolimbs has no UI by design; you "experience" it by calling its tools and
reading the JSON. The demo script lets you do that directly:

```bash
python scripts/demo.py doctor                  # backend / license status
python scripts/demo.py packs                   # curated packs
python scripts/demo.py search github 5         # live ClawHub search
python scripts/demo.py runtime python "print(6*7)"
python scripts/demo.py sandbox "echo hi"
python scripts/demo.py menu                     # interactive
```

To use it inside the agent instead, copy `exolimbs/` into
`~/.hermes/plugins/exolimbs/` (or `pip install exolimbs`), then
`hermes plugins enable exolimbs` and try `/exo doctor` in a session.

## Development

```bash
pip install -e ".[dev,browser]"
pytest -q
```

## License

MIT (this plugin). Not affiliated with OpenClaw/ClawHub. See `LICENSE`.
