@quackstro/ark 🚢

Ark — Encrypted backup & restore plugin for OpenClaw. Preserve your entire setup and migrate to a new system in one command.

Features

• AES-256-GCM encryption with PBKDF2 key derivation (600K iterations)
• Selective backup/restore — choose which categories to include
• 10 backup categories: config, credentials, wallet, brain, doc-rag, cron, extensions, workspace, devices, identity
• Retention policy — auto-prune old backups by count or age
• Agent tools — backup_create, backup_restore, backup_list, backup_status
• CLI commands — openclaw backup create|restore|list|prune
• Slash commands — /ark, /ark backup, /ark list, /ark restore, /ark prune, /ark help
• Zero external dependencies — uses Node.js built-in crypto, zlib, and a minimal tar implementation

Install

From source (recommended)

cd ~/.openclaw/extensions
git clone https://github.com/Quackstro/openclaw-ark ark
cd ark && npm install && npm run build

Via npm (coming soon)

openclaw plugins install @quackstro/ark

Documentation

• Command Reference — All slash commands, agent tools, and CLI usage
• Architecture — Archive format, encryption, categories, tar implementation
• Migration Guide — Step-by-step guide for moving to a new system

Usage

Telegram

Command	Description
/ark	Status overview
/ark backup <passphrase>	Create encrypted backup
/ark list	List all backups
/ark restore	Restore instructions
/ark prune	Remove old backups
/ark help	Command reference

CLI

# Create a backup (all categories)
openclaw backup create -p "my-secure-passphrase"

# Create with specific categories only
openclaw backup create -p "my-passphrase" -c config,wallet,brain

# List backups
openclaw backup list

# Restore (all categories)
openclaw backup restore ./backups/openclaw-backup-2026-02-11.ocbak -p "my-passphrase"

# Restore specific categories only
openclaw backup restore ./backup.ocbak -p "my-passphrase" -c config,workspace

# Dry-run restore (preview without writing)
openclaw backup restore ./backup.ocbak -p "my-passphrase" --dry-run

# Prune old backups per retention policy
openclaw backup prune

Agent (conversational)

"Create a backup with passphrase 'hunter2'" "Show backup status" "Restore from the latest backup" "List my backups"

Configuration

{
  plugins: {
    entries: {
      ark: {
        enabled: true,
        config: {
          backupDir: "~/.openclaw/backups",
          categories: {
            config: true,
            credentials: true,
            wallet: true,
            brain: true,
            docrag: true,
            cron: true,
            extensions: true,
            workspace: true,
            devices: true,
            identity: true
          },
          retention: {
            maxBackups: 5,
            maxAgeDays: 30
          },
          notifications: {
            enabled: true,
            channel: "telegram",
            target: "your-chat-id"
          }
        }
      }
    }
  }
}

Backup Categories

Category	Contains	Sensitive
config	openclaw.json (API keys, channel tokens)	🔐 Yes
credentials	OAuth tokens, provider credentials	🔐 Yes
wallet	DOGE keystore, UTXOs, audit log	🔐 Yes
brain	Brain stores (LanceDB), pending actions	No
docrag	Ingested documents + embeddings	No
cron	Cron job definitions + run history	No
extensions	Installed plugins (source code)	No
workspace	Agent workspace (AGENTS.md, memory/, scripts/)	Mixed
devices	Paired device configs	No
identity	Agent identity data	No

Archive Format (.ocbak)

OCBAK1 (6 bytes magic)
Salt   (32 bytes — random)
IV     (16 bytes — random)
AuthTag(16 bytes — GCM auth tag)
Body   (AES-256-GCM encrypted tar.gz)

Key derivation: PBKDF2-SHA512, 600,000 iterations.

Migration Workflow

1. On old system: openclaw backup create -p "migrate-2026"
2. Copy the .ocbak file to the new system
3. On new system: Install OpenClaw, then openclaw backup restore ./file.ocbak -p "migrate-2026"
4. Restart: sudo supervisorctl restart openclaw

Testing

# Run all tests
npm test

# Or directly
node --test tests/config.test.ts tests/engine.test.ts

23 tests covering:

• Config parsing (defaults, overrides, categories, tilde expansion)
• Backup creation, listing, restore (correct/wrong passphrase, dry-run, selective)
• Pruning (max count enforcement)
• Archive format (magic bytes, salt, ciphertext uniqueness)

License

MIT — Quackstro LLC