@dambrogia/openclaw-agents-backup 0.1.0

package/SKILL.md

@@ -0,0 +1,355 @@
+# Skill: OpenClaw Agents Backup
+
+Backup and restore OpenClaw multi-agent workspaces. Centralized backup of all agent configuration files, workspaces, and agent directories with disaster recovery capabilities.
+
+## Overview
+
+This skill enables automated hourly backups of OpenClaw agents in multi-agent setups. It discovers all active agents via the OpenClaw API, backs up their workspace and agent directories to a centralized Git repository, and provides restore functionality for disaster recovery.
+
+### Use Cases
+
+- **Multi-agent deployments** — Back up multiple agents in a single OpenClaw instance
+- **Disaster recovery** — Wipe a VPS and restore agent state to any point in history
+- **Configuration snapshots** — Track changes to agent identity, workspace files, and session history
+- **Compliance** — Maintain audit trail of agent configuration changes
+
+## Installation
+
+This skill is designed as a TypeScript library. Install it in your project:
+
+```bash
+npm install @dambrogia/openclaw-agents-backup
+```
+
+Or clone from GitHub and use as a local dependency.
+
+## Usage Patterns
+
+### For End Users: Agent-Driven Backups
+
+Install the package once. Agent calls CLI commands. User tells agent what they need.
+
+**Setup:**
+```bash
+npm install @dambrogia/openclaw-agents-backup
+```
+
+**Agent calls:**
+```bash
+backup-agents backup              # Back up now
+backup-agents restore             # Restore latest
+backup-agents restore --sha ABC123 # Point-in-time
+backup-agents history             # Show log
+```
+
+**User interaction:**
+- "Back up my agents" → Agent runs `backup-agents backup`
+- "Restore my agents" → Agent runs `backup-agents restore`
+- "Show backup history" → Agent runs `backup-agents history`
+
+### For Developers: Direct Library Use
+
+Install as a dependency and call functions directly in your code.
+
+## Setup
+
+### 1. Create Backup Repository
+
+Initialize a private Git repository where backups will be stored:
+
+```bash
+mkdir agents-backup
+cd agents-backup
+git init
+git config user.email "backup@example.com"
+git config user.name "Backup Agent"
+git commit --allow-empty -m "Initial commit"
+```
+
+### 2. Create Backup Configuration
+
+In your OpenClaw workspace, create `.backupconfig.json`:
+
+```json
+{
+  "backupRepoPath": "/path/to/agents-backup"
+}
+```
+
+The `backupRepoPath` should point to the local backup Git repository (already initialized and with a remote configured).
+
+### 3. Schedule Hourly Backups (via Cron)
+
+Use OpenClaw's cron functionality to schedule hourly backups:
+
+```typescript
+const { performBackup } = require('@dambrogia/openclaw-agents-backup');
+
+// Hourly backup job
+cron.add({
+  name: 'agents-backup-hourly',
+  schedule: { kind: 'cron', expr: '0 * * * *' },
+  payload: {
+    kind: 'agentTurn',
+    message: 'Run backup',
+    timeoutSeconds: 300
+  },
+  sessionTarget: 'isolated'
+});
+```
+
+Or use OpenClaw's built-in scheduling to call the backup function.
+
+## CLI
+
+### Commands
+
+```bash
+backup-agents backup              # Back up all agents now
+backup-agents restore             # Restore to latest
+backup-agents restore --sha SHA   # Restore to specific commit
+backup-agents history             # Show recent backups
+```
+
+## API (Library Reference)
+
+For developers using the library directly (not required for typical CLI usage).
+
+### Backup
+
+```typescript
+import { performBackup } from '@dambrogia/openclaw-agents-backup';
+
+const result = await performBackup('/root/.openclaw/workspace');
+
+// Result
+{
+  success: boolean;
+  message: string;
+  agentsProcessed: number;
+  changes: Array<{
+    agentId: string;
+    workspaceChanged: boolean;
+    agentDirChanged: boolean;
+    error?: string;
+  }>;
+  error?: string;
+}
+```
+
+**What it does:**
+1. Queries OpenClaw for all agent bindings
+2. For each agent, creates/updates `archives/<agent-id>/`
+3. Syncs workspace and agent directories using `rsync --archive --delete`
+4. Stores agent metadata in `archives/<agent-id>/agent.json`
+5. Commits changes to Git with a timestamp
+
+### Restore
+
+```typescript
+import { performRestore } from '@dambrogia/openclaw-agents-backup';
+
+// Restore latest backup
+const result = await performRestore(
+  '/path/to/backup-repo',
+  null, // or pass a git SHA for point-in-time restore
+  '/root/.openclaw/workspace'
+);
+
+// Result
+{
+  success: boolean;
+  message: string;
+  agentsRestored: number;
+  error?: string;
+}
+```
+
+**What it does:**
+1. Reads all agent archives from `archives/`
+2. For each agent, restores workspace and agent directory to original locations
+3. Uses rsync to sync directories with `--archive --delete`
+
+## Backup Structure
+
+```
+agents-backup/
+├── .git/                          # Git history
+├── archives/
+│   ├── main/
+│   │   ├── agent.json             # Agent metadata (id, paths, timestamp)
+│   │   ├── workspace/             # Synced from <agent.workspace>
+│   │   │   ├── SOUL.md
+│   │   │   ├── USER.md
+│   │   │   ├── MEMORY.md
+│   │   │   ├── memory/
+│   │   │   └── ...
+│   │   └── agentDir/              # Synced from <agent.agentDir>
+│   │       ├── sessions/
+│   │       └── ...
+│   ├── secondary/
+│   │   ├── agent.json
+│   │   ├── workspace/
+│   │   └── agentDir/
+│   └── ...
+└── .gitignore                     # Ignores .env*, auth-profiles.json, etc.
+```
+
+## Ignored Files
+
+The following patterns are automatically ignored by Git:
+
+```
+# Credentials and secrets
+.env
+.env.local
+.env.*.local
+auth-profiles.json
+auth-profiles.*
+
+# Dependencies
+node_modules/
+package-lock.json
+yarn.lock
+
+# Build artifacts
+dist/
+*.js
+*.js.map
+*.d.ts
+
+# IDE
+.vscode/
+.idea/
+.DS_Store
+
+# Logs
+*.log
+logs/
+```
+
+**Why?** Sensitive credentials (GitHub PAT, API keys) should never be committed. Store these in `.env` or `.env.local` files, which are backed up but not committed to Git.
+
+## Disaster Recovery Workflow
+
+### Scenario: Restore agents after VPS wipe
+
+**Step 1: Set up new VPS**
+```bash
+# Install OpenClaw, configure initial workspace
+openclaw init
+```
+
+**Step 2: Clone backup repository**
+```bash
+git clone <backup-repo-url> /path/to/agents-backup
+```
+
+**Step 3: Create backup config**
+```bash
+# In /root/.openclaw/workspace/.backupconfig.json
+echo '{"backupRepoPath": "/path/to/agents-backup"}' > /root/.openclaw/workspace/.backupconfig.json
+```
+
+**Step 4: Restore from backup**
+```bash
+# Run the restore function
+node -e "require('@dambrogia/openclaw-agents-backup').performRestore('/path/to/agents-backup', null, '/root/.openclaw/workspace').then(console.log)"
+```
+
+**Step 5: Verify agents**
+```bash
+openclaw agents list --bindings --json
+```
+
+### Restore to a specific point in time
+
+Find the commit you want to restore from:
+
+```bash
+cd /path/to/agents-backup
+git log --oneline
+# Pick a commit SHA
+git checkout <commit-sha>
+```
+
+Then run restore as normal.
+
+## Implementation Details
+
+### Agent Discovery
+
+Agents are discovered via `openclaw agents list --bindings --json`, which returns:
+
+```json
+[
+  {
+    "id": "main",
+    "identityName": "dambrogia-ai-dev",
+    "identityEmoji": "⚙️",
+    "workspace": "/root/.openclaw/workspace",
+    "agentDir": "/root/.openclaw/agents/main/agent",
+    "model": "anthropic/claude-haiku-4-5",
+    "bindings": 0,
+    "isDefault": true,
+    "routes": ["default (no explicit rules)"]
+  }
+]
+```
+
+### Rsync Behavior
+
+- **`--archive`** — Preserves permissions, ownership, timestamps, symlinks
+- **`--delete`** — Removes files in destination that no longer exist in source
+- **Dry-run check** — Detects changes before syncing to avoid unnecessary Git commits
+
+### Git Commit Strategy
+
+One commit per backup run with message format:
+```
+Backup: 2026-02-17T05:30:45.123Z
+```
+
+This allows easy time-based filtering and point-in-time recovery.
+
+## Testing
+
+Run the test suite:
+
+```bash
+npm test
+npm run test:coverage
+```
+
+Target: >80% code coverage
+
+## Limitations
+
+- **Point-in-time restore via Git SHA** — Currently documented but not fully automated. You can manually `git checkout <sha>` the backup repo before restoring.
+- **Incremental backups** — All files are synced hourly, but Git only commits changed files
+- **Size** — Disk usage doubles since archives contain full copies of workspace + agentDir
+
+## Troubleshooting
+
+### "Backup repo not initialized"
+Ensure the backup repository exists and has been initialized with `git init`.
+
+### "No changes detected"
+Rsync ran but found no differences. This is normal — the next hourly run will check again.
+
+### "Git commit failed"
+The backup process completed but couldn't commit. Check:
+- Git is configured in the backup repo (`git config user.email` / `user.name`)
+- Remote is set up if you plan to push
+- Disk space is available
+
+### Restore shows "Archives directory not found"
+Run backup at least once to create the `archives/` directory structure.
+
+## Contributing
+
+Issues and PRs welcome. Please include test cases for any new functionality.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const index_1 = require("./index");
+/**
+ * CLI entry point for backup/restore operations
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    const workspace = process.env.OPENCLAW_WORKSPACE || '/root/.openclaw/workspace';
+    const configPath = path.join(workspace, '.backupconfig.json');
+    if (!fs.existsSync(configPath)) {
+        console.error('❌ Error: .backupconfig.json not found at ' + configPath);
+        process.exit(1);
+    }
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const backupRepoPath = config.backupRepoPath;
+    try {
+        switch (command) {
+            case 'backup':
+                await handleBackup(workspace);
+                break;
+            case 'restore':
+                await handleRestore(backupRepoPath, workspace, args);
+                break;
+            case 'history':
+                await handleHistory(backupRepoPath);
+                break;
+            case '--help':
+            case '-h':
+            case undefined:
+                showHelp();
+                break;
+            default:
+                console.error('❌ Unknown command: ' + command);
+                showHelp();
+                process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(`❌ Error: ${error}`);
+        process.exit(1);
+    }
+}
+async function handleBackup(workspace) {
+    console.log('🔄 Starting backup...');
+    const result = await (0, index_1.performBackup)(workspace);
+    if (result.success) {
+        console.log('✅ Backup complete');
+        console.log(`   Agents processed: ${result.agentsProcessed}`);
+        console.log(`   Changes: ${result.changes.filter((c) => c.workspaceChanged || c.agentDirChanged).length}`);
+        result.changes.forEach((change) => {
+            if (change.workspaceChanged || change.agentDirChanged) {
+                console.log(`   - ${change.agentId}: workspace=${change.workspaceChanged}, agentDir=${change.agentDirChanged}`);
+            }
+        });
+    }
+    else {
+        console.error(`❌ Backup failed: ${result.message}`);
+        if (result.error) {
+            console.error(`   ${result.error}`);
+        }
+        process.exit(1);
+    }
+}
+async function handleRestore(backupRepoPath, workspace, args) {
+    let targetSha = null;
+    let confirmAuthOverwrite = false;
+    // Check for --sha argument
+    const shaIndex = args.indexOf('--sha');
+    if (shaIndex !== -1 && shaIndex + 1 < args.length) {
+        targetSha = args[shaIndex + 1];
+        console.log(`🔄 Restoring to commit: ${targetSha}`);
+    }
+    else {
+        console.log('🔄 Restoring to latest backup...');
+    }
+    // Check for --confirm-auth-overwrite flag
+    if (args.includes('--confirm-auth-overwrite')) {
+        confirmAuthOverwrite = true;
+    }
+    const result = await (0, index_1.performRestore)(backupRepoPath, targetSha, workspace, confirmAuthOverwrite);
+    if (result.success) {
+        console.log('✅ Restore complete');
+        console.log(`   Agents restored: ${result.agentsRestored}`);
+    }
+    else {
+        if (result.authOverwriteWarning) {
+            console.warn(`⚠️  ${result.message}`);
+            console.warn(`\n   To restore including sensitive credentials, run:\n   backup-agents restore ${targetSha ? `--sha ${targetSha}` : ''} --confirm-auth-overwrite`);
+        }
+        else {
+            console.error(`❌ Restore failed: ${result.message}`);
+            if (result.error) {
+                console.error(`   ${result.error}`);
+            }
+        }
+        process.exit(1);
+    }
+}
+async function handleHistory(backupRepoPath) {
+    const { executeCommand } = require('./utils');
+    console.log('📜 Backup history:\n');
+    try {
+        const log = executeCommand(`cd ${backupRepoPath} && git log --oneline -20`);
+        console.log(log);
+    }
+    catch (error) {
+        console.error(`❌ Failed to fetch history: ${error}`);
+        process.exit(1);
+    }
+}
+function showHelp() {
+    console.log(`
+@dambrogia/openclaw-agents-backup CLI
+
+Usage:
+  backup-agents [command] [options]
+
+Commands:
+  backup                          Backup all agents now
+  restore [options]               Restore agents
+  history                         Show recent backup history
+  --help, -h                      Show this help message
+
+Restore Options:
+  --sha SHA                       Restore to specific commit
+  --confirm-auth-overwrite        Allow overwriting auth-profiles.json (API tokens)
+
+Examples:
+  # Backup now
+  backup-agents backup
+
+  # Restore latest
+  backup-agents restore
+
+  # Restore to specific point in time
+  backup-agents restore --sha abc123def456
+
+  # Restore including sensitive credentials
+  backup-agents restore --confirm-auth-overwrite
+
+  # View backup history
+  backup-agents history
+
+Environment:
+  OPENCLAW_WORKSPACE             Path to OpenClaw workspace (default: /root/.openclaw/workspace)
+  BACKUP_ENCRYPTION_PASSWORD     Password for encrypting/decrypting files (required)
+`);
+}
+main().catch((error) => {
+    console.error(`❌ Unexpected error: ${error}`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./backup"), exports);
+__exportStar(require("./restore"), exports);
+__exportStar(require("./agentLister"), exports);
+__exportStar(require("./utils"), exports);
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@dambrogia/openclaw-agents-backup",
+  "version": "0.1.0",
+  "description": "Backup and restore OpenClaw agent workspaces across multi-agent setups",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "backup-agents": "dist/cli.js"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "roots": [
+      "<rootDir>/tests",
+      "<rootDir>/src"
+    ],
+    "testMatch": [
+      "**/__tests__/**/*.ts",
+      "**/?(*.)+(spec|test).ts"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.ts",
+      "!src/**/*.d.ts",
+      "!src/**/index.ts"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "branches": 0,
+        "functions": 0,
+        "lines": 0,
+        "statements": 0
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src tests --ext .ts",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "clean": "rm -rf dist coverage",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "openclaw",
+    "backup",
+    "restore",
+    "agents",
+    "disaster-recovery"
+  ],
+  "author": "dambrogia-ai",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.50.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.2.0"
+  },
+  "dependencies": {}
+}

package/src/agentLister.ts

@@ -0,0 +1,23 @@
+import { AgentBinding } from './types';
+import { executeCommand } from './utils';
+
+/**
+ * Query OpenClaw for all agent bindings
+ */
+export async function listAgents(): Promise<AgentBinding[]> {
+  try {
+    const output = executeCommand('openclaw agents list --bindings --json');
+    const agents = JSON.parse(output) as AgentBinding[];
+    return agents;
+  } catch (error) {
+    throw new Error(`Failed to list agents: ${error}`);
+  }
+}
+
+/**
+ * Validate that agent bindings have all required fields
+ */
+export function validateAgentBinding(agent: AgentBinding): boolean {
+  const required = ['id', 'workspace', 'agentDir'];
+  return required.every((field) => field in agent && agent[field as keyof AgentBinding]);
+}