Tutoriais de VPS
Gemini CLI no VPS: API key, SSH, tmux e isolamento (2026)
Instale Gemini CLI com usuário Ubuntu comum e Node compatível, autentique sem desktop com API key, retome tmux e confira permissões, quota, atualizações e mudanças.

Gemini CLI no VPS depende mais de Node.js, autenticação sem desktop e continuidade SSH que de npm install. Cobrimos um desenvolvedor, Ubuntu e modelos cloud: usuário comum, runtime compatível, API key e sessão tmux.
CLI lê repositório e executa ferramentas permitidas; chamadas vão ao serviço Google escolhido. Não instala modelo Gemini local. Não precisa de porta web: entrada remota continua SSH.
A instalação oficial exige Node.js 20+ e internet; recomenda 4 GB+ RAM para sessões curtas e 16 GB+ para sessões longas/repositórios grandes. Não garante desempenho. Some builds, testes, Docker e concorrência.
Confira SSH, npm e modelo antes de contratar longo prazo. Veja regiões AI Studio/API, permissões e quotas. Separe agentes de produção; usuário exemplo não tem sudo.
No Ubuntu 24.04/26.04, administrador precisa de sudo. Crie coder se necessário:
sudo apt update
sudo apt install -y curl git tmux ca-certificates
sudo adduser --disabled-password --gecos '' coder
sudo -iu coder
Depois opere como coder. Node do sistema pode ser antigo: confira node -v, não apenas sucesso de apt install nodejs. nvm instala LTS do usuário sem sudo npm global:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm install --lts
nvm alias default 'lts/*'
node -v
npm -v
Confirme node -v pelo menos 20; instale versão estável @google/gemini-cli:
npm install -g @google/gemini-cli
gemini --version
command -v gemini
Se faltam nvm/gemini ao reconectar, . "$HOME/.nvm/nvm.sh" como coder e confira nvm em ~/.bashrc. Não use sudo npm install -g misturando root e usuário comum.
A guia de autenticação mostra key e Vertex AI. O aviso específico Code Assist individual informa que Login with Google não está mais disponível para contas consumidoras afetadas, incluindo CLI. Páginas gerais podem manter orientações antigas: confira seu tipo de conta. Aqui usamos key do AI Studio. Confira região, quota e custo; sem keys em Git/chamados/conversas. Organizações/Vertex AI têm métodos próprios.
Como coder, gere arquivo 600 com entrada oculta. Comandos usam Bash: %q cita valor para carregar com segurança sem key literal no histórico.
install -d -m 700 "$HOME/.config/gemini-cli"
read -r -s -p '粘贴 Gemini API Key: ' gemini_api_key
printf '\n'
umask 077
printf 'export GEMINI_API_KEY=%q\n' "$gemini_api_key" > "$HOME/.config/gemini-cli/key.sh"
unset gemini_api_key
chmod 600 "$HOME/.config/gemini-cli/key.sh"
. "$HOME/.config/gemini-cli/key.sh"
test -n "${GEMINI_API_KEY:-}" && echo 'API Key 已加载'
Mantenha key.sh fora do Git. Orçamentos/alertas não necessariamente bloqueiam gasto. Em vazamento, rotacione no provedor e atualize arquivo. Se solicitado, escolha Use Gemini API key. Teste em repositório descartável:
mkdir -p "$HOME/workspaces/demo"
cd "$HOME/workspaces/demo"
git init
printf '# VPS Gemini CLI 测试仓库\n' > README.md
gemini -p '只用一句话说明当前仓库有什么文件,不要修改文件'
O exemplo pede descrição em uma frase sem alterações; use equivalente no seu idioma. Pedido só leitura não isola filesystem. -p usa modo headless. Para região/quota, confira conta antes de reinstalar. Clone como coder em ~/workspaces/, com credencial específica, sem copiar chave SSH privada principal.
Queda SSH pode encerrar processo em primeiro plano; tmux mantém terminal. Como coder:
tmux new -s gemini
export NVM_DIR="$HOME/.nvm"
. "$NVM_DIR/nvm.sh"
. "$HOME/.config/gemini-cli/key.sh"
cd "$HOME/workspaces/demo"
gemini
Ctrl-b depois d desanexam sem fechar. Depois use sudo -iu coder e:
tmux ls
tmux attach -t gemini
Se tmux ls não encontra server, confira usuário e sessão encerrada. tmux não restaura automaticamente após reboot nem automatiza trabalho contínuo. Reabra projeto, carregue key e confira Git depois.
A guia shell descreve confirmações, dependentes também do modo/política. Comece com explicação/plano, depois aprove escrita/dependências. Não habilite aprovação geral, sobretudo perto de produção.
Usuário comum não é sandbox completo. coder lê arquivos permitidos. Afaste .env produtivo, backups e chaves cloud; sem sudo. Para isolamento, veja sandbox Docker/Podman e montagens. Grupo Docker de coder pode controlar host.
Confira git status, git diff e testes relevantes antes de commit. Git remoto/backup externo continuam necessários; veja snapshots/backups.
gemini: command not found: node -v, command -v npm, command -v gemini; carregue ~/.nvm/nvm.sh como coder, sem root.
Login navegador indisponível: aviso consumidor afeta essa rota. Use key e confira test -n "${GEMINI_API_KEY:-}"; Vertex AI configurado é outra opção. Copiar tokens de navegador não resolve universalmente.
401/quota/modelo: projeto, região, permissão, quota e saída. Autenticação válida não garante disponibilidade; confira limites/preços.
Projeto errado ao reconectar: pwd/git status e caminho; tmux attach mantém diretório anterior. Sem mudanças, confira git diff e saída: sessão viva não é tarefa concluída.
Antes de atualizar, anote gemini --version, copie projeto e ~/.gemini/ como coder, rode npm install -g @google/gemini-cli@latest, confira versão/pedido. Veja releases e volte à versão testada se falha; evite previews em produção.
GPU? Não para modelos cloud. Dimensione ferramentas/repositórios.
Conta pessoal Google? Aviso consumidor afeta Login with Google individual. Aqui key; organizações Code Assist Standard/Enterprise e Vertex AI seguem autenticação autorizada.
tmux programa o dia todo? Só mantém terminal; automação exige gatilhos, permissões, logs e tratamento de falhas.
Outros agentes? Aqui resolvemos Node e autenticação Gemini. Veja Codex CLI e Claude Code para seus fluxos.