Como instalar e executar o OpenCode em um VPS

O que é o OpenCode e o que será configurado

O OpenCode é um agente de programação com IA de código aberto, criado para o terminal. Você inicia o programa dentro de um diretório de projeto, e ele lê o código, propõe alterações, edita ficheiros e executa comandos, tudo através de uma interface de terminal (TUI). O programa usa a licença MIT, liga-se a mais de 75 fornecedores de modelos e, com cerca de 219,000 estrelas no GitHub em outubro de 2026, é o agente de programação de código aberto com mais estrelas. Para executar o OpenCode num VPS, instale-o sob um utilizador dedicado sem privilégios, coloque a chave da API do modelo num ficheiro privado e inicie-o dentro do tmux para que a sessão continue ativa quando a ligação cair. Este guia faz exatamente isso, por essa ordem.

Uma nota sobre os nomes evita confusão. O repositório canónico é anomalyco/opencode, mantido pela equipa Anomaly (anteriormente conhecida como SST), e o projeto esteve anteriormente em sst/opencode. Também existe no GitHub um repositório antigo e não relacionado chamado opencode-ai/opencode, agora arquivado. Confirme, portanto, que está a consultar a documentação do projeto correto. O site oficial é opencode.ai.

Por que executar o OpenCode em um VPS

Uma sessão de um agente de programação é longa. O OpenCode pode passar vários minutos a trabalhar numa refatoração ou num conjunto de testes. Se for executado no seu portátil, fechar a tampa ou perder a ligação Wi-Fi interrompe a sessão a meio da tarefa. Num VPS dentro do tmux, o agente continua a trabalhar depois de desligar. Mais tarde, pode voltar a ligar-se à sessão para ler o que ele fez. Este é o mesmo padrão de executar o Claude Code num VPS com tmux e é o maior ganho de qualidade de vida ao transferir um agente do portátil.

A segunda razão é a localização. Um VPS está próximo do código que implementa: o repositório, as ferramentas de compilação, a base de dados de testes e, muitas vezes, o ambiente de staging já estão nesse servidor ou junto dele. Um agente que edita código e executa os testes funciona melhor na máquina onde esses testes são efetivamente executados. Como o servidor está sob o seu controlo, também pode fornecer deliberadamente ao agente um ambiente contido, como descrito na secção seguinte.

Se ainda estiver a escolher uma ferramenta, executar um agente de IA para programação num VPS compara um conjunto mais amplo de opções, incluindo Aider e Goose.

Dê ao OpenCode o seu próprio utilizador

O ponto de partida é simples: um agente de programação edita ficheiros e executa comandos. Essa é a sua função e também o risco. O OpenCode executará compilações, testes e quaisquer comandos da shell necessários para a tarefa, e o critério do modelo é bom, mas não é perfeito. A conta usada pelo agente limita o alcance de um comando malicioso ou incorreto. Por isso, não o execute como root nem como o mesmo utilizador que administra o servidor.

Ao contrário de um agente em segundo plano, o OpenCode é interativo. O seu utilizador precisa de uma shell real e de um diretório inicial:

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

Mantenha os projetos nos quais pretende que ele trabalhe dentro de /home/opencode, clonados por esse utilizador. Não atribua direitos de sudo à conta. Se o agente executar um comando destrutivo, só poderá destruir o que essa conta possuir. O princípio é o mesmo de executar serviços com um utilizador sem privilégios. Trabalhe também dentro de um repositório git e faça commit antes de atribuir uma tarefa ao agente. Assim, uma alteração incorreta ao trabalho confirmado fica a git revert ou git restore de distância, em vez de causar uma perda. As alterações que nunca foram confirmadas não estão protegidas.

Instalar o OpenCode

O projeto documenta várias formas de instalação, e duas delas são adequadas para um servidor. O script de instalação é a opção mais rápida, e executá-lo como o utilizador opencode mantém tudo dentro da home desse utilizador:

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

A prática habitual de curl | bash aplica-se aqui, como em qualquer outro contexto: num servidor importante, descarregue primeiro o script, leia-o e só depois execute-o. Após a instalação, inicie uma nova shell para que a alteração ao PATH feita pelo instalador entre em vigor. Em seguida, confirme que o binário responde:

opencode --version

Se preferir um gestor de pacotes e o Node.js já estiver instalado no servidor, o método com npm instala a mesma ferramenta no prefixo global do npm:

sudo npm install -g opencode-ai

Com um Node.js instalado a nível do sistema, esse prefixo costuma ser /usr/local ou /usr, cujo diretório bin está no PATH de todos os utilizadores. Um gestor de versões ou um prefixo personalizado coloca o binário noutro local. Por isso, execute primeiro npm prefix -g se precisar que opencode seja encontrado pelo utilizador opencode.

