cloud-sync/README.md

instance-sync

Per-user Minecraft instance sync over the Timemachine Network, backed by restic. Single Python zipapp drops into Prism / MMC / ATLauncher pre-launch and post-exit hooks alongside packwiz-installer-bootstrap. Part of the automc platform.

Repo + package + on-disk dir names are still cloud-sync / cloud_sync / .cloud-sync/ for now — the rename was at the product / UI / CLI level. A future commit can pick up the file-system rename when it's worth breaking existing installs.

See DESIGN.md for the full architecture (restic backend, two-port cloud-svc control plane, etc.).

Status

Working skeleton + sync logic. 33 tests pass. E2E verified against a local restic-rest-server (pull empty → push initial → delete local → pull restores → modify+push creates second snapshot → client forget --prune correctly blocked by --append-only).

Install / build

Requires Python ≥ 3.10. No runtime deps (stdlib only).

# build single-file zipapp
make build       # → cloud-sync.pyz (~53 KB)

# or pip-install
make install     # pip install -e .

Usage in Prism (or MMC / ATLauncher)

One-time global wiring. Settings → Default → Custom commands (NOT per-instance):

Pre-launch:  python /path/to/cloud-sync.pyz pull --pack-folder=$INST_MC_DIR
Post-exit:   python /path/to/cloud-sync.pyz push --pack-folder=$INST_MC_DIR

That single line works for every existing and future instance. Instances without a .cloud-sync/sync.json are no-ops (silent rc=0, MC launches normally) — sync only kicks in for instances you've explicitly opted in.

Per-instance opt-in:

# interactive — opens Qt login dialog for the token
python /path/to/cloud-sync.pyz setup --pack-folder=/path/to/instance/minecraft

# scripted equivalent
python /path/to/cloud-sync.pyz init \
    --pack-folder=/path/to/instance/minecraft \
    --url=https://cloud.tm.center \
    --token=DISCORD_ID:PASSWORD

That mints a fresh instance_id (ULID), writes .cloud-sync/sync.json (the opt-in marker) and .cloud-sync/token (mode 600). Subsequent launches sync automatically via the global hook.

Opting out / pausing:

python /path/to/cloud-sync.pyz disable --pack-folder=/path/to/instance/minecraft

Renames sync.json → sync.json.disabled. Instance returns to no-op behavior (the opt-in gate only sees a literal sync.json). Re-enable later with:

python /path/to/cloud-sync.pyz enable  --pack-folder=/path/to/instance/minecraft

That rename-back preserves the original instance_id so snapshots continue against the same restic repo — no fresh ULID, no orphaned history. For a truly fresh start, disable then delete sync.json.disabled by hand before re-running setup.

Player needs Python 3.10+ AND a Qt binding (pip install PySide6). Without Qt the pyz falls back to headless mode for status; the conflict + login dialogs are Qt-only — without them, conflict aborts the launch defensively and setup prompts for the token via stdin.

CLI

instance-sync pull / push [--pack-folder=PATH]
                          [--token-file=PATH]
                          [--restic-binary=PATH]
                          [--no-download]
                          [-g | --no-gui]
                          [--instance-label="Friendly Name"]

instance-sync setup       [--url=URL] [--pack-folder=PATH]     # interactive
instance-sync init        --url=URL [--token=ID:PASS] ...      # scripted
instance-sync disable     [--pack-folder=PATH]                 # sync.json → sync.json.disabled
instance-sync enable      [--pack-folder=PATH]                 # sync.json.disabled → sync.json

pull and push don't take --url — it's loaded from sync.json. --instance-label overrides the UI display name (defaults to $INST_NAME from Prism, then $INST_ID, then the first 8 chars of instance_id).

Programmatic API (for frazclient)

from pathlib import Path
import cloud_sync

cloud_sync.pull(cloud_sync.Args(
    pack_folder=Path("/srv/mc/instance"),
    token_file=Path("/srv/mc/instance/.cloud-sync/token"),
    restic_binary=None,        # auto-discover
    allow_download=True,
    headless=True,
    instance_label=None,       # default to env / id-prefix
))

Url is taken from <pack_folder>/.cloud-sync/sync.json; the caller is expected to have run setup or init beforehand (or to write sync.json themselves via cloud_sync.config.write(...)).

frazclient's client.py consumes this directly via import cloud_sync instead of subprocessing the pyz.

On-disk layout

Per-instance state under <pack-folder>/.cloud-sync/:

.cloud-sync/
  token                       # discord_id:password (mode 0600)
  scope.json                  # optional; defaults baked in if missing
  restic-<RESTIC_VERSION>      # auto-downloaded binary
  files-from.txt              # restic --files-from
  exclude-from.txt            # restic --exclude-from

Auto-excluded from sync. Multiple MC instances = multiple .cloud-sync/ dirs with independent credentials.

Why Python (not a JAR)

1. Antivirus. Unsigned JARs that auto-download binaries + upload files are textbook Windows Defender false-positive triggers. Python invoked by code-signed python.exe mostly sidesteps that.
2. Qt UI. PySide6 gives us a real native window with the Prism-dark Steam-style layout. JVM Qt bindings are abandoned.
3. frazclient already needs Python. Inlining as an import is zero overhead; the same package serves Prism via the pyz.

Cost: players using Prism must have Python 3.10+ AND Qt installed. Most Linux/Mac systems ship Python; Windows users install once from the Microsoft Store or python.org. Qt comes via pip install PySide6.

Where the data lives

Component	Role	Repo
instance-sync (this)	Player-side. Subprocesses restic for pull/push. Surfaces login + conflict + progress dialogs.	Timemachine/cloud-sync
cloud-svc	Operator-side control plane (provisioning + admin).	Timemachine/cloud-svc
restic-rest-server (existing)	Timemachine Network data plane. Player's restic hits it directly with their password.	upstream
discord-bot	Calls cloud-svc on /cloud register to provision a player's Timemachine Network account.	Timemachine/discord-bot

License

MIT.