Paano mag-install ng Gemini CLI sa VPS

Ang iyong bubuuin

Isang always-on Gemini CLI sa iyong sariling server na accessible via SSH. Magpapatakbo ito ng mga long agent tasks na tuloy-tuloy kahit isara mo na ang laptop. Tatlong commands lang ang kailangan sa installation. Ang mahirap ay ang mga steps na nangangailangan ng desktop environment: gustong magbukas ng Google CLI ng browser para sa login, pero walang browser ang iyong server. Kaya ang karamihan sa guide na ito ay para sa headless path — gagamit tayo ng current Node na wala sa default distro, global npm install na hindi kailangan ng root, browserless auth gamit ang API key na hindi nakasulat sa shell history, at tmux para hindi maputol ang running task kapag nawala ang SSH session.

Ang Gemini CLI ay isang open-source (Apache-2.0) Node program (@google/gemini-cli) na kumokonekta sa Google Gemini models. Kaya nitong magbasa at magsulat ng files, magpatakbo ng shell commands, at gumamit ng mga tools sa working directory. Sa isang VPS, isa itong maliit at always-available na agent na pwedeng iwanang nagtatrabaho — kaya mahalaga ang account na gagamitin at ang credentials sa server kaysa sa anumang settings dito.

Mga Prerequisites at ang mga dapat tandaan

• Isang bagong Ubuntu 24.04 KVM VPS na may root o sudo access. Maaaring gamitin ang anumang KVM plan; magaan lang ang CLI, gumagamit lang ng ilang daang MB ng RAM kapag idle.
• Node.js 20 o mas bago. Ito ang kailangang minimum version; ang package mula sa distro ay mas mababa rito — tingnan ang susunod na section.
• Outbound HTTPS (port 443) patungo sa Google's APIs. Hindi kailangan ng anumang inbound ports; ang tool na ito ay isang client, hindi server, kaya hindi mo kailangang magbukas ng firewall hole para dito.
• Paraan ng authentication na hindi nangangailangan ng browser sa server: maaaring Gemini API key mula sa Google AI Studio, o SSH tunnel pabalik sa browser sa iyong sariling machine. Ang API-key path ang pinakamainam para sa mga script at unattended runs.
• Docker o Podman, kung gusto mo ng --sandbox isolation. Optional ito at tatalakayin sa dulo.

Ang karaniwang pagkakamali: ang gemini first-run login flow ay ginawa para sa desktop. Sinusubukan nitong magbukas ng browser, kaya sa isang headless box, maaaring mag-fail ito o magbigay ng link na hindi gumagana. Pumili na ng auth path bago magsimula.

Node: masyadong luma ang distro package

Ang Ubuntu 24.04 ay may Node 18.19.1 sa sarili nitong repositories, kasama ang npm 9.2.0. Idinedeklara ng engines: { node: ">=20" } sa Gemini CLI ang package.json, at hindi default na pinipigilan ng npm ang mismatch — itutuloy pa rin ang installation at maglalabas ng warning na nagsasabi ng 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 }

Kapag itinuloy ang paggamit sa kabila ng warning na iyon, tatakbo ang CLI sa isang unsupported runtime. Magkakaroon ito ng error o mag-crash kapag gumamit na ng Node 20+ API na inaasahan nitong naroon. Ang Node 18 ay reached end-of-life na rin noong April 2025, kaya hindi ito magandang opsyon. Mag-install ng current LTS bago i-install ang CLI. Ang dalawang malinis na paraan ay NodeSource (isang system-wide signed apt repo) o nvm (isang per-user version manager). Pumili ng isa.

NodeSource, kung gusto mong available ang Node sa lahat ng user sa machine:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version

Dapat mag-print ang node --version ng v20.x o mas mataas — ang v24.x ang kasalukuyang active LTS. Tingnan ang NodeSource page para sa current setup script; ang setup_24.x sa URL ang dapat palitan kapag may lumabas na bagong LTS.

nvm, kung mas gusto mong panatilihin ang Node sa loob ng home directory ng isang user at hindi ito gagamitan ng sudo:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node --version

Ang v0.40.1 sa URL na iyon ay current noong isinulat ito; tingnan ang README ng nvm para sa pinakabagong release at palitan ang version bago ito i-run. May malaking bentahe ang nvm para sa trabahong ito: ini-install nito ang Node at ang mga global packages nito sa ilalim ng ~/.nvm, kaya hindi na mangyayari ang global-install permission problem sa susunod na section. Kung gagamitin mo ang nvm, maaari mo nang i-skip ang npm-prefix step.

