camilbenameur/remote-devbox

¿Qué hace remote-devbox?

Estás configurando (o reparando) un devbox: un servidor Linux donde las sesiones de Claude Code se ejecutan mientras la aplicación de escritorio de Claude en el ordenador del usuario es solo la interfaz. Trabaja a través de las fases en orden. Cada fase indica lo que haces tú, lo que solo el usuario puede hacer y cómo verificar que ha funcionado.

<skill> a continuación significa la carpeta que contiene este archivo.

Lo que obtiene el usuario

• La pestaña Código de la aplicación de escritorio, sin cambios, con cada sesión ejecutándose en el devbox vía SSH: shell, pruebas, instalaciones, Python, Node, Chrome. El ordenador solo dibuja la interfaz.
• La suscripción del usuario, no los créditos de API. La aplicación de escritorio pasa y renueva el inicio de sesión de la sesión. Nunca establezcas ANTHROPIC_API_KEY en el devbox: la facturación pasaría a la API.
• Dos navegadores como servidores MCP: chrome, un Chrome compartido con sesión iniciada en las cuentas del usuario, y playwright, un Chrome aislado en blanco por sesión. Una pantalla virtual muestra el Chrome compartido en cualquier navegador web en la red privada del usuario (noVNC).
• Sesiones que continúan con el ordenador apagado: devbox-relay reanuda sesiones cortadas de la aplicación de escritorio en segundo plano, y devbox-rc aloja sesiones iniciadas desde claude.ai/code o la aplicación de teléfono.
• El mismo CLAUDE.md global, habilidades, memoria y hooks de plugins que en el ordenador.

Lee references/how-it-works.md cuando necesites los mecanismos, y references/troubleshooting.md en cuanto algo falle.

Reglas básicas para ti

• El usuario hace: pagos y pedidos, cada contraseña e inicio de sesión (proveedor, Tailscale, código de dispositivo de GitHub, /login de Claude, los sitios web en el Chrome compartido), clics en la configuración de la aplicación de escritorio y la consola de administración de Tailscale. Dale el enlace o comando exacto, uno a la vez, luego espera. Nunca escribas una contraseña, número de tarjeta o código de un solo uso tú mismo.
• Antes de pedir algo, expón el plan, el precio y el compromiso, y obtén un sí.
• Los scripts de configuración son idempotentes: cuando uno falla, lee el error, corrige la causa, ejecútalo de nuevo.
• En el devbox, sudo no necesita contraseña. Aun así, pregunta al usuario antes de cualquier cambio en el sistema que los scripts no hagan por sí mismos (paquetes, servicios, firewall, sshd, usuarios).
• Cuando trabajes en el devbox en vivo del usuario, nunca detengas los servicios devbox-*, edites ~/.claude o reemplaces binarios en ~/.local/bin sin decirlo primero: sus sesiones pueden estar en ejecución.

Fase 0: comprobar el ordenador

1. Plataforma. Windows: scripts en <skill>/client/windows/ (Windows PowerShell 5.1 es suficiente). macOS o Linux: <skill>/client/unix/.
2. Solo Windows: cliente OpenSSH 9.4 o más reciente (ssh -V). La aplicación de escritorio lo requiere. Si es más antiguo: winget install Microsoft.OpenSSH.Preview.
3. La aplicación de escritorio de Claude está instalada y con sesión iniciada, y el plan del usuario incluye Claude Code.
4. git config --global user.name y user.email están establecidos (los scripts los copian al devbox).
5. Pregunta al usuario qué partes opcionales quiere: gatehaul (ejecuta compilaciones pesadas en GitHub Codespaces, -Gatehaul / --gatehaul), el Chrome compartido con sesión iniciada (activado por defecto), copia de memoria.

Fase 1: elegir y pedir un servidor

Usa references/providers.md. Requisitos: máquina virtual KVM, Ubuntu 24.04, x86_64 preferido (arm64 funciona pero no está probado de extremo a extremo), 8 GB de RAM como mínimo (16 a 24 GB para varias sesiones paralelas más Chrome), 80 GB de disco y una consola web del proveedor (es la ruta de rescate si SSH alguna vez se bloquea).

Ayuda al usuario a comparar, luego abre la página de pedido para él si tienes un navegador. El usuario elige el plan, paga y confirma. Si el proveedor pide una clave SSH al hacer el pedido, muéstrala primero:

powershell -ExecutionPolicy Bypass -File <skill>\client\windows\setup-devbox.ps1 -ShowKey

bash <skill>/client/unix/setup-devbox.sh --show-key

Pregunta al usuario la IP pública y el usuario inicial (a menudo root; ubuntu en OVH y Oracle).

Fase 2: iniciar el servidor

powershell -ExecutionPolicy Bypass -File <skill>\client\windows\setup-devbox.ps1 -HostAddress <IP> -InitialUser root

bash <skill>/client/unix/setup-devbox.sh --host <IP> --initial-user root

Ejecútalo en una terminal donde el usuario pueda escribir (el panel de terminal de la aplicación de escritorio, o pídele que lo ejecute). Necesita tres cosas del usuario:

