camilbenameur/remote-devbox

O que remote-devbox faz?

Você está configurando (ou reparando) um devbox: um servidor Linux onde as sessões do Claude Code são executadas enquanto o app de desktop Claude no computador do usuário é apenas a interface. Trabalhe pelas fases em ordem. Cada fase informa o que você faz, o que apenas o usuário pode fazer e como verificar se funcionou.

<skill> abaixo significa a pasta que contém este arquivo.

O que o usuário obtém

• A aba Code do app de desktop, inalterada, com cada sessão rodando no devbox via SSH: shell, testes, instalações, Python, Node, Chrome. O computador apenas desenha a interface.
• A assinatura do usuário, não créditos de API. O app de desktop passa e atualiza o login da sessão. Nunca defina ANTHROPIC_API_KEY no devbox: a cobrança iria para a API.
• Dois navegadores como servidores MCP: chrome, um Chrome compartilhado logado nas contas do usuário, e playwright, um Chrome isolado em branco por sessão. Uma tela virtual exibe o Chrome compartilhado em qualquer navegador web na rede privada do usuário (noVNC).
• Sessões que continuam com o computador desligado: devbox-relay retoma sessões cortadas do Desktop em segundo plano, e devbox-rc hospeda sessões iniciadas a partir de claude.ai/code ou do aplicativo de telefone.
• O mesmo CLAUDE.md global, skills, memória e hooks de plugins que no computador.

Leia references/how-it-works.md quando precisar da mecânica, e references/troubleshooting.md assim que algo falhar.

Regras básicas para você

• O usuário faz: pagamento e pedido, cada senha e login (provedor, Tailscale, código de dispositivo do GitHub, /login do Claude, os sites no Chrome compartilhado), cliques nas configurações do app de desktop e no console administrativo do Tailscale. Dê a eles o link ou comando exato, um de cada vez, e então aguarde. Nunca digite uma senha, número de cartão ou código de uso único.
• Antes de pedir qualquer coisa, apresente o plano, o preço e o compromisso, e obtenha um sim.
• Os scripts de configuração são idempotentes: quando um falhar, leia o erro, corrija a causa, execute-o novamente.
• No devbox, sudo não requer senha. Ainda assim, peça permissão ao usuário antes de qualquer alteração no sistema que os scripts não façam por conta própria (pacotes, serviços, firewall, sshd, usuários).
• Ao trabalhar no devbox ativo do usuário, nunca pare os serviços devbox-*, edite ~/.claude ou substitua binários em ~/.local/bin sem avisar primeiro: as sessões deles podem estar rodando.

Fase 0: verifique o computador

1. Plataforma. Windows: scripts em <skill>/client/windows/ (Windows PowerShell 5.1 está ok). macOS ou Linux: <skill>/client/unix/.
2. Apenas Windows: cliente OpenSSH 9.4 ou mais recente (ssh -V). O app de desktop exige. Se mais antigo: winget install Microsoft.OpenSSH.Preview.
3. O app de desktop Claude está instalado e logado, e o plano do usuário inclui Claude Code.
4. git config --global user.name e user.email estão definidos (os scripts os copiam para o devbox).
5. Pergunte ao usuário quais partes opcionais ele deseja: gatehaul (executa builds pesados em GitHub Codespaces, -Gatehaul / --gatehaul), o Chrome compartilhado logado (ativo por padrão), cópia de memória.

Fase 1: escolha e peça um servidor

Use references/providers.md. Requisitos: máquina virtual KVM, Ubuntu 24.04, x86_64 preferido (arm64 funciona, mas não é testado de ponta a ponta), pelo menos 8 GB de RAM (16 a 24 GB para várias sessões paralelas mais Chrome), 80 GB de disco e um console web do provedor (é o caminho de resgate se o SSH for bloqueado).

Ajude o usuário a comparar, então abra a página de pedido para eles se você tiver um navegador. O usuário escolhe o plano, paga e confirma. Se o provedor pedir uma chave SSH no momento do pedido, mostre-a primeiro:

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

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

Peça ao usuário o IP público e o usuário inicial (geralmente root; ubuntu na OVH e Oracle).

Fase 2: inicialize o 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

Execute em um terminal onde o usuário possa digitar (o painel de terminal do app de desktop, ou peça a eles para executar). Precisa de três coisas do usuário:

