Arc OS Docs Open in app →

Cloud Repo Model — Guía

Phase 69. Cada proyecto de Arc OS vive en un repositorio privado de GitHub gestionado por Arc OS en tu nombre. No necesitas una cuenta de GitHub, nunca verás github.com — pero si quieres conectar también tus propios repos, puedes.

TL;DR

¿Por qué una org bot de GitHub gestionada?

Arc OS posee una organización de GitHub (arc-os-platform) que aloja cada repo auto-gestionado de cada usuario. No la ves, no inicias sesión en ella, y tu cuenta nunca aparece como miembro. Una GitHub App robótica con permisos estrictamente acotados crea los repos, registra las credenciales, y nunca retiene un token por más de una hora.

Dos consecuencias prácticas:

  1. Puedes registrarte en Arc OS sin una cuenta de GitHub. Primer registro, primer proyecto, primer Cloud Workspace — todo funciona sin pasar por github.com.
  2. Puedes irte cuando quieras. Cada repo es un repositorio git estándar, totalmente clonable; mantenemos un script de exportación en nuestro código por si en el improbable caso GitHub alguna vez retira nuestra org bot.

Para una inmersión arquitectónica, consulta docs/architecture/PHASE_69_CLOUD_REPO_MODEL.md.

Los tres tipos de repo

Cuando abras Ajustes → Cloud Workspace → Repositories, verás tres secciones:

1. System

Campo Valor
Dónde /workspace/_system
Propósito Notas entre proyectos, CLAUDE.md personal, scratchpad
Visibilidad Solo tú
Creado Automáticamente en tu primer proyecto
Eliminable No

Esta es tu memoria "todo-en-todas-partes". Cualquier cosa que pongas en CLAUDE.md aquí aplica a cada worker de Arc OS, sin importar el proyecto. El CLAUDE.md por-proyecto sobrescribe el nivel system para ese proyecto.

2. Project

Campo Valor
Dónde /workspace/<project>
Propósito El código, notas y configuración de un proyecto de Arc OS
Visibilidad Tú (la colaboración llega en Phase 68)
Creado Automáticamente cuando creas el proyecto
Eliminable Archivado cuando eliminas el proyecto; recuperable 30 días

Una fila por proyecto. El badge muestra synced_at para que veas cuándo ocurrió el último push. Hacer clic en el ícono de GitHub abre la vista de solo lectura del repo en github.com — útil para permalinks, blame o descargar un zip sin arc pull.

3. External

Campo Valor
Dónde /workspace/<name> (eliges el nombre del dir)
Propósito Repos de clientes, tus propios repos de GitHub, cualquier cosa no gestionada por Arc
Visibilidad Lo que el upstream permita
Creado Lo añades vía pegado de URL SSH o OAuth de GitHub (próximamente en Phase 69.5a)
Eliminable Sí — botón Trash en la fila

Los repos externos están enteramente bajo tu control. Arc OS los clona al momento de la provisión, pero no hace auto-commit ni los empuja a ningún lado. Úsalos para bases de código que pertenecen a un cliente, un trabajo diurno, o una cuenta personal que no quieres que Arc OS gestione.

Comandos del día a día

Los tres son parte de arc (el binario CLI, instrucciones de instalación en arc-cli-reference.md). Funcionan desde cualquier work tree de git en tu laptop y solo necesitan un arc login una vez.

arc pull [project]

Si el directorio actual no es un work tree de git, esto clona el repo del proyecto dentro. Si sí lo es, esto hace fast-forward de main a la última versión de tu repo en la org bot.

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

Se niega a sobrescribir cambios sin commitear — commitea o haz stash primero.

arc push [project]

