Como Correr o Code Server e o Claude Code num VPS: Um Ambiente de Desenvolvimento de IA Baseado no Navegador

Fecha o portátil, vai a um café e abre um navegador num tablet. O seu editor VS Code completo está ali mesmo, com um terminal a correr o Claude Code ao lado, num servidor que controla. Sem cadeia de ferramentas local, sem sincronização, sem esperar que um portátil acorde.

Essa combinação é o que este guia constrói: Code Server (VS Code no navegador) e Claude Code (a CLI de programação por IA da Anthropic) num único Linux VPS. Muitos tutoriais cobrem um ou o outro, mas correr ambos na mesma máquina dá-lhe um IDE assistido por IA ao estilo do Codespaces, acessível a partir de qualquer dispositivo, pelo custo de um VPS e com acesso root completo. Um esclarecimento antes de começar: Servidor de Código aqui refere-se ao projeto de código aberto da Coder (coder/code-server), não ao VS Code Server da Microsoft nem à plataforma empresarial separada da Coder. Partilham um nome e confundem-se constantemente, por isso vale a pena fixá-lo agora.

No final, terá um ambiente de desenvolvimento assistido por IA, baseado no navegador e funcional, a correr num VPS que possui, protegido com HTTPS e configurado para sobreviver a uma ligação perdida.

A versão curta

• A pilha: O Code Server dá-lhe o VS Code num separador do navegador; o Claude Code acrescenta o assistente de programação por IA da Anthropic no mesmo servidor. Alcança tudo a partir de qualquer dispositivo com um navegador.
• O verdadeiro limite mínimo de RAM é 4 GB, e o Claude Code é a razão. O Code Server sozinho corre em 1 GB, mas o Claude Code exige 4 GB+, por isso a pilha combinada precisa de pelo menos 4 GB de RAM, 2 vCPU e 120 GB de armazenamento. Preveja 8 GB se quiser conforto.
• A ordem de instalação importa menos do que o passo de autenticação. Os instaladores nativos de ambas as ferramentas são de uma linha cada. Autenticar o Claude Code num servidor sem navegador é a parte em que a maioria das configurações fica presa. Copia um URL de início de sessão para o seu navegador local, ou usa um token ou uma chave de API.
• O Claude Code não é gratuito. Exige um plano Claude pago (Pro, Max, Team ou Enterprise) ou uma chave de API da Anthropic. O plano gratuito Claude.ai não o inclui.

O Que Vai Precisar

Antes de começar, certifique-se de que tem o seguinte em ordem. Cada um destes é referenciado por um passo posterior, por isso vale a pena confirmá-los agora em vez de descobrir uma falha a meio do processo.

• Um Linux VPS que cumpra o limite mínimo de dimensionamento abaixo. O Ubuntu 22.04 LTS é usado ao longo deste guia; os comandos são quase idênticos no Debian e noutras versões do Ubuntu.
• O tamanho certo: pelo menos 4 GB RAM, 2 vCPU, and 120 GB of NVMe storage. O mínimo de 4 GB vem do Claude Code, não do Code Server (a secção de dimensionamento explica porquê).
• Um nome de domínio (opcional mas recomendado) se quiser HTTPS com um certificado real. Pode correr o Code Server num endereço IP, mas um domínio torna o passo do proxy reverso mais limpo.
• Um plano Claude pago ou uma chave de API da Anthropic. O Claude Code exige uma subscrição Pro, Max, Team ou Enterprise, ou uma conta Claude Console (API). O plano gratuito Claude.ai não inclui acesso ao Claude Code. Confirme qual tem antes do passo de instalação, porque isso decide como se autentica.
• Acesso SSH básico ao servidor com um utilizador com capacidade sudo.

Escolher o Seu VPS

A primeira decisão é o tamanho, e o conselho comum que vai encontrar para o Code Server está errado para esta pilha. A maioria dos guias do Code Server cita um mínimo de 1 GB de RAM, o que é exato para o Code Server por si só. Assim que adiciona o Claude Code, esse limite mínimo desloca-se.

