Cloud Repo Model — Guide

Phase 69. Every Arc OS project lives in a private GitHub repository managed by Arc OS on your behalf. You don't need a GitHub account, you never see github.com — but if you want to connect your own repos too, you can.

TL;DR

Each Arc OS project = one private repo. Created automatically the moment you create the project.
Each user also gets one "system" repo for cross-project notes and your personal CLAUDE.md.
Your Cloud Workspace clones every repo into /workspace/<project> on provision. Work there directly, push when ready.
Three commands cover the lifecycle: arc pull, arc push, arc cloud sync.
External repos welcome. Paste any SSH URL or (soon) pick from your own GitHub via OAuth.

Why a managed GitHub bot org?

Arc OS owns a GitHub organisation (arc-os-platform) that holds every auto-managed repo for every user. You don't see it, you don't log in to it, and your account never appears as a member. A robotic GitHub App with tightly-scoped permissions creates the repos, registers credentials, and never holds a token longer than one hour.

Two practical consequences:

You can sign up to Arc OS without a GitHub account. First-time signup, first project, first Cloud Workspace — all of it works with no github.com round-trip.
You can leave whenever you want. Every repo is a standard git repository, fully cloneable; we keep an export script in our codebase against the unlikely event that GitHub ever takes our bot org offline.

For an architectural deep-dive, see docs/architecture/PHASE_69_CLOUD_REPO_MODEL.md.

The three repo types

When you open Settings → Cloud Workspace → Repositories, you'll see three sections:

1. System

Field	Value
Where	`/workspace/_system`
Purpose	Cross-project notes, personal `CLAUDE.md`, scratchpad
Visibility	You only
Created	Automatically on your first project
Removable	No

This is your "everything-everywhere" memory. Anything you put in CLAUDE.md here applies to every Arc OS worker, regardless of project. Per-project CLAUDE.md overrides system-level for that project.

2. Project

Field	Value
Where	`/workspace/<project>`
Purpose	The code, notes, and config for one Arc OS project
Visibility	You (collaboration arrives in Phase 68)
Created	Automatically when you create the project
Removable	Archived when you delete the project; recoverable 30 days

One row per project. The badge shows synced_at so you can see when the last push happened. Clicking the GitHub icon opens the read-only repo view on github.com — useful for permalinks, blame, or downloading a zip without arc pull.

3. External

Field	Value
Where	`/workspace/<name>` (you pick the dir name)
Purpose	Client repos, your own GitHub repos, anything not Arc-managed
Visibility	Whatever the upstream allows
Created	You add via SSH URL paste or GitHub OAuth (coming in Phase 69.5a)
Removable	Yes — Trash button on the row

External repos are entirely under your control. Arc OS clones them at provision time, but it doesn't auto-commit or push them anywhere. Use them for codebases that belong to a client, a day job, or a personal account you don't want Arc OS managing.

Day-to-day commands

All three are part of arc (the CLI binary, install instructions in arc-cli-reference.md). They work from any git work tree on your laptop and only need an arc login once.

`arc pull [project]`

If the current directory is not a git tree, this clones the project repo into it. If it is, this fast-forwards main to the latest from your bot-org repo.

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

Refuses to overwrite uncommitted changes — commit or stash first.

`arc push [project]`

