Clawhub Skill Deploy Pilot

Automates versioned Docker Compose and LXC deployments with health checks, blue-green updates, chat approvals, and automatic rollback for zero-downtime updates.

Security Scan

The skill's files, instructions, and declared permissions are consistent with a deployment/orchestration tool; nothing indicates it is trying to do something unrelated, but review is advised because it executes system commands and interacts with external systems.

Purpose & Capability

The name/description (Docker Compose + LXC deployments, health checks, blue-green, approvals) matches the included scripts, CLI, and declared permissions (docker, pvesh, ssh, net:http, file read/write in its workspace). The dependencies and features are proportional to the stated purpose.

Instruction Scope

SKILL.md and the Python script direct the agent/user to write config under ~/.openclaw/workspace/deploy-pilot and run the included deploy-pilot.py. Runtime behavior includes running docker/pvesh/ssh commands, performing HTTP/TCP/SSH checks, and executing pre/post hooks or arbitrary 'script' checks. These are expected for a deploy tool but mean the skill can execute arbitrary local and remote commands and initiate network traffic; the user should inspect hooks and any approval integration code before use.

Install Mechanism

There is no external download/install step — this is an instruction-and-code bundle. All code is included in the skill package (no remote extracts or unusual URLs), so nothing will be pulled from untrusted hosts during install.

Credentials

The skill does not request environment variables or credentials in metadata. It requires system tools (docker, ssh, pvesh) that are reasonable for the functionality. Chat approval integration references the platform's message tool but does not request external tokens in the skill manifest; that integration will depend on the user's OpenClaw messaging configuration.

Persistence & Privilege

always:false (not forced), and the skill only writes to its own workspace (~/.openclaw/workspace/deploy-pilot). Declared permissions to run docker/pvesh/ssh and network access are appropriate for a deployment orchestrator. The skill does not request system-wide configuration changes or other skills' credentials.

Assessment

This appears to be a legitimate deployment tool, but it performs privileged actions (runs docker/pvesh/ssh, executes hooks/scripts, and sends network requests). Before installing: (1) review deploy-pilot.py for any code paths that send sensitive data externally (especially approval/notification code), (2) inspect any pre/post hooks or default hook locations so they cannot run untrusted code, (3) verify how the WhatsApp/Telegram approval integration is implemented and that you control the messaging configuration, (4) run the provided smoke tests in an isolated environment (or sandbox) first, and (5) ensure SSH keys and Proxmox credentials used by the tool are limited-scoped. The skill's source/homepage is listed as unknown while skill.json references a GitHub repo — consider confirming the origin before production use.

deploy-pilot — Docker/LXC Deployment Automation

Version: 1.0.0
Author: OpenClaw
Category: Infrastructure + Automation
Complexity: Advanced

Deploy with confidence. Version control for your containers.

---

What It Does

deploy-pilot manages Docker Compose and LXC container deployments with full versioning, health checks, automatic rollback, and chat-based approval workflows. Zero-downtime updates with one command.

Core Features

• Version-tracked deployments — Every deploy is a snapshot. Rollback with one command.
• Health checks — Auto-verify container health after deployment. Fail fast.
• Blue-green deployments — Deploy new version alongside old, switch seamlessly.
• Approval workflows — Deploy requests sent to WhatsApp/Telegram. User approves or rejects.
• Docker Compose + LXC — Works with docker-compose stacks AND Proxmox LXC containers.
• Pre/post hooks — Custom scripts before/after deployment (backups, migrations, etc).
• History & audit trail — Track every deployment, who approved it, and what changed.
• Automatic rollback — If health check fails, automatically rollback to previous version.

---

Installation

Quick Start

# Clone/download the skill
mkdir -p ~/.openclaw/workspace/skills/deploy-pilot
cd ~/.openclaw/workspace/skills/deploy-pilot

# Copy SKILL.md and scripts
cp SKILL.md deploy-pilot.py deploy-pilot.sh ./

# Make scripts executable
chmod +x deploy-pilot.sh deploy-pilot.py

# Initialize config
./deploy-pilot.py init

