PPHermes

One-click launch of Hermes Agent on PPIO Agent Sandbox.

Install

pip install pphermes

macOS / Linux:

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

Windows (PowerShell):

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

Quick Start

# 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)

# 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

# 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.

# 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 for details.

Documentation

• CLI Skill Reference
• API Key Guide