Pushes whatever your local HEAD is to the bot-org repo. Refuses on dirty trees so you never push half-edited files. Under the hood it briefly swaps the remote URL to a one-hour token, pushes, then restores the public SSH form — so no credentials sit on disk after the command exits.

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]`

Prints the state matrix without mutating anything (beyond a 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

If your local HEAD is ahead of origin/main, the next line is ahead/behind: so you immediately see how far the two trees have drifted.

You can omit [project] in any of the three commands if you're inside an arc <project> dev session (we pick up ARC_PROJECT from the environment).

How Cloud Workspace fits in

When you provision a Cloud Workspace, the master server:

Boots a fresh container, mounts /workspace.
Writes a one-hour GitHub App installation token to ~/.git-credentials inside the container (never to argv, never to docker inspect).
Sets credential.helper=store, plus a benign user.email / user.name so commits don't fail with "tell me who you are".
Clones your system repo into /workspace/_system and every project repo into /workspace/<project>.

When the container goes idle (no activity for 30 minutes) we pause it — but before pausing, we auto-commit any dirty trees as [auto] pre-pause snapshot and push them, so your work is always in the bot-org repo before the lights go out. On wake we refresh the token and git fetch every repo so the next terminal session lands on fresh refs.

The token lives a maximum of one hour; every wake or pause-push refreshes it. The bot-side App ID + private key never enter a container.

Naming convention

Repos in the bot org are named <arc-user-id>--<slug>:

1775855296184--_system — your system repo
1775855296184--myapp — your myapp project

You only ever see the slug in the Arc OS UI (_system, myapp). The user-id prefix is what keeps two users from colliding on the same project name inside one GitHub org.

Adding external repos

Two paths, same end result (a row in the External section):

Paste an SSH URL

Open Settings → Cloud Workspace → Repositories.
Click + Add external.
Paste any [email protected]:owner/repo.git or https://... URL.
Click Clone.

This is the only path that works today. If the repo is private, you need to have set up your own GitHub SSH key inside the container (covered in standard-cloud.md § "GitHub SSH Setup"). Public repos clone straight away.

Connect GitHub (coming in Phase 69.5a — `#347`)

Click + Add external → tab Connect GitHub.
Authorise the Arc OS GitHub OAuth app (scope public_repo by default; toggle on Include private for repo scope).
Pick repos from the checkbox list.
Click Add selected.

This will land as part of #347 — track it in the roadmap.

What happens if I delete a project?

The project repo is archived, not deleted. Archived repos stay in the bot org for 30 days, after which the daily cleanup job removes them. If you change your mind in that window, the rebuild is a one-line restore via the Arc OS support flow.

Your system repo is never archived automatically — it follows your account, not your projects.

What happens if I delete my Arc OS account?

GDPR Art. 17 erasure (Phase 64) cascades the bot-org repos: both your _system repo and every per-project repo are archived on account delete, then permanently dropped on the same 30-day timer. The hourly manifest mirror to S3 (see ban-day insurance below) ensures even the archived list is auditable for compliance.

Ban-day insurance

We chose a single bot org over self-hosting Gitea because the cost analysis comes out ~€5k cheaper across 24 months. The trade-off is that we depend on GitHub's terms of service.

Two mitigations we ship from day one:

Hourly manifest mirror. A cron job snapshots the full repo list of our bot org to S3 every hour, so we always have an up-to-date inventory.
Export runbook in the repo. scripts/phase-69-export-to-gitea.ts documents the 6-step migration from the bot org to a fresh Gitea instance, with rollback gates between every step. We dry-run this quarterly so it doesn't bit-rot.

Estimated wall clock if we ever need to flip: ~2 days end-to-end.

FAQ

Do I need a GitHub account? No. Sign up with email, create a project, provision a Cloud Workspace — all of it works without github.com.

Can my teammate see my project repo? No (until Phase 68 collaboration ships). Project repos are private to the owner.

Why HTTPS clone URLs? GitHub App installation tokens authenticate over HTTPS, not SSH. The repo_url we show in the UI is the SSH form (useful for read-only opens on github.com); the clone_url we hand to git clone is the HTTPS form with a short-lived embedded token.

Where's the diff with Standard Cloud? Standard Cloud is the container fleet (Hetzner, paused after idle, accessible via web terminal). Cloud Repo Model is the git layer that backs the /workspace volume. Both are part of the Starter Cloud plan; you don't pay separately.

Can I disable auto-create for one project? Not today. If you want a code-less Arc OS project (notes only), use the system repo for the writing and treat the project as a knowledge container.