Cloud Repo Model — Guia

Phase 69. Cada projeto Arc OS vive em um repositório GitHub privado gerenciado pelo Arc OS em seu nome. Você não precisa de uma conta GitHub, você nunca vê github.com — mas se quiser conectar seus próprios repos também, você pode.

TL;DR

• Cada projeto Arc OS = um repo privado. Criado automaticamente no momento em que você cria o projeto.
• Cada usuário também recebe um repo "system" para notas entre projetos e seu CLAUDE.md pessoal.
• Seu Cloud Workspace clona cada repo em /workspace/<project> no provisionamento. Trabalhe diretamente ali, faça push quando estiver pronto.
• Três comandos cobrem o ciclo de vida: arc pull, arc push, arc cloud sync.
• Repos externos são bem-vindos. Cole qualquer URL SSH ou (em breve) escolha do seu próprio GitHub via OAuth.

Por que uma org bot do GitHub gerenciada?

O Arc OS é dono de uma organização GitHub (arc-os-platform) que abriga cada repo auto-gerenciado de cada usuário. Você não a vê, não faz login nela, e sua conta nunca aparece como membro. Um GitHub App robótico com permissões fortemente escopadas cria os repos, registra credenciais, e nunca retém um token por mais de uma hora.

Duas consequências práticas:

1. Você pode se cadastrar no Arc OS sem uma conta GitHub. Cadastro inicial, primeiro projeto, primeiro Cloud Workspace — tudo funciona sem nenhuma ida ao github.com.
2. Você pode sair quando quiser. Cada repo é um repositório git padrão, totalmente clonável; mantemos um script de exportação em nosso codebase para o evento improvável de que o GitHub um dia tire nossa org bot do ar.

Para um mergulho arquitetural profundo, veja docs/architecture/PHASE_69_CLOUD_REPO_MODEL.md.

Os três tipos de repo

Quando você abrir Configurações → Cloud Workspace → Repositories, verá três seções:

1. System

Esta é sua memória "tudo-em-todo-lugar". Qualquer coisa que você colocar no CLAUDE.md aqui se aplica a cada worker do Arc OS, independentemente do projeto. O CLAUDE.md por projeto sobrescreve o nível system para aquele projeto.

2. Project

Uma linha por projeto. O badge mostra synced_at para você ver quando o último push aconteceu. Clicar no ícone do GitHub abre a visão somente-leitura do repo no github.com — útil para permalinks, blame, ou baixar um zip sem arc pull.

3. External

Repos externos estão inteiramente sob seu controle. O Arc OS os clona no momento do provisionamento, mas não faz auto-commit nem push deles para lugar algum. Use-os para codebases que pertencem a um cliente, a um trabalho fixo, ou a uma conta pessoal que você não quer que o Arc OS gerencie.

Comandos do dia a dia

Todos os três fazem parte do arc (o binário CLI, instruções de instalação em arc-cli-reference.md). Eles funcionam de qualquer árvore de trabalho git no seu laptop e só precisam de um arc login uma vez.

arc pull [project]

Se o diretório atual não for uma árvore git, isto clona o repo do projeto nele. Se for, isto fast-forward main para o mais recente do seu repo bot-org.

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

Recusa sobrescrever mudanças não commitadas — faça commit ou stash primeiro.

arc push [project]

Faz push do que seu HEAD local for para o repo bot-org. Recusa em árvores sujas para você nunca fazer push de arquivos meio-editados. Por baixo dos panos, ele brevemente troca a URL do remote por um token de uma hora, faz push, depois restaura a forma SSH pública — assim nenhuma credencial fica em disco após o comando sair.

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]