A lista de requisitos de sistema do próprio Claude Code 4 GB+ RAM (segundo os documentos de configuração do Claude Code). O Code Server precisa de cerca de 1 GB. Correr ambos, mais as extensões do seu editor, um projeto ativo, e a memória que uma sessão agêntica do Claude Code usa enquanto trabalha, significa que o limite mínimo realista da pilha combinada é:

A coluna recomendada é onde vai querer estar se instalar várias extensões, mantiver projetos grandes com diretórios node_modules avultados no servidor, ou correr o Claude Code em tarefas agênticas que tocam muitos ficheiros de uma só vez. O mínimo faz correr a pilha; a especificação recomendada mantém-na confortável.

Dois pontos que lhe poupam dinheiro e confusão:

Não é necessária GPU. O Claude Code envia o seu trabalho para a API da Anthropic, por isso toda a inferência do modelo acontece remotamente. Não está a correr um modelo no seu servidor. Um VPS de CPU padrão é a escolha correta, e pagar por uma instância com GPU aqui não lhe traz nada.

Escolha um datacenter perto de si. Um IDE de navegador é sensível à latência de rede de uma forma que uma aplicação web normal não é, porque cada tecla premida e cada edição de ficheiro viajam por uma ligação WebSocket até ao servidor e de volta. Quanto mais perto o servidor estiver de onde está fisicamente sentado, mais o editor parece local. Se programa a partir de uma região a maior parte do tempo, escolha a localização mais próxima dela.

Conclusão-chave da secção: Dimensione para o Claude Code, não para o Code Server. O requisito de 4 GB do Claude Code define o seu limite mínimo. O valor de 1 GB do Code Server não se aplica assim que ambas as ferramentas partilham a máquina.

Instalar o Code Server

Este passo produz um editor VS Code funcional, acessível no seu navegador na porta 8080. O Code Server disponibiliza um script de instalação que trata da configuração dos pacotes por si.

Corra o instalador oficial:

curl -fsSL https://code-server.dev/install.sh | sh

O script deteta a sua distribuição e instala o Code Server como um serviço systemd. Quando terminar, inicie o serviço e ative-o para que volte após um reinício:

sudo systemctl enable --now code-server@$USER

O Code Server liga-se a 127.0.0.1:8080 por predefinição e gera uma palavra-passe aleatória no primeiro arranque. Precisa dessa palavra-passe para iniciar sessão. Ela vive no ficheiro de configuração gerado:

cat ~/.config/code-server/config.yaml

O resultado esperado tem este aspeto:

bind-addr: 127.0.0.1:8080
auth: password
password: 5f3a9c1b2e8d7460a1f2c3b4
cert: false

Copie o valor da palavra-passe. Vai introduzi-lo no ecrã de início de sessão do Code Server assim que o servidor estiver acessível no seu navegador, o que, neste momento, não está, porque está ligado a 127.0.0.1 (apenas localhost). Isso é intencional: expor o Code Server em segurança é um passo posterior, feito através de um proxy reverso e não abrindo a porta 8080 à internet.

Nota: O Code Server limita a taxa de tentativas de início de sessão. Se falhar a palavra-passe algumas vezes e ficar brevemente bloqueado, isso é o limitador de taxa, não uma instalação estragada. Espere um minuto e tente de novo.

Se preferir saltar totalmente a instalação manual, o marketplace da Cloudzy tem uma implementação de Code Server com um clique que provisiona o servidor com o Code Server já instalado. É o caminho mais rápido se está a escolher um host agora; os passos manuais acima funcionam em qualquer VPS Ubuntu, por isso o resto deste guia mantém-se agnóstico quanto ao fornecedor.

Instalar o Claude Code

Este passo acrescenta o assistente de programação por IA ao mesmo servidor. O Claude Code instala-se como um único binário e corre a partir do terminal: o mesmo terminal que mais tarde vai abrir dentro do IDE do navegador.

Use o instalador nativo, que é o método recomendado pela Anthropic:

curl -fsSL https://claude.ai/install.sh | bash

Confirme que foi instalado:

claude --version

Se já corre Node.js 18 ou posterior e prefere gerir a ferramenta através do npm, esse caminho existe como alternativa:

npm install -g @anthropic-ai/claude-code