1. Impressão digital da chave do host. O script a mostra e pergunta sim/não. Diga ao usuário para compará-la com a saída do console web do provedor de ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub.
2. Senha inicial, uma vez, para que a chave possa ser autorizada (ignorada se a chave foi fornecida no pedido).
3. Código de dispositivo do GitHub: gh auth login imprime um código e um link.

O que faz: cria a chave ~/.ssh/devbox_ed25519 (sem frase secreta, o app de desktop deve conectar sem solicitação), executa host/10-root-bootstrap.sh (usuário dev com sudo, SSH somente com chave, linger, swap, Node, gh, Chrome, Tailscale, ufw, fail2ban, unattended upgrades, pacotes de tela virtual), adiciona o bloco Host devbox ao ~/.ssh/config, testa, restringe o SSH ao usuário dev, executa host/20-user-setup.sh (uv, CLI do Claude Code, gatehaul opcional, servidores MCP, ferramentas ~/.local/bin, serviços de tela virtual, serviço de relay e hook), então sincroniza a configuração do Claude (Fase 6).

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

Fase 3: rede privada, depois feche o SSH público

1. Usuário: instale Tailscale no computador e faça login (winget install tailscale.tailscale, a Mac App Store ou tailscale.com/download).
2. No devbox: ssh -t devbox sudo tailscale up --hostname=devbox. Ele imprime um link de login: o usuário o abre.
3. Usuário: console administrativo do Tailscale, Machines, devbox, Disable key expiry. Caso contrário, o devbox sai da rede após 180 dias e apenas o console do provedor restará.
4. Em ~/.ssh/config, defina o HostName do bloco devbox para devbox (MagicDNS) ou para o endereço de ssh devbox tailscale ip -4. Verifique ssh devbox true.
5. Feche o SSH público: ssh -t devbox 'bash ~/devbox-setup/30-root-lockdown.sh'. Ele se recusa enquanto uma sessão SSH que não vem através do Tailscale estiver aberta: feche essas primeiro (incluindo sessões do app de desktop abertas no IP público).

Resgate de bloqueio: console web do provedor, depois sudo ufw allow OpenSSH.

Fase 4: conecte o app de desktop

O usuário, no app de desktop: aba Code, menu de ambiente abaixo da caixa de prompt, New environment, SSH (rótulos a partir do final de 2026, podem mudar):

Campo	Valor
SSH host	devbox (retirado de ~/.ssh/config)
SSH key	vazio
Worktree folder	~/worktrees
Folder for a session	~/dev/<projeto>

Na primeira conexão, o app instala seu próprio mecanismo em ~/.claude/remote/ no devbox e mostra a chave do host: mesma impressão digital da Fase 2. As sessões nesse ambiente são executadas no devbox. Não há painel de Navegador em sessões SSH: encaminhe portas (consulte Uso diário).

Fase 5: o Chrome logado

1. ssh devbox devbox-browser login (o Chrome reinicia sem sua porta de depuração, porque o Google frequentemente recusa login em um Chrome que a possui).
2. O usuário abre http://devbox:6080/vnc.html de uma máquina na tailnet. Senha: ssh devbox devbox-browser password. Sem Tailscale: ssh -N -L 6080:localhost:6080 devbox e http://localhost:6080/vnc.html.
3. O usuário faz login nos sites que os agentes devem usar. Avise contra bancos e qualquer coisa onde uma instrução injetada possa custar dinheiro: cada sessão pode controlar este navegador.
4. ssh devbox devbox-browser normal o devolve aos agentes (porta de depuração 9222, apenas local).

Verifique: em uma sessão devbox, peça ao MCP chrome para abrir um site no qual o usuário fez login e confirme que a conta está visível, sem ler conteúdo privado. O ícone da barra de tarefas e o menu de contexto da tela abrem este Chrome; ele também é o navegador padrão do devbox.

Fase 6: espelhe o ambiente Claude local

Objetivo: uma sessão no devbox se comporta como uma no computador.

1. CLAUDE.md global e skills:

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

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

   Ele adiciona <skill>/templates/host-header.md (o que difere no devbox: caminhos, navegadores, tela, continuidade, regra de sudo) ao ~/.claude/CLAUDE.md local, mescla ~/.claude/skills (sem .venv, node_modules, .git), e com -Memory copia a memória automática da pasta de projetos local (-LocalDevDir, padrão ~/Documents/dev) para a memória de ~/dev no devbox. Execute novamente sempre que o CLAUDE.md local ou as skills mudarem. Edite o template de cabeçalho, não a cópia no devbox, que é sobrescrita.
