• One-step migration — export on source, bootstrap on target. Done.
• Dual runtime — Use whichever ecosystem you prefer: npx or uvx. Bundles are 100% cross-compatible.
• AES-256-GCM encryption — Optional passphrase-based encryption with PBKDF2 key derivation (200k iterations).
• Export profiles — Ship everything (full), skip secrets (no-credentials), or transfer just personality (memory-only).
• Automatic backups — Every import creates a timestamped backup of the existing state before overwriting.
• Integrity verification — SHA-256 checksums embedded in the bundle manifest, verified on import.
• Built-in transfer — Copy bundles to remote hosts via SCP without leaving the CLI.
• Health checks — Bootstrap runs openclaw doctor and openclaw status after restore.

Choose your runtime:

# Node.js (npm)
npm install -g bundleclaw

# Python (pip)
pip install bundleclaw

Or run directly without installing:

# Node.js
npx bundleclaw --help

# Python
uvx bundleclaw --help

# 1. Export agent state (on source machine)
bundleclaw export \
  --source ~/.openclaw \
  --workspace ~/.openclaw/workspace \
  --profile full \
  --encrypt-pass 'strong-passphrase' \
  --out agent-state.bcz

# 2. Transfer to target machine
bundleclaw transfer \
  --bundle agent-state.bcz \
  --to user@target-host:/tmp/agent-state.bcz

# 3. Bootstrap on target (import + verify + restart)
bundleclaw bootstrap \
  --bundle /tmp/agent-state.bcz \
  --encrypt-pass 'strong-passphrase' \
  --target ~/.openclaw

Package OpenClaw state into a .bcz bundle.

bundleclaw export \
  --source <openclaw-home> \
  --workspace <workspace-path> \
  --out <output-file> \
  --profile <full|no-credentials|memory-only> \
  --encrypt-pass <passphrase>          # optional

Restore a bundle onto the target machine.

bundleclaw import \
  --bundle <bcz-file> \
  --target <openclaw-home> \
  --encrypt-pass <passphrase>          # if encrypted

A timestamped backup of the existing state is created automatically before restore.

Run integrity checks after import.

bundleclaw verify --target <openclaw-home>

Checks for: openclaw.json, workspace/SOUL.md, workspace/memory/ directory.

Copy a bundle to a remote host via SCP.

bundleclaw transfer \
  --bundle <bcz-file> \
  --to <user@host:/path> \
  --scp-bin <scp>                      # optional, defaults to "scp"

All-in-one: import + verify + optional service restart + health checks.

bundleclaw bootstrap \
  --bundle <bcz-file> \
  --target <openclaw-home> \
  --encrypt-pass <passphrase>          # if encrypted
  --restart-cmd <command>              # default: "openclaw gateway restart"
  --skip-restart                       # skip service restart

┌──────────────────────────────────────────────────────────┐
│                     BundleClaw                           │
├────────────────────────┬─────────────────────────────────┤
│     Node CLI           │         Python CLI              │
│  (TypeScript/npm)      │      (Typer/pip)                │
├────────────────────────┴─────────────────────────────────┤
│              Shared .bcz Bundle Format v1                │
│                                                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │ manifest.json│  │  payload/    │  │  AES-256-GCM   │  │
│  │  - checksums │  │  - config    │  │  encryption    │  │
│  │  - profile   │  │  - identity  │  │  (optional)    │  │
│  │  - metadata  │  │  - workspace │  │                │  │
│  └─────────────┘  └──────────────┘  └────────────────┘  │
└──────────────────────────────────────────────────────────┘

BundleClaw handles sensitive agent state. Follow these guidelines:

• Always encrypt bundles that contain credentials (--encrypt-pass).
• Use secure transport (SCP/SFTP) when transferring bundles between machines.
• Use no-credentials profile when encryption isn't feasible.
• Delete bundles after successful migration — they may contain secrets.
• Review the bundle format specification at spec/FORMAT.md.

bundleclaw/
├── node-cli/              # Node.js implementation (TypeScript)
│   ├── src/index.ts       # CLI entry point
│   ├── package.json
│   └── tsconfig.json
├── python-cli/            # Python implementation (Typer)
│   ├── bundleclaw/
│   │   ├── __init__.py
│   │   └── cli.py         # CLI entry point
│   └── pyproject.toml
├── spec/
│   └── FORMAT.md          # Bundle format v1 specification
├── .github/
│   └── workflows/
│       ├── ci.yml         # Build verification on push/PR
│       └── release.yml    # Auto-publish to npm + PyPI on tags
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE                # MIT
├── SECURITY.md
└── README.md              # You are here

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

• Setting up the development environment
• Code style and conventions
• Submitting pull requests
• Reporting issues

MIT © 2026 immersir