Como rodar o Gemini CLI em um VPS sem interface gráfica
Aprenda a rodar o Gemini CLI em um VPS sem interface gráfica: use Node atual, instale com npm sem sudo, autentique por API key e mantenha tarefas no tmux após quedas do SSH.
O que você vai criar
Um Gemini CLI sempre ativo num servidor que controla, acessível por SSH, a executar tarefas longas de agentes que continuam a trabalhar depois de fechar o portátil. A instalação resume-se a três comandos. O trabalho está no que pressupõe um desktop: a CLI da Google tenta abrir um navegador para iniciar sessão, mas o servidor não tem nenhum. Por isso, a maior parte deste guia aborda o procedimento sem interface gráfica, uma versão atual do Node que a distribuição não fornece, uma instalação global do npm que não requer root, a autenticação sem navegador com uma chave de API mantida fora do histórico da shell e o tmux, para que uma sessão SSH interrompida não termine uma tarefa em execução.
O Gemini CLI é um programa Node de código aberto (Apache-2.0) (@google/gemini-cli) que comunica com os modelos Gemini da Google e pode ler e escrever ficheiros, executar comandos da shell e utilizar ferramentas no diretório de trabalho. Num VPS, é um agente pequeno e sempre disponível que pode deixar a trabalhar. Por isso, a conta usada para o executar e as credenciais armazenadas no servidor são mais importantes do que qualquer definição isolada deste guia.
Pré-requisitos e as armadilhas importantes
- Um VPS KVM Ubuntu 24.04 novo com root ou sudo. O guia de instalação do Google recomenda 4 GB ou mais de RAM para uso ocasional e 16 GB ou mais para sessões longas e bases de código grandes.
- Node.js 20 ou mais recente. Este é o único requisito rígido de versão, e o pacote da distribuição é anterior a ele; consulte a próxima seção. O Node 20 chegou ao fim da vida útil em April 30, 2026, portanto instale o 26.
- HTTPS de saída (porta 443) para as APIs do Google. Nenhuma porta de entrada é necessária; este é um cliente, não um servidor, portanto você não precisa abrir uma brecha no firewall.
- Uma forma de autenticação que não exija um navegador no servidor: uma Gemini API key do Google AI Studio, com uso gratuito ou pago, ou o login do Google, que, em um servidor headless, exige colar um código de volta no terminal. O uso da API key é a opção adequada para scripts e execuções não supervisionadas.
- Docker ou Podman, somente se você quiser o isolamento do
--sandbox. Opcional, abordado perto do final.
A armadilha que pega todo mundo atualmente é a conta, não o navegador. O Google anunciou em May 19, 2026 que, a partir de June 18, 2026, o Gemini CLI deixaria de atender solicitações de assinantes do Google AI Pro e Ultra e de usuários gratuitos do Gemini Code Assist para indivíduos, direcionando esses usuários para seu substituto, o Antigravity CLI (agy). O Gemini CLI continua funcionando com Gemini API keys, incluindo o nível gratuito separado, com Gemini Enterprise Agent Platform API keys e com uma licença Gemini Code Assist Standard ou Enterprise da organização. Decida o método de autenticação antes de começar.
Node: o pacote da distribuição é antigo demais
O Ubuntu 24.04 disponibiliza o Node 18.19.1 nos próprios repositórios. O package.json do Gemini CLI declara engines: { node: ">=20" } em package.json, e o npm não interrompe a instalação automaticamente quando há uma incompatibilidade. Ele instala mesmo assim e exibe um aviso que informa a diferença:
npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE package: '@google/gemini-cli@0.50.0',
npm WARN EBADENGINE required: { node: '>=20' },
npm WARN EBADENGINE current: { node: 'v18.19.1', npm: '9.2.0' }
npm WARN EBADENGINE }Se você ignorar esse aviso, o CLI será executado em um runtime não suportado e poderá apresentar comportamento incorreto ou falhar assim que chegar a uma API do Node 20+ que deveria existir. O Node 18 também chegou ao fim da vida útil em abril de 2025, portanto não é uma opção viável de qualquer forma. Instale uma versão LTS atual antes de instalar o CLI. As duas opções adequadas são NodeSource (um repositório apt assinado e disponível para todo o sistema) ou nvm (um gerenciador de versões por usuário). Escolha uma.
NodeSource, se você quiser disponibilizar o Node para todos os usuários do sistema:
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash -
sudo apt-get install -y nodejs
node --versionnode --version deve imprimir v20.x ou superior para atender ao requisito do CLI, mas o Node 20 está no fim da vida útil desde 30 de abril de 2026. Portanto, use v26.x, a LTS ativa atual. O Node 26 entrou em LTS em 28 de outubro de 2026, com a versão 26.13.0. Consulte a página da NodeSource para obter o script de configuração atual. O setup_26.x na URL é a parte que deve ser alterada quando uma nova versão LTS for lançada.
nvm, se você preferir manter o Node no diretório pessoal de um único usuário e nunca executar operações nele com sudo:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node --versionO v0.40.1 nessa URL fixa a versão do instalador. Consulte o README do nvm para verificar a versão mais recente e substitua a versão antes de executar o comando. O nvm tem uma vantagem importante neste caso: instala o Node e os pacotes globais em ~/.nvm. Assim, o problema de permissões da instalação global descrito na próxima seção simplesmente não ocorre. Se você escolher o nvm, poderá ignorar a etapa de configuração do prefixo do npm.
Instalar a CLI sem sudo npm -g
O comando tentador é sudo npm install -g @google/gemini-cli. Não o utilize. Um prefixo global pertencente a root provoca erros de permissões em todas as instalações seguintes e deixa ficheiros pertencentes a root na cache do npm, causando problemas meses mais tarde. Execute um npm install -g simples, sem sudo, contra um Node do sistema e obterá o outro erro:
npm error code EACCES
npm error syscall mkdir
npm error path /usr/lib/node_modules/@google
npm error errno -13
npm error Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/@google'Isto significa que o npm está a tentar escrever em /usr/lib, onde o seu utilizador não tem permissões. A solução não é usar sudo. Defina o prefixo global do npm como o seu diretório pessoal, para que as instalações globais sejam feitas num local que lhe pertence:
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @google/gemini-cli
gemini --version~/.bashrc mantém a exportação disponível para shells Bash interativos. O tmux inicia um shell de login por predefinição; no Ubuntu, o ~/.profile predefinido também carrega ~/.bashrc. Se personalizou os seus ficheiros de login, confirme que continuam a carregá-lo. gemini --version imprimir um número de versão é o teste completo. Se obtiver gemini: command not found, a exportação de PATH não foi aplicada; consulte os modos de falha. Com nvm, ignore totalmente as linhas do prefixo: o nvm já instala os pacotes globais no seu diretório pessoal.
Se executou sudo npm anteriormente e agora vê Your cache folder contains root-owned files, corrija-o uma vez com sudo chown -R $(id -u):$(id -g) ~/.npm.
O problema de autenticação sem interface e como contorná-lo
Execute gemini interativamente pela primeira vez. Ele oferecerá a opção de fazer login com sua conta do Google. Em um desktop, isso abre uma aba do navegador. Em um VPS Linux sem interface, a CLI verifica primeiro se há uma tela disponível. Quando nenhum dos itens DISPLAY, WAYLAND_DISPLAY ou MIR_SOCKET está definido, ela não tenta abrir um navegador. Ela exibe um link de login e espera que você cole um código:
Please visit the following URL to authorize the application:
https://accounts.google.com/o/oauth2/v2/auth?...
Enter the authorization code:Esse fluxo funciona por SSH comum e exige um navegador para o login inicial. As credenciais bem-sucedidas são armazenadas localmente para as sessões futuras. Desde June 18, 2026, ele só permite o acesso se sua conta do Google estiver entre as contas que o Gemini CLI ainda atende.
Há duas formas diretas de prosseguir.
A primeira é usar uma chave de API, que é a opção padrão correta para um servidor. Crie uma chave no Google AI Studio (aistudio.google.com). O uso de chave de API tem um nível gratuito separado, portanto não é necessário configurar cobrança para começar. Passe a chave para a CLI usando GEMINI_API_KEY. Em seguida, execute gemini e selecione Gemini API Key no seletor de autenticação. Definir apenas a variável não substitui uma escolha de autenticação já armazenada. Agora, sobre manter a chave fora do histórico e de arquivos legíveis por todos: não digite export GEMINI_API_KEY=AIza... no prompt. Ela será gravada em ~/.bash_history em texto claro. Também não a coloque em um arquivo que outras pessoas possam ler. Leia a chave em um prompt oculto e depois grave-a em um arquivo com modo 600 que o shell carrega na inicialização:
umask 077
read -rsp 'Gemini API key: ' GEMINI_API_KEY
printf '\n'
printf 'export GEMINI_API_KEY=%s\n' "$GEMINI_API_KEY" > ~/.gemini_env
chmod 600 ~/.gemini_env
echo '[ -f ~/.gemini_env ] && . ~/.gemini_env' >> ~/.bashrc
source ~/.bashrcchmod 600 significa que somente seu usuário pode ler o arquivo. Confirme que a chave chegou ao ambiente com printenv GEMINI_API_KEY. Se esse comando não imprimir nada, a variável está ausente, embora a CLI também possa usar uma chave armazenada. Ela também lê um arquivo .env em ~/.gemini/, se você preferir esse formato. A mesma regra se aplica: chmod 600 ~/.gemini/.env.
A segunda forma é usar o próprio login do Google. Em um servidor sem interface, isso não exige túnel nem porta aberta. Desde June 18, 2026, essa opção é útil principalmente para uma licença organizacional do Gemini Code Assist Standard ou Enterprise. Defina GOOGLE_CLOUD_PROJECT também. O Gemini Code Assist gratuito para pessoas físicas e o acesso por assinatura do Google AI Pro ou Ultra não são mais atendidos. Inicie a CLI em uma sessão SSH comum e selecione Sign in with Google:
geminiCopie a URL exibida para o navegador do seu laptop e aprove o acesso. O Google redirecionará para https://codeassist.google.com/authcode, que exibirá um código de autorização. Cole o código no prompt Enter the authorization code: do VPS para concluir o login. Nada no servidor espera um callback. Portanto, não há porta para fixar nem ssh -L para configurar. OAUTH_CALLBACK_PORT só é relevante para o fluxo de loopback usado pela CLI quando ela encontra uma tela disponível. Se você se conectar com encaminhamento X11 (ssh -X), DISPLAY será definido e a CLI usará esse fluxo de loopback, com um redirecionamento para http://127.0.0.1:PORT/oauth2callback no servidor. Execute NO_BROWSER=true gemini para forçar o fluxo de colar um código. O login inicial exige que você esteja diante de um navegador, mas as credenciais armazenadas também funcionam em execuções de scripts sem interface. Para qualquer processo que permaneça em execução, use a chave de API.
Para usar Vertex AI ou um projeto do Google Cloud em vez do AI Studio, defina GOOGLE_API_KEY e selecione Vertex AI na CLI. Como alternativa, defina GOOGLE_CLOUD_PROJECT para uma licença do Code Assist. A disciplina com variáveis de ambiente e o arquivo com modo 600 continua sendo a mesma.
Execute dentro do tmux para que uma sessão SSH interrompida não encerre o processo
Um processo gemini iniciado diretamente a partir do seu shell SSH é filho desse shell. Se você perder a conexão, fechar o laptop, perder o Wi-Fi ou atingir um timeout de inatividade, sshd encerra o pseudo-terminal, o shell recebe SIGHUP e, por sua vez, encerra a CLI. Uma tarefa que esteja editando arquivos há dez minutos é encerrada junto, e, ao reconectar, não há nenhum processo para recuperar.
O tmux resolve isso assumindo o controle do shell, em vez de sshd controlá-lo. Este é o mesmo padrão de executar um agente de programação de IA em uma VPS remota dentro do tmux e funciona da mesma forma aqui:
sudo apt install -y tmux
tmux new -A -s gemini
# inside the session:
gemini
# detach with Ctrl-b then d, the task keeps running
# reconnect later from any machine:
tmux attach -t geminitmux new -A -s gemini conecta a uma sessão chamada gemini se ela existir e a cria caso não exista. Por isso, é o único comando que você precisa executar logo depois de cada login. O shell interno pertence ao servidor tmux desconectado, não à sua sessão SSH. Assim, perder a conexão não interrompe a CLI. Reconecte, conecte-se à sessão e você voltará ao mesmo histórico de rolagem. Se você acabar executando várias sessões de agentes no mesmo servidor, uma por sessão do tmux, o tmux não conecta as conversas entre elas. A Gemini CLI oferece subagentes remotos pelo protocolo A2A, com configuração separada. Para tarefas independentes, coordene por meio de arquivos no disco. Para o padrão do Claude Code, consulte como uma sessão pode enviar texto para outra na mesma VPS.
Para execuções não interativas e baseadas em scripts, a Gemini CLI tem um modo headless: gemini -p "summarise the failing tests in this repo" imprime uma resposta e sai, enquanto --output-format json fornece uma saída legível por máquinas para ser redirecionada para outro local. O modo headless com uma chave de API é exatamente o que você precisa dentro de uma sessão tmux que executa um job em lote longo ou quando o comando é disparado por uma entrada do cron, com uma ressalva: um job do cron não carrega nenhum dos seus arquivos de login. Portanto, faça o comando carregar ~/.gemini_env para esta configuração. Credenciais armazenadas em cache ou um arquivo .env carregado pela CLI também funcionam; a ausência isolada de uma variável do shell não prova que a execução não tenha credenciais.
Sandboxing e permissões em um servidor que também executa produção
Um agente com acesso ao shell tem acesso ao shell. O Gemini CLI pode executar comandos e, por padrão, pede confirmação antes de cada comando arriscado, mas as pessoas recorrem a --yolo (aprovação automática de todas as chamadas de ferramentas), e então ele pode excluir arquivos, fazer push para o git ou acessar serviços internos com a autoridade disponível dentro do sandbox configurado. Os padrões atuais habilitam o sandbox para --yolo. Em um servidor que também executa produção, isso representa um raio de impacto real, não hipotético.
Três controles, em ordem do benefício que proporcionam:
- Execute-o com um usuário dedicado e sem privilégios. Não use root nem um membro de
sudo. Crie um usuárioagentcom seu próprio diretório home, instale o Node e a CLI nesse usuário, e uma instrução interpretada incorretamente ficará restrita a essa conta. Esta é a decisão de maior impacto. - Mantenha as credenciais de produção fora do servidor. Não use
~/.aws/credentialsde produção, não copie.envda produção para o servidor e não use uma senha de banco de dados com acesso de escrita a nada importante. Forneça uma credencial de staging ou somente leitura. - Use o sandbox integrado. Com Docker ou Podman instalado,
gemini --sandbox(ouGEMINI_SANDBOX=docker) executa as chamadas de ferramentas do agente dentro de um container que monta apenas o diretório do projeto atual, e não o restante do sistema de arquivos do host. Isso não substitui o usuário sem privilégios, mas é uma segunda camada forte quando o mesmo VPS está executando trabalho real.
Se você estiver executando o Gemini CLI junto de outras ferramentas auto-hospedadas, como um servidor MCP que expõe ferramentas ao agente no mesmo VPS, trate cada recurso adicionado como mais uma superfície que o agente pode alcançar e limite os tokens fornecidos a exatamente uma tarefa.
Quota, custo e o caminho de autenticação escolhido
O caminho de autenticação determina como você é cobrado e, desde June 18, 2026, se suas solicitações serão atendidas. A partir dessa data, segundo o anúncio do Google, o Gemini CLI deixou de atender solicitações de assinantes do Google AI Pro e Ultra e de usuários gratuitos do Gemini Code Assist for individuals. As chaves da Gemini API mantêm um nível gratuito separado, enquanto o uso pago é cobrado por modelo e pelo consumo de tokens. As chaves da Gemini Enterprise Agent Platform API e as licenças Gemini Code Assist Standard ou Enterprise das organizações continuam sendo compatíveis. Os limites dependem do método de autenticação, do modelo e do nível; as solicitações também podem falhar quando a capacidade compartilhada do serviço está indisponível.
Duas observações práticas. Um agente não supervisionado em um loop pode consumir a quota rapidamente, portanto monitore-o nas primeiras execuções antes de confiar nele em um cron job. E, se o motivo para usar um modelo no servidor for privacidade ou inferência sem medição de uso, em vez dos modelos hospedados pelo Google, essa é outra ferramenta: hospedar um LLM aberto com Ollama em um VPS mantém os pesos e os prompts no seu próprio servidor, ao custo de executar um modelo muito menor que o Gemini.
Mantê-lo atualizado
O Gemini CLI lança versões com frequência. Como foi instalado num prefixo pertencente ao utilizador, as atualizações nunca precisam de sudo:
npm install -g @google/gemini-cli@latest
gemini --versionExistem canais de lançamento: @latest é o estável, @preview é a versão de pré-visualização semanal e @nightly é a versão mais recente e instável. Fixe @latest em qualquer ambiente de que dependa. Com nvm, os pacotes globais ficam na versão ativa do Node. Por isso, depois de nvm use para mudar de versão do Node, pode ser necessário reinstalar a CLI. Consulte as notas de lançamento em vez de instalar todas as correções assim que ficam disponíveis.
Modos de falha, com as strings exatas
npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, seguido pelo encerramento da CLI em tempo de execução. O Node é demasiado antigo: a distribuição inclui o 18.19.1, que também já atingiu o fim do suporte. Instale uma versão LTS atual a partir do NodeSource ou do nvm (o Node 20 cumpre o requisito mínimo da CLI, mas também atingiu o fim do suporte em April 2026), confirme com node --version e, se tiver vários Nodes instalados, verifique se which node aponta para o novo e não para /usr/bin/node.
npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. Foi feita uma instalação global num prefixo pertencente a root. Não use sudo, defina npm config set prefix ~/.npm-global, coloque ~/.npm-global/bin em PATH e reinstale como o seu utilizador normal. Se um sudo npm anterior deixou ficheiros de cache pertencentes a root (Your cache folder contains root-owned files), execute sudo chown -R $(id -u):$(id -g) ~/.npm.
Failed to open browser ou um redirect_uri que aponta para http://127.0.0.1:PORT, ao qual não consegue chegar. A CLI encontrou uma variável de display, frequentemente proveniente de ssh -X, e utilizou o fluxo de loopback, cujo callback chega ao servidor. Execute NO_BROWSER=true gemini para obter o fluxo de colar um código ou use o caminho da API key (GEMINI_API_KEY). Numa sessão SSH simples, deverá ver Enter the authorization code:; aprove o URL no browser do seu portátil e cole o código apresentado pelo Google.
O processo desapareceu quando a ligação SSH caiu. Executou gemini diretamente a partir da shell SSH, por isso era um processo filho dessa shell e terminou quando o pty foi desligado. Não há nada a recuperar. Inicie todas as sessões com tmux new -A -s gemini e execute a CLI dentro dessa sessão.
A autenticação continua a falhar com a key definida, a CLI volta ao seletor de autenticação ou um pedido devolve API key not valid com HTTP 400. Verifique o método de autenticação selecionado e a key. Selecione Gemini API Key no seletor de autenticação; a CLI segue a seleção de autenticação guardada mesmo quando GEMINI_API_KEY está presente. Confirme com printenv GEMINI_API_KEY; se estiver vazio, verifique se ~/.gemini_env foi carregado ou forneça a key através do armazenamento suportado pela CLI ou do ficheiro .env. API key not valid significa que a key fornecida está incorreta, malformada ou já não existe; compare a key com a do AI Studio e remova espaços em branco no início ou no fim.
429 / RESOURCE_EXHAUSTED / uma mensagem de limite de pedidos. Atingiu uma quota ou um limite de pedidos, ou o caminho do Google Cloud não tem capacidade partilhada disponível. Verifique os detalhes do erro e os limites do seu nível. Se a quota estiver esgotada, aguarde até a janela ser reposta, reduza a velocidade do agente ou peça mais quota; para erros temporários de capacidade, tente novamente com backoff exponencial. Mudar para uma API key faturada não garante capacidade. Um agente preso num ciclo de novas tentativas continua a atingir este limite; pare-o e verifique o que está a fazer.
FAQ
Como autenticar o Gemini CLI em um servidor sem interface gráfica?
Use uma chave de API do Google AI Studio; o nível gratuito separado não exige faturamento. Coloque-a em um arquivo com modo 600 que o shell carregue (export GEMINI_API_KEY=...), execute gemini e selecione Gemini API Key para usar a autenticação sem navegador. Se você entrar com uma conta Google, por exemplo, usando uma licença Code Assist Standard ou Enterprise, o CLI exibirá uma URL em um servidor sem interface gráfica; abra-a no seu laptop, aprove o acesso e cole o código exibido pelo Google no prompt Enter the authorization code:. Não é necessário fixar nenhuma porta nem criar um túnel. O login inicial exige um navegador, mas as credenciais armazenadas em cache funcionam em sessões posteriores e em execuções sem interface gráfica. O acesso gratuito ao Gemini Code Assist para pessoas físicas terminou em June 18, 2026; essa mudança não removeu o nível gratuito para chaves de API.
Por que a instalação global do npm solicita sudo e como evitar isso?
Porque o prefixo global padrão do npm é /usr/lib/node_modules, no qual seu usuário não pode gravar, e um npm install -g simples falha com EACCES. A solução incorreta é sudo npm -g, que deixa arquivos pertencentes a root e causa falhas em instalações posteriores. A solução correta é apontar o prefixo para seu diretório pessoal (npm config set prefix ~/.npm-global) e adicionar o seu bin a PATH, ou usar nvm, que instala automaticamente os pacotes globais no seu diretório pessoal.
Como manter o Gemini CLI em execução depois de me desconectar?
Execute-o dentro do tmux. Um processo iniciado a partir do seu shell SSH morre quando a conexão cai porque é filho desse shell; o tmux executa o shell sob um servidor separado que continua ativo após a desconexão. Use tmux new -A -s gemini, execute gemini dentro dele, desconecte-se com Ctrl-b d e reconecte-se depois com tmux attach -t gemini.
É seguro executar o Gemini CLI em um servidor de produção?
Somente com cuidado, porque um agente com acesso ao shell pode fazer qualquer coisa que o usuário sob o qual é executado puder fazer. Execute-o como um usuário dedicado sem privilégios e sem sudo, mantenha as credenciais de produção fora da máquina, evite a aprovação automática --yolo e use --sandbox (Docker ou Podman) para isolar as chamadas de ferramentas do host. A conta sob a qual ele é executado é mais importante do que qualquer sinalizador individual configurado.
Preciso abrir portas no firewall para o Gemini CLI?
Não. Ele é um cliente que faz chamadas HTTPS de saída para as APIs do Google, portanto precisa da porta de saída 443, mas não de portas de entrada. O login do Google em um servidor sem interface gráfica também não exige nenhuma porta: você cola um código de volta no terminal em vez de receber um callback no servidor. Mantenha as conexões de entrada bloqueadas.