VPS Tutorials
Gemini CLI on a VPS: API Keys, SSH, tmux and Isolation (2026)
Install Gemini CLI with an ordinary Ubuntu user and supported Node.js, authenticate headlessly with an API key, reconnect through tmux and verify permissions, quota, updates and project changes.

Putting Gemini CLI on a VPS is usually less about npm install than the Node.js version, headless authentication and recovering an SSH session. This guide covers one developer, one Ubuntu VPS and cloud-hosted models: create an ordinary user, install a supported runtime, authenticate with an API key and keep an interactive session in tmux.
The CLI reads repository files and runs permitted tools on the VPS; model requests go to the selected Google service. This is not local Gemini model deployment. No additional public web port is required: SSH remains the remote entry point.
The official installation guide requires Node.js 20+ and internet access. It recommends 4 GB+ RAM for ordinary short sessions and 16 GB+ for long sessions/large codebases. These are recommendations, not performance guarantees. Account separately for builds, tests, Docker, CPU and disk space on the same machine.
Verify SSH, npm access and the selected model service before buying a long-term VPS. Check Gemini API and AI Studio availability, account entitlement and quotas. Keep development agents separate from production services where possible; the example runtime user is outside the sudo group.
On Ubuntu 24.04/26.04, installation assumes the administrator has sudo. Create coder unless it already exists:
sudo apt update
sudo apt install -y curl git tmux ca-certificates
sudo adduser --disabled-password --gecos '' coder
sudo -iu coder
Run subsequent commands as coder. Ubuntu's packaged Node may be too old; inspect node -v, not merely whether apt install nodejs succeeded. The nvm installer provides a user-owned LTS runtime without global sudo npm:
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
Confirm node -v is at least 20, then install the stable package @google/gemini-cli:
npm install -g @google/gemini-cli
gemini --version
command -v gemini
If nvm or gemini disappears after reconnecting, use . "$HOME/.nvm/nvm.sh" as coder and check nvm loading in ~/.bashrc. Do not use sudo npm install -g to mix root installation paths with ordinary-user execution.
The authentication guide describes API keys and Vertex AI. Google's more specific consumer Code Assist deprecation notice states that affected individual accounts can no longer use Login with Google, including in Gemini CLI. General authentication pages may still describe that older route; check notices for your account type. This guide uses a Gemini API key from AI Studio instead. Confirm region, quotas and paid-use conditions; never paste keys into repositories, tickets or chat. Organizational Code Assist and Vertex AI have their own entitlement/authentication paths.
As coder, use hidden input to create a private 600 key file. These commands use Bash input/quoting features: %q makes the value safe to source in Bash and avoids putting the key directly in command history.
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 已加载'
Keep key.sh outside Git. Provider budgets/alerts may help track costs but are not necessarily hard spending limits. Rotate a suspected leaked key at the provider and replace the file. If prompted, choose Use Gemini API key. Test a small request in a disposable repository:
mkdir -p "$HOME/workspaces/demo"
cd "$HOME/workspaces/demo"
git init
printf '# VPS Gemini CLI 测试仓库\n' > README.md
gemini -p '只用一句话说明当前仓库有什么文件,不要修改文件'
The sample prompt asks for a one-sentence repository description without edits; use an equivalent prompt in your language. A read-only request is an instruction, not filesystem isolation. -p invokes headless mode for authentication/network testing. For quota or region errors, investigate the account/key before reinstalling the VPS. Clone real projects as coder into ~/workspaces/, using repository-scoped credentials rather than copying a main personal SSH private key.
A disconnected SSH terminal can terminate foreground work. tmux keeps the terminal process on the VPS. As 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
Press Ctrl-b then d to detach without ending the session. After a later SSH login, run sudo -iu coder, then:
tmux ls
tmux attach -t gemini
If tmux ls reports no server, verify the same Linux user and whether the previous session already exited. tmux does not survive a VPS reboot automatically or turn an interactive agent into perpetual automation. After reboot, reopen the project, load credentials and inspect Git state.
Gemini CLI can request shell commands; the shell-tool guide describes confirmation behavior, which also depends on mode/policy. Begin with explanation and a plan before approving writes or dependencies. Do not enable blanket automatic approval for convenience, especially alongside production services.
An ordinary user is not a complete sandbox. coder can read files its Linux permissions allow. Keep production .env, database backups and cloud credentials outside that boundary, without sudo. For stronger isolation, review Docker/Podman sandboxing and workspace mounts; adding coder to a privileged Docker group can grant host-level control.
After edits, inspect git status, git diff and meaningful tests before committing. Maintain a Git remote and independent project backups; snapshots and backups serve different recovery purposes.
gemini: command not found: inspect node -v, command -v npm and command -v gemini. Reload ~/.nvm/nvm.sh as coder, not root.
Browser sign-in unavailable: affected consumer Login with Google is deprecated. Use the API-key route and verify test -n "${GEMINI_API_KEY:-}". Headless authentication also supports configured Vertex AI; copying browser token files is not a universal solution.
401, quota or unavailable model: check the key's project, region, entitlement, quota and outbound network. Valid authentication does not guarantee model quota; use current limits and pricing.
Wrong project after reconnect: run pwd and git status, then check the directory. tmux attach reconnects to a session retaining its previous location. If no edits appear, inspect git diff and output rather than treating a living session as completed work.
Before updating, record gemini --version, back up the project and ~/.gemini/ as coder, then run npm install -g @google/gemini-cli@latest. Check version and a small read-only request again. Consult release notes and return to a tested release for regressions; avoid preview experiments in production projects.
GPU required? Not for the cloud models used here. Size the VPS for repository/tool workloads and concurrency.
Personal Google sign-in on a headless VPS? The consumer deprecation notice affects individual Login with Google access. This workflow uses an API key; organizational Code Assist Standard/Enterprise or Vertex AI users should follow their authorized methods.
Does tmux automate coding all day? It only preserves a running terminal. Unattended jobs need their own triggers, permissions, logs and failure handling.
Already using another terminal agent? This guide addresses Gemini's Node/runtime and headless authentication. See Codex CLI on a VPS and Claude Code for their distinct workflows.