Em ambos os casos, a verificação é igual: opencode --version apresenta um número de versão. Um command not found depois da instalação pelo script significa que a shell atual ainda não leu o PATH atualizado. Termine a sessão e volte a iniciar sessão como o utilizador opencode.

Os dois comandos instalam a linha OpenCode 1.x, que continua a disponibilizar versões (1.19.3 em 16 de outubro de 2026), e este guia descreve essa linha. O OpenCode 2 já está disponível como uma instalação separada, através de https://opencode.ai/v2/install ou do pacote npm @opencode/cli, e funciona de outra forma: um servidor em segundo plano partilhado por cada conta de utilizador gere as sessões, as permissões e a execução de ferramentas, e o terminal liga-se a esse servidor. O guia de migração indica que deve remover uma instalação 1.x gerida por pacote antes de instalar a versão 2, porque ambas utilizam o comando opencode.

Coloque a chave da API num ficheiro privado

O OpenCode precisa de uma chave para o fornecedor de modelos que utilizar. Essa chave pode gastar o seu dinheiro, por isso trate-a como uma palavra-passe. Crie um ficheiro que apenas o utilizador opencode possa ler, com o modo 600, e mantenha a chave nesse ficheiro em vez de a escrever em comandos, onde ficaria guardada no histórico da shell:

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

Coloque nesse ficheiro a variável do seu fornecedor, por exemplo ANTHROPIC_API_KEY=... ou o equivalente do seu fornecedor, porque o OpenCode utiliza as variáveis de ambiente padrão dos fornecedores. Carregue o ficheiro na sua shell antes de iniciar o agente:

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

O OpenCode também tem uma alternativa interativa: o comando /connect dentro da TUI orienta-o na adição de um fornecedor e guarda a credencial em ~/.local/share/opencode/auth.json no diretório inicial do utilizador. Se utilizar esse método, confirme que o ficheiro é privado com chmod 600 ~/.local/share/opencode/auth.json. Ambos os métodos mantêm a chave fora das linhas de comando. Escolha um e utilize-o de forma consistente.

Inicie o OpenCode dentro do tmux

O tmux é o que torna a configuração do VPS útil, porque uma sessão do tmux continua em execução quando a ligação SSH termina. Inicie uma sessão, entre no projeto e execute o agente:

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

Deve ver a TUI aberta, com um prompt na parte inferior e o nome do projeto na interface. Dê-lhe uma tarefa em linguagem simples. O agente começa a ler ficheiros e a propor alterações. Quando quiser sair, desassocie-se com Ctrl-b e depois d. O agente continua a trabalhar mesmo com o portátil fechado. Volte a associar-se mais tarde com:

tmux attach -t opencode

A sessão, a conversa e qualquer tarefa em execução permanecem exatamente no ponto onde as deixou. Isto resiste a desligamentos da sua ligação, mas não a um reboot do servidor. Depois de um reboot, inicie uma nova sessão do tmux da mesma forma. Também pode abrir uma segunda janela do tmux e executar outro agente em paralelo. No entanto, as sessões do OpenCode permanecem independentes umas das outras, enquanto as sessões do Claude Code no mesmo servidor podem enviar mensagens entre si, o que oferece uma forma diferente de dividir uma tarefa em duas.

Ligar o OpenCode a um modelo

O OpenCode não depende de um fornecedor específico. Utiliza o AI SDK e o catálogo Models.dev para suportar mais de 75 fornecedores, pelo que a mesma ferramenta funciona com Anthropic, OpenAI, Google e dezenas de outros, incluindo servidores locais. A opção mais rápida é o comando /connect dentro da TUI, que apresenta os fornecedores e gere as credenciais. Para obter uma configuração que possa versionar e reproduzir, 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-5-5"
}

Escolha um modelo que o seu fornecedor ainda disponibilize. A Anthropic retirou claude-sonnet-4-20250514 em 15 de junho de 2026, pelo que as configurações que ainda o indicam falham.

Um modelo local funciona através do mesmo ficheiro, porque qualquer servidor compatível com OpenAI pode ser declarado como fornecedor. Se disponibilizar um modelo com Ollama no mesmo VPS, a configuração aponta para a API local, e o nome do modelo é o que ollama list apresentar no seu servidor:

{
  "$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" } }
    }
  }
}

Vale a pena adotar desde o primeiro dia um comportamento integrado. O OpenCode disponibiliza dois agentes, entre os quais pode alternar com a tecla Tab: Build, o agente predefinido com acesso total, e Plan, um agente restrito para análise que recusa edições de ficheiros fora do seu próprio diretório de plano sem pedir autorização. O Plan não é estritamente apenas de leitura, porque ainda pode executar comandos de shell, e um comando de shell pode alterar ficheiros. Inicie uma nova tarefa no Plan, deixe-o ler o código e propor uma abordagem, e só mude para Build quando concordar com o plano. Se quiser que essa primeira análise seja realmente apenas de leitura, proíba as edições e os comandos de shell do Plan em opencode.json, porque o OpenCode considera deny como bloqueio da ação, enquanto ask apenas pede a sua aprovação:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": { "edit": "deny", "bash": "deny" }
    }
  }
}