I-install ang CLI nang walang sudo npm -g

Ang nakakaakit na command ay ang sudo npm install -g @google/gemini-cli. Huwag itong gawin. Ang paggamit ng root-owned global prefix ay nagdudulot ng permission errors sa bawat susunod na install. Mag-iiwan din ito ng mga root-owned files sa iyong npm cache na magiging problema pagkalipas ng ilang buwan. Kapag nag-run ka ng plain (no-sudo) npm install -g laban sa system Node, makukuha mo naman ang isa pang failure:

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'

Sinusubukan ng npm na magsulat sa /usr/lib, na walang access ang iyong user. Ang solusyon ay hindi sudo — kundi ang ituro ang global prefix ng npm sa iyong home directory para ang mga global install ay mapunta sa folder na may ownership ka:

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

Ang ~/.bashrc, at hindi ~/.profile, ay sadyang ganyan: ang tmux — na gagamitin mo sa loob ng CLI sa susunod na dalawang section — ay nagpapatakbo ng non-login shell na binabasa ang ~/.bashrc at hindi binabasa ang ~/.profile. Dahil dito, ang isang PATH line sa maling file ay magreresulta sa pagiging invisible ng gemini sa mismong lugar na kailangan mo ito. Ang pag-print ng version number ng gemini --version ang mismong test. Kung ang makuha mo ay gemini: command not found, hindi gumana ang iyong PATH export — tingnan ang mga failure modes. Para sa nvm, i-skip na lang ang lahat ng prefix lines: awtomatiko na itong nag-i-install ng globals sa ilalim ng iyong home.

Kung nag-run ka ng sudo npm dati at nakikita mo ngayon ang Your cache folder contains root-owned files, ayusin ito gamit ang sudo chown -R $(id -u):$(id -g) ~/.npm.

Ang headless auth problem, at kung paano ito malalagpasan

Sa unang pagtakbo ng gemini nang interactive, mag-aalok ito na mag-log in gamit ang iyong Google account. Sa desktop, magbubukas ito ng browser tab. Sa headless VPS, walang browser, kaya ang flow ay magpi-print lamang ng localhost URL na dapat mong buksan, o kaya ay mag-eerror nang tuluyan na may ganitong mensahe:

Failed to open browser. Please visit the following URL to authorize:
https://accounts.google.com/o/oauth2/v2/auth?...&redirect_uri=http://localhost:PORT

Ang problema ay ang redirect_uri=http://localhost:PORT. Kahit buksan mo ang URL na iyon sa iyong laptop at i-approve ito, magre-redirect ang Google sa http://localhost:PORT — ang localhost sa loob ng server, isang port na hindi ma-a-access ng iyong laptop. Hindi matatapos ang login.

May dalawang tamang paraan para malusutan ito.

Ang una ay ang API key, na siyang tamang default para sa isang server. Gumawa ng key sa Google AI Studio (aistudio.google.com) at ibigay ito sa CLI bilang isang environment variable; babasahin nito ang GEMINI_API_KEY at lalaktawan ang browser flow. Ngayon, para sa "huwag itong ilagay sa history at sa mga file na nababasa ng iba." Huwag i-type ang export GEMINI_API_KEY=AIza... sa prompt — mapupunta ito sa ~/.bash_history nang cleartext, at huwag itong ilalagay sa file na pwedeng basahin ng iba. Isulat ito sa isang mode-600 file na i-so-source ng shell sa simula:

umask 077
printf 'export GEMINI_API_KEY=%s\n' 'AIzaSyYOUR_KEY_HERE' > ~/.gemini_env
chmod 600 ~/.gemini_env
echo '[ -f ~/.gemini_env ] && . ~/.gemini_env' >> ~/.bashrc
source ~/.bashrc

Ang chmod 600 ay nangangahulugang ang iyong user lamang ang pwedeng magbasa ng file. I-verify kung pumasok ang key sa environment gamit ang printenv GEMINI_API_KEY; kung walang lumabas, babalik ang CLI sa browser flow at mag-eerror. Babasahin din nito ang isang .env file sa ~/.gemini/ kung mas gusto mo ang layout na iyon — pareho ang rule, kaya chmod 600 ~/.gemini/.env.

Ang ikalawang paraan ay ang paggamit ng personal-Google-account login (at ang free tier nito) sa pamamagitan ng pag-tunnel ng OAuth callback pabalik sa iyong laptop. Ang problema ay ang loopback server ng CLI ay gumagamit ng random na port sa bawat takbo, kaya walang stable na port na pwedeng i-forward maliban kung i-pin muna ito gamit ang OAUTH_CALLBACK_PORT environment variable, at pagkatapos ay i-forward ang eksaktong port na iyon:

