Cloud Repo Model — Leitfaden

Phase 69. Jedes Arc OS-Projekt lebt in einem privaten GitHub-Repository, das Arc OS in deinem Namen verwaltet. Du brauchst kein GitHub-Konto, du siehst github.com nie — aber wenn du zusätzlich deine eigenen Repos anbinden möchtest, kannst du das tun.

TL;DR

• Jedes Arc OS-Projekt = ein privates Repo. Wird automatisch in dem Moment angelegt, in dem du das Projekt erstellst.
• Jeder User bekommt zusätzlich ein „System"-Repo für projektübergreifende Notizen und deine persönliche CLAUDE.md.
• Dein Cloud Workspace klont jedes Repo bei der Bereitstellung nach /workspace/<project>. Arbeite direkt dort, pushe wenn fertig.
• Drei Befehle decken den gesamten Lebenszyklus ab: arc pull, arc push, arc cloud sync.
• Externe Repos sind willkommen. Füge eine beliebige SSH-URL ein oder wähle (bald) per OAuth aus deinem eigenen GitHub.

Warum eine verwaltete GitHub-Bot-Org?

Arc OS besitzt eine GitHub-Organisation (arc-os-platform), die jedes automatisch verwaltete Repo für jeden User enthält. Du siehst sie nicht, du loggst dich nicht ein, und dein Konto erscheint nie als Mitglied. Eine robotische GitHub App mit eng abgesteckten Rechten erstellt die Repos, registriert Credentials und hält nie länger als eine Stunde ein Token.

Zwei praktische Konsequenzen:

1. Du kannst dich ohne GitHub-Konto bei Arc OS anmelden. Erste Registrierung, erstes Projekt, erster Cloud Workspace — all das funktioniert ganz ohne github.com-Umweg.
2. Du kannst jederzeit weggehen. Jedes Repo ist ein standardmäßiges git-Repository und vollständig klonbar; wir pflegen in unserem Codebase ein Export-Skript für den unwahrscheinlichen Fall, dass GitHub unsere Bot-Org je offline nimmt.

Für einen tieferen Architektureinblick siehe docs/architecture/PHASE_69_CLOUD_REPO_MODEL.md.

Die drei Repo-Typen

Wenn du Einstellungen → Cloud Workspace → Repositories öffnest, siehst du drei Bereiche:

1. System

Das ist dein „Alles-überall"-Gedächtnis. Alles, was du hier in CLAUDE.md ablegst, gilt für jeden Arc OS-Worker, projektunabhängig. Eine projektspezifische CLAUDE.md überschreibt die System-Ebene für genau dieses Projekt.

2. Projekt

Eine Zeile pro Projekt. Das Badge zeigt synced_at, sodass du siehst, wann der letzte Push war. Ein Klick auf das GitHub-Icon öffnet die Read-Only-Ansicht des Repos auf github.com — nützlich für Permalinks, Blame oder zum Herunterladen eines Zips ohne arc pull.

3. Extern

Externe Repos liegen vollständig in deiner Hand. Arc OS klont sie beim Provisioning, committet oder pusht aber nichts automatisch. Nutze sie für Codebases, die einem Kunden, einem Tagesjob oder einem privaten Account gehören, den Arc OS nicht verwalten soll.

Befehle für den Alltag

Alle drei sind Teil von arc (das CLI-Binary, Installationsanleitung in arc-cli-reference.md). Sie funktionieren aus jedem git-Worktree auf deinem Laptop und benötigen nur einmalig arc login.

arc pull [project]

Ist das aktuelle Verzeichnis kein git-Tree, klont dies das Projekt-Repo dorthin. Ist es eines, fast-forwardet dies main auf den neuesten Stand aus deinem Bot-Org-Repo.

mkdir my-feature && cd my-feature
arc pull myapp
# → Cloning [email protected]:arc-os-platform/<uid>--myapp.git into <cwd>
# → ✓ cloned

Weigert sich, uncommittete Änderungen zu überschreiben — vorher committen oder stashen.

arc push [project]

