Respaldar y restaurar

Esta guía cubre las cinco cosas que la gente realmente hace con los respaldos: crear uno, recogerlo, mover un espacio de trabajo, reponerlo y guardar copias fuera de la máquina. Para conocer la forma exacta de cada artefacto y cada operación, consulta la referencia de respaldo.

Todo lo que hay aquí está en Ajustes → Servidor → Copia de seguridad y restauración.

Requisitos previos

Un cliente completo — la aplicación de escritorio o la web. Un teléfono emparejado no puede desencadenar nada de esto, por diseño.
Para crear, listar, descargar o eliminar una instantánea de la instalación: el propietario de la instalación.
Para las acciones por espacio de trabajo: administrador de ese espacio de trabajo para exportar, propietario para importarlo o eliminarlo.
Para las descargas y las subidas: una conexión directa al servidor. El relevo intermediado transporta tramas RPC, no transferencias de archivos, y los controles de transferencia se desactivan con una nota cuando estás en una.

Qué cubre un respaldo

Ambos artefactos son solo bases de datos:

Una instantánea de la instalación es un directorio con marca de tiempo: manifest.json, global.db y un <workspaceId>/workspace.db por cada espacio de trabajo.
Una exportación de espacio de trabajo es ese único archivo workspace.db.

Ninguno de los dos incluye el resto del directorio de datos: secrets.json (claves de emparejamiento, credenciales de proveedor, SSO), el blobs/ de un espacio de trabajo (imágenes pegadas en los mensajes), skills/, agents/, chat_credentials/, el audio de reuniones grabadas o las imágenes de rigs. Parte de eso es desechable y parte no — la tabla completa está en la referencia, y cubrirlo es para lo que sirve la sección de copias fuera de la máquina.

Crear una instantánea de toda la instalación

Abre Ajustes → Servidor → Copia de seguridad y restauración.
En Instantáneas de la instalación, presiona Crear copia ahora.
El aviso indica el directorio que se escribió, en el host del servidor. La nueva instantánea aparece al principio de la lista.

El servidor sigue funcionando en todo momento. Cada archivo se escribe con VACUUM INTO, que es consistente frente a una base de datos activa, así que no hay ventana de mantenimiento ni necesidad de detener agentes.

Cada fila de la lista muestra la marca de tiempo, el tamaño en disco, cuántos espacios de trabajo se capturaron y si la instantánea está Completa o Incompleta. Incompleta significa que falta el manifiesto o que nombra archivos que no están — un respaldo interrumpido por una falla o un disco lleno. Aun así se listan a propósito: una instantánea que no ves es una que crees tener. Una instantánea incompleta no puede restaurar toda la instalación, pero los archivos de espacio de trabajo que sí contiene todavía se pueden adoptar de uno en uno.

Una fila también puede decir n espacios de trabajo no capturados. Eso es un espacio de trabajo registrado pero al que nunca se escribió (todavía no hay archivo), o uno cuya copia falló — revisa el registro del servidor.

Programar los respaldos de espacios de trabajo y su retención

Abre Ajustes → Pipelines → Plantillas de pipeline para el espacio de trabajo y busca Workspace backup. Su programación habilitada se ejecuta todos los domingos a las 03:00 UTC: Back up workspace, seguido de Delete backups older than (30 días de forma predeterminada). El segundo nodo se ejecuta solo después de que el respaldo se complete con éxito. Puedes cambiar los días de retención en el nodo o desactivar la programación. Si el servidor está apagado a la hora programada, la programación se pone al día una vez cuando vuelve, en lugar de repetir cada semana perdida.

Los respaldos de espacio de trabajo viven en el servidor bajo backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. El nodo de retención solo elimina respaldos antiguos de este espacio de trabajo; nunca elimina instantáneas de la instalación ni respaldos de otros espacios de trabajo. Estos archivos son solo de base de datos. Para retenerlos fuera de la máquina, cópialos de forma independiente.

Estos respaldos son independientes de la lista Instantáneas de la instalación. Para restaurar uno, usa Datos del espacio de trabajo → Importar con la ruta workspace.db del lado del servidor del respaldo. Importar sustituye la base de datos actual de ese espacio de trabajo, así que expórtala primero si podrías necesitar deshacer la restauración.

Eliminar una instantánea de la instalación

