{"_id":"@dambrogia/openclaw-agents-backup","_rev":"3-b5dfc613d52dc8dbd4c1b20a9d58c9dd","name":"@dambrogia/openclaw-agents-backup","dist-tags":{"latest":"1.2.0"},"versions":{"0.1.0":{"name":"@dambrogia/openclaw-agents-backup","version":"0.1.0","keywords":["openclaw","backup","restore","agents","disaster-recovery"],"author":{"name":"dambrogia-ai"},"license":"MIT","_id":"@dambrogia/openclaw-agents-backup@0.1.0","maintainers":[{"name":"dambrogia","email":"domdambrogia@gmail.com"}],"bin":{"backup-agents":"dist/cli.js"},"dist":{"shasum":"f5788cb781de77cd02f75a705037d18491531729","tarball":"https://registry.npmjs.org/@dambrogia/openclaw-agents-backup/-/openclaw-agents-backup-0.1.0.tgz","fileCount":23,"integrity":"sha512-irhz9Wz9DlBGL3U4FSq/5hQk0A4Viv8Afw8KCoq17MKnUGxwcchCjylAdulaw7/60AfQyVsrwGrES07X5VvMVw==","signatures":[{"sig":"MEUCIEbvCKdp7FT56wO3elzgBCrHoq0xZNbCNTXnxdihYDPJAiEA4iJhSjjJ+KOcFY31D8t2NEtSuCcGd9ltA2yZuCoC9PU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":81994},"jest":{"roots":["<rootDir>/tests","<rootDir>/src"],"preset":"ts-jest","testMatch":["**/__tests__/**/*.ts","**/?(*.)+(spec|test).ts"],"testEnvironment":"node","coverageThreshold":{"global":{"lines":0,"branches":0,"functions":0,"statements":0}},"collectCoverageFrom":["src/**/*.ts","!src/**/*.d.ts","!src/**/index.ts"]},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"cf16b4ed42922fb561e9f8838bcf92ef30711349","scripts":{"lint":"eslint src tests --ext .ts","test":"jest","build":"tsc","clean":"rm -rf dist coverage","prepare":"npm run build","test:coverage":"jest --coverage"},"_npmUser":{"name":"dambrogia","email":"domdambrogia@gmail.com"},"_npmVersion":"10.9.2","description":"Backup and restore OpenClaw agent workspaces across multi-agent setups","directories":{},"_nodeVersion":"23.6.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.5.0","eslint":"^8.50.0","ts-jest":"^29.1.0","typescript":"^5.2.0","@types/jest":"^29.5.0","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-agents-backup_0.1.0_1771547411896_0.04595624534869014","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@dambrogia/openclaw-agents-backup","version":"1.1.0","keywords":["openclaw","backup","restore","agents","disaster-recovery"],"author":{"name":"dambrogia-ai"},"license":"MIT","_id":"@dambrogia/openclaw-agents-backup@1.1.0","maintainers":[{"name":"dambrogia","email":"domdambrogia@gmail.com"}],"bin":{"backup-agents":"dist/cli.js"},"dist":{"shasum":"dc9ffc223862fd854778a5951216c675b8598a08","tarball":"https://registry.npmjs.org/@dambrogia/openclaw-agents-backup/-/openclaw-agents-backup-1.1.0.tgz","fileCount":23,"integrity":"sha512-TSjdb4i2gsEg0uT7qpkk1kKamd6jop8tfykVR5txzyl57BrmtWpuJba7F+qjepdV2QV7c6W/wvEHHQT0T0BaKw==","signatures":[{"sig":"MEUCIQD9fTQ43xkf9BMOKQrIy9y2VZhNRXWQMm2RUNrIr6LfagIgOBg8Kpq8UVUm6cqkNQ2jymvjUPGqnkmNXNWPQxpfjLM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":82087},"jest":{"roots":["<rootDir>/tests","<rootDir>/src"],"preset":"ts-jest","testMatch":["**/__tests__/**/*.ts","**/?(*.)+(spec|test).ts"],"testEnvironment":"node","coverageThreshold":{"global":{"lines":0,"branches":0,"functions":0,"statements":0}},"collectCoverageFrom":["src/**/*.ts","!src/**/*.d.ts","!src/**/index.ts"]},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"6195c502a3fc7227f912d5cdb2787bc4a47cfdcf","scripts":{"lint":"eslint src tests --ext .ts","test":"jest","build":"tsc","clean":"rm -rf dist coverage","prepare":"npm run build","test:coverage":"jest --coverage"},"_npmUser":{"name":"dambrogia","email":"domdambrogia@gmail.com"},"_npmVersion":"10.9.2","description":"Backup and restore OpenClaw agent workspaces across multi-agent setups","directories":{},"_nodeVersion":"23.6.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.5.0","eslint":"^8.50.0","ts-jest":"^29.1.0","typescript":"^5.2.0","@types/jest":"^29.5.0","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-agents-backup_1.1.0_1771607729747_0.6143704298666328","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@dambrogia/openclaw-agents-backup","version":"1.2.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":{"name":"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":{},"_id":"@dambrogia/openclaw-agents-backup@1.2.0","gitHead":"1650856721f29d069dbec0534fea1d281b9cc3b2","_nodeVersion":"23.6.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-ETfn49CqA2Vp/rnOuZaQnueexvSNzQwoMO481T96SsCdmAiCjeBU3R/9Ng5zvAAwVaE0svlFQjCLLLIVya6V4g==","shasum":"c27fe07d8686bf17a149e30a3966a7e3f16239b6","tarball":"https://registry.npmjs.org/@dambrogia/openclaw-agents-backup/-/openclaw-agents-backup-1.2.0.tgz","fileCount":23,"unpackedSize":82087,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFlMEGKPEvCV3FjkWG1DjuPuUUUbGyLPQ05La7G5HakpAiEA4GroWJ9/uXQmMJUDw7ArH6Tr4EljeyTIAXDygswfdxI="}]},"_npmUser":{"name":"dambrogia","email":"domdambrogia@gmail.com"},"directories":{},"maintainers":[{"name":"dambrogia","email":"domdambrogia@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-agents-backup_1.2.0_1771612021771_0.672731981158242"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-20T00:30:11.808Z","modified":"2026-02-20T18:27:02.039Z","0.1.0":"2026-02-20T00:30:12.030Z","1.1.0":"2026-02-20T17:15:29.884Z","1.2.0":"2026-02-20T18:27:01.934Z"},"author":{"name":"dambrogia-ai"},"license":"MIT","keywords":["openclaw","backup","restore","agents","disaster-recovery"],"description":"Backup and restore OpenClaw agent workspaces across multi-agent setups","maintainers":[{"name":"dambrogia","email":"domdambrogia@gmail.com"}],"readme":"# @dambrogia/openclaw-agents-backup\n\nBackup and restore OpenClaw multi-agent workspaces. Automated hourly snapshots with full disaster recovery capabilities.\n\n[![npm version](https://img.shields.io/npm/v/@dambrogia/openclaw-agents-backup)](https://www.npmjs.com/package/@dambrogia/openclaw-agents-backup)\n[![Tests](https://github.com/dambrogia-ai/openclaw-agents-backup/actions/workflows/test.yml/badge.svg)](https://github.com/dambrogia-ai/openclaw-agents-backup/actions)\n[![Coverage](https://img.shields.io/badge/coverage->80%25-green)](./README.md)\n\n## Why This Exists\n\nOpenClaw enables multiple agents to run in a single instance. Each agent has its own workspace with configuration, memory, identity files, and session history. If something goes wrong—disk corruption, accidental deletion, security incident—you lose everything.\n\nThis skill automates hourly backups of all agent workspaces and agent directories to a central Git repository. When disaster strikes, you can restore any agent to any point in history by pulling from your backup repo.\n\n## Agent Integration\n\nThe easiest way to use this skill is to install it and let your agent call the CLI commands.\n\n### Setup (One-time)\n\n1. **Install the skill in your agent's project:**\n```bash\nnpm install @dambrogia/openclaw-agents-backup\n```\n\nThat's it. You're done.\n\n### Usage\n\nYour agent can now run:\n\n```bash\nbackup-agents backup              # Back up all agents now\nbackup-agents restore             # Restore to latest backup\nbackup-agents restore --sha abc123 # Restore to specific point in time\nbackup-agents history             # Show recent backups\n```\n\nJust tell your agent what you need:\n\n- **\"Back up my agents\"** → Agent runs `backup-agents backup`\n- **\"Restore my agents\"** → Agent runs `backup-agents restore`\n- **\"Restore agents to yesterday\"** → Agent runs `backup-agents restore --sha <commit>`\n- **\"Show me backup history\"** → Agent runs `backup-agents history`\n\n### Scheduled Backups\n\nFor automated hourly backups, set up a cron job in your OpenClaw instance:\n\n```javascript\n// Runs every hour at :00\ncron.add({\n  name: 'agents-backup-hourly',\n  schedule: { kind: 'cron', expr: '0 * * * *' },\n  payload: {\n    kind: 'agentTurn',\n    message: 'Back up all agents: backup-agents backup',\n    timeoutSeconds: 300\n  },\n  sessionTarget: 'isolated',\n  notify: false\n});\n```\n\nOr just tell your agent: **\"Schedule hourly backups of my agents\"**\n\n---\n\n## Quick Start\n\n### 1. Initialize Backup Repository\n\n```bash\nmkdir my-agents-backup\ncd my-agents-backup\ngit init\ngit config user.email \"backup@example.com\"\ngit config user.name \"Backup Bot\"\ngit commit --allow-empty -m \"Initial commit\"\n```\n\n### 2. Create Backup Config\n\nIn your OpenClaw workspace (`~/.openclaw/workspace`), create `.backupconfig.json`:\n\n```json\n{\n  \"backupRepoPath\": \"/path/to/my-agents-backup\"\n}\n```\n\n### 3. Install the Library\n\n```bash\nnpm install @dambrogia/openclaw-agents-backup\n```\n\n### 4. Schedule Hourly Backups\n\nUse OpenClaw's cron system or call the backup function hourly.\n\n```javascript\nconst { performBackup } = require('@dambrogia/openclaw-agents-backup');\n\n// Run every hour\nawait performBackup('/root/.openclaw/workspace');\n```\n\n### 5. Disaster Recovery\n\nWhen you need to restore:\n\n```bash\n# Wipe the VPS, reinstall OpenClaw\nopenclaw init\n\n# Clone your backup\ngit clone <backup-repo-url> /path/to/my-agents-backup\n\n# Create config pointing to backup repo\necho '{\"backupRepoPath\": \"/path/to/my-agents-backup\"}' > ~/.openclaw/workspace/.backupconfig.json\n\n# Restore all agents to current state\nnode -e \"require('@dambrogia/openclaw-agents-backup').performRestore(...)\"\n```\n\n## Features\n\n✅ **Multi-agent support** — Back up all agents in one command  \n✅ **Hourly snapshots** — Automated backup schedule  \n✅ **Git history** — Full point-in-time recovery via Git commits  \n✅ **Selective ignore** — `.env`, secrets, and temporary files never committed  \n✅ **Minimal disk usage** — Only changed files are stored in Git  \n✅ **Simple restore** — One command to restore any agent to any point  \n✅ **Test coverage** — >80% covered, production-ready\n\n## What Gets Backed Up\n\nFor each agent, the skill backs up:\n\n- **Workspace** — Identity files (SOUL.md, USER.md, IDENTITY.md), memory (MEMORY.md, memory/), configuration, tools\n- **Agent directory** — Session files, auth profiles, history (when available)\n\nWhat's **not** backed up (by design):\n\n- `.env*` files (use these for secrets)\n- `auth-profiles.json` (sensitive auth data)\n- `node_modules/`, build artifacts, logs\n\n## API Reference\n\nAgents call these functions directly. Most users don't need to interact with the API — just tell your agent what you need.\n\n### Backup\n\n```typescript\nimport { performBackup } from '@dambrogia/openclaw-agents-backup';\n\nconst result = await performBackup('/root/.openclaw/workspace');\n\n/*\n{\n  success: true,\n  message: \"Backed up 3 agents. Changes: 2\",\n  agentsProcessed: 3,\n  changes: [\n    { agentId: 'main', workspaceChanged: true, agentDirChanged: false },\n    { agentId: 'worker-1', workspaceChanged: false, agentDirChanged: true },\n    { agentId: 'worker-2', workspaceChanged: false, agentDirChanged: false }\n  ]\n}\n*/\n```\n\n### Restore\n\n```typescript\nimport { performRestore } from '@dambrogia/openclaw-agents-backup';\n\n// Restore latest backup\nconst result = await performRestore(\n  '/path/to/backup-repo',\n  null,\n  '/root/.openclaw/workspace'\n);\n\n// Or restore to specific point in time (git SHA)\nconst result = await performRestore(\n  '/path/to/backup-repo',\n  'abc123def456',\n  '/root/.openclaw/workspace'\n);\n\n/*\n{\n  success: true,\n  message: \"Successfully restored 3 agents\",\n  agentsRestored: 3\n}\n*/\n```\n\n## Backup Structure\n\n```\nmy-agents-backup/\n├── .git/                 # Full Git history\n├── archives/\n│   ├── main/\n│   │   ├── agent.json    # Metadata: paths, timestamp, identity\n│   │   ├── workspace/    # Synced workspace directory\n│   │   └── agentDir/     # Synced agent directory\n│   ├── worker-1/\n│   │   ├── agent.json\n│   │   ├── workspace/\n│   │   └── agentDir/\n│   └── ...\n└── .gitignore\n```\n\nEach backup run creates one Git commit. You can browse history:\n\n```bash\ncd my-agents-backup\ngit log --oneline\n# Restore to a specific commit\ngit checkout abc123def456\n```\n\n## Testing\n\n```bash\nnpm test              # Run tests\nnpm run test:coverage # Check coverage (>80% required)\nnpm run lint          # ESLint check\nnpm run build         # TypeScript compilation\n```\n\n## Common Scenarios\n\n### Restore an Agent After Accidental Changes\n\n```bash\n# Find the commit before the change\ncd my-agents-backup\ngit log --oneline | head -10\n\n# Restore that state\ngit checkout <commit-hash>\nnode -e \"require('@dambrogia/openclaw-agents-backup').performRestore(...)\"\n```\n\n### Back Up Before Major Changes\n\nRun backup manually before modifying agent code or identity:\n\n```javascript\nconst { performBackup } = require('@dambrogia/openclaw-agents-backup');\nawait performBackup('/root/.openclaw/workspace');\n```\n\nCheck that files were committed in Git.\n\n### Migrate Agents to New VPS\n\n1. Set up new VPS with OpenClaw\n2. Clone your backup repo\n3. Point `.backupconfig.json` to it\n4. Run restore — agents are back online\n\n## Size Considerations\n\nEach backup cycle syncs full agent workspaces and agent directories. Disk usage:\n\n- **`archives/` directory** — Full copy of workspace + agentDir per agent (updated hourly, size stays constant)\n- **Git repository** — Only changed files are committed; grows incrementally with actual changes\n\n### Realistic Example\n\n**1 agent with 100MB workspace:**\n- `archives/main/workspace/` — 100MB (constant, updated each sync)\n- Git growth — 500KB-1MB per day (memory files + config changes) = ~15MB/month\n- Total after 30 days — ~115MB\n\n**3 agents with 100MB each:**\n- `archives/` total — ~300MB (constant)\n- Git growth — ~45MB/month (3 agents × 15MB/month)\n- Total after 30 days — ~345MB\n\n**Note:** If agents have cloned git repos in their workspace, those don't inflate Git (stored in `archives/` only, not committed to backup Git). Backup repo itself grows only by actual edits to memory, config, and metadata files — typically small daily changes.\n\nRecommendation: For typical setups, monthly growth is 10-50MB. A 35GB disk is more than sufficient for years of backups.\n\n**⚠️ Warning:** If agents accidentally save large files (binaries, datasets, etc.) to their workspace, Git history will grow quickly. Use `.gitignore` in agent workspaces to prevent committing large artifacts.\n\n## Limitations\n\n- **Point-in-time restore via Git SHA** — Requires manual `git checkout` before calling restore\n- **No encryption** — Backup repo should be private and secure\n- **No compression** — Backups stored as full directory syncs in Git\n- **Single backup location** — Multi-region replication not supported\n- **Large files bloat Git** — If agents accidentally save large files (binaries, datasets, etc.) to workspace, Git history will balloon. Recommend using `.gitignore` in agent workspaces to prevent this\n\n## Troubleshooting\n\n**Q: Backup runs but doesn't commit?**  \nA: Check Git configuration in the backup repo:\n```bash\ncd /path/to/backup-repo\ngit config user.email \"test@example.com\"\ngit config user.name \"Test\"\ngit log --oneline  # Verify commits are created\n```\n\n**Q: Restore says \"Archives directory not found\"?**  \nA: Run backup at least once to create the archives directory structure.\n\n**Q: Can I back up to a remote server?**  \nA: Yes! `backupRepoPath` can be a local clone of a remote repo. Configure a Git remote and push after backups:\n```bash\ncd /path/to/backup-repo\ngit remote add origin <repo-url>\ngit push origin main\n```\n\n## Performance\n\n- **Backup time** — Depends on agent size and disk speed. Typical: 30s–2min per agent\n- **Restore time** — Similar to backup time\n- **Cron interval** — Hourly recommended; can run more/less frequently\n\n## License\n\nMIT — Use freely in your projects.\n\n## Contributing\n\nIssues, PRs, and questions welcome! Please include test cases for any changes.\n\n---\n\n**Made for OpenClaw multi-agent setups. Disaster recovery, made simple.**\n","readmeFilename":"README.md"}