![\"clawmacdo](\"clawmacdo.png\")
\n\n \n
` when you already have an 8-character Telegram pairing code to approve in the same run. The default fast budgets are `--active-timeout-secs 120` and `--ssh-timeout-secs 30`; actual restore time still depends on Lightsail making the instance runnable.\n\n### Destroy an Instance\n\nDelete an instance by name across any supported provider. Removes cloud SSH key, local key, and (for BytePlus) EIP and VPC resources.\n\n```bash\n# DigitalOcean\nclawmacdo destroy \\\n --provider digitalocean \\\n --do-token \"$DO_TOKEN\" \\\n --name \"openclaw-abc123\"\n\n# Tencent Cloud (skip confirmation prompt)\nclawmacdo destroy \\\n --provider tencent \\\n --tencent-secret-id \"$TENCENT_SECRET_ID\" \\\n --tencent-secret-key \"$TENCENT_SECRET_KEY\" \\\n --name \"openclaw-abc123\" \\\n --yes\n\n# BytePlus (also releases EIP and VPC resources)\nclawmacdo destroy \\\n --provider byteplus \\\n --byteplus-access-key \"$BYTEPLUS_ACCESS_KEY\" \\\n --byteplus-secret-key \"$BYTEPLUS_SECRET_KEY\" \\\n --name \"openclaw-abc123\"\n```\n\n### Snapshot/Restore Progress Tracking\n\nSnapshot and restore operations return an `operation_id` immediately and run asynchronously. Track progress via SSE:\n\n```bash\n# Start a snapshot (returns operation_id immediately)\ncurl -X POST http://localhost:3456/api/deployments/{id}/snapshot \\\n -H 'Content-Type: application/json' \\\n -d '{\"snapshot_name\": \"my-backup\", \"do_token\": \"$DO_TOKEN\"}'\n# Response: {\"ok\": true, \"message\": \"Snapshot operation started.\", \"operation_id\": \"abc-123\"}\n\n# Start a restore (returns operation_id immediately)\ncurl -X POST http://localhost:3456/api/snapshots/restore \\\n -H 'Content-Type: application/json' \\\n -d '{\"provider\": \"digitalocean\", \"snapshot_name\": \"my-backup\", \"do_token\": \"$DO_TOKEN\"}'\n# Response: {\"ok\": true, \"message\": \"Restore operation started.\", \"operation_id\": \"def-456\"}\n\n# Stream progress via SSE\ncurl -N http://localhost:3456/api/deploy/{operation_id}/events\n# SSE messages include [Step N/T] for progress bars\n# Terminal: SNAPSHOT_COMPLETE_JSON:{...} or RESTORE_COMPLETE_JSON:{...}\n# Error: SNAPSHOT_ERROR:... or RESTORE_ERROR:...\n```\n\n### Track Deploy Progress\n\n```bash\n# Track by deploy ID, hostname, or IP\nclawmacdo track \n\n# Follow mode — live refresh until complete\nclawmacdo track --follow\n\n# JSON output (NDJSON)\nclawmacdo track --json\n```\n\n### Web UI Mode\n\n```bash\n# Start browser interface\nclawmacdo serve --port 3456\n# Open http://localhost:3456\n```\n\nThe login screen uses a 6-digit PIN gate and shows invalid PIN attempts as an inline alert on the page.\n\n### Cloud Migration\n\n```bash\n# Migrate from one cloud to another\nclawmacdo migrate \\\n --source-ip 1.2.3.4 \\\n --source-ssh-key ~/.ssh/old_instance \\\n --target-provider tencent \\\n --customer-name \"migrated-openclaw\"\n```\n\n### Backup & Restore\n\n```bash\n# Create local backup\nclawmacdo backup\n\n# List backups\nclawmacdo list-backups\n\n# Deploy with specific backup\nclawmacdo deploy --restore-from ~/.openclaw/backups/openclaw-2024-03-09_14-30-15.tar.gz\n```\n\n### Memory Archive Download\n\n```bash\n# Download all memory archives from an instance to the current directory\nclawmacdo memory-download --instance my-server\n\n# Download to a specific output directory\nclawmacdo memory-download --instance my-server --output ~/backups/\n\n# Download to a specific file path\nclawmacdo memory-download --instance 1.2.3.4 --output ~/backups/memory.tar.gz\n```\n\nThe command SSHes into the instance, creates a tar.gz of all files under `/home/openclaw/.openclaw/memory/`, downloads it locally, and cleans up the temporary archive on the remote host.\n\n### OpenClaw Identity\n\n```bash\nclawmacdo openclaw-identity --instance my-server \\\n --openclaw-name \"Clawdia\" \\\n --owner-name \"Kenneth\"\n```\n\nThis command sets the target agent's OpenClaw identity and writes managed owner context into the remote workspace `USER.md`, then restarts the gateway.\n\n### Gyne Consumer Profile\n\n```bash\nclawmacdo gyne-consumer-profile --instance my-server --name consumer-4\n\n# Equivalent terminology for the profile name\nclawmacdo gyne-consumer-profile --instance my-server --consumer-name consumer-4\n\n# Restart a specific unit, or skip the restart entirely\nclawmacdo gyne-consumer-profile --instance my-server --name consumer-4 --service gyne-agent.service\nclawmacdo gyne-consumer-profile --instance my-server --name consumer-4 --no-restart\n\n# Non-default workspace project or base task stream\nclawmacdo gyne-consumer-profile --instance my-server \\\n --project gyne-agent \\\n --task-stream openclaw:tasks \\\n --name consumer-4 \\\n --json\n```\n\nThis command SSHes into the instance as the OpenClaw user, resolves the configured workspace for `--agent` (default `main`), and updates only `workspace//.env` (default `gyne-agent/.env`). It sets `CONSUMER_NAME=` and `CONSUMER_TASK_STREAM=:`, preserving the rest of the `.env` and creating a `.clawmacdo-gyne-*.bak` backup beside it. If `--task-stream` is omitted, the command derives the base stream from the existing `TASK_STREAM` value, falling back to `openclaw:tasks`.\n\nBy default it then restarts the Gyne consumer `systemctl --user` service so the worker re-registers under the new `CONSUMER_NAME` (changing `.env` alone does not affect a running process). The unit is auto-detected from the enabled `--user` services (a `gyne`/`consumer` unit, excluding the gateway); pass `--service ` to target a specific unit, or `--no-restart` to only edit `.env`.\n\n### OpenClaw Markdown Download\n\n```bash\nclawmacdo openclaw-md-download --instance my-server --output ~/backups/\n```\n\nDownloads the active OpenClaw workspace Markdown context files as a ZIP: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `llm_wiki.md` when present, plus daily memory logs under `memory/*.md`.\n\n### OpenClaw LLM Wiki\n\n```bash\nclawmacdo openclaw-llm-wiki --instance my-server \\\n --project remotion-avatar \\\n --title \"Project LLM Wiki\" \\\n --prompt \"Include architecture, runbooks, and open questions.\"\n\n# Upload an existing Markdown file from a web backend or local path\nclawmacdo openclaw-llm-wiki --instance my-server \\\n --project remotion-avatar \\\n --llm-wiki-md ./llm_wiki.md \\\n --skip-claude \\\n --json\n```\n\nSSHes into the instance as the OpenClaw user, resolves the target agent workspace, creates or uploads an attachable `llm_wiki.md` under `workspace//`, seeds that project wiki folder, then optionally launches Claude Code inside the project directory to refine the wiki structure. `--project` defaults to `llm_wiki`; `--llm-wiki-md` uploads any local Markdown file as `/llm_wiki.md`; `--skip-claude` makes the command upload/seed only. `--json` returns `{ ok, project, files, claude_status, error }` plus paths so web apps can display Claude failure details.\n\n### Claude Code Reconnect\n\n```bash\nclawmacdo claude-auth-start --instance my-server --json\nclawmacdo claude-auth-status --instance my-server --json\n```\n\n`claude-auth-start` SSHes into the instance as the OpenClaw user, starts Claude Code auth in a remote PTY, captures the generated login URL, and returns JSON for app integrations:\n\n```json\n{\n \"ok\": true,\n \"valid\": false,\n \"status\": \"pending\",\n \"login_url\": \"https://claude.ai/...\",\n \"instance\": \"my-server\"\n}\n```\n\nAfter the user completes the browser flow, poll `claude-auth-status --json` until `valid` is `true` and `status` is `authenticated`. The status command exits successfully while auth is still pending, so web apps can parse the JSON instead of scraping SSH errors.\n\n### OpenClaw Wiki Files\n\n```bash\nclawmacdo wiki-tree --instance my-server --project llm_wiki --json\nclawmacdo wiki-index --instance my-server --project llm_wiki --json\nclawmacdo wiki-read --instance my-server --path llm_wiki/INDEX.md --json\nclawmacdo wiki-write --instance my-server --path llm_wiki/INDEX.md \\\n --content-file /tmp/INDEX.md \\\n --base-sha \\\n --json\nclawmacdo wiki-write --instance my-server --path llm_wiki/new-page.md \\\n --content-file /tmp/new-page.md \\\n --base-sha NEW \\\n --json\nclawmacdo wiki-ingest --instance my-server --project wiki-163327 \\\n --source /tmp/uploaded-doc.md \\\n --prompt \"Decide where this belongs, update existing pages if needed, create new pages if needed, update index/log.\" \\\n --json\nclawmacdo wiki-export --instance my-server --project llm_wiki --output ~/backups/ --json\nclawmacdo wiki-delete --instance my-server --project wiki-163327 --json\n```\n\nThese commands resolve the configured OpenClaw agent workspace on the instance and only operate on safe relative Markdown paths under that workspace. `wiki-read` returns `content`, `sha256`, `mtime`, and `size`; `wiki-write` requires `--base-sha` so a web app cannot overwrite a file that changed after it was opened. Use `--base-sha NEW` only when creating a new file. `wiki-index` returns per-page hashes plus headings, tags, and Markdown/wiki links for graph or navigation UIs. `wiki-ingest` uploads a converted Markdown source into `/raw/sources/`, launches Claude Code inside that project to decide where the content belongs, and returns `{ project, source_files, changed_files, summary }` JSON for app integrations. `wiki-delete` is intentionally narrower: it only deletes a direct `workspace/wiki-*` project folder and rejects empty names, absolute paths, traversal, symlinks, files, and non-`wiki-*` slugs.\n\n### Gateway Token Rotation\n\n```bash\nclawmacdo openclaw-gateway-token --instance my-server\nclawmacdo openclaw-gateway-url --instance my-server --json\n```\n\nRegenerates `gateway.auth.token` in `/home/openclaw/.openclaw/openclaw.json`, keeps password auth in sync when configured, backs up the old config to `openclaw.json.bak`, and restarts the gateway.\n\n`openclaw-gateway-url --json` returns the current public Tailscale Funnel Gateway URL when available:\n\n```json\n{\n \"ok\": true,\n \"public_url\": \"https://example.ts.net\",\n \"gateway_url\": \"https://example.ts.net/auth.html#...\",\n \"gateway_token_present\": true\n}\n```\n\n### Remotion Avatar Setup\n\n```bash\nclawmacdo remotion-avatar-setup --instance my-server --name \"Kenny\" \\\n --openai-api-key \"$OPENAI_API_KEY\" \\\n --voice-gender female \\\n --avatar-glb ./kenny_avatar.glb \\\n --json\n```\n\nConfigures `/home/openclaw/.openclaw/workspace/remotion-3d-AI-avatar/.env` with `CHAT_BASE_URL=http://127.0.0.1:18789/v1`, `CHAT_API_KEY` from the OpenClaw gateway token, `CHAT_MODEL=openclaw`, `VITE_AVATAR_NAME` from `--name`, `OPENAI_API_KEY` from `--openai-api-key`/`OPENAI_API_KEY`, and voice settings (`VOICE_GENDER`, `TTS_VOICE`; male maps to `onyx`, female maps to `nova`); optionally uploads `avatar.glb` or `_avatar.glb` to the app as `public/avatar.glb`; replaces `kenken64` with the provided name; starts the app; starts a free Cloudflare Quick Tunnel to the frontend port; and prints the public `trycloudflare.com` URL.\n\nWith `--json`, the command returns a stable object for web apps:\n\n```json\n{\n \"ok\": true,\n \"remotion_url\": \"https://example.trycloudflare.com\",\n \"remotion_service\": \"active\",\n \"tunnel_service\": \"active\"\n}\n```\n\n### Scheduled Cron Jobs\n\n```bash\n# Add a scheduled message (sent via telegram on a cron schedule)\nclawmacdo cron-message \\\n --instance my-server \\\n --name \"daily-digest\" \\\n --schedule \"0 9 * * *\" \\\n --message \"Summarise today's headlines\" \\\n --channel telegram\n\n# Add a scheduled message using an interval instead of a cron expression\nclawmacdo cron-message \\\n --instance my-server \\\n --name \"hourly-check\" \\\n --every 1h \\\n --message \"What is the current BTC price?\" \\\n --channel telegram \\\n --to 7547736315\n\n# Add a scheduled tool execution\nclawmacdo cron-tool \\\n --instance my-server \\\n --name \"weekly-report\" \\\n --schedule \"0 8 * * 1\" \\\n --tool web-search \\\n --args \"latest AI news\" \\\n --channel telegram\n\n# List all cron jobs on an instance\nclawmacdo cron-list --instance my-server\n\n# Remove a cron job by name\nclawmacdo cron-remove --instance my-server --name daily-digest\n```\n\n> **Performance note:** All cron commands batch the device-pairing approval step with the first gateway command into a single SSH session, minimising handshake overhead.\n\n### Webhook Hooks\n\n```bash\n# Enable webhook hooks on an instance (generates token, creates default notify mapping)\nclawmacdo hooks-enable --instance my-server\n\n# Send a task to the agent via webhook (delivers response to Telegram)\nclawmacdo hooks-send --instance my-server --task \"Check today's weather for Singapore\"\n\n# Send to a specific mapping\nclawmacdo hooks-send --instance my-server --task \"Generate a report\" --mapping notify\n\n# Show hooks status and all mappings\nclawmacdo hooks-status --instance my-server\n\n# Disable webhook hooks\nclawmacdo hooks-disable --instance my-server\n```\n\nExternal services can also POST directly:\n```bash\ncurl -X POST https:///hooks/notify \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"task\":\"your instruction to the agent\"}'\n```\n\n> **Template note:** The `messageTemplate` uses `{{task}}` to extract the `task` field from the JSON payload. Other available template variables: `{{payload.field}}`, `{{headers.X-Header}}`, `{{query.param}}`, `{{path}}`, `{{now}}`.\n\n## Examples\n\n### Full Deploy with All Options\n\n```bash\nclawmacdo deploy \\\n --provider digitalocean \\\n --customer-name \"production-openclaw\" \\\n --customer-email \"admin@company.com\" \\\n --size s-2vcpu-4gb \\\n --region nyc1 \\\n --primary-model anthropic \\\n --failover-1 openai \\\n --failover-2 gemini \\\n --anthropic-key \"$ANTHROPIC_API_KEY\" \\\n --openai-key \"$OPENAI_API_KEY\" \\\n --gemini-key \"$GEMINI_API_KEY\" \\\n --telegram-bot-token \"$TELEGRAM_TOKEN\" \\\n --whatsapp-phone-number \"+1234567890\" \\\n --tailscale \\\n --tailscale-auth-key \"$TAILSCALE_AUTH\" \\\n --backup ~/openclaw-backup.tar.gz\n```\n\n### Quick Status Check\n\n```bash\n# List all instances\nclawmacdo status\n\n# Check specific provider\nclawmacdo status --provider tencent\n```\n\n## Programmatic Usage (Node.js)\n\nThe npm package exports `getBinaryPath()` so you can call clawmacdo from Node.js scripts or automation tools.\n\n```bash\nnpm install clawmacdo\n```\n\n```javascript\nconst { execSync, spawn } = require(\"child_process\");\nconst { getBinaryPath } = require(\"clawmacdo\");\n\nconst bin = getBinaryPath(); // absolute path to the clawmacdo binary\n\n// --- Deploy a new instance ---\nconst deploy = execSync(`${bin} deploy \\\n --provider lightsail \\\n --customer-name \"my-openclaw\" \\\n --customer-email \"you@example.com\" \\\n --aws-access-key-id \"${process.env.AWS_ACCESS_KEY_ID}\" \\\n --aws-secret-access-key \"${process.env.AWS_SECRET_ACCESS_KEY}\" \\\n --anthropic-key \"${process.env.ANTHROPIC_API_KEY}\" \\\n --primary-model anthropic \\\n --json`, { encoding: \"utf8\" });\nconsole.log(JSON.parse(deploy));\n\n// --- Track deploy progress (streaming) ---\nconst track = spawn(bin, [\"track\", \"\", \"--follow\", \"--json\"]);\ntrack.stdout.on(\"data\", (chunk) => {\n console.log(\"progress:\", chunk.toString());\n});\n\n// --- Set up Telegram bot ---\nexecSync(`${bin} telegram-setup \\\n --instance \\\n --bot-token \"${process.env.TELEGRAM_TOKEN}\"`, { stdio: \"inherit\" });\n\n// --- Set up WhatsApp (displays QR code) ---\nexecSync(`${bin} whatsapp-setup \\\n --instance \\\n --phone-number \"+6512345678\"`, { stdio: \"inherit\" });\n\n// --- Fetch WhatsApp QR code ---\nconst qr = execSync(`${bin} whatsapp-qr --instance `, { encoding: \"utf8\" });\nconsole.log(qr); // ASCII QR code\n\n// --- Check WhatsApp status ---\nconst status = execSync(`${bin} whatsapp-status --instance `, { encoding: \"utf8\" });\nconsole.log(status); // \"connected\", \"pending_qr\", etc.\n\n// --- Wait for WhatsApp scan (blocks until connected or timeout) ---\nexecSync(`${bin} whatsapp-wait --instance --timeout 120`, { stdio: \"inherit\" });\n\n// --- Change AI model ---\nexecSync(`${bin} update-model \\\n --instance \\\n --primary-model openai \\\n --openai-key \"${process.env.OPENAI_API_KEY}\"`, { stdio: \"inherit\" });\n\n// --- Rotate Bedrock token for the OpenClaw workspace tty proxy ---\nexecSync(`${bin} bedrock-token-set \\\n --instance \\\n --bearer-token \"${process.env.AWS_BEARER_TOKEN_BEDROCK}\"`, { stdio: \"inherit\" });\n\n// --- Install a plugin ---\nexecSync(`${bin} plugin-install \\\n --instance \\\n --plugin \"@openguardrails/moltguard\"`, { stdio: \"inherit\" });\n\n// --- Refresh IP after restart ---\nexecSync(`${bin} update-ip --instance `, { stdio: \"inherit\" });\n\n// --- Create snapshot ---\nexecSync(`${bin} do-snapshot \\\n --do-token \"${process.env.DO_TOKEN}\" \\\n --droplet-id 12345 \\\n --snapshot-name \"my-backup\"`, { stdio: \"inherit\" });\n\n// --- Restore from snapshot ---\nexecSync(`${bin} do-restore \\\n --do-token \"${process.env.DO_TOKEN}\" \\\n --snapshot-name \"my-backup\"`, { stdio: \"inherit\" });\n\n// --- Destroy an instance ---\nexecSync(`${bin} destroy \\\n --provider digitalocean \\\n --do-token \"${process.env.DO_TOKEN}\" \\\n --name \"openclaw-abc123\" --yes`, { stdio: \"inherit\" });\n\n// --- Start the web UI programmatically ---\nconst server = spawn(bin, [\"serve\", \"--port\", \"3456\"], { stdio: \"inherit\" });\n```\n\n### TypeScript\n\n```typescript\nimport { getBinaryPath } from \"clawmacdo\";\nimport { execSync } from \"child_process\";\n\nconst bin: string = getBinaryPath();\nexecSync(`${bin} deploy --provider lightsail ...`, { stdio: \"inherit\" });\n```\n\n## Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `DO_TOKEN` | DigitalOcean API token | For DO deploys |\n| `AWS_ACCESS_KEY_ID` | AWS IAM access key ID | For Lightsail deploys |\n| `AWS_SECRET_ACCESS_KEY` | AWS IAM secret access key | For Lightsail deploys |\n| `AWS_REGION` | AWS region (default: `us-east-1`) | For Lightsail deploys |\n| `TENCENT_SECRET_ID` | Tencent Cloud Secret ID | For Tencent deploys |\n| `TENCENT_SECRET_KEY` | Tencent Cloud Secret Key | For Tencent deploys |\n| `AZURE_TENANT_ID` | Azure AD tenant ID | For Azure deploys |\n| `AZURE_SUBSCRIPTION_ID` | Azure subscription ID | For Azure deploys |\n| `AZURE_CLIENT_ID` | Azure service principal client ID | For Azure deploys |\n| `AZURE_CLIENT_SECRET` | Azure service principal client secret | For Azure deploys |\n| `BYTEPLUS_ACCESS_KEY` | BytePlus Access Key | For BytePlus deploys |\n| `BYTEPLUS_SECRET_KEY` | BytePlus Secret Key | For BytePlus deploys |\n| `BYTEPLUS_ARK_API_KEY` | BytePlus ARK API key (for AI model inference) | For BytePlus ARK model |\n| `ARK_API_KEY` | ARK bearer token for `ark-chat` | For `ark-chat` |\n| `ARK_ENDPOINT_ID` | ARK endpoint ID for `ark-chat` | For `ark-chat` |\n| `CLAUDE_API_KEY` | Anthropic Claude API key | Optional |\n| `OPENAI_API_KEY` | OpenAI API key | Optional |\n| `TELEGRAM_TOKEN` | Telegram bot token | Optional |\n| `TAILSCALE_AUTH_KEY` | Tailscale auth key | Optional |\n| `CLAWMACDO_API_KEY` | API key protecting `/api/*` endpoints | Optional (Web UI) |\n| `CLAWMACDO_PIN` | 6-digit PIN for web UI login page | Optional (Web UI) |\n| `CLAWMACDO_BIND` | Server bind address (default: `127.0.0.1`) | Optional (Web UI) |\n| `CLAWMACDO_STATE_DIR` | Directory for deploy records, SSH keys, backups, and `deployments.db` (default: `~/.clawmacdo`) | Optional |\n| `CLAWMACDO_TOKIO_WORKER_THREADS` | Tokio async runtime worker threads (default capped at `2`) | Optional |\n| `CLAWMACDO_MAX_CONCURRENCY` | Caps Tokio blocking threads for SSH/SCP-heavy work (default `8`) | Optional |\n| `CLAWMACDO_RAYON_NUM_THREADS` | Mirrors to `RAYON_NUM_THREADS` before runtime startup | Optional |\n| `CLAWMACDO_SPAWN_RETRIES` | Retries detached deploy child process spawn failures | Optional |\n| `CLAWMACDO_SPAWN_RETRY_DELAY_MS` | Delay between detached deploy spawn retries in milliseconds | Optional |\n| `SKILLS_API_URL` | Railway skills API base URL | For skill commands |\n| `USER_SKILLS_API_KEY` | API key for user-skills endpoints | For skill commands |\n\n## Railway Persistence\n\nWhen running `clawmacdo serve` on Railway, attach a Railway Volume at:\n\n```text\n/app/.clawmacdo\n```\n\nThis repository includes a root `Dockerfile` and `railway.toml` for the web UI. Railway should build the Rust binary and start:\n\n```sh\nclawmacdo serve --port \"$PORT\"\n```\n\nIf Railway still starts `node /app/server.js`, remove the service-level start command override in Railway and redeploy from this repository config.\n\nSet `CLAWMACDO_STATE_DIR=/app/.clawmacdo` so deploy records, SSH keys, backups, and `deployments.db` survive redeploys. The Docker image sets this by default. If Railway provides `RAILWAY_VOLUME_MOUNT_PATH=/app/.clawmacdo`, clawmacdo also auto-detects that mount path.\n\nRailway Volumes are mounted as root by default. For non-root container images, either set `RAILWAY_RUN_UID=0` as a quick operational fix, or chown the mounted directory in the hosting app image before starting the server:\n\n```sh\nmkdir -p /app/.clawmacdo\nchown -R nextjs:nodejs /app/.clawmacdo\nexec \"$@\"\n```\n\nWithout a persistent volume, Railway redeploys can remove `deploys/`, `keys/`, and `deployments.db`. Existing cloud instances may then be unreachable from clawmacdo unless the old deploy record and SSH private key can be recovered; after attaching the volume, destroy/recreate those orphaned instances and provision again.\n\nRailway references: [Volumes](https://docs.railway.com/volumes), [Volume permissions](https://docs.railway.com/reference/volumes).\n\n## Skills Data API\n\nThe `skills-data-api/` directory contains a standalone Node.js/Express service for browsing and serving Claude Code skill marketplace data, backed by MongoDB.\n\n```bash\n# Install dependencies\ncd skills-data-api\nnpm install\n\n# Load skills data into MongoDB\npwsh -File ./load-mongo.ps1\n\n# Start the API server\nnode index.js\n```\n\nOperational repo scripts now ship with PowerShell entrypoints under `scripts/*.ps1` and can be run cross-platform with `pwsh -File`.\n\n### Docker\n\n```bash\ncd skills-data-api\ndocker build -t skills-data-api .\ndocker run -p 3000:3000 \\\n -e MONGODB_URI=\"mongodb://host.docker.internal:27017/skills\" \\\n skills-data-api\n```\n\n### Key Endpoints\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/skills` | List all skills (paginated) |\n| `GET` | `/api/skills/:name` | Get a skill by name |\n| `GET` | `/api/skills/search?q=...` | Search skills by keyword |\n\nSee [`skills-data-api/README.md`](skills-data-api/README.md) for full API documentation.\n\n## Project Structure\n\n```\nclawmacdo/\n├── Cargo.toml # Workspace configuration\n├── crates/ # All crates in workspace\n│ ├── clawmacdo-cli/ # 🖥️ Main CLI binary & command orchestration\n│ ├── clawmacdo-core/ # 🔧 Config, errors, shared types\n│ ├── clawmacdo-cloud/ # ☁️ Cloud provider implementations\n│ ├── clawmacdo-provision/# 🔨 Server provisioning & setup logic\n│ ├── clawmacdo-db/ # 💾 Database operations & storage\n│ ├── clawmacdo-ssh/ # 🔑 SSH/SCP operations & key management\n│ └── clawmacdo-ui/ # 🎨 Web UI, progress bars, user prompts\n├── skills-data-api/ # 🧠 Node.js skills marketplace API (MongoDB)\n├── e2e/ # 🧪 Playwright end-to-end test suite\n├── assets/ # Static assets (mascot, etc.)\n└── docs/ # Design docs and usage reference\n```\n\n### Crate Overview\n\n| Crate | Purpose | Dependencies |\n|-------|---------|--------------|\n| **clawmacdo-cli** | Main binary, command parsing, orchestration | All other crates |\n| **clawmacdo-core** | Configuration, errors, shared types | Minimal (serde, anyhow) |\n| **clawmacdo-cloud** | DigitalOcean, AWS Lightsail, Tencent Cloud & BytePlus APIs | reqwest, async-trait |\n| **clawmacdo-provision** | Server setup, package installation | SSH, Core, UI |\n| **clawmacdo-db** | SQLite operations, job tracking | rusqlite |\n| **clawmacdo-ssh** | SSH connections, file transfers | ssh2 |\n| **clawmacdo-ui** | Progress bars, web interface | indicatif, axum |\n\n## Development\n\n### Workspace Commands\n\n```bash\n# Build all crates\ncargo build\n\n# Run the full Rust quality pipeline\ncargo fmt --all\ncargo clippy --all-targets --all-features -- -D warnings\ncargo test\n\n# Build specific crate\ncargo build -p clawmacdo-core\n\n# Update dependencies\ncargo update\n```\n\nThe workspace now includes focused Rust tests around config/path validation, deployment database lookups, cron/hook command construction helpers, QR parsing, and web middleware behavior. Add new tests close to the module they protect.\n\n### Adding Dependencies\n\nAdd to workspace `Cargo.toml`:\n```toml\n[workspace.dependencies]\nnew-crate = \"1.0\"\n```\n\nThen reference in individual crate:\n```toml\n[dependencies]\nnew-crate = { workspace = true }\n```\n\n## Architecture Notes\n\nThe refactored workspace follows a **dependency hierarchy**:\n\n1. **clawmacdo-core** - Foundation (no internal deps)\n2. **clawmacdo-ssh** - Depends on core\n3. **clawmacdo-db** - Depends on core\n4. **clawmacdo-ui** - Depends on core\n5. **clawmacdo-cloud** - Depends on core\n6. **clawmacdo-provision** - Depends on core, ssh, ui, cloud\n7. **clawmacdo-cli** - Orchestration layer (depends on all)\n\nThis prevents circular dependencies and enables clean testing.\n\n## Performance Optimizations\n\n- **LTO enabled** for release builds\n- **Panic = abort** for smaller binaries\n- **Symbol stripping** in release mode\n- **Feature gates** for optional components\n- **Minimal Tokio features** (not \"full\")\n\n## Security Hardening\n\n- Privileged remote provisioning commands now run through stdin-fed shells instead of nested quoted `sudo` / `su -c` wrappers.\n- User-supplied hostnames are normalized and validated before any deploy flow uses them.\n- The web UI now only accepts backup archives from `~/.clawmacdo/backups` and SSH keys from `~/.clawmacdo/keys`.\n- Backup restore validates the local `.tar.gz` before upload and extracts remotely with `--no-same-owner` and `--no-same-permissions` into a dedicated restore directory.\n- The gateway service now reads `~/.openclaw/gateway.env` instead of the broader `.env`, so setup-only secrets such as `ANTHROPIC_SETUP_TOKEN` are not inherited by the long-running service.\n- Deploy Step 15 gateway health check uses exponential backoff (max ~70s) instead of 150 fixed 1s polls; model setup and profile setup are batched into a single SSH session per provider.\n- Direct Docker-group access for `openclaw` has been removed. If sandbox mode is requested during deploy, the deploy now forces sandbox mode off until a safer non-root mediation path exists.\n- Lightsail credentials are passed only to the child AWS CLI processes instead of mutating process-global environment variables or writing `~/.aws/credentials`.\n- Tencent's optional security-group helper now takes SSH ingress from `CLAWMACDO_TENCENT_SSH_CIDR` and defaults to `127.0.0.1/32` instead of opening SSH to the world.\n\nSee [docs/HIGH_SECURITY_FIXES.md](docs/HIGH_SECURITY_FIXES.md) for the finding-by-finding code map, rationale, and functionality impact.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Run `cargo fmt --all`, `cargo clippy --all-targets --all-features -- -D warnings`, and `cargo test`\n5. Submit a pull request\n\n## License\n\nCopyright (c) 2026 Kenneth Phang\n\nThis software is licensed under a dual license model:\n\n1. **GNU General Public License v3.0** — for open source use\n See [LICENSE-GPL.md](LICENSE-GPL.md) for details.\n\n2. **Commercial License** — for proprietary/commercial use\n See [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md) for details.\n\nFor licensing inquiries, contact: bunnyppl@gmail.com\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [CLI Usage Guide](docs/clawmacdo_usage.md) | Complete reference for all subcommands with examples and sample responses |\n| [Deployment Architecture](docs/DEPLOYMENT_ARCHITECTURE_RESEARCH.md) | Cloud provider architecture research and design decisions |\n| [Codebase Logic & Data Flow](docs/CODEBASE_LOGIC_AND_DATA_FLOW.md) | End-to-end logic flow, module boundaries, and data structures |\n| [Tracking Architecture](docs/TRACKING_ARCHITECTURE.md) | Deploy/snapshot/restore progress tracking system design |\n| [TanStack Progress Tracking](docs/tanstack-progress-tracking.md) | Frontend integration guide for TanStack (React Query) progress bars |\n| [Security Scan](docs/SECURITY_SCAN.md) | Security scanning CLI and vulnerability assessment |\n| [Security Flaw Evaluation](docs/EVAL_SECURITY_FLAW.md) | Security flaw evaluation report and findings |\n| [High Security Fixes](docs/HIGH_SECURITY_FIXES.md) | Code-level remediation map for all HIGH findings |\n| [Tencent Cloud Plan](docs/TENCENT_PLAN.md) | Tencent Cloud provider support plan |\n| [Repository Guidelines](docs/AGENTS.md) | Contribution guidelines and repository conventions |\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and release notes.\n\n---\n\n**Current version:** 0.93.0\n\n\n\n","readmeFilename":"README.md"}