En Instantáneas de la instalación, despliega la instantánea, incluida una incompleta, y usa Eliminar instantánea en la sección de peligro. Confirma su nombre. El directorio completo de la instantánea se elimina del servidor de forma permanente; descárgala primero si necesitas una copia. Un pipeline de respaldos de espacio de trabajo nunca elimina estas instantáneas.

Recoger una copia en tu propia máquina

Las rutas que muestra la página están en la máquina que ejecuta cc_server. Cuando esa no es la máquina en la que estás, usa los botones Descargar:

Junto a cada espacio de trabajo, en Datos del espacio de trabajo → Descargar, para un solo archivo .db.
Junto a cada instantánea, en Instantáneas de la instalación → Descargar, para toda la instantánea como un .zip.

En escritorio eliges dónde queda el archivo y el aviso lo indica; en la web va a las descargas del navegador. En cualquier caso, ambos reportan el progreso en bytes, porque son las dos cargas útiles que llegan a los gigabytes.

Ambos generan una copia nueva en el momento en que presionas el botón, la transmiten en streaming y eliminan después la copia del servidor — una descarga no es «buscar el archivo que creó antes el botón de exportar».

Descomprimir el archivo de una instantánea reproduce exactamente la estructura de la instantánea, que es lo que hace que restaurarla sea una copia de vuelta.

Mover un espacio de trabajo a otra instalación

Un espacio de trabajo es un solo archivo de base de datos, así que entregarlo es una operación de archivos.

En el servidor de origen, Ajustes → Servidor → Copia de seguridad y restauración → Datos del espacio de trabajo, despliega el espacio de trabajo y presiona Descargar.
En el servidor de destino, crea (o elige) el espacio de trabajo que lo va a recibir.
Despliega ese espacio de trabajo y, en Restaurar desde este dispositivo, presiona Elegir un archivo y subirlo. Elige el .db que descargaste.

Si ambos servidores son la misma máquina en la que estás, Guardar en el servidor más Importar → Elegir archivo hacen lo mismo sin el viaje de ida y vuelta; las rutas del diálogo de importación se resuelven en el host del servidor.

Hay dos cosas que se permiten y se registran en lugar de rechazarse: importar un archivo cuyo id de espacio de trabajo registrado difiere del destino (así es como duplicas un espacio de trabajo o lo restauras con un id nuevo) e importar un archivo de una instalación distinta. En este segundo caso, los dispositivos emparejados y los ids de usuario del archivo pertenecen a la instalación de la que vino y no se resolverán en esta — los datos propios del espacio de trabajo están intactos, pero vuelve a comprobar la pertenencia después de adoptarlo.

Los tokens del bot de chat viven junto a la base de datos, no dentro de ella, así que un espacio de trabajo que le entregas a alguien más no lleva credenciales activas. La instalación receptora vuelve a conectar las suyas.

Restaurar un espacio de trabajo desde una instantánea

En Instantáneas de la instalación, despliega la instantánea que quieres.
Busca la fila del espacio de trabajo y presiona Restaurar.
Confirma. Todo lo que ese espacio de trabajo ha hecho desde que se tomó la instantánea se pierde.

Esta es la misma operación que una importación, apuntada a la copia que la instantánea tiene del archivo de ese espacio de trabajo — a propósito, para que no haya un segundo mecanismo que pudiera tratar el mismo archivo de forma distinta.

Una fila puede decir Ya no está en este servidor, con Restaurar deshabilitado: la instantánea contiene un espacio de trabajo que esta instalación ya no tiene. Recupéralo a mano — crea un espacio de trabajo y luego, en Datos del espacio de trabajo, importa en él desde <snapshot path>/<old workspace id>/workspace.db. La instantánea desplegada muestra su propia Ruta en el servidor en un campo de copiado, y el título de la fila es el id anterior del espacio de trabajo, así que tienes ambas mitades de esa ruta frente a ti.

Restaurar toda la instalación

No hay botón para esto, y no debería haberlo: reemplaza las bases de datos que el servidor en ejecución mantiene abiertas.

Detén cc_server. Si ejecutas la aplicación de escritorio con su servidor integrado, cierra la aplicación.

Copia el contenido de la instantánea sobre el directorio de datos. La estructura de la instantánea refleja la de la instalación activa, así que esto es una copia simple:

# macOS default; see the CLI reference for other platforms
DATA_DIR="$HOME/Library/Application Support/control-center"
SNAPSHOT="$DATA_DIR/backups/2026-07-28T09-12-33-000Z"

cp "$SNAPSHOT/global.db" "$DATA_DIR/global.db"
for d in "$SNAPSHOT"/*/; do
  id=$(basename "$d")
  mkdir -p "$DATA_DIR/$id"
  cp "$d/workspace.db" "$DATA_DIR/$id/workspace.db"
done

Elimina los archivos -wal y -shm que estén junto a las bases de datos que reemplazaste. Pertenecen a los archivos anteriores, y uno obsoleto junto a una base de datos restaurada es un riesgo de corrupción.
Inicia el servidor de nuevo.

La instantánea no contiene ningún secrets.json, así que una instalación restaurada en un host nuevo conserva sus datos pero no sus credenciales: los dispositivos emparejados, los tokens de proveedor y la configuración de SSO se tienen que volver a establecer, o restaurar desde donde sea que guardaras ese archivo. Restaurar en el mismo host, donde secrets.json nunca se perdió, lo conserva todo.

Copiar los respaldos fuera de la máquina

Una instantánea en el mismo disco que la base de datos que copió te protege de una mala importación, no del disco. Nada en Control Center envía una copia a ningún lado, así que esta parte es tuya.

Sincronizar las instantáneas

Las instantáneas son inmutables una vez escritas y se nombran por marca de tiempo, así que cualquier herramienta de sincronización las maneja bien. Excluye transfer/, que es un banco de trabajo para descargas y subidas en curso:

DATA_DIR="$HOME/Library/Application Support/control-center"

# To another host over ssh
rsync -a --delete --exclude 'transfer/' \
  "$DATA_DIR/backups/" backup-host:/srv/control-center-backups/

# To object storage
aws s3 sync --exclude 'transfer/*' \
  "$DATA_DIR/backups/" s3://my-bucket/control-center/backups/

# Or with deduplication, encryption and its own retention
restic backup --exclude 'transfer' "$DATA_DIR/backups"

--delete refleja tu limpieza local en el remoto. Quítalo si quieres que el remoto conserve instantáneas por más tiempo que el host.

Incluir lo que una instantánea deja fuera

Para poder reconstruir la instalación y no solo sus datos, copia esto también. Son archivos ordinarios, seguros de copiar mientras el servidor está en ejecución:

rsync -a \
  "$DATA_DIR/secrets.json" \
  backup-host:/srv/control-center-backups/config/

rsync -a --relative \
  "$DATA_DIR"/./*/chat_credentials \
  "$DATA_DIR"/./*/blobs \
  "$DATA_DIR"/./*/skills \
  "$DATA_DIR"/./*/agents \
  backup-host:/srv/control-center-backups/workspace-files/

secrets.json tiene permisos 0600 y contiene cada clave de emparejamiento, credencial de proveedor y ajuste de SSO de la instalación. Dondequiera que quede debe estar al menos tan protegido como el host del servidor — cifrado en reposo y que no sea un bucket que cualquiera pueda leer.

Omite spaces/ (worktrees copy-on-write, reaprovisionados desde tus repos), pr_clones/ (una caché), models/ (se descargan de nuevo), media_cache/ y rigs/ (estado de la máquina, y grandes). El audio de reuniones grabadas en meetings/ vale la pena incluirlo si conservas reuniones.

Programar una instantánea de toda la instalación fuera de la aplicación

El pipeline integrado solo respalda un espacio de trabajo. Para una instantánea de toda la instalación sin supervisión, no hay subcomando de CLI, y el RPC de instantáneas requiere un cliente completo emparejado que sea el propietario de la instalación. Un temporizador del lado del host puede usar VACUUM INTO contra las bases de datos activas:

#!/usr/bin/env bash
set -euo pipefail

DATA_DIR="${CC_SERVER_DATA_DIR:-$HOME/.local/share/control-center}"
DEST="/srv/control-center-snapshots/$(date -u +%Y-%m-%dT%H-%M-%SZ)"
mkdir -p "$DEST"

sqlite3 "$DATA_DIR/global.db" "VACUUM INTO '$DEST/global.db'"

for db in "$DATA_DIR"/*/workspace.db; do
  id=$(basename "$(dirname "$db")")
  mkdir -p "$DEST/$id"
  sqlite3 "$db" "VACUUM INTO '$DEST/$id/workspace.db'"
