@storacha/clawracha

Sync OpenClaw agent workspaces to Storacha — decentralized, encrypted, multi-device.

No servers. No accounts to share. Just UCAN delegations and content-addressed data.

What It Does

Clawracha watches your agent's workspace for file changes and syncs them to a Storacha Space via UCN Pail — a CRDT key-value store backed by merkle clocks. Multiple devices can sync the same workspace without conflicts.

• Regular files → content-addressed via UnixFS, stored as CIDs
• Markdown files → CRDT merge via md-merge — concurrent edits merge automatically, no conflicts
• Private spaces → end-to-end encrypted via KMS before upload
• Multi-device → delegation bundles let you grant access to other devices

Quick Start

1. Install

# In your OpenClaw project
pnpm add @storacha/clawracha

Add to your OpenClaw config (openclaw.config.json or equivalent):

{
  "plugins": {
    "clawracha": {
      "enabled": true
    }
  }
}

2. Initialize

Generate an agent identity for your workspace:

openclaw clawracha init --agent myagent

This creates a .storacha/config.json in the agent's workspace with a fresh Ed25519 keypair.

3. Set Up a New Workspace

openclaw clawracha setup --agent myagent

This will:

1. Ask for your Storacha email (sends a confirmation link)
2. Wait for email confirmation and payment plan verification
3. Ask you to choose Public or Private (encrypted) access
4. Create a new Storacha Space
5. Generate delegations (upload, name, plan)
6. Do an initial sync of existing workspace files
7. Start watching for changes

4. Add Another Device

On the existing device (the one already set up):

openclaw clawracha grant did:key:z6Mk... --agent myagent

This outputs a delegation bundle (a base64 string). Copy it.

On the new device:

openclaw clawracha init --agent myagent
openclaw clawracha join <paste-bundle-here> --agent myagent

The new device pulls all existing files and starts syncing.

Interactive Setup

Don't want to remember the steps? Use the guided flow:

openclaw clawracha onboard --agent myagent

This walks you through init → setup/join interactively.

CLI Commands

All commands require --agent <id> to specify which agent workspace to operate on.

| Command | Description | |---------|-------------| | init --agent <id> | Generate agent identity (Ed25519 keypair) | | setup --agent <id> | Create a new Storacha Space via login | | join <bundle> --agent <id> | Join an existing workspace from a delegation bundle | | grant <DID> --agent <id> | Create a delegation bundle for another device | | status --agent <id> | Show sync status (delegations, space, running state) | | inspect --agent <id> | Debug internal state (pail entries, pending ops, revisions) | | onboard --agent <id> | Interactive guided setup |

Grant Options

# Output bundle as base64 to stdout (default)
openclaw clawracha grant did:key:z6Mk... --agent myagent

# Write bundle to a file instead
openclaw clawracha grant did:key:z6Mk... --agent myagent -o bundle.car

Agent Tools

When the plugin is running, agents get two MCP tools:

• storacha_sync_status — Check current sync state (running, last sync, entry count, pending changes)
• storacha_sync_now — Trigger an immediate sync cycle

How Sync Works

1. File watcher (chokidar) detects changes in the workspace
2. Changed files are encoded:
   • Regular files → UnixFS DAG blocks
   • Markdown files → CRDT entry via md-merge (RGA tree + event history)
   • Private spaces → encrypted before encoding
3. Changes become pail operations (put/del)
4. Operations are batched into a UCN revision and published
5. All blocks are packed into a CAR file and uploaded to Storacha
6. Remote changes from other devices are pulled, diffed, and applied locally

See docs/architecture.md for the full technical deep-dive and docs/reference.md for hidden features, edge cases, and troubleshooting.

Configuration

In your OpenClaw plugin config:

{
  "plugins": {
    "clawracha": {
      "enabled": true,
      "watchPatterns": ["**/*"],
      "ignorePatterns": [".git", "node_modules", ".storacha"]
    }
  }
}

| Option | Default | Description | |--------|---------|-------------| | enabled | false | Enable/disable the sync plugin | | watchPatterns | ["**/*"] | Glob patterns for files to sync | | ignorePatterns | [".git", "node_modules", ".storacha"] | Glob patterns to exclude |

Public vs Private Spaces

During setup, you choose the access type:

• Public — Files are stored as plaintext on IPFS/Filecoin. Anyone with the CID can access them.
• Private (encrypted) — Files are encrypted via Storacha's KMS before upload. Only devices with the proper delegations can decrypt.

Private spaces use @storacha/encrypt-upload-client with Google KMS for key management. The plan delegation grants KMS access, and decrypt delegations are scoped per-CID with 15-minute expiry.

Requirements

• Node.js ≥ 20
• OpenClaw ≥ 2026.0.0
• A Storacha account with an active payment plan

Docs

• Architecture Guide — How it works under the hood (sync lifecycle, CRDT merge, blockstore tiers, encryption, delegation model)
• Reference — .clawrachaignore, inspect command, delegation encoding, troubleshooting

License

Apache-2.0 OR MIT