Backup · Migration (Export / Import)

Wenn man Blyck auf einen anderen Computer überträgt (z. B. Windows-Laptop → macOS Mac mini) und den Ordner userData manuell kopiert, zeigen die Chats auf die absoluten Pfade des alten PCs, die Secrets sind an den OS-Schlüsselbund gebunden und lassen sich nicht entsperren, und OS-abhängige Binärdateien laufen nicht.

Backup · Migration packt mit einem Klick (Export) und packt wieder aus (Import), wobei beim Auspacken die Pfade automatisch umgewandelt werden, sodass der Chat-Verlauf nahtlos weiterläuft. Alle 4 Richtungen Win↔Mac funktionieren.

Warum manuelles Kopieren kaputtgeht

Problem	Inhalt
Diskrepanz absoluter Pfade	Der Chat zeigt auf D:\develope\…, aber der neue PC hat /Users/…
OS-abhängige Secrets	DB-/SSH-Passwörter und GitHub-Token sind über den OS-Schlüsselbund (safeStorage) verschlüsselt und auf einem anderen PC nicht entschlüsselbar
OS-abhängige Binärdateien	python venv, LSP-Server usw. laufen auch nach dem Kopieren nicht
Riesiger neu erzeugbarer Cache	Der Such-/Embedding-Index (workspace.sqlite ~226 MB) wird komplett mitgeschleppt

Was übertragen und was verworfen wird

🟢 Übertragungsziel (im Bundle enthalten)

• chats/ — Chat-Verlauf (inklusive Nachrichten, in sich abgeschlossen)
• blyck-history.db — Änderungsverlauf (VACUUM INTO-Snapshot)
• db-history.json · db-snippets.json — DB-Abfrageverlauf · Snippets
• layout.json · blyck-locale.json · embeddings-settings.json — Layout · Sprache · Einstellungen
• connections.json — DB-/SSH-Zugriffsmetadaten (im Klartext-Bundle werden Secrets entfernt)
• attachments/ · changeSet-snapshots/ — optional

⚫ Ausgeschlossen — auf dem Ziel-PC neu erzeugt

• workspace.sqlite — Such-/Embedding-Index (~226 MB). Größtenteils aus der Codebasis abgeleitet, daher schrumpft das Bundle bei vollständigem Ausschluss von 230 MB → wenige MB, und der Indexer reindiziert auf dem Ziel-PC automatisch.
• python-venvs/ · lsp-servers/ — OS-Binärdateien (neu erzeugt)
• Electron/Chromium-Laufzeitcache, Logs usw.

Globale CLI-Verzeichnisse werden in keiner Phase übertragen

Globale Verzeichnisse wie ~/.claude · ~/.codex sind nicht Blyck-exklusiv, sondern werden von allen Arbeiten dieses PCs geteilt. Überschreibt man sie, gehen die vorhandenen Sitzungen des Ziels verloren und Index sowie Logins geraten durcheinander. Die Gesprächskontinuität des Modells wird über ein Re-Seed-Fallback behandelt (das Modell liest den Bildschirmverlauf erneut und holt auf), was funktional ausreichend ist.

Bundle-Format .blyckbundle

ZIP-Container + manifest.json (Schema · App-Version · Quell-OS · Pfadwurzeln · sha256 pro Datei).