Imprime a matriz de estado sem mutar nada (além de um 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

Se seu HEAD local estiver à frente do origin/main, a próxima linha é ahead/behind: para você ver imediatamente o quanto as duas árvores divergiram.

Você pode omitir [project] em qualquer um dos três comandos se estiver dentro de uma sessão arc <project> dev (pegamos ARC_PROJECT do ambiente).

Como o Cloud Workspace se encaixa

Quando você provisiona um Cloud Workspace, o servidor master:

1. Inicializa um container novo, monta /workspace.
2. Escreve um token de instalação do GitHub App de uma hora em ~/.git-credentials dentro do container (nunca em argv, nunca em docker inspect).
3. Define credential.helper=store, mais um user.email / user.name benignos para que commits não falhem com "tell me who you are".
4. Clona seu repo system em /workspace/_system e cada repo de projeto em /workspace/<project>.

Quando o container fica ocioso (sem atividade por 30 minutos) nós o pausamos — mas antes de pausar, fazemos auto-commit de quaisquer árvores sujas como [auto] pre-pause snapshot e push delas, para que seu trabalho esteja sempre no repo bot-org antes das luzes se apagarem. No despertar, refrescamos o token e fazemos git fetch em cada repo para que a próxima sessão de terminal pouse em refs frescas.

O token vive no máximo uma hora; cada despertar ou pause-push o atualiza. O App ID + chave privada do lado bot nunca entram em um container.

Convenção de nomenclatura

Repos na org bot são nomeados <arc-user-id>--<slug>:

• 1775855296184--_system — seu repo system
• 1775855296184--myapp — seu projeto myapp

Você só vê o slug na UI do Arc OS (_system, myapp). O prefixo user-id é o que impede dois usuários de colidirem no mesmo nome de projeto dentro de uma org GitHub.

Adicionando repos externos

Dois caminhos, mesmo resultado final (uma linha na seção External):

Cole uma URL SSH

1. Abra Configurações → Cloud Workspace → Repositories.
2. Clique em + Add external.
3. Cole qualquer URL [email protected]:owner/repo.git ou https://....
4. Clique em Clone.

Este é o único caminho que funciona hoje. Se o repo for privado, você precisa ter configurado sua própria chave SSH do GitHub dentro do container (coberto em standard-cloud.md § "GitHub SSH Setup"). Repos públicos clonam imediatamente.

Conecte GitHub (chegando na Phase 69.5a — #347)

1. Clique em + Add external → aba Connect GitHub.
2. Autorize o app OAuth do GitHub do Arc OS (escopo public_repo por padrão; alterne Include private para escopo repo).
3. Escolha repos da lista de checkboxes.
4. Clique em Add selected.

Isto chegará como parte do #347 — acompanhe no roadmap.

O que acontece se eu excluir um projeto?

O repo do projeto é arquivado, não excluído. Repos arquivados ficam na org bot por 30 dias, após os quais o job diário de limpeza os remove. Se você mudar de ideia nessa janela, a reconstrução é um restore de uma linha via o fluxo de suporte do Arc OS.

Seu repo system nunca é arquivado automaticamente — ele segue sua conta, não seus projetos.

O que acontece se eu excluir minha conta Arc OS?

O apagamento GDPR Art. 17 (Phase 64) cascateia os repos da org bot: tanto seu repo _system quanto cada repo por projeto são arquivados na exclusão da conta, depois derrubados permanentemente no mesmo timer de 30 dias. O espelhamento horário do manifesto para S3 (veja seguro contra ban-day abaixo) garante que mesmo a lista arquivada é auditável para compliance.

Seguro contra ban-day

Escolhemos uma única org bot ao invés de auto-hospedar Gitea porque a análise de custo sai ~€5k mais barata ao longo de 24 meses. O trade-off é que dependemos dos termos de serviço do GitHub.

Duas mitigações que entregamos desde o primeiro dia:

1. Espelhamento horário do manifesto. Um cron job tira snapshot da lista completa de repos da nossa org bot para S3 a cada hora, então sempre temos um inventário atualizado.
2. Runbook de exportação no repo. scripts/phase-69-export-to-gitea.ts documenta a migração de 6 passos da org bot para uma instância fresca de Gitea, com gates de rollback entre cada passo. Fazemos dry-run dele trimestralmente para que não apodreça.

Tempo de relógio estimado se um dia precisarmos virar a chave: ~2 dias de ponta a ponta.

FAQ

Eu preciso de uma conta GitHub? Não. Cadastre-se com e-mail, crie um projeto, provisione um Cloud Workspace — tudo funciona sem github.com.

Meu colega de time pode ver meu repo de projeto? Não (até a colaboração da Phase 68 chegar). Repos de projeto são privados ao dono.

Por que URLs de clone HTTPS? Tokens de instalação do GitHub App autenticam via HTTPS, não SSH. O repo_url que mostramos na UI é a forma SSH (útil para aberturas somente-leitura no github.com); o clone_url que entregamos ao git clone é a forma HTTPS com um token embutido de curta duração.

Onde está a diferença com o Standard Cloud? Standard Cloud é a frota de containers (Hetzner, pausada após ocioso, acessível via terminal web). Cloud Repo Model é a camada git que dá suporte ao volume /workspace. Ambos fazem parte do plano Starter Cloud; você não paga separadamente.

Posso desabilitar auto-create para um projeto? Não hoje. Se você quer um projeto Arc OS sem código (apenas notas), use o repo system para a escrita e trate o projeto como um container de conhecimento.

Veja também

• standard-cloud.md — provisionamento de container, terminal web, ciclo de vida
• arc-cli-reference.md — superfície CLI completa
• github-integration.md — integração com sua própria conta GitHub (preocupação diferente: webhooks, OAuth sign-in)
• docs/architecture/PHASE_69_CLOUD_REPO_MODEL.md — a especificação arquitetural completa