# Verify installation
./deploy-pilot.py --help

Dependencies

Required:

• Python 3.8+
• bash 4.0+
• docker (for Docker Compose stacks)
• curl (for HTTP health checks)
• jq (for JSON parsing)

Optional (for Proxmox LXC):

• pvesh (Proxmox command-line client)
• SSH access to Proxmox host

Optional (for chat approval):

• OpenClaw message tool configured (WhatsApp/Telegram)

Setup OpenClaw Integration

If you want approval workflows and chat notifications:

# Create approval config
mkdir -p ~/.openclaw/workspace/deploy-pilot
cat > ~/.openclaw/workspace/deploy-pilot/config.json << 'EOF'
{
  "approval_channel": "whatsapp",
  "approval_timeout_minutes": 30,
  "notify_deployments": true,
  "auto_rollback_on_health_fail": true
}
EOF

---

Commands

Initialize & Setup

deploy-pilot init

Interactive setup:

• Set base directory for stacks
• Choose deployment strategy (docker or lxc)
• Configure health checks
• Set up approval workflows

---

Manage Stacks

# List all managed stacks
deploy-pilot stacks

# Register a new Docker Compose stack
deploy-pilot add docker /path/to/docker-compose.yml

# Register a new LXC container
deploy-pilot add lxc <node> <vmid> <name>

# Show details for a stack
deploy-pilot show <stack>

# Remove a stack from management
deploy-pilot remove <stack>

---

Deploy

# Deploy latest version
deploy-pilot deploy <stack>

# Deploy specific version
deploy-pilot deploy <stack> --version 1.2.0

# Deploy with custom image tags
deploy-pilot deploy <stack> --images "web:v2.0,api:v3.0"

# Dry-run (show what would be deployed)
deploy-pilot deploy <stack> --dry-run

# Skip health check
deploy-pilot deploy <stack> --skip-health-check

# Force deployment (skip approval)
deploy-pilot deploy <stack> --force

Example workflow:

# 1. Request deployment (goes to WhatsApp)
$ deploy-pilot deploy web-api

Deployment request sent to WhatsApp.
Waiting for approval (timeout: 30 minutes)...

# User replies "approve" on WhatsApp

# 2. Approved, deploying...
[✓] Pre-deploy hook: running database migrations
[✓] Creating snapshot: web-api@2.1.0
[✓] Pulling new images
[✓] Starting blue environment
[✓] Health check (10/10 passed)
[✓] Switching traffic to new version
[✓] Cleaning up old environment

Deployment complete. Stack: web-api | Version: 2.1.0 | Duration: 2m34s

---

Rollback

# Rollback to previous version
deploy-pilot rollback <stack>

# Rollback to specific version
deploy-pilot rollback <stack> --version 1.5.0

# Dry-run
deploy-pilot rollback <stack> --dry-run

Example:

$ deploy-pilot rollback web-api
Rollback: web-api from 2.1.0 → 2.0.0
[✓] Creating snapshot: web-api@2.1.0 (previous good state)
[✓] Reverting to version 2.0.0
[✓] Health check (10/10 passed)
[✓] Switching traffic

Rollback complete. Stack: web-api | Previous version: 2.0.0 | Duration: 1m12s

---

Health Checks

# Check current health of a stack
deploy-pilot health <stack>

# Verbose health output
deploy-pilot health <stack> --verbose

# Check all stacks
deploy-pilot health --all

Output:

Stack: web-api (v2.1.0)
  Container web-web    : ✓ RUNNING (1d2h)
  Container web-db     : ✓ RUNNING (1d2h)
  HTTP /health endpoint: ✓ 200 OK (45ms)
  Disk usage          : ✓ 62% (within threshold)
  Memory usage        : ✓ 1.2GB / 2GB (60%)
  Custom check (ping) : ✓ PASSED (12ms)

Overall health: ✓ HEALTHY
Last check: 5 minutes ago

---

History & Audit

# Show deployment history for a stack
deploy-pilot history <stack>

# Show last N deployments
deploy-pilot history <stack> --limit 10

