Cloud Sync

Cloud Sync

PiCode Cloud keeps your editor settings and your Pi profile in step across machines. It is the paid half of the plan; the program itself stays free and complete without it. Everything below is what the code actually does.

Sync is bidirectional and per resource: the engine pulls what changed on another machine, pushes what changed here, and merges when both sides moved.

What syncs, and where it comes from

Resource	What it carries	Where it lives locally
settings	editor settings	data/user-data/User/settings.json
keybindings	keyboard shortcuts	data/user-data/User/keybindings.json
snippets	code snippets	data/user-data/User/snippets/
tasks	build tasks	data/user-data/User/tasks.json
prompts	prompt templates	data/user-data/User/prompts/
mcp	MCP servers	the MCP configuration
extensions	installed extensions	the editor's extension inventory
globalState	UI state (theme, last-used model…)	data/user-data/User/globalStorage
profiles	editor profiles	data/user-data/User/profiles/
piProfile	Pi's own profile	data/pi-agent

piProfile is the resource that makes PiCode different from plain settings sync: it carries the agent harness — agents/, subagents/, skills/, memory/, chains/, gentle-ai/ and specpi/, plus settings.json, models.json, subagents.json, trust.json and mcp-adapter.json — as a bundle of files. Merging is last-writer-wins per file; a file changed on both sides becomes one whole-file conflict.

The journey

┌──────────────── PiCode, on your machine (data/) ────────────────┐
│  settings · keybindings · snippets · tasks · prompts · mcp       │
│  extensions · UI state · editor profiles   → data/user-data/…    │
│  Pi profile (agents, skills, memory, models…) → data/pi-agent    │
│                                                                  │
│            └───────────────────────┬─────────────────────────────┘
│                                    ▼
│     The native sync engine (VS Code's, in the background)
│       · reads each resource
│       · compares local vs remote vs the last synced base
│       · uploads what changed, pulls and merges what changed away
└────────────────────────────────────┬─────────────────────────────┘
                                     │  HTTPS + your account token
                                     ▼
                     https://www.getpicode.app/api/v1/…
                                     │
                        ┌────────────┴─────────────┐
                        ▼                          ▼
                 Firebase Auth               🔐 PiCode API (Vercel)
                 “who are you?”               · encrypts the content
                                              · stores and serves it
                                              · enforces the quota
                                                     │
                                                     ▼
                                             🗄️ Firestore (encrypted)

When it runs: on start-up, every five minutes, and whenever something changes — with a short debounce so a burst of edits becomes one sync.

How it is stored in the cloud

• Manifest — users/{uid}/sync/manifest: the latest version of each resource and a running count of the bytes used.
• Content — users/{uid}/sync/resources/{resource}/{version}: the content, already encrypted.
• Encryption — AES-256-GCM over the compressed content, server-side. The client only ever exchanges plaintext; the API encrypts on write and decrypts on read. The stored envelope is picode-enc:v2:….
• Retention — the newest 20 revisions per resource.
• Quota — Free ≈ 1 MB · Pro ≈ 50 MB.
• Authentication — Firebase Auth through the PiCode Account provider; the engine's requests carry the account's bearer token.

What never leaves the machine

• 🔒 auth.json and its backups — credentials are machine-bound and are not part of the Pi profile bundle.
• 🚫 sessions/, npm/, node_modules/, bin/, extensions/, tmp/, git/ and caches inside the profile.

A separate channel: Pi sessions

Conversation transcripts are backed up, not continuously synced, over their own resource:

~/.pi/agent/sessions/<project>/*.jsonl
        │  each file becomes its own opaque ref on the piSessionsBackup resource
        │  incremental by SHA-1: only files whose hash changed are uploaded
        ▼
    cloud  ·  a 7-day rolling window  ·  a 45 MB soft ceiling
           ·  deleting a transcript locally never deletes the cloud copy

It is driven by two commands: picode.backupSessions and picode.restoreSessions (the latter asks for confirmation before writing back).

The profile is the unit

Everything above is designed around one idea: data/ is a portable profile. Copying it moves a whole PiCode; deleting it yields a clean one. Cloud sync is that same folder travelling between machines, with credentials left out and everything else encrypted before it crosses the wire.

---

Related: Pi Inside · Distribution and Licensing · Architecture · Roadmap and Known State