The native installer is the primary path in Anthropic's current documentation, and it auto-updates in the background. The npm package can also auto-update, but that depends on the npm global directory being writable; if it isn't, Claude Code shows a one-time notice instead of updating silently. Choose the native installer unless you have a specific reason to prefer npm.

O Claude Code suporta Ubuntu 20.04+, Debian 10+ e Alpine 3.19+, por isso o VPS que dimensionou acima já se qualifica. Exige um plano Claude pago ou uma chave de API da Anthropic, que confirmou nos pré-requisitos, e o plano gratuito Claude.ai não o inclui.

Para a referência de instalação autoritativa, a documentação atual encontra-se em code.claude.com. (Links mais antigos para docs.anthropic.com redirecionam para lá; use diretamente o endereço code.claude.com.)

Autenticar o Claude Code num Servidor Sem Interface Gráfica

Execute claude pela primeira vez e ele tenta abrir uma janela do navegador para completar o início de sessão. Num servidor remoto acedido por SSH, não há navegador para abrir. Este é o único passo que trava a maioria das configurações de servidor, e tem três soluções limpas.

O método direto: copiar o URL de início de sessão para o seu navegador local. Quando você executa claude no servidor, ele imprime um URL de início de sessão (prima c para copiá-lo para a área de transferência se não abrir automaticamente). Abra esse URL no navegador da sua própria máquina, inicie sessão e complete a autorização. Se o navegador mostrar um código de início de sessão em vez de redirecionar, cole esse código de volta no terminal na indicação Paste code here if prompted. Isto é normal em sessões SSH e contentores. Este é o caminho interativo padrão para uma subscrição Pro ou Max.

O método persistente: um token de vida longa. Se não quiser voltar a autenticar o servidor periodicamente, gere um token OAuth de um ano:

claude setup-token

O comando conduz o utilizador pela autorização OAuth uma vez e imprime um token. Não guarda o token por si, por isso copie-o e defina-o como uma variável de ambiente para que o Claude Code o apanhe em cada execução:

export CLAUDE_CODE_OAUTH_TOKEN=your-token-here

Adicione essa linha de export ao perfil da sua shell (por exemplo ~/.bashrc) para que persista entre sessões. Este token autentica-se contra a sua subscrição e exige um plano Pro, Max, Team ou Enterprise.

O método da chave de API. Se usa uma conta Claude Console (API) em vez de uma subscrição, defina antes a sua chave de API:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Uma nota de exatidão para não ser apanhado de surpresa numa fatura: uma chave de API é faturada por token através do Claude Console, que é um caminho de faturação separado de uma subscrição Pro ou Max. Se tiver ambos, uma subscrição e ANTHROPIC_API_KEY definida, a chave de API tem precedência assim que for aprovada. Por isso, se pretende usar a sua subscrição, não deixe uma chave de API perdida no seu ambiente.

Conclusão-chave da secção: Três vias para autenticar numa máquina sem interface gráfica: copiar o URL de início de sessão para o seu navegador local, correr claude setup-token para obter um token de subscrição de vida longa, ou definir ANTHROPIC_API_KEY para faturação direta pela API.

Expor o Code Server em Segurança com HTTPS

Neste momento o Code Server está ligado ao localhost e serve HTTP simples. Não vai querer abrir a porta 8080 à internet e iniciar sessão sobre uma ligação não encriptada, porque qualquer pessoa no caminho da rede poderia ler a sua sessão. A solução padrão é um proxy reverso que termina o HTTPS à frente do Code Server.

Há uma restrição rígida que molda este passo: O Code Server depende de WebSockets (segundo os requisitos da Coder). O editor usa uma ligação WebSocket persistente para a sua comunicação em tempo real com o servidor, por isso o seu proxy reverso tem de encaminhar corretamente os upgrades de WebSocket. É por isso que a escolha do proxy importa.

Use o Caddy ou o Nginx. Ambos lidam com o proxy de WebSocket de forma fiável, e ambos estão disponíveis como aplicações de um clique no marketplace da Cloudzy se quiser saltar a instalação manual. O Caddy é o caminho mais curto porque obtém e renova um certificado Let's Encrypt automaticamente. Um Caddyfile mínimo para o Code Server é:

# /etc/caddy/Caddyfile
code.example.com {
    reverse_proxy 127.0.0.1:8080
}