Empuja lo que sea tu HEAD local al repo de la org bot. Se niega en árboles sucios para que nunca empujes archivos a medio editar. Por dentro intercambia brevemente la URL del remote por un token de una hora, hace push, y luego restaura la forma SSH pública — así no quedan credenciales en disco después de que el comando termina.

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 la matriz de estado sin mutar nada (más allá de un 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

Si tu HEAD local está por delante de origin/main, la siguiente línea es ahead/behind: para que veas inmediatamente cuánto han divergido los dos árboles.

Puedes omitir [project] en cualquiera de los tres comandos si estás dentro de una sesión arc <project> dev (tomamos ARC_PROJECT del entorno).

Cómo encaja Cloud Workspace

Cuando haces provisión de un Cloud Workspace, el servidor master:

  1. Arranca un contenedor fresco, monta /workspace.
  2. Escribe un token de instalación de GitHub App de una hora a ~/.git-credentials dentro del contenedor (nunca a argv, nunca a docker inspect).
  3. Establece credential.helper=store, más un user.email / user.name benignos para que los commits no fallen con "tell me who you are".
  4. Clona tu repo system en /workspace/_system y cada repo de proyecto en /workspace/<project>.

Cuando el contenedor queda inactivo (sin actividad por 30 minutos) lo pausamos — pero antes de pausar, hacemos auto-commit de cualquier árbol sucio como [auto] pre-pause snapshot y los empujamos, así tu trabajo siempre está en el repo de la org bot antes de que se apaguen las luces. Al despertar refrescamos el token y hacemos git fetch de cada repo para que la siguiente sesión de terminal aterrice en refs frescas.

El token vive un máximo de una hora; cada despertar o push-de-pausa lo refresca. El App ID + private key del lado bot nunca entran a un contenedor.

Convención de nombres

Los repos en la org bot se nombran <arc-user-id>--<slug>:

Solo ves el slug en la UI de Arc OS (_system, myapp). El prefijo de user-id es lo que evita que dos usuarios colisionen en el mismo nombre de proyecto dentro de una org de GitHub.

Añadir repos externos

Dos caminos, el mismo resultado final (una fila en la sección External):

Pegar una URL SSH

  1. Abre Ajustes → Cloud Workspace → Repositories.
  2. Haz clic en + Add external.
  3. Pega cualquier URL [email protected]:owner/repo.git o https://....
  4. Haz clic en Clone.

Este es el único camino que funciona hoy. Si el repo es privado, necesitas haber configurado tu propia llave SSH de GitHub dentro del contenedor (cubierto en standard-cloud.md § "GitHub SSH Setup"). Los repos públicos clonan directamente.

Conectar GitHub (próximamente en Phase 69.5a — #347)

  1. Haz clic en + Add external → pestaña Connect GitHub.
  2. Autoriza la app OAuth de GitHub de Arc OS (scope public_repo por defecto; activa Include private para el scope repo).
  3. Elige repos de la lista de checkboxes.
  4. Haz clic en Add selected.

Esto aterrizará como parte de #347 — sígelo en el roadmap.

¿Qué pasa si elimino un proyecto?

El repo del proyecto es archivado, no eliminado. Los repos archivados permanecen en la org bot por 30 días, tras los cuales el job diario de limpieza los remueve. Si cambias de opinión en esa ventana, la reconstrucción es una restauración de una línea vía el flujo de soporte de Arc OS.

Tu repo system nunca se archiva automáticamente — sigue a tu cuenta, no a tus proyectos.

¿Qué pasa si elimino mi cuenta de Arc OS?

El borrado GDPR Art. 17 (Phase 64) cascadea los repos de la org bot: tanto tu repo _system como cada repo por-proyecto son archivados al eliminar la cuenta, luego eliminados permanentemente en el mismo temporizador de 30 días. El espejo horario del manifest a S3 (ver seguro contra ban-day más abajo) asegura que incluso la lista archivada es auditable para cumplimiento.

Seguro contra ban-day

Elegimos una sola org bot en lugar de self-hostear Gitea porque el análisis de costos resulta ~€5k más barato a lo largo de 24 meses. El trade-off es que dependemos de los términos de servicio de GitHub.

Dos mitigaciones que enviamos desde el día uno:

  1. Espejo horario del manifest. Un cron job toma un snapshot de la lista completa de repos de nuestra org bot a S3 cada hora, así siempre tenemos un inventario actualizado.
  2. Runbook de exportación en el repo. scripts/phase-69-export-to-gitea.ts documenta la migración en 6 pasos de la org bot a una instancia fresca de Gitea, con gates de rollback entre cada paso. Lo ejecutamos en dry-run trimestralmente para que no se pudra.

Tiempo estimado de reloj de pared si alguna vez necesitamos cambiar: ~2 días end-to-end.

FAQ

¿Necesito una cuenta de GitHub? No. Regístrate con email, crea un proyecto, haz provisión de un Cloud Workspace — todo funciona sin github.com.

¿Mi compañero de equipo puede ver el repo de mi proyecto? No (hasta que la colaboración de Phase 68 llegue). Los repos de proyecto son privados al propietario.

¿Por qué URLs de clone HTTPS? Los tokens de instalación de GitHub App autentican sobre HTTPS, no SSH. La repo_url que mostramos en la UI es la forma SSH (útil para aperturas de solo lectura en github.com); la clone_url que le pasamos a git clone es la forma HTTPS con un token de corta duración embebido.

¿Dónde está la diferencia con Standard Cloud? Standard Cloud es la flota de contenedores (Hetzner, pausada tras inactividad, accesible vía terminal web). Cloud Repo Model es la capa git que respalda el volumen /workspace. Ambos son parte del plan Starter Cloud; no pagas por separado.

¿Puedo deshabilitar auto-create para un proyecto? Hoy no. Si quieres un proyecto de Arc OS sin código (solo notas), usa el repo system para la escritura y trata el proyecto como un contenedor de conocimiento.

Ver también