1. Huella de la clave del host. El script la muestra y pregunta sí/no. Dile al usuario que la compare con la salida de la consola web del proveedor de ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub.
2. Contraseña inicial, una vez, para que la clave pueda ser autorizada (se omite si la clave se dio al hacer el pedido).
3. Código de dispositivo de GitHub: gh auth login imprime un código y un enlace.

Lo que hace: crea la clave ~/.ssh/devbox_ed25519 (sin frase de contraseña, la aplicación de escritorio debe conectarse sin aviso), ejecuta host/10-root-bootstrap.sh (usuario dev con sudo, SSH solo con clave, linger, swap, Node, gh, Chrome, Tailscale, ufw, fail2ban, actualizaciones desatendidas, paquetes de pantalla virtual), añade el bloque Host devbox a ~/.ssh/config, lo prueba, restringe SSH al usuario dev, ejecuta host/20-user-setup.sh (uv, CLI de Claude Code, gatehaul opcional, servidores MCP, herramientas ~/.local/bin, servicios de pantalla virtual, servicio relay y hook), luego sincroniza la configuración de Claude (Fase 6).

Verificación: ssh devbox 'claude --version; claude mcp list; systemctl --user is-active devbox-vnc devbox-chrome devbox-relay'.

Fase 3: red privada, luego cerrar SSH público

1. Usuario: instala Tailscale en el ordenador e inicia sesión (winget install tailscale.tailscale, la Mac App Store, o tailscale.com/download).
2. En el devbox: ssh -t devbox sudo tailscale up --hostname=devbox. Imprime un enlace de inicio de sesión: el usuario lo abre.
3. Usuario: consola de administración de Tailscale, Máquinas, devbox, Deshabilitar caducidad de clave. De lo contrario, el devbox abandona la red después de 180 días y solo queda la consola del proveedor.
4. En ~/.ssh/config, establece el HostName del bloque devbox a devbox (MagicDNS) o a la dirección de ssh devbox tailscale ip -4. Verifica ssh devbox true.
5. Cerrar SSH público: ssh -t devbox 'bash ~/devbox-setup/30-root-lockdown.sh'. Se niega mientras haya una sesión SSH que no provenga de Tailscale abierta: ciérralas primero (incluyendo sesiones de la aplicación de escritorio abiertas en la IP pública).

Rescate por bloqueo: consola web del proveedor, luego sudo ufw allow OpenSSH.

Fase 4: conectar la aplicación de escritorio

El usuario, en la aplicación de escritorio: pestaña Código, menú de entorno bajo la caja de aviso, Nuevo entorno, SSH (las etiquetas pueden haber cambiado a finales de 2026):

Campo	Valor
Host SSH	devbox (tomado de ~/.ssh/config)
Clave SSH	vacío
Carpeta de worktree	~/worktrees
Carpeta para una sesión	~/dev/<proyecto>

En la primera conexión, la aplicación instala su propio motor en ~/.claude/remote/ en el devbox y muestra la clave del host: la misma huella que en la Fase 2. Las sesiones en ese entorno se ejecutan en el devbox. No hay panel de navegador en sesiones SSH: reenvía puertos en su lugar (ver Uso diario).

Fase 5: el Chrome con sesión iniciada

1. ssh devbox devbox-browser login (Chrome se reinicia sin su puerto de depuración, porque Google a menudo rechaza el inicio de sesión en un Chrome que tiene uno).
2. El usuario abre http://devbox:6080/vnc.html desde una máquina en la tailnet. Contraseña: ssh devbox devbox-browser password. Sin Tailscale: ssh -N -L 6080:localhost:6080 devbox y http://localhost:6080/vnc.html.
3. El usuario inicia sesión en los sitios que los agentes deben usar. Aconseja no usar bancos ni nada donde una instrucción inyectada podría costar dinero: cada sesión puede controlar este navegador.
4. ssh devbox devbox-browser normal lo devuelve a los agentes (puerto de depuración 9222, solo local).

Verificación: en una sesión del devbox, pide al MCP chrome que abra un sitio donde el usuario haya iniciado sesión y confirma que la cuenta es visible, sin leer contenido privado. El icono de la barra de tareas y el menú contextual de la pantalla abren este Chrome; también es el navegador predeterminado del devbox.

Fase 6: reflejar el entorno local de Claude

Objetivo: una sesión en el devbox se comporta como una en el ordenador.

1. CLAUDE.md global y habilidades:

   powershell -ExecutionPolicy Bypass -File <skill>\client\windows\sync-claude-config.ps1 -Memory
   

   bash <skill>/client/unix/sync-claude-config.sh --memory
   

   Antepone <skill>/templates/host-header.md (lo que difiere en el devbox: rutas, navegadores, pantalla, continuidad, regla de sudo) al ~/.claude/CLAUDE.md local, fusiona ~/.claude/skills (sin .venv, node_modules, .git), y con -Memory copia la memoria automática de la carpeta de proyectos local (-LocalDevDir, por defecto ~/Documents/dev) a la memoria de ~/dev en el devbox. Vuelve a ejecutarlo cada vez que cambien el CLAUDE.md local o las habilidades. Edita la plantilla del encabezado, no la copia en el devbox, que se sobrescribe.