Essa é a configuração inteira. O Caddy deteta o upgrade de WebSocket e encaminha-o sem diretivas adicionais, e provisiona HTTPS para code.example.com por conta própria. Recarregue o Caddy com sudo systemctl reload caddy e navegue para https://code.example.com, e alcança o ecrã de início de sessão do Code Server sobre uma ligação encriptada.

Se preferir o Nginx, a configuração é mais longa porque define os cabeçalhos de upgrade de WebSocket explicitamente e obtém o certificado separadamente com o Certbot:

# /etc/nginx/sites-available/code-server
server {
    listen 80;
    listen [::]:80;
    server_name code.example.com;
    location / {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection upgrade;
        proxy_set_header Accept-Encoding gzip;
    }
}

Nota: O Nginx e o Caddy são os dois proxies que a documentação oficial da Coder documenta, e ambos são as escolhas fiáveis aqui. O Apache também consegue fazer proxy do Code Server, mas o seu encaminhamento de WebSocket exige configuração de módulos adicional (proxy_wstunnel mais regras de reescrita) que a documentação oficial não cobre, e as configurações que falham esses módulos tendem a acabar a depurar ligações de editor perdidas. Se já corre o Apache para outros sites, o caminho mais simples é pôr o Code Server atrás do Nginx ou do Caddy num vhost separado, em vez de configurar o Apache para lhe fazer proxy.

Manter as Suas Sessões Vivas

Duas coisas diferentes correm neste servidor, e comportam-se de forma diferente quando a sua ligação cai. Vale a pena saber qual é qual antes de perder uma hora de uma execução agêntica do Claude Code por causa de uma tampa de portátil fechada.

O próprio Code Server sobrevive às desconexões porque o instalou como um serviço systemd. Fechar o separador do navegador ou perder o SSH não para o serviço Code Server. Em reconexões normais, regressa à mesma sessão do IDE no navegador, embora desconexões muito longas possam exigir um recarregamento da janela, consoante o comportamento de reconexão do Code Server.

O Claude Code é diferente. Quando corre claude num terminal interativo por SSH, ele fica atado a essa sessão de terminal. Feche o separador do navegador que contém esse terminal, ou perca a ligação SSH, e o processo morre com ele, a meio da tarefa se estava a trabalhar. A solução é correr o Claude Code dentro de um multiplexador de terminal para que a sessão se separe da sua ligação e continue a correr.

O tmux é a ferramenta padrão para isto. Se nunca o usou antes, três comandos cobrem o que precisa:

# Start a new named session
tmux new -s claude

# Run claude inside it as normal, then detach without stopping it:
# press Ctrl-b, then d

# Reattach later, from any new SSH session:
tmux attach -t claude

Iniciar claude dentro da sessão tmux, separe-se com Ctrl-b e depois d, e a execução agêntica continua no servidor. Volte a ligar-se com tmux attach -t claude sempre que se reconectar (a partir de um dispositivo diferente, se quiser) e está de volta à mesma sessão ativa.

Nota: o screen funciona da mesma forma se já o usa (screen -S claude para iniciar, Ctrl-a e depois d para separar, screen -r claude para voltar a ligar). Qualquer das ferramentas resolve o mesmo problema; escolha a que conhece.

Usar o Claude Code Dentro do IDE do Navegador

Assim que ambas as ferramentas estiverem na máquina, há duas formas de alcançar o Claude Code a partir do IDE do navegador: o terminal integrado e a extensão do VS Code. Uma delas é fiável hoje; a outra precisa de ser testada antes de depender dela.

