CachyOS Migration Tool

Script de migración y bootstrap para workstations Linux. Orientado al flujo de migración hacia CachyOS / Arch con entornos de desarrollo Python/Web, IA tooling y workflows terminal-heavy.

Probado únicamente en CachyOS. El bootstrap usa pacman y yay (AUR) — no es compatible con distribuciones basadas en apt/rpm sin adaptación.

Incluye soporte específico para perfiles MacBook Pro Intel detectados por modelo, con una primera base validada para:

MacBookPro12,1 — MacBook Pro Retina 13" 2015
MacBookPro8,1 — MacBook Pro 13" Early 2011

Qué hace

Operación	Descripción
Backup	Exporta configuraciones, repos Git, datos de usuario y metadata (SSH, VSCode, ZSH, IA tooling)
Bootstrap	Instala y configura una workstation CachyOS desde cero: KDE Plasma, dev tooling, Docker, Syncthing
Restore	Restaura el backup en la nueva instalación, adaptando UID/GID y permisos
Restic backup	Prepara y ejecuta backup continuo por SFTP/SSH con fallback LAN/remoto y timer de usuario
Post-check	Valida el estado del sistema tras el primer reinicio post-bootstrap
MBP Watch	Daemon systemd de monitorización de hardware + dashboard web + plasmoid KDE
Extras	Hyprland opcional, YouTube Force H264, VA-API Brave/Chromium según perfil Intel detectado, BTRFS snapshots

Novedades actuales

Detección de hardware Apple por modelo y perfil aplicado
Bootstrap con checklist dinámico: solo muestra bloques compatibles con el equipo detectado
TUI Python y whiptail adaptadas al contexto del dispositivo
Backup TUI con exploración de destino, selección real de elementos de /home/usuario y verificación final del backup
Comandos de test para validar perfiles, catálogo y sintaxis antes de tocar el sistema

Uso rápido

# Interfaz interactiva (selecciona automáticamente el mejor motor TUI)
./migration.sh

# Flujo recomendado tras instalar CachyOS
./migration.sh bootstrap
# → reiniciar
./migration.sh postcheck
./migration.sh restore --source /ruta/del/backup
./migration.sh post-restore-fixups

# Comprobaciones rápidas
./migration.sh test profiles
./migration.sh test catalog
./migration.sh test syntax
./migration.sh test

El script selecciona el motor TUI en este orden: Python + curses (sin dependencias externas) → whiptail → menú de texto plano. Se puede forzar con TUI_BACKEND=python|whiptail|text.

Comandos CLI

./migration.sh backup    [--target RUTA] [--dry-run]
./migration.sh bootstrap [--dry-run] [--hyprland yes|no] [--apple-laptop yes|no]
./migration.sh postcheck
./migration.sh restore   [--source RUTA] [--force] [--dry-run]
./migration.sh post-restore-fixups [--dry-run]
./migration.sh restic-backup [init [--smoke-test] | run | status | snapshots | install-timer | disable-timer]

./migration.sh export-ai-context         [--dry-run]
./migration.sh install-youtube-force-h264  [--dry-run]
./migration.sh install-talk2ai            [--dry-run]
./migration.sh install-codexbar-tray      [--dry-run]
./migration.sh configure-vaapi-brave       [--dry-run]

./migration.sh install-mbp-watch           [--dry-run]
./migration.sh add-mbp-plasmoid            [--target primary|screen:N] [--dry-run]
./migration.sh move-mbp-plasmoid           [--target primary|screen:N] [--dry-run]
./migration.sh reinstall-mbp-plasmoid      [--target primary|screen:N] [--dry-run]
./migration.sh uninstall-mbp-plasmoid      [--dry-run]
./migration.sh uninstall-mbp-watch         [--dry-run]

El timer de restic-backup sigue comprobando cada 30 minutos, pero por defecto solo ejecuta copias entre 08:00 y 22:00. Ese horario se ajusta en ~/.config/cachyos-migration-tool/backup.env con BACKUP_ALLOWED_START_HOUR, BACKUP_ALLOWED_END_HOUR y BACKUP_ENFORCE_SCHEDULE.