# Filter by status
deploy-pilot history <stack> --status success
deploy-pilot history <stack> --status failed
deploy-pilot history <stack> --status rolled-back

# Show full details of a deployment
deploy-pilot history <stack> --id deployment-12345 --details

Example:

$ deploy-pilot history web-api --limit 5

ID                  | Version | Status    | Approved By | Duration | Time
deploy-00001        | 2.1.0   | success   | marius      | 2m34s    | 2026-02-25 14:23
deploy-00000        | 2.0.0   | rolled-back | marius    | 0m45s    | 2026-02-25 13:45
deploy-99999        | 2.0.0   | success   | marius      | 3m12s    | 2026-02-25 12:00
deploy-99998        | 1.9.0   | success   | automated   | 2m01s    | 2026-02-24 22:15
deploy-99997        | 1.9.0   | failed    | marius      | 1m33s    | 2026-02-24 20:30

---

Configuration & Hooks

# Show deployment strategy for a stack
deploy-pilot config <stack>

# Update health check config
deploy-pilot config <stack> --health-endpoint /api/health
deploy-pilot config <stack> --health-timeout 60

# Add pre-deploy hook
deploy-pilot hook <stack> pre "scripts/backup-db.sh"

# Add post-deploy hook
deploy-pilot hook <stack> post "scripts/notify-team.sh"

# List hooks
deploy-pilot hook <stack> list

# Remove hook
deploy-pilot hook <stack> remove <hook-id>

---

Cron Integration (Scheduled Deployments)

# Deploy on a schedule (useful for auto-updates of images)
deploy-pilot cron-setup <stack> "0 2 * * *" "deploy-pilot deploy <stack>"

# List scheduled deployments
deploy-pilot cron list

# Remove scheduled deployment
deploy-pilot cron remove <stack>

---

Advanced: JSON Output

All commands support --json for programmatic use:

deploy-pilot stacks --json
deploy-pilot health <stack> --json
deploy-pilot history <stack> --json

---

Real-World Examples

Example 1: Zero-Downtime Web App Deployment

# Current state: web-api v2.0.0, 3 replicas

# Deploy new version (automatic approval workflow)
$ deploy-pilot deploy web-api --images "api:2.1.0"

Deployment request sent to WhatsApp with:
  - Current version: 2.0.0
  - New version: 2.1.0
  - Changes: API security patch + bug fixes

# (User approves on WhatsApp after reviewing changes)

# Deployment proceeds:
[✓] Blue-green setup: spinning up 3 new replicas with v2.1.0
[✓] Health checks passing on new replicas
[✓] Gradual traffic switch (no downtime)
[✓] Old replicas kept for 5 minutes (fast rollback if needed)
[✓] Cleanup old environment

Result: Zero-downtime update. Customers see no interruption.
Rollback available for 5 minutes if issues found.

Example 2: Database Migration + Deployment

# Stack with API + PostgreSQL

# Define pre-deploy hook to run migrations
$ deploy-pilot hook api-db pre "scripts/migrate.sh"

# Now when you deploy:
$ deploy-pilot deploy api-db --version 2.5.0

[✓] Running pre-hook: database migration (alembic upgrade head)
    - Added column: users.phone_number
    - Added index: users(email)
[✓] Creating snapshot (in case rollback needed)
[✓] Deploying new API version
[✓] Health check: database connectivity OK
[✓] Success!

# If something went wrong:
$ deploy-pilot rollback api-db

[✓] Downgrading database schema (alembic downgrade -1)
[✓] Reverting API to v2.4.0
[✓] All OK

Example 3: Multi-Environment Stack (Dev → Prod)

# Use same compose file, different deployments
deploy-pilot add docker dev  /compose/docker-compose.yml --env=dev
deploy-pilot add docker prod /compose/docker-compose.yml --env=prod

# Deploy to dev (no approval needed)
deploy-pilot deploy dev --force

# Deploy to prod (requires approval)
deploy-pilot deploy prod --images "web:v2.1.0,api:v2.1.0"

(Request goes to WhatsApp with dev metrics)
(User reviews test results from dev, approves)
(Prod deploys with same images as dev)