O caminho do terminal funciona, por construção. Abra o Code Server no seu navegador, abra o seu terminal integrado (Terminal > New Terminal, ou Ctrl+`), e corra:

claude

Tem agora a CLI completa do Claude Code a correr dentro do IDE do navegador, no mesmo diretório do projeto que tem aberto. Este é o caminho de confiança: o terminal é uma shell real no servidor, e o Claude Code é uma CLI instalada nesse servidor, por isso corre. Emparelhe-o com o passo do tmux acima e a sessão sobrevive a uma ligação perdida.

O caminho da extensão do VS Code é possível, mas o caminho do terminal continua a ser a base mais segura para esta configuração. A Anthropic publica uma extensão Claude Code para VS Code e a sua documentação atual diz que pode ser instalada a partir do Open VSX, o que importa porque o Code Server usa o Open VSX em vez do VS Code Marketplace da Microsoft. Tente procurar por "Claude Code" na vista de Extensions do Code Server, ou instale a extensão Anthropic.claude-code do Open VSX se ela aparecer na sua instância. Se a extensão não instalar de forma limpa, ou se a integração no IDE se comportar de forma diferente da do VS Code de ambiente de trabalho, recorra ao terminal integrado. A CLI funciona em qualquer terminal, e para esta configuração de VPS, esse é o caminho fiável.

Implemente o Seu Próprio IDE de IA Baseado no Navegador

Tem agora o quadro completo: um editor VS Code acessível pelo navegador com o Claude Code ao lado, protegido com HTTPS e configurado para sobreviver a uma ligação perdida, num VPS que controla.

A única parte disto que é puro trabalho de configuração é o início: provisionar um servidor e instalar o Code Server antes de poder fazer algo interessante. Se quiser saltar isso, oferecemos uma implementação de Code Server com um clique no marketplace da Cloudzy que provisiona o VPS com o Code Server já a correr, para que aterre diretamente no ecrã de início de sessão e vá diretamente instalar o Claude Code e autenticar. Para uso diário regular, ponha ainda assim a instância atrás de HTTPS com o Caddy ou o Nginx como mostrado acima, em vez de tratar o início de sessão http://<server-ip>:8080 em bruto como o caminho final de acesso de produção.

O mesmo Linux VPS aloja a pilha inteira (editor, CLI de IA e proxy reverso) com o acesso root que esta configuração precisa. A partir daí, os passos acima são tudo o que se interpõe entre si e programar com IA a partir de qualquer navegador.

Se ainda está a ponderar qual CLI de programação por IA adotar antes de construir isto, as nossas comparações de OpenCode versus Claude Code e o mais amplo confronto de CLIs de programação agêntica cobrem os prós e contras.

Perguntas frequentes

De Que Especificações de VPS Preciso para o Code Server e o Claude Code?

Precisa de pelo menos 4 GB de RAM, 2 vCPU e 120 GB de armazenamento para a pilha combinada. O mínimo de 4 GB é impulsionado pelo Claude Code, não pelo Code Server (o Code Server sozinho corre em cerca de 1 GB). Para um uso confortável com extensões e projetos maiores, 8 GB de RAM e 4 vCPU é o tamanho recomendado.

O Claude Code É Gratuito?

Não. O Claude Code exige um plano Claude pago (Pro, Max, Team ou Enterprise) ou uma chave de API da Anthropic através do Claude Console. O plano gratuito Claude.ai não inclui acesso ao Claude Code.

Como Autentico o Claude Code num Servidor Sem Navegador?

Corra claude e copie o URL de início de sessão que ele imprime para o navegador da sua máquina local, de modo a completar o início de sessão, colando o código de volta no terminal se for solicitado. Para um servidor persistente, corra claude setup-token para gerar um token OAuth de um ano e defina-o como CLAUDE_CODE_OAUTH_TOKEN, ou defina ANTHROPIC_API_KEY para se autenticar com uma chave de API do Claude Console.

A Extensão Claude Code para VS Code Funciona Dentro do Code Server?

A CLI do Claude Code corre totalmente dentro do terminal integrado do Code Server, que é a forma mais fiável de a usar nesta configuração de IDE de navegador. A extensão do VS Code também vale a pena experimentar, porque a Anthropic diz que pode ser instalada a partir do Open VSX, e o Code Server usa o Open VSX em vez do VS Code Marketplace da Microsoft. Se a extensão não instalar de forma limpa ou se comportar de forma diferente na sua instância, use antes o caminho do terminal integrado.

Posso Usar Isto a Partir de um iPad ou Telemóvel?

Sim. O Code Server é baseado no navegador, por isso qualquer dispositivo com um navegador moderno (incluindo um iPad ou telemóvel) alcança o IDE completo. Esse acesso independente do dispositivo é a principal vantagem de um IDE de navegador sobre o VS Code Remote SSH, que precisa de uma instalação local do VS Code para se ligar.