done

Ejecútalo como el mismo usuario que es dueño del directorio de datos, desde cron o un temporizador de systemd, y sincroniza DEST fuera del host después. VACUUM INTO necesita SQLite 3.27 o posterior.

Escríbelo fuera de <dataDir>/backups/. Un directorio hecho a mano ahí no tiene manifest.json, así que la aplicación lo listaría como una instantánea incompleta y la lista dejaría de ser un registro honesto de lo que el propio servidor produjo.

Purgar las instantáneas antiguas de toda la instalación

Puedes eliminar instantáneas de la instalación individuales en la aplicación. Para una política de retención del lado del host, mantén el directorio de respaldos de espacio de trabajo separado de las instantáneas de la instalación:

find "$DATA_DIR/backups" -mindepth 1 -maxdepth 1 -type d \
  ! -name exports ! -name transfer ! -name workspace-backups \
  -mtime +30 -exec rm -rf {} +

Revisa la salida de una ejecución con -print antes de agregar -exec. Conserva más de una: la falla de la que te proteges suele ser «el último respaldo también tiene el problema».

Comprobar que un respaldo está bien

Un respaldo que nadie ha restaurado es una hipótesis.

Comprobación barata — el archivo abre y sus páginas están intactas:

sqlite3 "$SNAPSHOT/global.db" 'PRAGMA integrity_check;'   # expects: ok

Comprobación real — adóptalo. Crea un espacio de trabajo de prueba en una instalación que no sea de producción, importa en él un archivo de espacio de trabajo y mira si los espacios, los tickets y los mensajes que esperas están ahí. Eso ejercita el mismo camino que toma una restauración real, incluida la reconstrucción de FTS, y es la única comprobación que te dice que el respaldo se puede restaurar y no solo leer.

Haz esto una vez cuando configures los respaldos, y de nuevo siempre que cambies dónde se guardan.

Solución de problemas

Síntoma	Causa y solución
Los controles de descarga y subida están deshabilitados con una nota sobre un relevo	Estás conectado a través del relevo intermediado, que no transporta transferencias de archivos. Conéctate directamente
«El servidor lo rechazó»	Rol. Crear o listar una instantánea de la instalación requiere al operador de la instalación. Descargar un espacio de trabajo requiere admin, restaurar uno requiere owner y un zip de una instantánea completa requiere al operador de la instalación
«Este servidor no expone ninguna superficie de copia de seguridad»	El host no tiene conectado ningún puerto de respaldo — un servidor de demostración. Las operaciones están ausentes en lugar de rechazarse
«El archivo supera el tamaño que acepta el servidor»	Las subidas están limitadas a 8 GiB. Pon el archivo en el host del servidor y usa Importar → Elegir archivo en su lugar
Importación rechazada: no es una base de datos de espacio de trabajo de Control Center	El archivo no tiene ninguna fila `workspace_meta` — no es una exportación de espacio de trabajo, o está truncado. No se reemplazó nada
Una instantánea aparece como Incompleta	Le falta el manifiesto o nombra archivos ausentes. Crea una nueva; mientras tanto, adopta los archivos de espacio de trabajo individuales que contiene
Una instantánea indica que no se capturaron espacios de trabajo	Nunca se escribió en esos espacios de trabajo, o su copia falló. Revisa el registro del servidor
Una instalación restaurada no tiene credenciales de host de código ni de SSO	`secrets.json` no está en una instantánea. Restáuralo desde donde lo hayas guardado, o vuelve a conectar los proveedores
A un espacio de trabajo restaurado le faltan imágenes pegadas	Los blobs viven junto a la base de datos, no dentro de ella. Copia también `<workspaceId>/blobs/`

Guías relacionadas

Ejecutar un servidor headless: de dónde viene el directorio de datos
Conectarte a un servidor remoto: conexiones directas frente a las que pasan por el relevo
Emparejar un dispositivo: la credencial con la que firman las rutas de transferencia

Conceptos y referencia relacionados

Respaldo, exportación e importación: cada operación, ruta, campo y límite
Espacios de trabajo y aislamiento: por qué un espacio de trabajo es un archivo
CLI de cc_server: la estructura del directorio de datos