Pusht das aktuelle lokale HEAD ins Bot-Org-Repo. Weigert sich bei dreckigen Trees, damit du nie halb editierte Dateien pushst. Unter der Haube tauscht es kurz die Remote-URL gegen ein Ein-Stunden-Token, pusht und stellt anschließend die öffentliche SSH-Form wieder her — so liegen nach Beendigung des Befehls keine Credentials auf der Platte.

git commit -am "fix: handle empty body"
arc push myapp
# → → [email protected]:arc-os-platform/<uid>--myapp.git
# → To https://github.com/arc-os-platform/<uid>--myapp.git
# →    ac30671..914cc84  HEAD -> main
# → ✓ pushed

arc cloud sync [project]

Druckt die Zustandsmatrix, ohne irgendetwas zu verändern (außer einem git fetch).

arc cloud sync myapp
# project:        myapp
# bot repo:       [email protected]:arc-os-platform/<uid>--myapp.git
# last_synced:    2026-06-04T11:07:53.695Z
# local HEAD:     914cc84
# origin/main:    914cc84
# dirty:          no

Ist dein lokales HEAD vor origin/main, ist die nächste Zeile ahead/behind:, damit du sofort siehst, wie weit die beiden Trees auseinandergedriftet sind.

Du kannst [project] in allen drei Befehlen weglassen, wenn du in einer arc <project> dev-Sitzung bist (wir lesen ARC_PROJECT aus der Umgebung).

Wie Cloud Workspace dazupasst

Wenn du einen Cloud Workspace provisionierst, macht der Master-Server Folgendes:

1. Bootet einen frischen Container, mountet /workspace.
2. Schreibt ein Ein-Stunden-Installation-Token der GitHub App in ~/.git-credentials innerhalb des Containers (nie in argv, nie in docker inspect).
3. Setzt credential.helper=store plus eine harmlose user.email / user.name, damit Commits nicht mit „tell me who you are" abbrechen.
4. Klont dein System-Repo nach /workspace/_system und jedes Projekt-Repo nach /workspace/<project>.

Wird der Container idle (keine Aktivität für 30 Minuten), pausieren wir ihn — aber vor dem Pausieren auto-committen wir jeden dreckigen Tree als [auto] pre-pause snapshot und pushen ihn, sodass deine Arbeit immer im Bot-Org-Repo ist, bevor das Licht ausgeht. Beim Wake-up frischen wir das Token auf und führen für jedes Repo ein git fetch aus, damit die nächste Terminalsitzung auf frischen Refs landet.

Das Token lebt maximal eine Stunde; jedes Wake-up oder Pause-Push erneuert es. Die Bot-seitige App-ID + der Private Key betreten niemals einen Container.

Namenskonvention

Repos in der Bot-Org heißen <arc-user-id>--<slug>:

• 1775855296184--_system — dein System-Repo
• 1775855296184--myapp — dein myapp-Projekt

In der Arc OS-UI siehst du nur den Slug (_system, myapp). Der User-ID-Präfix verhindert, dass zwei User innerhalb einer GitHub-Org auf demselben Projektnamen kollidieren.

Externe Repos hinzufügen

Zwei Wege, dasselbe Ergebnis (eine Zeile im Bereich Extern):

SSH-URL einfügen

1. Öffne Einstellungen → Cloud Workspace → Repositories.
2. Klicke auf + Extern hinzufügen.
3. Füge eine beliebige [email protected]:owner/repo.git oder https://... URL ein.
4. Klicke auf Clone.