Example 4: Proxmox LXC Deployment

# Register LXC container on Proxmox
deploy-pilot add lxc pve 205 app-container

# Configure health check (SSH connectivity + systemctl status)
deploy-pilot config app-container --health-check "ssh://root@10.0.0.205:systemctl is-active service"

# Deploy new container version
deploy-pilot deploy app-container --image ubuntu:22.04 --force

(New LXC container cloned from template, health checked, old kept as backup)

---

Configuration File Structure

Located at: ~/.openclaw/workspace/deploy-pilot/stacks.json

{
  "stacks": {
    "web-api": {
      "type": "docker",
      "path": "/home/compose/web-api",
      "compose_file": "docker-compose.yml",
      "health_checks": [
        {
          "type": "http",
          "endpoint": "http://localhost:8080/health",
          "timeout": 30,
          "expected_code": 200
        }
      ],
      "hooks": {
        "pre": ["scripts/backup.sh"],
        "post": ["scripts/notify.sh"]
      },
      "versions": [
        {
          "id": "2.1.0",
          "timestamp": "2026-02-25T14:23:00Z",
          "images": {"web": "myrepo/web:2.1.0", "api": "myrepo/api:2.1.0"},
          "status": "success",
          "approved_by": "marius"
        }
      ]
    }
  }
}

---

Troubleshooting

Deployment stuck waiting for approval

# Check approval status
deploy-pilot status <deployment-id>

# Force completion (skip approval, use with caution)
deploy-pilot force <deployment-id>

Health check failing

# Verbose health check output
deploy-pilot health <stack> --verbose

# Disable health check for this deployment
deploy-pilot deploy <stack> --skip-health-check

# (Fix the issue, then re-deploy)

Rollback failed

# Check available versions
deploy-pilot history <stack> --limit 20

# Manual rollback to specific version
deploy-pilot rollback <stack> --version <known-good-version>

Approval workflow not working

Check OpenClaw message tool:

# Test message delivery
openclaw message test "Test message"

# Verify config
cat ~/.openclaw/workspace/deploy-pilot/config.json

---

Performance & Limits

Metric	Free	Pro
Managed stacks	3	Unlimited
Deployment history	10 per stack	Unlimited
Blue-green overlaps	1	5 (parallel deployments)
Approval timeout	30 min (fixed)	Configurable
Health check frequency	Every deployment	Configurable (5min intervals)

---

Safety & Best Practices

✅ Do this:

• Always test in dev environment first
• Use health checks — they save you
• Review deployment changes before approving
• Keep a rollback plan (it's automatic, but know your escape route)
• Archive deployment history weekly

❌ Don't do this:

• Deploy without health checks
• Use --skip-approval in production
• Remove snapshots immediately after deploy
• Deploy during peak traffic without monitoring
• Ignore failed health checks

---

Architecture

                    ┌─────────────────────┐
                    │   User (WhatsApp)   │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │   deploy-pilot.py   │
                    │  (main orchestrator)│
                    └──────────┬──────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
  ┌─────▼────┐         ┌──────▼────┐         ┌──────▼────┐
  │ Docker   │         │   LXC     │         │ Health    │
  │ Compose  │         │ (Proxmox) │         │ Checker   │
  │ Executor │         │ API Client│         │ (HTTP/SSH)│
  └──────────┘         └───────────┘         └───────────┘
        │                      │                      │
  ┌─────▼──────────────────────┼──────────────────────┘
  │                            │
  └────────────────┬───────────┘
                   │
         ┌─────────▼──────────┐
         │  State DB (JSON)   │
         │  Version History   │
         │  Deployment Log    │
         └────────────────────┘

---

Support & Contribution

Questions? Check the examples above or read the source code.

Found a bug? Log it on AgentGram community.

Want a feature? Build it! These are executable scripts. Fork, modify, share.

---

License

MIT — Use freely. Attribution appreciated.

---

Last updated: 2026-02-25
Tested on: Ubuntu 22.04, Proxmox 8.0, Docker 26.0