2. Habilidades que necesitan configuración: para cada habilidad sincronizada, busca entornos Python (requirements.txt, pyproject.toml), paquetes Node, binarios y rutas de Windows en SKILL.md. Recrea entornos en el devbox y corrige rutas. Instala herramientas del sistema que necesiten (por ejemplo ffmpeg) después de preguntar.
3. Plugins: la aplicación de escritorio instala los plugins del usuario en sesiones SSH, pero sus hooks no se ejecutan allí. Para cada plugin habilitado con hooks/hooks.json, clona su fuente en el devbox en el mismo commit dentro de ~/.claude/hooks-thirdparty/<plugin>, y fusiona sus hooks en el ~/.claude/settings.json del devbox, reemplazando ${CLAUDE_PLUGIN_ROOT} por esa carpeta y corrigiendo los intérpretes para Linux (python a python3). Fusiona con jq; conserva el hook existente devbox-relay guard SessionStart. Lee los scripts de hook antes de habilitarlos.
4. Servidores MCP: compara claude mcp list localmente y en el devbox. Vuelve a añadir servidores stdio de ámbito de usuario que tengan sentido en Linux. Los conectores de claude.ai siguen la cuenta: no hay que hacer nada.
5. Proyectos: clona en ~/dev/<nombre> con gh repo clone. Copia archivos locales no commiteados o ignorados que importen (archivos .env solo con el consentimiento del usuario), instala dependencias, ejecuta una prueba ligera. Las compilaciones pesadas pertenecen a Codespaces vía gatehaul si está instalado.
6. Migración larga sin el usuario: si hay mucho que mover, escribe una lista de trabajo, luego inicia una sesión autónoma en el devbox con references/setup-agent-prompt.md a través de claude-task.

Fase 7: sesiones que continúan con el ordenador apagado

1. Inicio de sesión CLI en el devbox (el relay y el Control Remoto lo usan): ssh -t devbox claude, luego /login; el usuario abre el enlace y pega el código; /exit.
2. Relay: ya habilitado por 20-user-setup.sh. Verifica ssh devbox devbox-relay test (todos los casos OK) y ssh devbox devbox-relay status.
3. Servidor de Control Remoto, una vez a mano porque pide dos confirmaciones: ssh -t devbox 'cd ~/dev && claude remote-control', el usuario responde y dos veces, luego Ctrl+C. Luego ssh devbox 'touch ~/.config/devbox/rc-accepted && systemctl --user enable --now devbox-rc'. En claude.ai/code o la aplicación de teléfono, el entorno con el nombre de la carpeta y el host (por ejemplo dev · <hostname>) ahora inicia sesiones en el devbox. Elige el modo de permisos Auto allí para sesiones que deben progresar solas. claude.ai puede pedir al usuario que inicie sesión de nuevo para verificar el dispositivo.
4. Prueba real opcional, con el usuario: inicia una tarea pequeña en una sesión de escritorio que se detendrá en una pregunta de permiso, el usuario cierra la aplicación de escritorio, espera unos 30 minutos, la vuelve a abrir; el registro ~/dev/_relay/log.md muestra el relay, claude agents en el devbox muestra relay · <nombre>, y la sesión original reabierta indica que fue retransmitida.

Fase 8: verificación final

Ejecuta e informa cada línea:

ssh devbox 'claude --version; gh auth status 2>&1 | head -3; claude mcp list'
ssh devbox 'systemctl --user is-active devbox-vnc devbox-wm devbox-novnc devbox-panel devbox-chrome devbox-relay devbox-rc'
ssh devbox 'devbox-browser status; devbox-relay test | tail -1; free -h; df -h ~'
ssh devbox 'grep -c ANTHROPIC_API_KEY ~/.bashrc ~/.profile 2>/dev/null; sudo ufw status'

Esperado: cada servicio active (devbox-rc solo después de la Fase 7), servidores MCP chrome y playwright conectados, sin clave de API, ufw permitiendo solo tailscale0 (y 41641/udp). Luego dile al usuario qué está listo, qué le queda por hacer y cómo acceder a cada parte.

Uso diario (informa al usuario)

• Ver un servidor de desarrollo: ejecútalo en 127.0.0.1:<puerto> en el devbox, luego en el ordenador ssh -N -L <puerto>:localhost:<puerto> devbox y abre http://localhost:<puerto>.
• Tarea larga en tmux: claude-task start <nombre> ~/dev/<proyecto> "<aviso>" [--rc] [--mode auto], luego claude-task list | show | send | stop; tmux attach -t ct-<nombre> (Ctrl+b d para salir).
• Pasar una sesión a segundo plano a propósito: claude --resume <id> --fork-session --bg --remote-control "<nombre>" --permission-mode auto "<aviso>".
• Actividad del relay: ssh devbox devbox-relay status, registro en ~/dev/_relay/log.md.
• Actualizar herramientas: PW_MCP_VERSION=<v> INSTALL_GATEHAUL=1 GATEHAUL_VERSION=<tag> bash ~/devbox-setup/20-user-setup.sh.
• Un servidor apagado normalmente sigue facturándose.