Num servidor, uma primeira análise que não pode alterar nada é uma medida de segurança simples. O Claude Code apresenta a mesma decisão como modos de permissões, e vale a pena ler a mudança para o modo automático como predefinição se executar ambas as ferramentas, porque o modo em que uma sessão começa determina quanto um agente sem supervisão pode alterar.

O raio de impacto, sem rodeios

Um agente de programação não é passivo. Por isso, indique claramente o que esta configuração contém e o que não contém. Ela contém danos em ficheiros: o utilizador opencode é proprietário da sua própria home e de mais nada, portanto as edições e eliminações ficam limitadas a esse perímetro. Ela contém exposição de credenciais: a chave fica num único ficheiro com o modo 600, numa única conta. Ela não limita aquilo que a conta pode fazer legitimamente. Se o diretório do projeto contiver credenciais de deploy para produção, o agente pode utilizá-las. Mantenha essas credenciais completamente fora da conta do agente.

Ao contrário de um agente gateway como o OpenClaw, o OpenCode 1.x é um programa de terminal interativo, não um daemon. Por predefinição, não abre nenhuma porta de escuta. Apenas os flags --port, --hostname ou --mdns fazem o TUI escutar. Também não tem um serviço de longa duração. Por isso, não há nenhuma unidade systemd para criar nem nenhuma porta para filtrar para o próprio agente. O OpenCode 2 altera este comportamento com o seu servidor partilhado em segundo plano. Confirme este ponto novamente antes de migrar. O isolamento é feito pela conta de utilizador e pelo diretório do projeto. É por isso que a primeira secção deste guia é a mais importante.

O sistema que o aloja continua a exigir os cuidados habituais, porque um VPS de programação continua a ser um servidor público: SSH apenas com chaves e login de root desativado, como em Proteção do SSH num VPS, uma firewall com bloqueio por predefinição e atualizações regulares. Reveja também o que o agente produz. Leia os diffs antes de os enviar, tal como leria um pull request de um novo colaborador, porque é você que faz o deploy do resultado.

Por fim, mantenha a própria ferramenta atualizada. O OpenCode lança versões com frequência, e as atualizações incluem correções importantes para um programa que executa comandos no seu servidor. A atualização utiliza o mesmo método usado na instalação: execute novamente o script de instalação como o utilizador opencode ou execute sudo npm update -g opencode-ai se tiver instalado através do npm. Depois, confirme a nova versão com opencode --version. Ambos mantêm a versão na linha 1.x. A mudança para o OpenCode 2 é uma migração separada. Um minuto de manutenção ocasional custa menos do que investigar um comportamento que uma versão com vários meses já corrigiu.

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. Por isso, um modelo servido pelo Ollama no mesmo VPS funciona: declare o provider em opencode.json com o baseURL local e o nome do modelo apresentado pelo Ollama. A limitação é o hardware. Um modelo suficientemente bom para trabalho real de programação precisa de muita memória. Dimensione o servidor para o modelo antes de o descarregar.

Como mantenho o OpenCode em execução depois de fechar o portátil?

Execute-o dentro do tmux no VPS. Inicie o agent numa sessão com nome usando tmux new -s opencode. Desanexe a sessão com Ctrl-b e depois d. A sessão continua em execução no servidor depois de a ligação SSH terminar. Pode voltar a ligá-la a qualquer momento com tmux attach -t opencode. A conversa e qualquer tarefa em execução continuam disponíveis. Um reboot do servidor termina a sessão. Depois de um reboot, inicie uma sessão nova.

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

É controlável se o mantiver isolado. Dê ao OpenCode um utilizador dedicado sem privilégios e sem sudo. Mantenha os projetos no git e faça um commit antes de cada tarefa, para poder reverter uma alteração incorreta. Guarde a API key num ficheiro com o modo 600. Use o agent Plan numa primeira análise antes de permitir que o agent Build altere alguma coisa. Se quiser que essa análise seja estritamente só de leitura, defina as edições e os comandos shell como deny para Plan. O agent só poderá danificar o que pertencer à própria conta. O restante servidor ficará inacessível.

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

O OpenCode é open source (MIT) e independente do provider. Liga-se a mais de 75 providers de modelos, incluindo providers locais, através de uma única interface. O Claude Code é o agent de terminal da Anthropic, desenvolvido em torno dos modelos da Anthropic. Se quiser uma única ferramenta para vários providers, ou uma stack totalmente self-hosted com um modelo local, o OpenCode é a opção adequada. Ambos funcionam bem num VPS dentro do tmux com a mesma configuração de utilizador sem privilégios.