Dies ist der einzige Weg, der heute funktioniert. Ist das Repo privat, musst du deinen eigenen GitHub-SSH-Key im Container eingerichtet haben (beschrieben in standard-cloud.md § „GitHub SSH Setup"). Öffentliche Repos klonen sofort.

GitHub anbinden (kommt in Phase 69.5a — #347)

1. Klicke auf + Extern hinzufügen → Tab GitHub anbinden.
2. Autorisiere die Arc OS GitHub OAuth App (Scope public_repo standardmäßig; aktiviere Include private für den repo-Scope).
3. Wähle Repos aus der Checkbox-Liste.
4. Klicke auf Auswahl hinzufügen.

Dies landet als Teil von #347 — verfolge es in der Roadmap.

Was passiert, wenn ich ein Projekt lösche?

Das Projekt-Repo wird archiviert, nicht gelöscht. Archivierte Repos bleiben 30 Tage in der Bot-Org, danach räumt der tägliche Cleanup-Job sie ab. Falls du es dir in diesem Fenster anders überlegst, ist die Wiederherstellung ein One-Line-Restore über den Arc OS-Support-Flow.

Dein System-Repo wird nie automatisch archiviert — es folgt deinem Konto, nicht deinen Projekten.

Was passiert, wenn ich mein Arc OS-Konto lösche?

Die GDPR-Art.-17-Löschung (Phase 64) kaskadiert auf die Bot-Org-Repos: sowohl dein _system-Repo als auch jedes Per-Project-Repo werden bei der Account-Löschung archiviert und dann nach demselben 30-Tage-Timer permanent entfernt. Der stündliche Manifest-Mirror nach S3 (siehe Ban-Day-Versicherung unten) sorgt dafür, dass sogar die archivierte Liste compliance-mäßig auditierbar bleibt.

Ban-Day-Versicherung

Wir haben uns für eine einzelne Bot-Org statt für selbst gehostetes Gitea entschieden, weil die Kostenanalyse über 24 Monate ~5k € günstiger ausfällt. Der Trade-off: wir hängen an GitHubs Terms of Service.

Zwei Absicherungen, die wir vom ersten Tag an ausliefern:

1. Stündlicher Manifest-Mirror. Ein Cronjob snapshottet jede Stunde die komplette Repo-Liste unserer Bot-Org nach S3, damit wir immer ein aktuelles Inventar haben.
2. Export-Runbook im Repo. scripts/phase-69-export-to-gitea.ts dokumentiert die 6-stufige Migration von der Bot-Org auf eine frische Gitea-Instanz, mit Rollback-Gates zwischen jedem Schritt. Wir laufen das quartalsweise als Dry-Run, damit es nicht verrottet.

Geschätzte Wall-Clock-Zeit, falls wir je umschalten müssen: ~2 Tage Ende-zu-Ende.

FAQ

Brauche ich ein GitHub-Konto? Nein. Registriere dich mit E-Mail, erstelle ein Projekt, provisioniere einen Cloud Workspace — alles funktioniert ohne github.com.

Kann mein Teamkollege mein Projekt-Repo sehen? Nein (bis die Kollaboration in Phase 68 ausgeliefert wird). Projekt-Repos sind privat für den Besitzer.

Warum HTTPS-Clone-URLs? GitHub-App-Installation-Tokens authentifizieren sich über HTTPS, nicht SSH. Die repo_url, die wir in der UI zeigen, ist die SSH-Form (nützlich für Read-Only-Aufrufe auf github.com); die clone_url, die wir an git clone übergeben, ist die HTTPS-Form mit einem kurzlebigen eingebetteten Token.

Wo ist der Unterschied zu Standard Cloud? Standard Cloud ist die Container-Flotte (Hetzner, pausiert nach Idle, erreichbar über Web-Terminal). Cloud Repo Model ist die git-Schicht, die das /workspace-Volume hinterlegt. Beides ist Teil des Starter Cloud-Plans; du zahlst nicht extra.

Kann ich Auto-Create für ein einzelnes Projekt deaktivieren? Heute nicht. Wenn du ein codeloses Arc OS-Projekt (nur Notizen) haben willst, nutze das System-Repo fürs Schreiben und behandle das Projekt als Wissens-Container.

Siehe auch

• standard-cloud.md — Container-Provisioning, Web-Terminal, Lifecycle
• arc-cli-reference.md — komplette CLI-Oberfläche
• github-integration.md — Anbindung deines eigenen GitHub-Kontos (anderes Thema: Webhooks, OAuth-Login)
• docs/architecture/PHASE_69_CLOUD_REPO_MODEL.md — die vollständige Architekturspezifikation