clawroam

# ClawRoam — Portable Agent Environment

You are an OpenClaw agent with the **clawroam** skill installed. This skill
gives you automatic, continuous sync of the user's knowledge and environment
across all their machines — like iCloud for AI agents.

## Architecture

ClawRoam works like a combination of iCloud and Git:
- **Auto-sync**: file changes are detected, auto-committed, and pushed
- **Versioned**: every change is a commit — full history, rollback anytime
- **Encrypted**: Ed25519 keypair per installation — private key never leaves the machine
- **Multi-provider**: user picks where their vault lives

## Providers

| Provider | Type | Setup |
|----------|------|-------|
| ClawRoam Cloud | Managed (paid per MB) | One command — `clawroam cloud signup` |
| Google Drive | BYOS (free) | OAuth flow via `clawroam provider gdrive` |
| Dropbox | BYOS (free) | OAuth flow via `clawroam provider dropbox` |
| FTP/SFTP | BYOS (free) | Host + credentials via `clawroam provider ftp` |
| Git | BYOS (free) | Any git remote via `clawroam provider git` |
| S3 | BYOS (free) | Any S3-compatible via `clawroam provider s3` |
| WebDAV | BYOS (free) | Nextcloud etc via `clawroam provider webdav` |
| Local | BYOS (free) | USB/NAS mount via `clawroam provider local` |

"BYOS" = Bring Your Own Storage. Free forever. ClawRoam Cloud is the
convenience option for people who don't want to manage storage.

## What Syncs

```
ALWAYS SYNCED (shared knowledge pool):
  identity/USER.md          Who you are
  knowledge/MEMORY.md       Long-term memory
  knowledge/projects/       Project context
  requirements.yaml         System packages
  skills-manifest.yaml      Installed skills list

NEVER AUTO-SYNCED (per-instance):
  local/SOUL.md             This agent's personality
  local/IDENTITY.md         This agent's identity
  local/config-override     Local config tweaks

OPT-IN SYNC:
  openclaw config.json      Gateway/model config
  credentials/              Channel auth (encrypted separately)
```

#...

# 🦞 ClawRoam

**Portable identity vault for OpenClaw. Your AI agent follows you everywhere.**

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![OpenClaw Skill](https://img.shields.io/badge/OpenClaw-skill-orange.svg)](SKILL.md)

ClawRoam is an open-source OpenClaw skill that syncs your agent's knowledge, memory, and system packages across all your machines — like iCloud, but for AI agents.

## The idea

You have a work laptop, a home machine, maybe a server. Each runs OpenClaw. You want them to share your knowledge but have their own personality. ClawRoam makes that work:

- **Knowledge is shared** — USER.md, MEMORY.md, projects, package lists
- **Soul is local** — each instance keeps its own SOUL.md and IDENTITY.md
- **Sync is invisible** — changes auto-detect, auto-commit, auto-push
- **History is versioned** — every change is a git commit, rollback anytime
- **Storage is your choice** — Google Drive, Dropbox, Git, FTP, S3, or our managed cloud

## Quick start

```bash
# Install the skill
clawdhub install getlighty-clawroam

# Initialize (scans packages, generates keypair, captures knowledge)
clawroam init

# Pick storage — managed cloud (50 MB free):
clawroam provider setup cloud

# Or bring your own:
clawroam provider setup gdrive    # Google Drive
clawroam provider setup dropbox   # Dropbox
clawroam provider setup git       # Any git repo
clawroam provider setup ftp       # FTP/SFTP
clawroam provider setup s3        # S3-compatible
clawroam provider setup local     # USB/NAS

# Start auto-sync
clawroam sync start
```

### On a new machine

```bash
# Install OpenClaw + skill
npm install -g openclaw
clawdhub install getlighty-clawroam

# Connect to your vault
clawroam init
clawroam provider setup cloud  # same credentials

# Pull everything
clawroam migrate pull
# → Restores knowledge, shows package diff, offers to install missing
```

## How sync works

ClawRoam works like a combination of **iCloud** and **Git**:

1. **File watcher...