Como instalar OpenCode em um VPS

O que é o OpenCode e o que você está configurando

O OpenCode é um agente de codificação de IA de código aberto para o terminal. Você o inicia dentro de um diretório de projeto; ele lê seu código, propõe alterações, edita arquivos e executa comandos, tudo através de uma interface de usuário de terminal (TUI). Possui licença MIT, conecta-se a mais de 75 provedores de modelos e, com aproximadamente 165.000 estrelas no GitHub em meados de 2026, é o agente de codificação de código aberto mais estrelado. Para rodar o OpenCode em um VPS, você deve instalá-lo sob um usuário sem privilégios dedicado, colocar sua chave de API do modelo em um arquivo privado e iniciá-lo dentro do tmux para que a sessão permaneça ativa se a conexão cair. Este guia faz exatamente isso, nesta ordem.

Uma nota sobre a nomenclatura evita confusões. O repositório oficial é anomalyco/opencode, mantido pela equipe Anomaly (anteriormente conhecida como SST), e o projeto ficava em sst/opencode. Um repositório antigo e não relacionado chamado opencode-ai/opencode também existe no GitHub; verifique se você está lendo a documentação do projeto correto. O site oficial é opencode.ai.

Por que rodar o OpenCode em um VPS

Uma sessão de um agente de codificação é longa. O OpenCode pode gastar muitos minutos executando um refactor ou uma suíte de testes. Se rodar no seu laptop, fechar a tampa ou perder a conexão Wi-Fi interrompe a sessão no meio da tarefa. Em um VPS dentro do tmux, o agente continua trabalhando após o seu logout, e você pode dar reattach depois para ler o que foi feito. Este é o mesmo padrão de rodar o Claude Code em um VPS com tmux, e é o maior ganho de qualidade de vida ao mover um agente para fora do seu laptop.

A segunda razão é a localização. Um VPS está próximo ao código que você implanta: o repositório, as ferramentas de build, o banco de dados de testes e, frequentemente, o ambiente de staging já residem lá ou próximos a ele. Um agente que edita código e executa testes funciona melhor na máquina onde esses testes realmente rodam. E como o servidor é controlado por você, você pode fornecer um ambiente isolado ao agente propositalmente, como detalhado na próxima seção.

Se você ainda estiver escolhendo uma ferramenta, rodar um agente de IA de codificação em um VPS compara o campo de forma ampla, incluindo Aider e Goose.

Atribua um usuário próprio ao OpenCode

Este é o ponto de partida: um agente de codificação edita arquivos e executa comandos. Essa é a função dele, e também o risco. O OpenCode executará builds, testes e quaisquer comandos de shell que a tarefa exigir; o julgamento do modelo é bom, mas não é perfeito. O nível de acesso do agente é limitado ao que o usuário que ele utiliza pode alcançar. Portanto, não o execute como root e não o execute com o mesmo usuário que administra o servidor.

Diferente de um agente em segundo plano, o OpenCode é interativo, portanto o usuário precisa de um shell real e de um diretório home:

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

Mantenha os projetos em que ele deve trabalhar sob o diretório /home/opencode, clonados por esse usuário. Não conceda privilégios de sudo à conta. Se o agente executar um comando destrutivo, ele só poderá destruir o que este usuário específico possui; o raciocínio é o mesmo de executar serviços como um usuário sem privilégios. Trabalhe também dentro de um repositório git, pois um repositório transforma qualquer edição incorreta em um git revert em vez de uma perda de dados.

Instalar OpenCode

O projeto documenta duas formas de instalação. O script de instalação é o método mais rápido. Executá-lo como usuário opencode mantém todos os arquivos dentro do home desse usuário:

curl -fsSL https://opencode.ai/install | bash

A prática comum de curl | bash se aplica aqui como em qualquer outro lugar: em um servidor importante, baixe o script primeiro, leia-o e depois execute-o. Após a instalação, inicie um novo shell para que a alteração no PATH feita pelo instalador tenha efeito, então verifique se o binário responde:

opencode --version

Se preferir um gerenciador de pacotes e o Node.js já estiver instalado no sistema, o método via npm instala a mesma ferramenta para todo o sistema, o que coloca o binário opencode no PATH de todos os usuários:

sudo npm install -g opencode-ai

Em ambos os casos, a verificação é a mesma: opencode --version imprime um número de versão. Um command not found após a instalação via script significa que o shell atual ainda não leu o PATH atualizado; nesse caso, faça logout e login novamente como usuário opencode.

Coloque a chave da API em um arquivo privado

O OpenCode precisa de uma chave para o provedor de modelo que você utiliza. Como essa chave pode consumir seus créditos, trate-a como uma senha. Crie um arquivo com permissão 600, acessível apenas pelo usuário opencode, e armazene a chave nele em vez de digitá-la diretamente nos comandos, o que a deixaria exposta no histórico do shell:

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

Insira a variável do seu provedor no arquivo, como ANTHROPIC_API_KEY=... ou o equivalente para o seu provedor, pois o OpenCode utiliza as variáveis de ambiente padrão. Carregue o arquivo no seu shell antes de iniciar o agente:

set -a; source ~/opencode.env; set +a

O OpenCode também possui uma alternativa interativa: o comando /connect dentro da TUI guia você na adição de um provedor e salva a credencial em ~/.local/share/opencode/auth.json no home do usuário. Se utilizar este método, verifique se o arquivo está privado com o comando chmod 600 ~/.local/share/opencode/auth.json. Ambos os métodos evitam que a chave apareça nas linhas de comando; escolha um e mantenha a consistência.

Iniciar OpenCode dentro do tmux

O tmux é o que torna a configuração da VPS viável, pois uma sessão do tmux continua rodando quando sua conexão SSH termina. Inicie uma, acesse seu projeto e execute o agente:

tmux new -s opencode
cd ~/my-project
opencode

Você deve ver a TUI aberta com um prompt na parte inferior e o nome do seu projeto na interface. Forneça uma tarefa em linguagem natural e o agente começará a ler arquivos e propor mudanças. Para sair, desvincule com Ctrl-b seguido de d; o agente continuará trabalhando mesmo com seu laptop fechado. Para reconectar mais tarde, use:

tmux attach -t opencode

A sessão, a conversa e qualquer tarefa em execução estarão exatamente onde você as deixou. Isso sobrevive a desconexões, mas não a um reboot do servidor; portanto, após um reboot, inicie uma nova sessão tmux da mesma forma.

Aponte para um modelo

O OpenCode é agnóstico a provedores. Ele utiliza o AI SDK e o catálogo Models.dev para suportar mais de 75 provedores. A mesma ferramenta funciona com Anthropic, OpenAI, Google e dezenas de outros, incluindo servidores locais. O caminho rápido é o comando /connect dentro da TUI, que lista os provedores e gerencia as credenciais. Para uma configuração que possa ser commitada e reproduzida, coloque um opencode.json na raiz do projeto e defina o modelo como provider/model-id:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514"
}

Um modelo local funciona através do mesmo arquivo, pois qualquer servidor compatível com OpenAI pode ser declarado como um provedor. Se você rodar um modelo com Ollama na mesma VPS, a configuração aponta para a API local, e o nome do modelo é o que o ollama list exibir no seu sistema:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": { "your-model-name": { "name": "Local coding model" } }
    }
  }
}

Um hábito integrado vale a pena ser adotado desde o primeiro dia. O OpenCode possui dois agentes que você alterna usando a tecla Tab: Build, o agente padrão com acesso total, e Plan, que desabilita a capacidade de fazer alterações. Inicie uma nova tarefa no modo Plan, deixe que ele leia o código e proponha uma abordagem, e mude para o modo Build apenas quando concordar com o plano. Em um servidor, uma primeira passagem apenas de leitura é uma segurança barata.

