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. É iniciado dentro de um diretório de projeto. Lê o seu código, propõe alterações, edita ficheiros e executa comandos, tudo a partir de uma interface de utilizador de terminal (TUI). É licenciado sob a MIT. Liga-se a mais de 75 fornecedores de modelos. Com cerca de 165,000 estrelas no GitHub em meados de 2026, é o agente de programação de código aberto com mais estrelas. Para executar o OpenCode num VPS, instale-o com um utilizador dedicado sem privilégios, coloque a chave da API do modelo num ficheiro privado e inicie-o dentro do tmux. Assim, a sessão continua ativa se a ligação for interrompida. Este guia faz exatamente isso, por esta ordem.

Uma nota sobre os nomes evita confusões. O repositório canónico é anomalyco/opencode, mantido pela equipa Anomaly, anteriormente conhecida como SST. O projeto esteve anteriormente em sst/opencode. Também existe no GitHub um repositório não relacionado chamado opencode-ai/opencode. Confirme 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 um utilizador próprio

O ponto de partida é simples: um agente de programação edita ficheiros e executa comandos. Essa é a função dele e também o risco. O OpenCode executará compilações, testes e os comandos de shell que a tarefa parecer exigir. A avaliação do modelo é boa, mas não é perfeita. A conta usada pelo agente define o limite do que um comando incorreto pode alcançar. 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. Por isso, o utilizador precisa de um shell real e de um diretório pessoal:

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

Mantenha os projetos em que ele deve trabalhar 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 esta conta possui. O princípio é o mesmo de executar serviços com um utilizador sem privilégios. Trabalhe também dentro de um repositório git, porque um repositório transforma qualquer edição incorreta num git revert, em vez de numa perda.

Instalar o OpenCode

A documentação do projeto descreve duas formas de instalação. O script de instalação é a opção mais rápida. Executá-lo como o utilizador opencode mantém tudo dentro do diretório pessoal 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, transfira primeiro o script, leia-o e só depois execute-o. Após a instalação, inicie uma nova shell para aplicar a alteração ao PATH feita pelo instalador. 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 em todo o sistema. Assim, o binário opencode fica disponível no PATH para todos os utilizadores:

sudo npm install -g opencode-ai

Em ambos os casos, a verificação é igual: opencode --version apresenta um número de versão. Um command not found após a instalação pelo script significa que a shell atual ainda não leu o PATH atualizado. Nesse caso, termine a sessão e inicie-a novamente como o utilizador 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.

Aponte-o para um modelo

OpenCode é independente do provedor. Usa 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 mais rápido é o comando /connect dentro da TUI. Esse comando lista os provedores e gere as credenciais. Para 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-4-20250514"
}

Um modelo local funciona através do mesmo ficheiro, porque qualquer servidor compatível com OpenAI pode ser declarado como provedor. Se servir um modelo com Ollama no mesmo VPS, a configuração aponta para a API local. O nome do modelo é o que ollama list apresentar 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" } }
    }
  }
}

Vale a pena adotar desde o primeiro dia um comportamento integrado. OpenCode inclui dois agentes, entre os quais pode alternar com a tecla Tab: Build, o agente predefinido com acesso total, e Plan, que desativa a capacidade de fazer alterações. Inicie uma tarefa nova em Plan. Deixe-o ler o código e propor uma abordagem. Mude para Build apenas depois de concordar com o plano. Num servidor, uma primeira passagem apenas de leitura é uma medida de segurança simples. Claude Code apresenta a mesma decisão como modos de permissão, e a mudança para o modo automático como predefinição merece ser lida se executar ambas as ferramentas. O modo com que uma sessão começa determina quanto um agente não monitorizado pode alterar.

O raio de impacto, sem rodeios

Um agente de programação não é passivo. Por isso, diga 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 está 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 de produção, o agente poderá utilizá-las. Mantenha essas credenciais totalmente fora da conta do agente.

Ao contrário de um agente gateway como o OpenClaw, o OpenCode é um programa de terminal interativo, não um daemon. Não abre nenhuma porta em escuta e não tem nenhum serviço de longa duração. Por isso, não existe nenhuma unidade systemd para criar nem nenhuma porta que tenha de ser bloqueada na firewall para o próprio agente. O isolamento é garantido pela conta de utilizador e pelo diretório do projeto. É por isso que a primeira secção deste guia é a mais importante.

O servidor continua a exigir a manutenção normal, porque um VPS de programação continua a ser um servidor público: SSH apenas com chaves e com o login de root desativado, como em Reforço da segurança do SSH num VPS, uma firewall com política de 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ê quem 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 usa o mesmo método da 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. Alguns minutos de manutenção ocasional custam menos do que depurar um comportamento que uma versão com meses de existência 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 de programação real precisa de muita memória. Dimensione o servidor para o modelo antes de o transferir.

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 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?

É possível controlar o risco se o executar num ambiente limitado. Dê ao OpenCode um utilizador dedicado sem privilégios e sem sudo. Mantenha os projetos em git para que todas as alterações possam ser revertidas. Guarde a API key num ficheiro com o modo 600. Use o agent Plan para uma primeira análise apenas de leitura antes de permitir que o agent Build altere alguma coisa. Assim, o agent só pode danificar aquilo que a própria conta possui. O restante servidor fica 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 pretende usar uma ferramenta com 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.