# from your laptop, forward the callback port into the SSH session:
ssh -L 8085:localhost:8085 user@your-server
# then, on the server, pin the callback to the same port and start the CLI:
export OAUTH_CALLBACK_PORT=8085
gemini

Hindi makakapagbukas ng browser ang CLI, kaya magpi-print ito ng auth URL; buksan ito sa browser ng iyong laptop, i-approve, at kapag nag-redirect ang Google sa http://localhost:8085/..., dadalhin ito ng SSH forward sa loopback server sa VPS at matatapos ang login. Kung hindi naka-pin ang port, mapupunta ito sa bagong random port sa bawat takbo, na hindi mahuhuli ng anumang ssh -L na naka-set up nang advance. Gumagana ito, pero kailangan mong nakabukas ang browser, kaya hindi ito mainam para sa mga script. Para sa anumang tatakbo nang kusa, gamitin ang API key.

Para sa Vertex AI o Google Cloud project sa halip na AI Studio, i-set ang GOOGLE_API_KEY kasama ang GOOGLE_GENAI_USE_VERTEXAI=true, o GOOGLE_CLOUD_PROJECT para sa Code Assist licence — parehong disiplina sa environment-variable, parehong mode-600 file.

Patakbuhin ito sa loob ng tmux para hindi mamatay ang proseso kapag naputol ang SSH session

Ang gemini process na pinapatakbo mo nang direkta mula sa iyong SSH shell ay child process ng shell na iyon. Kapag nawala ang koneksyon — dahil sa pagsara ng laptop, pagkaputol ng Wi-Fi, o idle timeout — tatanggalin ng sshd ang pseudo-terminal. Makakatanggap ang shell ng SIGHUP, at maghihinto ang CLI. Ang task na nasa gitna ng pag-edit ng files ay mamamatay, at wala nang prosesong mabi-recover pagkatapos mag-reconnect.

Sinisolusyunan ito ng tmux sa pamamagitan ng pag-angkin sa shell sa halip na ang sshd ang may-ari nito. Ito ang parehong pattern gaya ng pagtakbo ng AI coding agent sa isang remote VPS sa loob ng tmux, at pareho ang mekanismo nito dito:

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 gemini

Mag-a-attach ang tmux new -A -s gemini sa session na may pangalang gemini kung ito ay existing, o gagawa ng bago kung wala pa. Ito ang dapat na unang command na patakbuhin pagkatapos ng bawat login. Ang shell sa loob ay pagmamay-ari ng detached tmux server, hindi ng iyong SSH session, kaya mananatiling gumagana ang CLI kahit maputol ang koneksyon. Mag-reconnect, mag-attach, at babalik ka sa parehong scrollback.

Para sa mga non-interactive at scripted na pagtakbo, may headless mode ang Gemini CLI: magpi-print ang gemini -p "summarise the failing tests in this repo" ng sagot at mag-e-exit, habang ang --output-format json ay nagbibigay ng machine-readable output para ma-pipe sa ibang lugar. Ang headless mode na may API key ang kailangan mo sa loob ng tmux session na nagpapatakbo ng mahabang batch job, o kapag galing sa cron entry — may isang babala: hindi binabasa ng cron job ang iyong mga login files, kaya dapat bigyan ang crontab line ng sarili nitong GEMINI_API_KEY (o hayaan ang command na i-source ang ~/.gemini_env), kung hindi ay babalik ang CLI sa browser flow at mag-e-error.

Sandboxing at permissions sa isang box na nagpapatakbo rin ng production

Ang agent na may shell access ay isang shell. Maaaring magpatakbo ng commands ang Gemini CLI, at sa default ay nagtatanong ito bago ang bawat risky command — pero ginagamit ng mga tao ang --yolo (auto-approve sa bawat tool call), kaya maaari itong mag-delete ng files, mag-push sa git, o tumama sa internal services gamit ang full authority ng user na pinapatakbo nito. Sa isang box na nagpapatakbo rin ng production, ang blast radius nito ay totoo at hindi lamang hypothetical.

Tatlong kontrol, ayon sa laki ng proteksyon na ibinibigay nito:

• I-run ito bilang isang dedicated, unprivileged user. Huwag root, at huwag member ng sudo. Gumawa ng agent user na may sariling home directory, i-install ang Node at ang CLI doon, para ang anumang maling instruction ay mananatili lamang sa account na iyon. Ito ang pinakaimportante na desisyon.
• Huwag ilagay ang production credentials sa box. Walang prod ~/.aws/credentials, walang .env na kinopya mula sa production, at walang database password na may write access sa anumang kritikal. Bigyan ito ng staging o read-only credential.
• Gamitin ang built-in sandbox. Kapag naka-install ang Docker o Podman, ang gemini --sandbox (o GEMINI_SANDBOX=docker) ay magpapatakbo ng tool calls ng agent sa loob ng isang container na isolated mula sa host filesystem at network. Hindi nito papalitan ang paggamit ng unprivileged user, pero isa itong malakas na second layer kapag ang parehong VPS ay gumagawa ng mga totoong trabaho.

Kung pinapatakbo mo ang Gemini CLI kasabay ng iba pang self-hosted tooling — halimbawa ay isang MCP server na nag-e-expose ng mga tools sa agent sa parehong VPS — ituring ang bawat idinagdag na capability bilang dagdag na surface na maaaring maabot ng agent, at limitahan ang tokens na ibinibigay dito sa eksaktong isang trabaho lamang.

Quota, cost, at ang piniling auth path

Ang piniling auth path ang magtatakda kung paano ka sisingilin. Ang personal Google account (ang OAuth path) ay gumagamit ng free Gemini Code Assist tier, na may mga limitasyon bawat minuto at bawat araw; kapag lumampas sa mga ito, magbabalik ang mga request ng rate-limit error hanggang sa mag-reset ang window. Ang API key mula sa AI Studio ay maaaring free-tier o may bayad depende sa project — ang billed key ay nagpapataas ng limits at sisingilin bawat token. Ang Vertex at Cloud-project auth ay sisingilin sa pamamagitan ng Google Cloud.

Dalawang praktikal na paalala. Ang isang unattended agent na nasa loop ay mabilis na makakaubos ng quota, kaya bantayan muna ito sa unang ilang beses bago ito i-set sa isang cron job. At kung ang dahilan mo sa paggamit ng server-side model ay privacy o unmetered inference sa halip na mga hosted model ng Google, ibang tool ang kailangan — ang self-hosting ng isang open LLM gamit ang Ollama sa isang VPS ay nagpapanatili ng mga weights at prompts sa sarili mong box, kapalit ng pagtakbo ng mas maliit na model kumpara sa Gemini.

Pagpapanatili ng update

Madalas ang release ng Gemini CLI. Dahil naka-install ito sa isang user-owned prefix, hindi na kailangan ang sudo para sa mga update:

npm install -g @google/gemini-cli@latest
gemini --version

Mayroong mga release channel: ang @latest ay stable, ang @preview ay weekly preview, at ang @nightly ay bleeding edge — i-pin sa @latest ang anumang ginagamit mo. Sa nvm, ang mga global package ay nasa ilalim ng active Node version, kaya pagkatapos ng nvm use para magpalit ng Node, maaaring kailanganin mong i-reinstall ang CLI. Basahin ang release notes sa halip na habulin ang bawat patch.

Failure modes, with the exact strings

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, pagkatapos ay nag-crash ang CLI sa runtime. Masyadong luma ang Node — ang distro ay 18.19.1, na past end-of-life na rin. Mag-install ng Node 20+ mula sa NodeSource o nvm, i-verify gamit ang node --version, at kung mayroon kang maraming Node, siguraduhin na ang which node ay nakaturo sa bago at hindi sa /usr/bin/node.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. Global install sa isang prefix na pagmamay-ari ng root. Huwag itong gamitan ng sudo — i-set ang npm config set prefix ~/.npm-global, ilagay ang ~/.npm-global/bin sa PATH, at i-reinstall bilang normal user. Kung may naunang sudo npm na nag-iwan ng mga cache file na pagmamay-ari ng root (Your cache folder contains root-owned files), i-run ang sudo chown -R $(id -u):$(id -g) ~/.npm.

Failed to open browser, isang login na nag-hang, o isang redirect_uri=http://localhost:PORT na hindi ma-access. Kailangan ng OAuth flow ang browser na wala sa server, at ang localhost callback nito ay nakaturo sa server, hindi sa iyong laptop. Gamitin ang API-key path (GEMINI_API_KEY), o i-pin ang OAUTH_CALLBACK_PORT, i-forward ito via SSH gamit ang ssh -L, at i-open ang URL nang lokal.