2. Skills que precisam de configuração: para cada skill sincronizada, procure ambientes Python (requirements.txt, pyproject.toml), pacotes Node, binários e caminhos do Windows em SKILL.md. Recrie ambientes no devbox e corrija caminhos. Instale ferramentas do sistema de que precisam (por exemplo, ffmpeg) após perguntar.
3. Plugins: o app de desktop instala os plugins do usuário em sessões SSH, mas seus hooks não são executados lá. Para cada plugin habilitado com hooks/hooks.json, clone sua fonte no devbox no mesmo commit em ~/.claude/hooks-thirdparty/<plugin> e mescle seus hooks no ~/.claude/settings.json do devbox, com ${CLAUDE_PLUGIN_ROOT} substituído por essa pasta e interpretadores corrigidos para Linux (python para python3). Mescle com jq; mantenha o hook devbox-relay guard SessionStart existente. Leia os scripts de hook antes de habilitá-los.
4. Servidores MCP: compare claude mcp list localmente e no devbox. Re-adicione servidores stdio de escopo do usuário que façam sentido no Linux. Conectores do claude.ai seguem a conta: nada a fazer.
5. Projetos: clone em ~/dev/<nome> com gh repo clone. Copie arquivos locais não commitados ou ignorados que importam (arquivos .env apenas com o consentimento do usuário), instale dependências, execute um teste leve. Builds pesados pertencem a Codespaces via gatehaul, se instalado.
6. Migração longa sem o usuário: se houver muito para mover, escreva uma lista de trabalho, depois inicie uma sessão autônoma no devbox com references/setup-agent-prompt.md através de claude-task.

Fase 7: sessões que continuam com o computador desligado

1. Login da CLI no devbox (o relay e o Remote Control o usam): ssh -t devbox claude, depois /login; o usuário abre o link e cola o código; /exit.
2. Relay: já habilitado por 20-user-setup.sh. Verifique ssh devbox devbox-relay test (todos os casos OK) e ssh devbox devbox-relay status.
3. Servidor Remote Control, uma vez manualmente porque pede duas confirmações: ssh -t devbox 'cd ~/dev && claude remote-control', o usuário responde y duas vezes, depois Ctrl+C. Então ssh devbox 'touch ~/.config/devbox/rc-accepted && systemctl --user enable --now devbox-rc'. Em claude.ai/code ou no app de telefone, o ambiente nomeado após a pasta e o host (por exemplo, dev · <nome_do_host>) agora inicia sessões no devbox. Escolha o modo de permissão Auto lá para sessões que devem progredir sozinhas. claude.ai pode pedir ao usuário para fazer login novamente para verificar o dispositivo.
4. Teste real opcional, com o usuário: inicie uma tarefa pequena em uma sessão do Desktop que pare em uma pergunta de permissão, o usuário fecha o app de desktop, espera cerca de 30 minutos, o reabre; o log ~/dev/_relay/log.md mostra o relay, claude agents no devbox mostra relay · <nome>, e a sessão original reaberta diz que foi retransmitida.

Fase 8: verificação final

Execute e relate cada linha:

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: todos os serviços active (devbox-rc apenas após a Fase 7), servidores MCP chrome e playwright conectados, nenhuma chave de API, ufw permitindo apenas tailscale0 (e 41641/udp). Então diga ao usuário o que está pronto, o que eles ainda precisam fazer e como acessar cada parte.

Uso diário (diga ao usuário)

• Ver um servidor de desenvolvimento: execute-o em 127.0.0.1:<porta> no devbox, depois no computador ssh -N -L <porta>:localhost:<porta> devbox e abra http://localhost:<porta>.
• Tarefa longa em tmux: claude-task start <nome> ~/dev/<projeto> "<prompt>" [--rc] [--mode auto], depois claude-task list | show | send | stop; tmux attach -t ct-<nome> (Ctrl+b d para sair).
• Enviar uma sessão para segundo plano intencionalmente: claude --resume <id> --fork-session --bg --remote-control "<nome>" --permission-mode auto "<prompt>".
• Atividade do relay: ssh devbox devbox-relay status, log em ~/dev/_relay/log.md.
• Atualizar ferramentas: PW_MCP_VERSION=<v> INSTALL_GATEHAUL=1 GATEHAUL_VERSION=<tag> bash ~/devbox-setup/20-user-setup.sh.
• Um servidor desligado geralmente ainda é cobrado.