How to Run Gemini CLI for VPS Wey No Get Browser
Run Gemini CLI for headless VPS with current Node, npm install without sudo, API key auth, and tmux wey keeps tasks alive after SSH drops.
Wetin you dey build
Na an always-on Gemini CLI for server wey you own, wey you fit reach through SSH, and wey dey run long agent tasks even after you close your laptop. The installation na three commands. The work dey come from things wey assume say desktop dey available: Google's CLI want open browser make you log in, but your server no get browser. So most of this guide na the headless path, current Node wey distro no go provide, global npm install wey no need root, browserless auth with API key wey you keep away from shell history, and tmux so dropped SSH session no go stop task wey dey run.
Gemini CLI na open-source (Apache-2.0) Node program (@google/gemini-cli) wey dey talk to Google's Gemini models and fit read and write files, run shell commands, and use tools for the working directory. For VPS, e be small, always-available agent wey you fit leave to work. Na why the account wey e run as, and the credentials wey dey for the server, matter pass any single setting for here.
Prerequisites and the honest gotchas
- Ubuntu 24.04 KVM VPS wey fresh, with root or sudo. Google's installation guide recommend 4 GB or more RAM for casual use, and 16 GB or more for long sessions and large codebases.
- Node.js 20 or newer. Na this one be the hard version floor, and distro package dey below am; see the next section. Node 20 itself reach end-of-life on April 30, 2026, so install 26.
- Outbound HTTPS (port 443) go Google's APIs. No inbound port dey needed; na client be this, no be server, so you no need open firewall hole for am.
- One way to authenticate wey no need browser for the server: either Gemini API key from Google AI Studio, with free or paid usage, or Google sign-in. For headless box, Google sign-in go make you paste code back into terminal. The API-key path na the one wey fit scale for scripts and unattended runs.
- Docker or Podman, only if you want the
--sandboxisolation. E optional, and we go cover am near the end.
The gotcha wey dey catch everybody now na the account, no be the browser. Google announce on May 19, 2026 say from June 18, 2026 Gemini CLI go stop serving requests for Google AI Pro and Ultra subscribers, and for free users of Gemini Code Assist for individuals. E direct those users go the replacement, Antigravity CLI (agy). Gemini CLI still work with Gemini API keys, including the separate free tier, Gemini Enterprise Agent Platform API keys, and organisation's Gemini Code Assist Standard or Enterprise licence. Decide the auth path before you start.
Node: distro package dey too old
Ubuntu 24.04 ships Node 18.19.1 for its own repositories. Gemini CLI's package.json dey declare engines: { node: ">=20" }, and npm no dey stop mismatch by default. E go install anyway and print warning wey show the gap:
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 }If you ignore that warning, the CLI go run on runtime wey no support am. E fit misbehave or crash once e reach Node 20+ API wey e expect to dey available. Node 18 also reach end-of-life for April 2025, so e no be useful option again. Install current LTS before you install the CLI. The two clean options na NodeSource (system-wide signed apt repo) or nvm (per-user version manager). Pick one.
NodeSource, if you want Node available to every user for the server:
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 suppose print v20.x or higher to satisfy the CLI. But Node 20 don reach end-of-life since April 30, 2026, so target v26.x, wey be the current active LTS. Node 26 enter LTS for October 28, 2026 with version 26.13.0. Check the NodeSource page for current setup script. The setup_26.x for the URL na the line wey you go increase when newer LTS land.
nvm, if you prefer keep Node inside one user's home and never touch am with sudo:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node --versionThe v0.40.1 for that URL pins the installer version. Check nvm's README for the latest release, then replace the version before you run am. nvm get real advantage for this work: e installs Node and its global packages under ~/.nvm, so the global-install permission problem for the next section no go happen at all. If you choose nvm, you fit skip the npm-prefix step.
Install CLI without sudo npm -g
Command wey tempt person na sudo npm install -g @google/gemini-cli. No run am. Global prefix wey root own go cause permission errors for every later install, and e go leave files wey root own inside your npm cache. This fit cause problem months later. If you run plain (no-sudo) npm install -g against system Node, you go get another error:
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'This one na npm wey dey try write inside /usr/lib, but your user no get permission. The fix no be sudo. Set npm global prefix to your home directory, so global installs go enter place wey you own:
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 make the export remain available to interactive Bash shells. By default, tmux dey start login shell; for Ubuntu, default ~/.profile dey also source ~/.bashrc. If you don customise your login files, make sure say dem still load am. If gemini --version print version number, test don complete. But if you get gemini: command not found instead, your PATH export no take effect; check the failure modes. If you dey use nvm, skip the prefix lines completely: nvm already dey install globals inside your home.
If you run sudo npm before and now you dey see Your cache folder contains root-owned files, repair am once with sudo chown -R $(id -u):$(id -g) ~/.npm.
Di headless auth problem, and how to pass am
Run gemini interactively the first time and e go offer make you log in with your Google account. For desktop, e go open browser tab. For headless Linux VPS, the CLI go first check for display. If none of DISPLAY, WAYLAND_DISPLAY or MIR_SOCKET dey set, e no go try launch browser at all. E go print sign-in link and wait make you paste code back:
Please visit the following URL to authorize the application:
https://accounts.google.com/o/oauth2/v2/auth?...
Enter the authorization code:This flow dey work through plain SSH and e need browser for the first login. After login succeed, credentials dey cache locally for future sessions. Since June 18, 2026, e go only let you enter if your Google account dey among the accounts Gemini CLI still supports.
There are two correct ways to pass am.
The first one na API key, and na the correct default for server. Create key for Google AI Studio (aistudio.google.com). API-key use get separate free tier, so billing no required to start. Give the key to the CLI as GEMINI_API_KEY. Then run gemini and select Gemini API Key for the auth picker. Setting the variable alone no override authentication choice wey already save. Now for the part about keeping am out of history and files wey everybody fit read. Do not type export GEMINI_API_KEY=AIza... for the prompt, because e go enter ~/.bash_history as cleartext. Also, no put am inside file wey other users fit read. Read the key through hidden prompt, then write am to mode-600 file wey the shell sources when e start:
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 mean say na only your user fit read the file. Confirm say the key enter the environment with printenv GEMINI_API_KEY. If e print nothing, the variable no dey set, although the CLI fit still use stored key. E also reads .env file inside ~/.gemini/ if you prefer that layout. The same rule apply, so chmod 600 ~/.gemini/.env.
The second way na the Google sign-in itself. For headless machine, e no need tunnel or open port. Since June 18, 2026, e mainly useful for organisation wey get Gemini Code Assist Standard or Enterprise licence; set GOOGLE_CLOUD_PROJECT too. Free Gemini Code Assist for individuals and Google AI Pro or Ultra subscription access no longer dey supported. Start the CLI through normal SSH session and choose Sign in with Google:
geminiCopy the URL wey e print into your laptop browser and approve am. Google go redirect to https://codeassist.google.com/authcode, where e go show authorization code. Paste the code at Enter the authorization code: prompt for the VPS and the login go complete. Nothing for the server dey wait for callback, so no port dey to reserve and no ssh -L dey to configure. OAUTH_CALLBACK_PORT only matter for the loopback flow wey the CLI use when e find display. If you connect with X11 forwarding (ssh -X), DISPLAY go set and the CLI go use that loopback flow instead, with redirect to http://127.0.0.1:PORT/oauth2callback for the server. Run NO_BROWSER=true gemini to force the paste-a-code flow. The first login need you to dey near browser, but cached credentials still work for headless scripted runs. For anything wey you leave running, use API key.
For Vertex AI or Google Cloud project instead of AI Studio, set GOOGLE_API_KEY and select Vertex AI for the CLI. Or set GOOGLE_CLOUD_PROJECT for Code Assist licence. Use the same environment-variable discipline and the same mode-600 file.
Run am inside tmux so dropped SSH session no go kill am
A gemini process wey you launch directly from your SSH shell na child of that shell. If connection drop, laptop close, Wi-Fi disconnect, or idle timeout happen, sshd go tear down the pseudo-terminal, shell go receive SIGHUP, then e go hang up the CLI too. If task don spend ten minutes editing files, e go die with am, and when you reconnect, no process dey to recover.
tmux fix this because e go own the shell instead of sshd owning am. Na the same pattern as running AI coding agent for remote VPS inside tmux, and e work the same way here:
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 go attach to session wey get name gemini if e exist, and create am if e no exist. So na the one command to run immediately after every login. The shell inside belong to detached tmux server, no be your SSH session, so if connection drop, the CLI go continue to work. Reconnect, attach, and you go return to the same scrollback. If you end up running many agent sessions for one box, one for each tmux session, tmux no go connect their conversations. Gemini CLI supports remote subagents through the A2A protocol with separate configuration; for independent jobs, coordinate through files for disk. For the Claude Code pattern, see how one session fit hand text give another for the same VPS.
For non-interactive, scripted runs, Gemini CLI get headless mode: gemini -p "summarise the failing tests in this repo" go print answer and exit, while --output-format json go give machine-readable output wey you fit pipe elsewhere. Headless mode with an API key na exactly wetin you need inside tmux session wey dey run long batch job, or when you fire am from cron entry, with one important caveat: cron job no dey source any of your login files, so make the command source ~/.gemini_env for this setup. Cached credentials or .env file wey CLI load fit work too; if shell variable dey missing alone, e no prove say the run no get credentials.
Sandboxing and permissions on a box wey also dey run production
An agent wey get shell access na shell. Gemini CLI fit run commands, and by default e dey ask before each risky one, but people dey use --yolo (auto-approve every tool call), then e fit delete files, push to git, or reach internal services with the authority wey dey available inside the sandbox wey dem configure. Current defaults enable sandboxing for --yolo. For a box wey also dey run production, this na real blast radius, no be something wey dey only for theory.
Three controls, arranged from the one wey help pass:
- Run am as dedicated, unprivileged user. No be root, and no be member of
sudo. Createagentuser with im own home, install Node and the CLI there, and if e misread instruction, the effect go remain inside that account. This na the single decision wey get the highest value. - Keep production credentials comot from the box. No prod
~/.aws/credentials, no.envcopied down from production, and no database password wey get write access to anything important. Give am staging credential or read-only credential. - Use the built-in sandbox. If Docker or Podman dey installed,
gemini --sandbox(orGEMINI_SANDBOX=docker) dey run the agent tool calls inside container wey mount only the current project directory, no be the rest of the host filesystem. E no replace the unprivileged user, but e be strong second layer when the same VPS dey do real work.
If you dey run Gemini CLI beside other self-hosted tools, like an MCP server wey dey expose tools to the agent for the same VPS, treat every extra capability as more surface wey the agent fit reach, and limit the tokens wey you give am to exactly one job.
Quota, cost, and di auth path wey you choose
Di auth path decide how dem go bill you, and since June 18, 2026 e also decide whether dem go serve you at all. From that date, according to Google's announcement, Gemini CLI stop serving requests for Google AI Pro and Ultra subscribers, plus free users of Gemini Code Assist for individuals. Gemini API keys still get separate free tier, while paid usage dey charged according to model and token usage. Gemini Enterprise Agent Platform API keys and organisations' Gemini Code Assist Standard or Enterprise licences still dey supported. Limits depend on the authentication method, model, and tier; requests fit still fail when shared service capacity no dey available.
Two practical notes. Unattended agent wey dey run for loop fit burn quota quickly, so monitor am the first few times before you trust am with a cron job. And if your reason for using server-side model na privacy or unmetered inference instead of Google's hosted models, na different tool be that. self-hosting an open LLM with Ollama on a VPS go keep the weights and prompts for your own box, but you go need run model wey small well-well pass Gemini.
E dey updated
Gemini CLI dey release often. Since you install am inside prefix wey user own, updates no ever need sudo:
npm install -g @google/gemini-cli@latest
gemini --versionRelease channels dey: @latest na stable, @preview na weekly preview, @nightly na bleeding edge. Pin anything wey you rely on to @latest. For nvm, global packages dey under the active Node version. So after nvm use to switch Node, you fit need install the CLI again. Read the release notes instead of chasing every patch.
Failure modes, with the exact strings
npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, then the CLI crashing at runtime. Node old too much, and the distro version na 18.19.1, wey don also pass end-of-life. Install current LTS from NodeSource or nvm (Node 20 meet the CLI minimum version, but e don reach end-of-life since April 2026), confirm am with node --version, and if you get multiple Nodes installed, check say which node dey point to the new one, no be /usr/bin/node.
npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. You install globally inside prefix wey root own. No use sudo, set npm config set prefix ~/.npm-global, put ~/.npm-global/bin for PATH, then reinstall as your normal user. If earlier sudo npm leave cache files wey root own (Your cache folder contains root-owned files), run sudo chown -R $(id -u):$(id -g) ~/.npm.
Failed to open browser, or a redirect_uri wey dey point to http://127.0.0.1:PORT wey you no fit reach. The CLI find display variable, often from ssh -X, and e use the loopback flow, but the callback go land for the server. Run NO_BROWSER=true gemini to get the paste-a-code flow, or use the API-key path (GEMINI_API_KEY). For plain SSH session, you suppose see Enter the authorization code: instead; approve the URL for your laptop browser and paste the code wey Google show you.
The process disappear when SSH disconnect. You run gemini directly from the SSH shell, so na child process of that shell, and e die together with the pty when connection cut. Nothing dey to recover. Start every session with tmux new -A -s gemini and run the CLI inside am.
Auth still fail even with the key set, the CLI return to its auth picker, or request return API key not valid with HTTP 400. Check both the authentication method wey you select and the key itself. Select Gemini API Key for the auth picker; the CLI dey follow the authentication selection wey e save, even when GEMINI_API_KEY dey present. Confirm with printenv GEMINI_API_KEY; if e empty, check say ~/.gemini_env don source, or supply the key through the CLI supported storage or .env file. API key not valid mean say the key wey you supply wrong, malformed, or e no longer exist; check the key against AI Studio and remove any whitespace for the beginning or end.
429 / RESOURCE_EXHAUSTED / rate-limit message. You hit quota or rate limit, or the Google Cloud path no get available shared capacity. Check the error details and the limits for your tier. If quota don finish, wait for the window to reset, slow down the agent, or request more quota; if na temporary capacity error, retry with exponential backoff. Moving to billed API key no guarantee capacity. If agent stuck inside retry loop, stop am and check wetin e dey do.
FAQ
How I go authenticate Gemini CLI for headless server?
Use API key from Google AI Studio; the separate free tier no need billing. Put am for file wey get mode-600 and your shell sources (export GEMINI_API_KEY=...), run gemini, then select Gemini API Key for browserless authentication. If you sign in with Google instead, for example with Code Assist Standard or Enterprise licence, the CLI for headless box go print URL; open am for your laptop, approve am, then paste the code wey Google show for Enter the authorization code: prompt. No port to pin and no tunnel. The first login need browser, but cached credentials go work for later sessions and headless runs. Free Gemini Code Assist for individuals access end on June 18, 2026; that change no remove the API-key free tier.
Why npm global install dey ask for sudo, and how I fit avoid am?
Because npm default global prefix na /usr/lib/node_modules, and your user no fit write there, so plain npm install -g go fail with EACCES. The wrong fix na sudo npm -g, because e go leave root-owned files wey go break later installs. The correct fix na to point the prefix to your home (npm config set prefix ~/.npm-global) and add am to bin for PATH, or use nvm, wey dey install global packages under your home automatically.
How I go keep Gemini CLI running after I disconnect?
Run am inside tmux. Process wey start from your SSH shell dey die when connection drop because na child of that shell; tmux dey run the shell under detached server wey survive the disconnect. Use tmux new -A -s gemini, run gemini inside, detach with Ctrl-b d, then reattach later with tmux attach -t gemini.
E safe to run Gemini CLI for production box?
Only if you dey careful, because agent wey get shell access fit do anything wey the user wey run am fit do. Run am as dedicated unprivileged user without sudo, keep production credentials comot from the machine, avoid --yolo auto-approval, and use --sandbox (Docker or Podman) to isolate tool calls from the host. The account wey run am matter pass any single flag wey you set.
I need open any firewall ports for Gemini CLI?
No. Na client wey dey make outbound HTTPS calls to Google's APIs, so e need outbound port 443 but no inbound ports. Google sign-in for headless box no need port too: you go paste code back into the terminal instead of receiving callback for the server. Keep inbound access locked down.