claude-timemachine
b31fdd023a
Product / UI / CLI / docs rebrand. Internal package, repo, and on-disk dir names stay 'cloud_sync' / 'cloud-sync' / '.cloud-sync/' to avoid breaking existing installs; a future commit can do the file-system rename when the cost is worth paying. User-facing changes: CLI prog name: cloud-sync -> instance-sync CLI description: cloud-svc URL -> Timemachine Network endpoint Dialog title: CLOUD SYNC -> INSTANCE SYNC Dialog title: CLOUD CONFLICT -> INSTANCE CONFLICT Dialog title: CONNECT CLOUD SAVE -> CONNECT TO THE NETWORK Card label: Cloud Save -> Remote Save Skip button: Skip cloud sync -> Skip instance sync Body copy: 'the cloud' -> 'the Timemachine Network' Window titles: Cloud sync — ... -> Instance sync — ... Log prefix: cloud-sync: -> instance-sync: Error prose: 'cloud-sync token' -> 'instance-sync token' Backend changes: restic --host tag: cloud-sync -> instance-sync State.host_tag dflt: cloud-sync -> instance-sync (Existing snapshots with the old tag still pull fine; we use 'latest'.) Drop tkinter fallback: ui.py now offers Qt OR Headless. tkinter is unnecessary given we already maintain Qt + headless; one less code path to keep styled, smaller pyz. make_progress() picks Qt first, falls through to HeadlessProgress on ImportError with a stderr hint to 'pip install PySide6'. README: rebrand title + prose; note repo/dir rename deferred; call out the PySide6 install step. Conflict/login dialogs are now Qt-only; without Qt, conflict aborts (defensive) and login tells the user to paste the token manually. 52 tests green; no test-file label changes needed since they only exercise internal APIs.
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)
Instance Settings → Custom commands:
Pre-launch:
python /path/to/cloud-sync.pyz pull --url=https://cloud.tm.center --pack-folder=$INST_MC_DIR
Post-exit:
python /path/to/cloud-sync.pyz push --url=https://cloud.tm.center --pack-folder=$INST_MC_DIR
Player needs Python 3.10+ on PATH AND a Qt binding (pip install PySide6). The first pull on a fresh instance opens a "CONNECT TO THE NETWORK" dialog; the player pastes a token they got via /cloud register in Discord. The token lands at <INST_MC_DIR>/.cloud-sync/token.
If PySide6 / PyQt6 is missing the pyz falls back to headless mode (status to stdout). The conflict + login dialogs do not have a headless mode — without Qt the conflict path aborts the launch defensively, and the login path tells the user to paste the token manually.
CLI
python cloud-sync.pyz {pull,push} \
--url URL Timemachine Network endpoint (required)
--pack-folder PATH Minecraft instance directory (default: cwd)
--token-file PATH override default <pack-folder>/.cloud-sync/token
--restic-binary PATH skip auto-discovery
--no-download fail if no usable restic; don't fetch from upstream
-g, --no-gui headless mode (no Qt windows)
Programmatic API (for frazclient)
from pathlib import Path
import cloud_sync
cloud_sync.pull(cloud_sync.Args(
url="https://cloud.tm.center",
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,
))
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)
- Antivirus. Unsigned JARs that auto-download binaries + upload files are textbook Windows Defender false-positive triggers. Python invoked by code-signed
python.exemostly sidesteps that. - Qt UI. PySide6 gives us a real native window with the Prism-dark Steam-style layout. JVM Qt bindings are abandoned.
- 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.