backup-YYYY-MM-DD.blyckbundle
├── manifest.json
└── files/                       # Spiegel der userData-relativen Pfade
    ├── chats/index.json, chat_*.json
    ├── blyck-history.db
    ├── db-history.json, db-snippets.json
    ├── layout.json, blyck-locale.json, embeddings-settings.json
    ├── connections.json         # Klartext-Bundle entfernt Secrets
    ├── attachments/**           # optional
    └── changeSet-snapshots/**   # optional

Pfad-Remapping — den Chat nahtlos weiterführen

Beim Import werden nur die maßgeblichen Pfadfelder des Chat-JSON ersetzt.

Feld	Remapping
projectRoot	✅ ersetzen
_lastSentProjectRoot	✅ ersetzen
extraRoots[]	✅ jedes Element ersetzen
projectRootSftp	❌ unverändert (Remote ist PC-unabhängig)
messages[]	❌ unverändert (Verlauf bewahren)

Die Regel ist längste Präfix-Übereinstimmung — beginnt ein Pfad mit der Quellwurzel, wird nur das Präfix durch die Zielwurzel ersetzt und die übrigen Trennzeichen umgewandelt. Nicht gemappte Wurzeln bleiben unverändert (der Chat öffnet sich, nur das Projekt bleibt ungelöst und wird vom Nutzer erneut geöffnet).

Plattformübergreifend in 4 Richtungen (alle Kombinationen Win↔Mac)

remapPath behandelt Quell-Trennzeichen (Aufteilen) und Ziel-Trennzeichen (Zusammenfügen) getrennt. Das Quell-Trennzeichen wird aus der Quellwurzel automatisch erkannt (\/Laufwerksbuchstabe → Win, / → POSIX), das Ziel-Trennzeichen durch das Ziel-OS bestimmt.

Richtung	Beispiel Quellpfad	Beispiel Ergebnis
Win→Win	D:\dev\App\src\a.js	E:\work\App\src\a.js
Win→Mac	D:\dev\App\src\a.js	/Users/x/App/src/a.js
Mac→Win	/Users/x/dev/App/src/a.js	D:\work\App\src\a.js
Mac→Mac	/Users/x/dev/App/src/a.js	/Users/y/App/src/a.js

Laufwerksbuchstabe/Wurzel unerheblich — da es sich um eine Präfix-Ersetzung handelt, wird jede Wurzelkombination wie D:\ ↔ /Users/ über die Mapping-Tabelle 1:1 aufgelöst.

Verschlüsseltes Bundle + Secrets inklusive

Beim Export wird bei Angabe eines Passworts das gesamte Bundle verschlüsselt.

• Methode: gesamtes Bundle AES-256-GCM — die ZIP-interne Verschlüsselung (ZipCrypto) ist angreifbar und wird daher nicht verwendet; stattdessen wird das ZIP erstellt und anschließend komplett mit dem Node-internen crypto verschlüsselt (0 externe Abhängigkeiten). KDF ist scrypt, die Verschlüsselung AES-256-GCM (Vertraulichkeit + Integrität).
• Falsche Passworteingabe = Fehlschlag der GCM-auth-tag-Prüfung → „Das Passwort ist falsch” sofort erkannt (keine Teilentschlüsselung, Daten unverändert).
• Über einen Klartext-Header (BLYCKENC1) wird bereits ohne Passwort vorab festgestellt, ob eine Verschlüsselung vorliegt.

Secrets nur im verschlüsselten Bundle

Nur im verschlüsselten Bundle dürfen DB-/SSH-Passwörter und GitHub-Token enthalten sein. Beim Export werden die per safeStorage entschlüsselten Klartext-Secrets ins verschlüsselte Bundle gelegt, und beim Import werden sie mit dem safeStorage des Ziel-OS neu verschlüsselt und abgelegt, sodass keine erneute Eingabe nötig ist. In ein Klartext-Bundle (unverschlüsselt) werden sie niemals aufgenommen (Secret-Strip bleibt bestehen).

Secrets sind richtungsunabhängig — Entschlüsselung per Win-safeStorage → verschlüsseltes Bundle → Neuverschlüsselung per Mac-safeStorage (und umgekehrt), sodass alle 4 Richtungen Win↔Mac funktionieren.

Export-Ablauf

1. Stillstandsprüfung — bei laufendem busy-Turn ablehnen (Datenkonsistenz)
2. blyck-history.db → per VACUUM INTO zu einem einzigen Snapshot (sicher während die App läuft)
3. enthaltene Dateien sammeln + sha256 pro Datei
4. chats scannen → distinkte Pfadwurzeln in manifest.pathRoots eintragen
5. Secret-Behandlung — ohne Passwort: strip / mit Passwort: Klartext-Secrets enthalten
6. ZIP-Packaging
7. bei angegebenem Passwort AES-256-GCM-Verschlüsselung → als *.blyckbundle ablegen

Import-Ablauf

1. inspect — per magic feststellen, ob verschlüsselt. Bei Verschlüsselung Passwort-Eingabeaufforderung
2. Entschlüsselung — Passwort → scrypt → AES-256-GCM. Bei auth-tag-Fehlschlag Abbruch (Daten unverändert)
3. Pfad-Remapping-UI — Eingabefeld pro Quellwurzel (automatischer Basisnamen-Vorschlag: D:\develope\Blyck_Web → ~/dev/Blyck_Web)
4. Sicherheits-Backup — aktuelle chats/ · *.db in userData/_pre-import-<ts>/ bewahren
5. files/ extrahieren → in userData schreiben
6. Remapping anwenden — projectRoot/_lastSentProjectRoot/extraRoots per längster Präfix-Ersetzung + Trennzeichen-Normalisierung (projectRootSftp · messages unverändert)
7. Secret-Wiederherstellung — verschlüsseltes Bundle: Neuverschlüsselung per safeStorage des Ziel-OS / Klartext-Bundle: Flag „erneute Eingabe nötig”
8. workspace.sqlite fehlt → beim nächsten Start automatische Reindizierung
9. Neustart-Hinweis

Modi — Ersetzen vs. Mergen

Modus	Verhalten	Verwendung
Ersetzen (replace)	aktuelle chats/ · *.db nach _pre-import-<ts> sichern und dann durch das Bundle ersetzen	komplette Migration auf einen neuen PC
Mergen (merge)	in die bestehende Installation anhand der chat id zusammenführen (Hinzufügen ohne Ersetzen)	die Arbeiten zweier PCs an einem Ort sammeln

Das Mergen ist sicher, weil chats/ aus einzelnen JSON-Dateien pro id besteht und sich daher kollisionsfrei zusammenführen lässt.

Sicherheitsvorkehrungen

• vor dem Import automatisches Backup der aktuellen Daten (_pre-import-<ts>)
• Kompatibilitäts-Gate für manifest-Schema/App-Version
• Integritätsprüfung per sha256 je Datei
• Import-Ablehnung während ein Chat busy ist
• explizite Nutzerbestätigung vor dem Ersetzen
• falsche Passworteingabe beim verschlüsselten Bundle → Abbruch in der Entschlüsselungsstufe (Daten unverändert)
• im Klartext-Bundle keine Secrets enthalten (Leck-Schutz)

FAQ

F. Öffnet sich der Chat-Verlauf auf dem neuen PC unverändert? → Ja. Beim Import werden projectRoot usw. per Pfad-Remapping automatisch in die Pfade des neuen PCs umgewandelt, sodass Chat und Projekt nahtlos weiterlaufen.

F. Muss ich DB-/SSH-Passwörter erneut eingeben? → Exportierst du als verschlüsseltes Bundle (mit Passwort), sind die Secrets enthalten und werden für das Ziel-OS neu verschlüsselt, sodass keine erneute Eingabe nötig ist. Beim Klartext-Bundle werden die Secrets aus Sicherheitsgründen entfernt, daher ist eine erneute Eingabe nötig.

F. Kann ich ein unter Windows erstelltes Bundle auf einem Mac auspacken? → Ja. Alle 4 Richtungen einschließlich Win→Mac und Mac→Win werden unterstützt. Pfad-Trennzeichen (\↔/) sowie Laufwerksbuchstabe/Wurzel werden automatisch umgewandelt.

F. Warum ist das Bundle so klein? → Die workspace.sqlite (Suchindex) im Bereich von 226 MB ist aus der Codebasis neu erzeugbar und wird daher ausgeschlossen. Auf dem Ziel-PC reindiziert der Indexer automatisch, der Chat-Verlauf selbst bleibt unverändert erhalten.

F. Was, wenn ich das Passwort vergesse? → Es gibt kein Wiederherstellungsmittel. AES-256-GCM lässt sich ohne Passwort nicht entschlüsseln, daher bewahre das Passwort des verschlüsselten Bundles sicher auf.

F. Was, wenn ich mit der Arbeit auf dem bestehenden PC zusammenführen möchte? → Nutze den Merge-Modus. Er führt anhand der chat id zusammen, löscht bestehende Chats nicht und fügt nur hinzu.