Metadata-Version: 2.4
Name: pphermes
Version: 1.1.2
Summary: One-click launch of Hermes Agent on PPIO Agent Sandbox
Author-email: PPIO <hello@ppio.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.25
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0

# PPHermes

One-click launch of [Hermes Agent](https://github.com/anthropics/hermes) on [PPIO Agent Sandbox](https://ppio.com/docs/sandbox/overview.md).

## Install

```bash
pip install pphermes
```

**macOS / Linux:**

```bash
curl -fsSL https://pphermes.ppio.com/install.sh | bash
```

**Windows (PowerShell):**

```powershell
irm https://pphermes.ppio.com/install.ps1 | iex
```

## Quick Start

```bash
# Set your API key
export PPIO_API_KEY="your-key"

# Launch a Hermes sandbox
pphermes launch

# List sandboxes
pphermes list

# Check status
pphermes status <sandbox_id>

# Stop a sandbox
pphermes stop <sandbox_id>
```

### On-demand mode (auto-pause / auto-resume)

```bash
# Auto-pause after 10 minutes of inactivity (default), resume on demand
pphermes launch --type on-demand

# Custom idle threshold (seconds, min 60)
pphermes launch --type on-demand --idle-timeout 1800
```

`on-demand` sandboxes hibernate when idle and only bill for active time.
Idle is detected by combining hermes' `state.db` last-message timestamp,
WAL mtime, running background processes, and upcoming cron jobs — long
tool calls and scheduled jobs are NOT misclassified as idle. The sandbox
auto-resumes on incoming HTTP traffic or shortly before a cron fires.

If your workflow runs tool calls that exceed 10 minutes (training,
long builds, large pulls), bump `--idle-timeout` accordingly or use
`--type always-on`.

### Pair a Feishu / Lark channel

```bash
# WebSocket mode (recommended — no public callback URL needed)
pphermes pair feishu <sandbox_id> --app-id cli_xxx --app-secret xxx

# Webhook mode — response surfaces the exact callback URL to paste into
# Feishu Open Platform → Event Subscription → Request URL.
pphermes pair feishu <sandbox_id> --app-id cli_xxx --app-secret xxx \
  --mode webhook --verification-token tok_xxx --json | jq -r .feishu_webhook_url
```

The Hermes Agent's webhook adapter binds **port 8765 + path
`/feishu/webhook`** — different from the OpenClaw convention
(`3000` + `/feishu/events`). Always copy the URL from the pair
command's response rather than hand-constructing it.

## Migrating from OpenClaw

If you already run an OpenClaw sandbox and want to switch to Hermes, copy
the full `~/.openclaw` agent state in a single command. Under the hood
PPHermes tars the source directory, uploads it **directly** to the target
sandbox's File Manager, then invokes Hermes's native `hermes claw migrate`
command — so SOUL.md, memories, skills, command allowlist, messaging
settings, secrets, TTS audio, and AGENTS.md all come along. The archive
never crosses our API server.

```bash
# Preview the migration (no writes on the target)
pphermes migrate <hermes_id> --from <openclaw_id> --dry-run

# Apply (default preset=full migrates everything, including secrets)
pphermes migrate <hermes_id> --from <openclaw_id> -y

# Skip secrets — keep the target Hermes .env as-is
pphermes migrate <hermes_id> --from <openclaw_id> --preset user-data -y

# Replace existing Hermes files on conflict (otherwise Hermes reports them)
pphermes migrate <hermes_id> --from <openclaw_id> --overwrite -y

# Drop bulky TTS audio from the tarball
pphermes migrate <hermes_id> --from <openclaw_id> --exclude-tts -y

# Also print step-by-step instructions for copying workspace files manually
pphermes migrate <hermes_id> --from <openclaw_id> --print-workspace-guide -y
```

Workspace files (`~/workspace/`, local repos) are NOT transferred
automatically — both products ship File Manager on port 7682 so you can
download from the source and upload to the target manually. See
[docs/design/migration.md](../../docs/design/migration.md) for details.

## Documentation

- [CLI Skill Reference](https://pphermes.ppio.com/skill.md)
- [API Key Guide](https://ppio.com/docs/support/api-key)
