Local Folder Sync

Sync a local folder with the PuppyOne cloud Context File System using the MUT protocol for version control.

What is Local Folder Sync

Local folder sync is built on the MUT protocol (a Git-like version control protocol) and creates a versioned sync channel between your local directory and PuppyOne Cloud.

• After editing files locally, use mut commit + mut push to push to the cloud
• When the cloud has changes, use mut pull to pull them locally
• Every push creates a version record — fully traceable and rollback-ready

┌──────────────┐                            ┌──────────────────┐
│              │  ── mut push ────────────→  │                  │
│  Local       │                             │  PuppyOne Cloud  │
│  ~/my-docs   │  ←── mut pull ───────────   │  Context FS      │
│              │                             │                  │
└──────────────┘      Version Control (MUT)  └──────────────────┘

Once synced, agents, MCP clients (Cursor / Claude Desktop), and the REST API can all access the content.

Quick Start

Prerequisites

npm install -g puppyone    # PuppyOne CLI
pip install mutai          # MUT CLI

Step 1: Create a sync connection

puppyone auth login
puppyone project use "My Project"
puppyone access add filesystem docs

The command prints the access endpoint URL, the Access Key, and a hint with both setup paths.

Step 2: Pick a setup path

You have two options: Clone a fresh folder or Connect an existing folder. Pick whichever matches your situation.

A. Clone to a fresh folder (no local files yet)

mut clone <endpoint-url> --credential <access-key>
cd docs

Creates a new ./docs/ directory populated from the cloud scope.

B. Connect an existing folder (you already have files locally)

cd /path/to/your/existing/folder
mut connect <endpoint-url> --credential <access-key>

mut connect pulls cloud state, three-way merges with whatever is on disk, then pushes the result. Files that exist only locally get uploaded; files that exist only in the cloud get downloaded. No overwrite, no data loss.

Want PuppyOne CLI to do it in one shot? Use --link:

puppyone access add filesystem docs --link /path/to/your/folder

This is equivalent to running puppyone access add filesystem docs && cd <link> && mut connect ... for you.

Step 3: Edit, commit, push

echo "# Welcome" > readme.md
mut commit -m "init docs"
mut push

Scopes

Each sync connection is bound to a scope — a path in the cloud project tree. Different local folders can sync to different scopes:

puppyone access add filesystem docs      # scope = /docs
puppyone access add filesystem code      # scope = /code
puppyone access add filesystem config    # scope = /config

This creates a unified project tree in the cloud:

Root/
├── docs/       ← from ~/my-docs
├── code/       ← from ~/my-code
└── config/     ← from ~/my-config

This allows different team members or agents to manage their own sections, all merging into the same project.

Sync Behavior

MUT vs Legacy "Real-time" Sync

File Type Support

Version Management

The MUT protocol automatically creates version records for every push.

View commit history

cd ~/my-docs
mut log

Rollback

View version history and rollback with one click in the PuppyOne Dashboard, or via the API.

Using with Claude Code

Local folder sync is the best way to give AI coding tools access to PuppyOne data:

1. Create connection and attach a local folder. Pick whichever fits your situation:

# A) The folder already exists on disk → one-shot
puppyone access add filesystem workspace --link ~/ai-workspace
 
# B) The folder doesn't exist yet → create AP, then clone
puppyone access add filesystem workspace
mut clone <url> --credential <key> --dir ~/ai-workspace
 
# C) The folder exists, but you ran A) without --link by accident
cd ~/ai-workspace
mut connect <url> --credential <key>

2. Edit with Claude Code in ~/ai-workspace

3. Commit and push:

cd ~/ai-workspace
mut commit -m "AI updates"
mut push

All changes have version history — you can compare AI modifications and rollback as needed.

Managing Connections

# List all connections
puppyone access ls
 
# View Access Key (available anytime)
puppyone access key <id>
 
# Regenerate Access Key
puppyone access key <id> --regenerate
 
# Delete connection
puppyone access rm <id>

FAQ

How do I sync multiple folders?

Create a separate scope connection for each folder:

puppyone access add filesystem project-a --link ~/project-a
puppyone access add filesystem project-b --link ~/project-b

Or split it into two steps:

puppyone access add filesystem project-a
mut clone   <url-a> --credential <key-a>           # fresh checkout
# or
cd ~/existing-project-b
mut connect <url-b> --credential <key-b>           # adopt an existing folder

Clone or Connect?

What if push reports a conflict?

Pull the latest version first, resolve conflicts, then push again:

mut pull
# Resolve conflicts...
mut commit -m "resolve conflicts"
mut push

Lost the Access Key?

puppyone access key <connection-id>

The key is stored in the database — it's not one-time. You can retrieve it anytime.