install-youtube-force-h264 y configure-vaapi-brave siguen disponibles por CLI, pero en la interfaz interactiva normal viven dentro de bootstrap, no como opciones sueltas del menú principal.

post-restore-fixups sirve para normalizar un $HOME restaurado en otra máquina: recompone CLIs npm/NVM (codex, gemini, pnpm), instala dependencias locales de talk2ai, elimina autostarts heredados de codexBar Tray, limpia locks de Brave y repara la dependencia google-auth-library de Antigravity IDE si falta.

Bootstrap — bloques seleccionables

En la TUI se presentan como checklist dinámico según el hardware detectado. Activos por defecto en el perfil inicial actual: sync, yay, flatpak, official, kde, aur, zsh, node y apple cuando aplica.

Bloque	Qué instala
`base`	KDE Plasma, zsh, kitty, tmux, neovim, ripgrep, fd, bat, eza, docker, syncthing…
`zsh`	Oh My Zsh + Powerlevel10k
`node`	nvm, Node LTS, pnpm, bun
`playwright`	Playwright para testing web con soporte MCP e integración con agentes IA
`ai`	Codex CLI, Engram, Claude Code
`mbpwatch`	Daemon MBP Watch (systemd)
`plasmoid`	Plasmoid KDE MBP Watch
`youtube`	Extensión YouTube Force H264
`apple`	thermald, powertop (extras Apple laptop Intel)
`facetime`	facetimehd-dkms + firmware (cámara PCIe MBP 2013+)
`talk2ai`	Descarga o actualiza `talk2ai` desde GitHub e instala `handy-bin` como dependencia
`restic`	Instala `restic` y queda marcado por defecto para backups/restores
`filezilla`	Instala FileZilla como cliente gráfico SFTP/FTP
`markdownpart`	Añade vista previa Markdown en Kate
`libreoffice`	Instala LibreOffice Fresh ES + Java 21
`androidstudio`	Instala Android Studio + JDK 21
`ipscan`	Instala Angry IP Scanner desde AUR
`tea`	Instala `tea` como CLI opcional para Gitea
`obsidian`	Obsidian desde repositorio oficial
`sshpass`	`sshpass` para SSH con contraseña no interactiva
`codexbar_tray`	Instala `codexBar Tray` desde un repo local restaurado/detectado
`ai_engram`	Instala Engram y lo configura para Codex CLI
`iwd`	iwd backend para NetworkManager
`hyprland`	Hyprland + waybar, rofi, hyprpaper, grim, mako
`wifi`	wireless-regdb + dominio regulatorio por país
`globalmenu`	Global Menu KDE para GTK y VS Code
`hwaccel`	Flags de aceleración HW para Brave/Chrome
`vaapi`	VA-API Brave/Chromium ajustado al perfil Intel detectado
`btrfs`	Snapper + grub-btrfs + snap-pac

Estructura del repositorio

migration.sh                    # punto de entrada
src/
├── main.sh                     # lógica de comandos y menú
├── lib/
│   ├── common.sh               # helpers compartidos
│   ├── tui.py                  # TUI Python/curses (primario)
│   └── tui.sh                  # TUI whiptail (fallback)
└── modules/
    ├── backup.sh
    ├── bootstrap.sh
    ├── restic_backup.sh
    └── restore.sh
src/tools/
└── extract_bcm43602_bundle.sh  # extrae firmware Wi-Fi desde el sistema actual
assets/
├── diagnostics/                # daemon mbp_watch, scripts de despliegue y dashboard local
│   └── web/                    # frontend HTML/JS/CSS del dashboard local
├── plasmoids/
│   └── mbp-watch/              # paquete KDE Plasma 6 (kpackagetool6)
├── scripts/
│   └── backup-monitor.sh       # genera backup-status.json para el plasmoid
├── systemd/
│   ├── cachyos-backup-monitor.*# timer/servicio del monitor del plasmoid
│   └── user/restic-backup.*    # timer/servicio del backup Restic
└── templates/
    ├── backup-restic.env.example
    └── restic-excludes.txt