O raio de alcance, honestamente

Um agente de codificação não é passivo, portanto defina claramente o que este setup contém e não contém. Ele contém danos a arquivos: o usuário opencode é dono apenas de seu próprio home, portanto edições e exclusões param nesse limite. Ele contém exposição de credenciais: a chave reside em um único arquivo com modo 600, em uma única conta. Ele não contém o que a conta pode fazer legitimamente; se o diretório do projeto contiver credenciais de deploy de produção, o agente poderá usá-las. Mantenha essas credenciais totalmente fora da conta do agente.

Diferente de um agente gateway como o OpenClaw, o OpenCode é um programa de terminal interativo, não um daemon. Ele não abre portas de escuta nem possui um serviço de longa duração; portanto, não há unidade systemd para criar nem porta para configurar no firewall para o agente em si. O isolamento é a conta de usuário e o diretório do projeto, por isso a primeira seção deste guia é a mais importante.

O ambiente ainda exige cuidados padrão, pois um VPS de codificação ainda é um servidor público: SSH apenas por chave com login root desabilitado, conforme SSH hardening on a VPS, firewall com política default-deny e atualizações rotineiras. Além disso, revise o que o agente produz. Leia os diffs antes de realizar o push, da mesma forma que você leria um pull request de um novo colaborador, pois você é o responsável pelo deploy do resultado.

Por fim, mantenha a ferramenta atualizada. O OpenCode lança versões frequentemente, e as atualizações trazem correções essenciais para um programa que executa comandos no seu servidor. A atualização utiliza o mesmo método da instalação: execute o script de instalação como o usuário opencode, ou execute sudo npm update -g opencode-ai se instalou via npm, e então confirme a nova versão com opencode --version. Um minuto de manutenção ocasional é mais barato do que depurar comportamentos que uma build de meses atrás já teria corrigido.

FAQ

O OpenCode pode usar um modelo local em vez de uma API paga?

Sim. O OpenCode trata qualquer servidor compatível com OpenAI como um provider, portanto um modelo servido pelo Ollama no mesmo VPS funciona: declare o provider em opencode.json com o baseURL local e o nome do modelo reportado pelo Ollama. O limitador é o hardware, pois um modelo capaz de realizar tarefas reais de programação exige memória significativa; dimensione o servidor para o modelo antes de baixá-lo.

Como manter o OpenCode rodando após eu fechar meu laptop?

Execute-o dentro do tmux no VPS. Inicie o agent em uma sessão nomeada com tmux new -s opencode, desconecte com Ctrl-b seguido de d, e a sessão continuará rodando no servidor após o encerramento da sua conexão SSH. Reconecte a qualquer momento com tmux attach -t opencode e a conversa e qualquer tarefa em execução ainda estarão lá. Um reboot do servidor encerra a sessão, portanto inicie uma nova após o reboot.

É seguro permitir que o OpenCode execute comandos no meu VPS?

É seguro se você limitar o acesso. Forneça ao OpenCode um usuário dedicado sem privilégios e sem sudo, mantenha seus projetos em git para que cada edição seja reversível, armazene a API key em um arquivo com mode 600, e use o Plan agent para uma primeira análise apenas de leitura antes de permitir que o Build agent altere qualquer coisa. O agent poderá danificar apenas o que pertence à sua própria conta, mantendo o restante do servidor inacessível.

Qual é a diferença entre OpenCode e Claude Code?

O OpenCode é open source (MIT) e agnóstico a provider, conectando-se a mais de 75 provedores de modelos, incluindo locais, através de uma única interface. O Claude Code é o agent de terminal da Anthropic, construído em torno dos modelos da Anthropic. Se você precisa de uma ferramenta para múltiplos providers, ou de uma stack totalmente self-hosted com um modelo local, o OpenCode é a escolha ideal; ambos funcionam bem em um VPS dentro do tmux com a mesma configuração de unprivileged-user.