Nawala ang process nang maputol ang SSH. Ni-run mo ang gemini nang direkta mula sa SSH shell, kaya naging child process ito ng shell na iyon at namatay kasabay ng pty pagkatapos ng disconnect. Walang maibabalik. Simulan ang bawat session gamit ang tmux new -A -s gemini at i-run ang CLI sa loob nito.

Bigo pa rin ang auth kahit naka-set ang key — bumabalik ang CLI sa auth picker nito, o ang request ay nagbabalik ng API key not valid na may HTTP 400. Ang key ay wala sa environment na nakikita ng CLI. I-confirm gamit ang printenv GEMINI_API_KEY; kung ito ay empty, hindi na-source ang ~/.gemini_env — i-check kung ang line ay nasa ~/.bashrc, na binabasa ng mga interactive shell (kasama ang tmux) pero hindi ng cron at iba pang non-interactive shells. Ang sobrang space o quote sa loob ng key value ay nagdudulot din ng API key not valid.

429 / RESOURCE_EXHAUSTED / isang rate-limit message. Naabot mo na ang quota para sa tier na ginagamit ng iyong auth. Maghintay hanggang mag-reset ang window, bagalan ang agent, o lumipat sa isang billed API key. Ang agent na stuck sa retry loop ay patuloy na tatama rito — i-stop ito at i-check ang ginagawa nito.

FAQ

Paano i-authenticate ang Gemini CLI sa isang headless server?

Gumamit ng API key sa halip na browser login. Gumawa ng key sa Google AI Studio, ilagay ito sa isang mode-600 file na ni-source ng iyong shell (export GEMINI_API_KEY=...), at lalampasan ng CLI ang OAuth browser flow. Kung kailangan mo ang free tier ng personal account, i-pin ang loopback port gamit ang OAUTH_CALLBACK_PORT=8085, i-forward ito pabalik sa iyong laptop gamit ang ssh -L 8085:localhost:8085 user@server, at i-open ang URL sa iyong local browser — ngunit kailangan mo ng browser para rito, kaya hindi ito mainam para sa mga script.

Bakit kailangan ng sudo sa npm global install, at paano ito maiiwasan?

Dahil ang default global prefix ng npm ay /usr/lib/node_modules, na walang write permission ang iyong user, kaya ang simpleng npm install -g ay mag-eerror ng EACCES. Ang maling solusyon ay ang sudo npm -g, dahil nag-iiwan ito ng mga file na pagmamay-ari ng root na magiging sanhi ng error sa mga susunod na install. Ang tamang solusyon ay ituro ang prefix sa iyong home (npm config set prefix ~/.npm-global) at idagdag ang bin nito sa PATH, o gumamit ng nvm, na awtomatikong nag-iinstall ng mga global package sa ilalim ng iyong home.

Paano pananatilihing tumatakbo ang Gemini CLI pagkatapos kong mag-disconnect?

Patakbuhin ito sa loob ng tmux. Ang prosesong sinimulan mula sa iyong SSH shell ay mamamatay kapag naputol ang koneksyon dahil child process ito ng shell na iyon; ang tmux ay nagpapatakbo ng shell sa ilalim ng isang detached server na mananatiling buhay kahit mag-disconnect. Gamitin ang tmux new -A -s gemini, patakbuhin ang gemini sa loob, i-detach gamit ang Ctrl-b d, at i-reattach muli gamit ang tmux attach -t gemini.

Ligtas ba na patakbuhin ang Gemini CLI sa isang production box?

Kailangan ng pag-iingat, dahil ang isang agent na may shell access ay maaaring gumawa ng anumang kayang gawin ng user na nagpapatakbo nito. Patakbuhin ito bilang isang dedicated unprivileged user na walang sudo, huwag ilagay ang mga production credentials sa machine, iwasan ang --yolo auto-approval, at gumamit ng --sandbox (Docker o Podman) upang i-isolate ang mga tool calls mula sa host. Mas mahalaga ang account na pinapatakbo nito kaysa sa anumang flag na iyong itatakda.

Kailangan ko bang magbukas ng anumang firewall ports para sa Gemini CLI?

Hindi. Ito ay isang client na gumagawa ng outbound HTTPS calls sa mga API ng Google, kaya kailangan nito ang outbound port 443 ngunit walang inbound ports. Kung gagamit ka ng OAuth tunnel, ang pinned callback port (halimbawa 8085) ay nasa localhost at maaabot sa pamamagitan ng iyong SSH forward, hindi sa isang bukas na inbound port. Panatilihing naka-lockdown ang inbound.