firmware/
└── brcm/                       # bundle BCM43602 para no depender de Wi-Fi en post-install
docs/                           # documentación completa

Restic + plasmoid MBP Watch

El flujo de backup permanente y su visualización en Plasma quedan separados en dos piezas:

./migration.sh restic-backup ... gestiona el repositorio Restic y el timer de backup de usuario, con ventana horaria configurable
assets/scripts/backup-monitor.sh + assets/systemd/cachyos-backup-monitor.* actualizan ~/.config/cachyos-migration-tool/backup-status.json para que el plasmoid MBP Watch muestre el estado del backup

La guía operativa de esta segunda parte está en docs/mbp-watch/backup-monitor.md.

Perfiles MacBook contemplados

El script detecta automáticamente hardware Apple vía DMI, aplica un perfil de compatibilidad y adapta la TUI y el bootstrap a ese modelo.

Perfiles contemplados ahora mismo:

MacBookPro12,1 — MacBook Pro Retina 13" 2015
MacBookPro8,1 — MacBook Pro 13" Early 2011

En función del perfil detectado:

se muestran solo los bloques de bootstrap compatibles
la corrección de VA-API cambia según la GPU Intel del equipo
el resumen de hardware visible en la TUI indica modelo detectado, perfil aplicado y características principales

Extras específicos ya cubiertos para MacBookPro12,1:

Wi-Fi BCM43602 — copia firmware local desde firmware/brcm/ y aplica workaround brcmfmac. Para actualizar el bundle desde el sistema actual: bash src/tools/extract_bcm43602_bundle.sh
Cámara FaceTime HD PCIe (14e4:1570) — instala facetimehd-dkms + firmware, configura módulo persistente y blacklist de bdc_pci
MBP Watch — daemon systemd que monitoriza temperatura, batería, Wi-Fi, drivers y eventos de kernel; genera dashboard web en http://localhost:7070/report.html y AI digest en /var/lib/mbp-watch/report.txt
VA-API Intel Broadwell — flags --use-gl=angle --use-angle=opengl para Brave/Chromium

Para MacBookPro8,1, el perfil inicial ya ajusta el catálogo de bootstrap y la ruta de VA-API para Intel Sandy Bridge.

Backup TUI

El flujo interactivo de backup ahora:

permite elegir el destino desde montajes típicos del sistema o navegar manualmente
deja profundizar por directorios antes de confirmar la ruta final
permite seleccionar elementos reales dentro de /home/usuario
mantiene la ejecución dentro de la propia TUI
verifica el resultado al finalizar y guarda logs útiles en la carpeta del backup

Requisitos

CachyOS (probado) o Arch Linux — requiere pacman y yay para paquetes AUR
bash 4+
python3 con módulo curses (TUI primaria, ya incluido en stdlib)
sudo para bootstrap y operaciones del daemon

El script funciona sin TUI gráfica: el modo texto no requiere dependencias adicionales.

Licencia

Distribuido bajo la GNU General Public License v3.0. Sin garantía de ningún tipo — úsalo bajo tu propia responsabilidad.

Documentación

→ docs/

Name		Name	Last commit message	Last commit date
Latest commit History 114 Commits
assets		assets
docs		docs
firmware/brcm		firmware/brcm
src		src
tech_docs		tech_docs
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
migration.sh		migration.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

CachyOS Migration Tool

Qué hace

Novedades actuales

Uso rápido

Comandos CLI

Bootstrap — bloques seleccionables

Estructura del repositorio

Restic + plasmoid MBP Watch

Perfiles MacBook contemplados

Backup TUI

Requisitos

Licencia

Documentación

About

Uh oh!

Releases 18

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

CachyOS Migration Tool

Qué hace

Novedades actuales

Uso rápido

Comandos CLI

Bootstrap — bloques seleccionables

Estructura del repositorio

Restic + plasmoid MBP Watch

Perfiles MacBook contemplados

Backup TUI

Requisitos

Licencia

Documentación

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 18

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages