Headless VPSలో Gemini CLIని రన్ చేయడం ఎలా?

మీరు ఏమి నిర్మిస్తున్నారు

మీ స్వంత సర్వర్‌లో ఎల్లప్పుడూ అందుబాటులో ఉండే Gemini CLIని మీరు నిర్మిస్తున్నారు. దీనిని SSH ద్వారా యాక్సెస్ చేయవచ్చు. మీరు ల్యాప్‌టాప్ మూసివేసినా, ఇది సుదీర్ఘమైన ఏజెంట్ పనులను కొనసాగిస్తుంది. దీని ఇన్‌స్టాలేషన్ కేవలం మూడు కమాండ్లతో పూర్తవుతుంది. డెస్క్‌టాప్ వాతావరణాన్ని ఆశించే అంశాలే ఇక్కడ సవాలుగా మారతాయి: Google CLI లాగిన్ కోసం బ్రౌజర్‌ను తెరవాలని కోరుకుంటుంది, కానీ మీ సర్వర్‌లో బ్రౌజర్ ఉండదు. కాబట్టి, ఈ గైడ్‌లో ఎక్కువ భాగం headless పద్ధతి, మీ డిస్ట్రో అందించని తాజా Node వెర్షన్, root అవసరం లేని global npm ఇన్‌స్టాలేషన్, మీ shell historyలో కనిపించని API keyతో బ్రౌజర్ అవసరం లేని auth, మరియు SSH సెషన్ డిస్‌కనెక్ట్ అయినా పనులు ఆగిపోకుండా ఉండేందుకు tmux వినియోగం గురించి ఉంటుంది.

Gemini CLI అనేది ఒక open-source (Apache-2.0) Node ప్రోగ్రామ్ (@google/gemini-cli). ఇది Google యొక్క Gemini మోడళ్లతో సంభాషిస్తుంది. ఇది ఫైళ్లను చదవగలదు, రాయగలదు, shell కమాండ్లను రన్ చేయగలదు మరియు వర్కింగ్ డైరెక్టరీలోని టూల్స్‌ను నియంత్రించగలదు. VPSలో ఇది ఎల్లప్పుడూ అందుబాటులో ఉండే ఒక చిన్న ఏజెంట్‌గా పనిచేస్తుంది. అందుకే, ఇది ఏ అకౌంట్ ద్వారా రన్ అవుతోంది మరియు సర్వర్‌లో ఉన్న credentials ఎంత సురక్షితంగా ఉన్నాయి అనేది ఇక్కడ పేర్కొన్న ఏ ఇతర సెట్టింగ్ కంటే చాలా ముఖ్యం.

ముందస్తు అవసరాలు మరియు గమనించాల్సిన ముఖ్య విషయాలు

• root లేదా sudo అనుమతులు కలిగిన కొత్త Ubuntu 24.04 KVM VPS. ఏదైనా KVM ప్లాన్ సరిపోతుంది; CLI చాలా తేలికైనది, ఖాళీగా ఉన్నప్పుడు కొన్ని వందల MB RAM మాత్రమే తీసుకుంటుంది.
• Node.js 20 లేదా అంతకంటే కొత్త వెర్షన్. ఇది తప్పనిసరిగా ఉండాల్సిన కనీస వెర్షన్, డిస్ట్రో ప్యాకేజీ దీనికంటే పాతదిగా ఉంటుంది, కాబట్టి తదుపరి విభాగాన్ని చూడండి.
• Google APIలకు అవుట్‌బౌండ్ HTTPS (port 443) కనెక్టివిటీ. ఇన్‌బౌండ్ పోర్ట్‌లు ఏవీ అవసరం లేదు; ఇది క్లయింట్ మాత్రమే, సర్వర్ కాదు, కాబట్టి దీని కోసం ఫైర్‌వాల్‌లో ఎటువంటి రంధ్రాలు చేయనవసరం లేదు.
• సర్వర్‌లో బ్రౌజర్ అవసరం లేకుండా ప్రామాణీకరణ (authentication) చేసే మార్గం: Google AI Studio నుండి Gemini API key లేదా మీ స్వంత మెషీన్‌లోని బ్రౌజర్‌కు SSH టన్నెల్. API-key మార్గం స్క్రిప్ట్‌లకు మరియు అటెండెన్స్ లేని రన్‌లకు అనుకూలంగా ఉంటుంది.
• Docker లేదా Podman, మీకు --sandbox ఐసోలేషన్ కావాలంటే మాత్రమే. ఇది ఐచ్ఛికం, చివరలో వివరించబడింది.

అందరినీ ఇబ్బంది పెట్టే విషయం: స్నేహపూర్వకమైన gemini ఫస్ట్-రన్ లాగిన్ ఫ్లో డెస్క్‌టాప్ కోసం రూపొందించబడింది. ఇది బ్రౌజర్‌ను తెరవడానికి ప్రయత్నిస్తుంది, headless బాక్స్‌పై ఇది విఫలమవుతుంది లేదా పని చేయని లింక్‌ను ఇస్తుంది. మీరు ప్రారంభించే ముందే ప్రామాణీకరణ మార్గాన్ని నిర్ణయించుకోండి.

గమనిక: డిస్ట్రో ప్యాకేజీ చాలా పాతది

Ubuntu 24.04 తన సొంత రిపోజిటరీలలో Node 18.19.1 ను, npm 9.2.0 తో కలిపి అందిస్తుంది. Gemini CLI యొక్క package.json, engines: { node: ">=20" } అవసరమని పేర్కొంటుంది. సాధారణంగా npm వెర్షన్ల మధ్య వ్యత్యాసం ఉన్నా ఆగిపోదు, అది ఇన్‌స్టాల్ చేసి ఆ వ్యత్యాసాన్ని తెలియజేస్తూ ఒక హెచ్చరికను చూపిస్తుంది:

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 }

ఆ హెచ్చరికను దాటి ముందుకు వెళ్తే, CLI సపోర్ట్ లేని runtime పై నడుస్తుంది. అప్పుడు అది Node 20+ API ని ఆశించి, అది లేనప్పుడు తప్పుగా ప్రవర్తించడం లేదా క్రాష్ అవ్వడం జరుగుతుంది. Node 18 ఏప్రిల్ 2025 లోనే end-of-life కు చేరుకుంది, కాబట్టి ఎలా చూసినా అది పనికిరాదు. CLI ని ఇన్‌స్టాల్ చేసే ముందే ప్రస్తుత LTS వెర్షన్‌ను ఇన్‌స్టాల్ చేయండి. దీనికి రెండు సులభమైన మార్గాలు ఉన్నాయి: NodeSource (సిస్టమ్-వైడ్ సైన్డ్ apt రిపోజిటరీ) లేదా nvm (యూజర్-లెవల్ వెర్షన్ మేనేజర్). ఏదో ఒకటి ఎంచుకోండి.

మీకు సర్వర్‌లోని ప్రతి యూజర్‌కు Node అందుబాటులో ఉండాలంటే NodeSource వాడండి:

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

node --version కమాండ్ v20.x లేదా అంతకంటే ఎక్కువ వెర్షన్‌ను చూపించాలి, v24.x ప్రస్తుతం యాక్టివ్‌గా ఉన్న LTS వెర్షన్. ప్రస్తుత సెటప్ స్క్రిప్ట్ కోసం NodeSource పేజీని చూడండి; కొత్త LTS వెర్షన్ వచ్చినప్పుడు URL లోని setup_24.x ని మార్చాల్సి ఉంటుంది.

ఒకవేళ మీరు Node ను ఒక యూజర్ హోమ్ డైరెక్టరీలోనే ఉంచి, sudo తో సంబంధం లేకుండా ఉండాలనుకుంటే nvm వాడండి:

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

ఈ డాక్యుమెంట్ రాసే సమయానికి ఆ URL లోని v0.40.1 ప్రస్తుత వెర్షన్‌గా ఉంది; లేటెస్ట్ రిలీజ్ కోసం nvm యొక్క README ని తనిఖీ చేసి, రన్ చేసే ముందు వెర్షన్‌ను మార్చుకోండి. ఈ పనికి nvm ఒక గొప్ప ప్రయోజనాన్ని కలిగి ఉంది: ఇది Node ను మరియు దాని గ్లోబల్ ప్యాకేజీలను ~/.nvm కింద ఇన్‌స్టాల్ చేస్తుంది, కాబట్టి తదుపరి విభాగంలో వచ్చే గ్లోబల్-ఇన్‌స్టాల్ పర్మిషన్ సమస్య అసలు రాదు. మీరు nvm మార్గాన్ని ఎంచుకుంటే, npm-prefix స్టెప్‌ను దాటవేయవచ్చు.

sudo npm -g లేకుండా CLIని ఇన్‌స్టాల్ చేయడం

ఆకర్షణీయంగా కనిపించే కమాండ్ sudo npm install -g @google/gemini-cli. కానీ దానిని వాడకండి. root యాజమాన్యంలో ఉండే global prefix వల్ల భవిష్యత్తులో ప్రతి ఇన్‌స్టాలేషన్ సమయంలో permission errors వస్తాయి. అంతేకాకుండా, మీ npm cache లో root యాజమాన్యంలోని ఫైళ్లు ఉండిపోయి, కొన్ని నెలల తర్వాత సమస్యలను కలిగిస్తాయి. system Node పై sudo లేకుండా npm install -g రన్ చేస్తే మరొక రకమైన వైఫల్యం ఎదురవుతుంది:

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'

ఇక్కడ npm, /usr/lib లోకి రాయడానికి ప్రయత్నిస్తోంది, కానీ మీ యూజర్ ఖాతాకు దానికి అనుమతి లేదు. దీనికి పరిష్కారం sudo వాడటం కాదు, npm యొక్క global prefix ను మీ home directory కి మళ్లించడం. తద్వారా global ఇన్‌స్టాలేషన్లు మీకు యాజమాన్యం ఉన్న చోట జరుగుతాయి:

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

~/.profile కాదు, ~/.bashrc వాడటం ఉద్దేశపూర్వకమైనది: మీరు రెండు సెక్షన్ల తర్వాత CLIని రన్ చేసే tmux, ఒక non-login shell ను ప్రారంభిస్తుంది. ఇది ~/.bashrc ను చదువుతుంది కానీ ~/.profile ను దాటవేస్తుంది. కాబట్టి తప్పు ఫైల్‌లో ఉన్న PATH లైన్ వల్ల, మీకు అవసరమైన చోట gemini కనిపించదు. gemini --version ద్వారా version నంబర్ ప్రింట్ అవ్వడమే పూర్తి పరీక్ష. ఒకవేళ మీకు gemini: command not found కనిపిస్తే, మీ PATH export అమలు కాలేదని అర్థం, అప్పుడు failure modes చూడండి. nvm వాడుతుంటే, prefix లైన్లను పూర్తిగా దాటవేయండి: అది ఇప్పటికే globals ను మీ home directory లోనే ఇన్‌స్టాల్ చేస్తుంది.

ఒకవేళ మీరు గతంలో ఎప్పుడైనా sudo npm రన్ చేసి ఉండి, ఇప్పుడు Your cache folder contains root-owned files కనిపిస్తుంటే, sudo chown -R $(id -u):$(id -g) ~/.npm తో దానిని ఒక్కసారి సరిచేయండి.

Headless auth సమస్య మరియు దానిని అధిగమించే విధానం

మొదటిసారి gemini ను ఇంటరాక్టివ్‌గా రన్ చేసినప్పుడు, అది మీ Google ఖాతాతో లాగిన్ అవ్వమని అడుగుతుంది. డెస్క్‌టాప్‌పై అయితే ఇది బ్రౌజర్ ట్యాబ్‌ను తెరుస్తుంది. Headless VPSలో బ్రౌజర్ ఉండదు కాబట్టి, ఆ ప్రక్రియ ఒక localhost URLని ప్రింట్ చేస్తుంది లేదా నేరుగా ఇలాంటి లోపంతో విఫలమవుతుంది:

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

ఇక్కడ అసలు సమస్య redirect_uri=http://localhost:PORT. మీరు ఆ URLని మీ ల్యాప్‌టాప్‌లో తెరిచి అనుమతించినా, Google దానిని http://localhost:PORT కి రీడైరెక్ట్ చేస్తుంది. ఇది సర్వర్‌లోని localhost, దీనిని మీ ల్యాప్‌టాప్ నుండి చేరుకోవడం సాధ్యం కాదు. కాబట్టి లాగిన్ పూర్తి కాదు.

దీనిని అధిగమించడానికి రెండు సరైన మార్గాలు ఉన్నాయి.

మొదటిది API key, సర్వర్ కోసం ఇదే సరైన పద్ధతి. Google AI Studio (aistudio.google.com) లో ఒక కీని సృష్టించి, దానిని environment variableగా CLIకి అందించండి; ఇది GEMINI_API_KEY ని చదివి బ్రౌజర్ ప్రక్రియను పూర్తిగా దాటవేస్తుంది. ఇప్పుడు "దీనిని history లో మరియు అందరికీ కనిపించే ఫైళ్లలో ఉంచవద్దు" అనే నియమాన్ని పాటించండి. ప్రాంప్ట్ వద్ద export GEMINI_API_KEY=AIza... అని టైప్ చేయవద్దు, అది ~/.bash_history లో cleartext రూపంలో సేవ్ అవుతుంది. అలాగే ఇతరులు చదవగలిగే ఫైళ్లలో దీనిని ఉంచవద్దు. దీనిని mode-600 ఫైల్‌లో రాసి, షెల్ ప్రారంభమైనప్పుడు దానిని source చేయండి:

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

chmod 600 అంటే మీ యూజర్ మాత్రమే ఆ ఫైల్‌ను చదవగలరు. కీ environment లోకి చేరిందో లేదో printenv GEMINI_API_KEY తో నిర్ధారించుకోండి; ఒకవేళ అది ఏమీ ప్రింట్ చేయకపోతే, CLI మళ్ళీ బ్రౌజర్ ప్రక్రియకు వెళ్లి విఫలమవుతుంది. మీరు ఆ పద్ధతిని ఇష్టపడితే, ~/.gemini/ లోని .env ఫైల్‌ను కూడా ఇది చదువుతుంది, నియమం అదే, కాబట్టి chmod 600 ~/.gemini/.env.

రెండవ మార్గం OAuth callbackని మీ ల్యాప్‌టాప్‌కు టన్నెల్ చేయడం ద్వారా వ్యక్తిగత Google ఖాతా లాగిన్‌ను (మరియు దాని free tierని) ఉపయోగించుకోవడం. ఇక్కడ సమస్య ఏమిటంటే, CLI యొక్క loopback సర్వర్ ప్రతి రన్‌కు ఒక random పోర్ట్‌ను కేటాయిస్తుంది. కాబట్టి మీరు OAUTH_CALLBACK_PORT environment variableతో దానిని స్థిరపరచకపోతే, forward చేయడానికి స్థిరమైన పోర్ట్ ఉండదు. దానిని స్థిరపరిచిన తర్వాత ఇలా forward చేయండి:

# 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

CLI బ్రౌజర్‌ను తెరవలేదు కాబట్టి, అది auth URLని ప్రింట్ చేస్తుంది; దానిని మీ ల్యాప్‌టాప్ బ్రౌజర్‌లో తెరిచి, అనుమతించండి. Google http://localhost:8085/... కి రీడైరెక్ట్ చేసినప్పుడు, SSH forward దానిని VPSలోని loopback సర్వర్‌కు పంపుతుంది మరియు లాగిన్ పూర్తవుతుంది. పోర్ట్‌ను స్థిరపరచకపోతే, ప్రతి రన్‌కు అది కొత్త random పోర్ట్‌కు మారుతుంది, దీనిని ముందుగా సెట్ చేసిన ssh -L పట్టుకోలేదు. ఇది పనిచేస్తుంది, కానీ దీనికి మీరు బ్రౌజర్ ముందు ఉండాలి, కాబట్టి స్క్రిప్ట్‌లకు ఇది పనికిరాదు. నిరంతరం నడిచే సేవల కోసం API keyనే వాడండి.

AI Studioకు బదులుగా Vertex AI లేదా Google Cloud ప్రాజెక్ట్ కోసం అయితే, GOOGLE_GENAI_USE_VERTEXAI=true తో పాటు GOOGLE_API_KEY ని సెట్ చేయండి, లేదా Code Assist లైసెన్స్ కోసం GOOGLE_CLOUD_PROJECT ని సెట్ చేయండి. పద్ధతి మరియు mode-600 ఫైల్ నియమం అవే.

SSH సెషన్ కట్ అయినా ప్రాసెస్ ఆగిపోకుండా ఉండటానికి tmux లో రన్ చేయండి

మీరు నేరుగా SSH షెల్ నుండి ప్రారంభించే gemini ప్రాసెస్ ఆ షెల్ యొక్క చైల్డ్ ప్రాసెస్ అవుతుంది. కనెక్షన్ కట్ అయినా, ల్యాప్‌టాప్ మూసివేసినా, Wi-Fi డిస్‌కనెక్ట్ అయినా లేదా ఐడిల్ టైమ్‌అవుట్ అయినా, sshd సూడో-టెర్మినల్‌ను తొలగిస్తుంది. అప్పుడు షెల్‌కు SIGHUP సిగ్నల్ అందుతుంది మరియు అది CLIని నిలిపివేస్తుంది. ఫైళ్లను ఎడిట్ చేస్తున్నప్పుడు పది నిమిషాల పని కూడా దానితో పాటే ఆగిపోతుంది, తిరిగి కనెక్ట్ అయినప్పుడు ఆ ప్రాసెస్‌ను పునరుద్ధరించడం సాధ్యం కాదు.

sshd షెల్‌ను నియంత్రించే బదులు tmux షెల్‌ను తన ఆధీనంలోకి తీసుకోవడం ద్వారా ఈ సమస్యను పరిష్కరిస్తుంది. ఇది రిమోట్ VPSలో tmux లోపల AI కోడింగ్ ఏజెంట్‌ను రన్ చేయడం వంటి పద్ధతే, మరియు ఇక్కడ కూడా ఇది అదే విధంగా పనిచేస్తుంది:

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

tmux new -A -s gemini అనేది gemini అనే పేరుతో సెషన్ ఉంటే దానికి కనెక్ట్ అవుతుంది, లేకపోతే కొత్తగా సృష్టిస్తుంది. కాబట్టి ప్రతి లాగిన్ తర్వాత రన్ చేయాల్సిన ఏకైక కమాండ్ ఇదే. దీని లోపల ఉండే షెల్ మీ SSH సెషన్‌కు కాకుండా, డిటాచ్ చేయబడిన tmux సర్వర్‌కు చెందుతుంది. కాబట్టి కనెక్షన్ కట్ అయినా CLI పని చేస్తూనే ఉంటుంది. మీరు తిరిగి కనెక్ట్ అయినప్పుడు, పాత సెషన్‌ను అటాచ్ చేసుకుంటే, మీరు వదిలేసిన చోటు నుండే మళ్ళీ పనిని కొనసాగించవచ్చు. ఒకే సర్వర్‌పై మీరు అనేక ఏజెంట్ సెషన్లను రన్ చేస్తుంటే, ఒక్కో tmux సెషన్‌కు ఒక్కో ఏజెంట్ చొప్పున రన్ చేయవచ్చు. Claude Code లాగా ఇక్కడ సెషన్ల మధ్య సమాచార మార్పిడి ఉండదు, కాబట్టి ఒక సెషన్ నుండి మరొక సెషన్‌కు సమాచారాన్ని పంపడం సాధ్యం కాదు. కాబట్టి ప్రతి Gemini జాబ్‌ను స్వతంత్రంగా ఉంచండి లేదా డిస్క్‌లోని ఫైళ్ల ద్వారా వాటిని సమన్వయం చేసుకోండి.

ఇంటరాక్టివ్ కాని, స్క్రిప్ట్ ఆధారిత రన్‌ల కోసం Gemini CLI లో హెడ్‌లెస్ మోడ్ ఉంది: gemini -p "summarise the failing tests in this repo" సమాధానాన్ని ప్రింట్ చేసి నిష్క్రమిస్తుంది, మరియు --output-format json మెషిన్-రీడబుల్ అవుట్‌పుట్‌ను ఇస్తుంది, దీనిని ఇతర కమాండ్లకు పైప్ (pipe) చేయవచ్చు. సుదీర్ఘమైన బ్యాచ్ జాబ్‌లను tmux సెషన్‌లో రన్ చేసేటప్పుడు లేదా cron ద్వారా రన్ చేసేటప్పుడు API కీతో కూడిన హెడ్‌లెస్ మోడ్ ఉపయోగకరంగా ఉంటుంది. అయితే ఒక చిన్న జాగ్రత్త: cron జాబ్ మీ లాగిన్ ఫైళ్లను లోడ్ చేయదు, కాబట్టి crontab లైన్‌లోనే మీ GEMINI_API_KEY ను అందించండి (లేదా కమాండ్ ద్వారా ~/.gemini_env ను సోర్స్ చేయండి), లేకపోతే CLI బ్రౌజర్ ఫ్లోకు వెళ్ళి విఫలమవుతుంది.

ప్రొడక్షన్ సర్వర్‌పై శాండ్‌బాక్సింగ్ మరియు అనుమతులు

షెల్ యాక్సెస్ ఉన్న ఏజెంట్ ఒక షెల్ లాంటిదే. Gemini CLI కమాండ్‌లను రన్ చేయగలదు. డిఫాల్ట్‌గా, ఇది ప్రతి ప్రమాదకరమైన కమాండ్‌కు ముందు అనుమతిని అడుగుతుంది. అయితే, వినియోగదారులు --yolo (ప్రతి టూల్ కాల్‌ను ఆటోమేటిక్‌గా ఆమోదించడం) ఉపయోగిస్తుంటారు. అప్పుడు అది ఫైళ్లను తొలగించడం, git కి పుష్ చేయడం లేదా అది రన్ అవుతున్న యూజర్ యొక్క పూర్తి అధికారాలతో అంతర్గత సేవలను యాక్సెస్ చేయడం వంటివి చేయగలదు. ప్రొడక్షన్ రన్ అవుతున్న సర్వర్‌పై ఇది కేవలం ఊహ మాత్రమే కాదు, చాలా పెద్ద ప్రమాదం.

మూడు నియంత్రణలు, వాటి ప్రాముఖ్యత క్రమంలో:

• దీనిని ప్రత్యేకమైన, తక్కువ అధికారాలు కలిగిన యూజర్‌గా రన్ చేయండి. root గా వద్దు, sudo లో సభ్యుడిగా కూడా వద్దు. సొంత హోమ్ డైరెక్టరీతో ఒక agent యూజర్‌ను సృష్టించండి. Node మరియు CLIని అక్కడ ఇన్‌స్టాల్ చేయండి. దీనివల్ల తప్పుగా అర్థం చేసుకున్న కమాండ్ ఆ ఖాతాకే పరిమితం అవుతుంది. ఇది అత్యంత ముఖ్యమైన నిర్ణయం.
• ప్రొడక్షన్ క్రెడెన్షియల్స్‌ను ఈ బాక్స్‌లో ఉంచవద్దు. ప్రొడక్షన్ ~/.aws/credentials వద్దు, ప్రొడక్షన్ నుండి కాపీ చేసిన .env వద్దు, మరియు ముఖ్యమైన వాటికి రైట్ యాక్సెస్ ఉన్న డేటాబేస్ పాస్‌వర్డ్‌లు వద్దు. దీనికి స్టేజింగ్ లేదా రీడ్-ఓన్లీ క్రెడెన్షియల్స్‌ను మాత్రమే ఇవ్వండి.
• ఇన్‌బిల్ట్ శాండ్‌బాక్స్‌ను ఉపయోగించండి. Docker లేదా Podman ఇన్‌స్టాల్ చేసి ఉంటే, gemini --sandbox (లేదా GEMINI_SANDBOX=docker) ఏజెంట్ యొక్క టూల్ కాల్‌లను హోస్ట్ ఫైల్‌సిస్టమ్ మరియు నెట్‌వర్క్ నుండి వేరు చేయబడిన కంటైనర్‌లో రన్ చేస్తుంది. ఇది తక్కువ అధికారాలు కలిగిన యూజర్‌కు ప్రత్యామ్నాయం కాదు, కానీ ఒకే VPS పై నిజమైన పనులు జరుగుతున్నప్పుడు ఇది రెండవ బలమైన రక్షణ పొరగా పనిచేస్తుంది.

మీరు ఇతర self-hosted టూలింగ్‌తో పాటు Gemini CLIని రన్ చేస్తుంటే, ఉదాహరణకు అదే VPS పై ఏజెంట్‌కు టూల్స్‌ను అందించే MCP server, అప్పుడు ప్రతి అదనపు సామర్థ్యాన్ని ఏజెంట్ చేరుకోగల అదనపు ఉపరితలంగా పరిగణించండి. దానికి ఇచ్చే టోకెన్‌లను కేవలం ఒకే పనికి మాత్రమే పరిమితం చేయండి.

కోటా, ఖర్చు మరియు మీరు ఎంచుకున్న అథెంటికేషన్ మార్గం

అథెంటికేషన్ మార్గం మీ బిల్లింగ్ విధానాన్ని నిర్ణయిస్తుంది. వ్యక్తిగత Google ఖాతా (OAuth మార్గం) ఉచిత Gemini Code Assist టైర్‌ను ఉపయోగిస్తుంది, దీనికి నిమిషానికి మరియు రోజుకు పరిమితులు ఉంటాయి; వీటిని మించితే, ఆ సమయ పరిమితి ముగిసే వరకు అభ్యర్థనలు rate-limit ఎర్రర్‌ను చూపుతాయి. AI Studio నుండి పొందిన API key ప్రాజెక్ట్‌ను బట్టి ఉచితంగా లేదా బిల్లింగ్ పద్ధతిలో ఉండవచ్చు; బిల్లింగ్ కీ పరిమితులను పెంచుతుంది మరియు ప్రతి token కు ఛార్జీ విధిస్తుంది. Vertex మరియు Cloud-project అథెంటికేషన్ Google Cloud ద్వారా బిల్ చేయబడతాయి.

రెండు ఆచరణాత్మక అంశాలు. లూప్‌లో నడిచే unattended agent కోటాను వేగంగా ఖర్చు చేయగలదు, కాబట్టి cron job కు అప్పగించే ముందు మొదటి కొన్నిసార్లు దానిని గమనించండి. ఒకవేళ Google హోస్ట్ చేసిన మోడల్స్ కంటే గోప్యత లేదా అపరిమితమైన inference కోసం మీరు సర్వర్-సైడ్ మోడల్‌ను కోరుకుంటే, అది వేరే పద్ధతి, Ollama తో VPS లో open LLM ను self-hosting చేయడం ద్వారా weights మరియు prompts మీ సొంత సర్వర్‌లోనే ఉంటాయి, అయితే Gemini తో పోలిస్తే చాలా చిన్న మోడల్‌ను మాత్రమే రన్ చేయగలరు.

అప్‌డేట్‌గా ఉంచడం

Gemini CLI తరచుగా కొత్త వెర్షన్‌లను విడుదల చేస్తుంది. మీరు దీన్ని యూజర్-ఓన్డ్ ప్రిఫిక్స్‌లో ఇన్‌స్టాల్ చేశారు కాబట్టి, అప్‌డేట్‌ల కోసం ఎప్పుడూ sudo అవసరం లేదు:

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

ఇందులో వివిధ రిలీజ్ ఛానెల్‌లు ఉన్నాయి: @latest అనేది స్టేబుల్ వెర్షన్, @preview అనేది వీక్లీ ప్రివ్యూ, @nightly అనేది లేటెస్ట్ ఫీచర్లతో కూడిన బ్లీడింగ్ ఎడ్జ్ వెర్షన్. మీరు దేనిపైనైనా ఆధారపడి పనిచేస్తుంటే, దాన్ని @latest కి పిన్ చేయండి. nvm ఉపయోగిస్తున్నప్పుడు, గ్లోబల్ ప్యాకేజీలు యాక్టివ్‌గా ఉన్న Node వెర్షన్ కింద ఉంటాయి. కాబట్టి, Node వెర్షన్‌ను మార్చడానికి nvm use ఉపయోగించిన తర్వాత, మీరు CLIని మళ్లీ ఇన్‌స్టాల్ చేయాల్సి రావచ్చు. ప్రతి చిన్న ప్యాచ్ కోసం వెతకడం కంటే, రిలీజ్ నోట్స్‌ను చదవడం మంచిది.

వైఫల్య రీతులు మరియు ఖచ్చితమైన స్ట్రింగ్‌లు

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, ఆపై రన్‌టైమ్‌లో CLI క్రాష్ అవ్వడం. Node వెర్షన్ చాలా పాతది, డిస్ట్రోలో ఉన్న 18.19.1 వెర్షన్ ఇప్పటికే ఎండ్-ఆఫ్-లైఫ్ (EOL) దాటిపోయింది. NodeSource లేదా nvm ద్వారా Node 20+ వెర్షన్‌ను ఇన్‌స్టాల్ చేయండి, node --version తో నిర్ధారించుకోండి. ఒకవేళ మీరు ఒకటి కంటే ఎక్కువ Node వెర్షన్లను ఇన్‌స్టాల్ చేసి ఉంటే, which node కొత్త వెర్షన్‌ను సూచిస్తుందో లేదో చూడండి, /usr/bin/node ను కాదు.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. root యాజమాన్యంలో ఉన్న ప్రిఫిక్స్‌లోకి గ్లోబల్ ఇన్‌స్టాలేషన్ చేయడం. దీనికి sudo ఉపయోగించవద్దు, npm config set prefix ~/.npm-global ని సెట్ చేయండి, ~/.npm-global/bin ని PATH లో ఉంచండి, మరియు మీ సాధారణ యూజర్ ఖాతాతో తిరిగి ఇన్‌స్టాల్ చేయండి. ఒకవేళ అంతకుముందు చేసిన sudo npm వల్ల root యాజమాన్యంలోని కాష్ ఫైళ్లు (Your cache folder contains root-owned files) మిగిలి ఉంటే, sudo chown -R $(id -u):$(id -g) ~/.npm ని రన్ చేయండి.

Failed to open browser, లాగిన్ హ్యాంగ్ అవ్వడం, లేదా మీరు చేరుకోలేని redirect_uri=http://localhost:PORT. OAuth ఫ్లోకు సర్వర్‌లో లేని బ్రౌజర్ అవసరం, మరియు దాని localhost కాల్‌బ్యాక్ మీ ల్యాప్‌టాప్‌కు కాకుండా సర్వర్‌కు పాయింట్ అవుతోంది. API-key మార్గాన్ని (GEMINI_API_KEY) ఉపయోగించండి, లేదా OAUTH_CALLBACK_PORT ని పిన్ చేసి, ssh -L తో SSH ద్వారా ఫార్వర్డ్ చేసి, ఆ URLని స్థానికంగా ఓపెన్ చేయండి.

SSH డిస్‌కనెక్ట్ అయినప్పుడు ప్రాసెస్ అదృశ్యమవ్వడం. మీరు gemini ని నేరుగా SSH షెల్ నుండి రన్ చేశారు, కాబట్టి అది ఆ షెల్ యొక్క చైల్డ్ ప్రాసెస్‌గా ఉండి, డిస్‌కనెక్ట్ అయినప్పుడు ptyతో పాటు ముగిసింది. దీన్ని తిరిగి పొందలేము. ప్రతి సెషన్‌ను tmux new -A -s gemini తో ప్రారంభించి, CLIని దాని లోపల రన్ చేయండి.

కీ సెట్ చేసినా Auth విఫలమవ్వడం, CLI తిరిగి auth పికర్‌కు రావడం, లేదా రిక్వెస్ట్ HTTP 400 తో API key not valid ని తిరిగి ఇవ్వడం. CLI చూసే ఎన్విరాన్‌మెంట్‌లో కీ లేదు. printenv GEMINI_API_KEY తో నిర్ధారించుకోండి; అది ఖాళీగా ఉంటే, మీ ~/.gemini_env ఎప్పుడూ సోర్స్ కాలేదని అర్థం. ఆ లైన్ ~/.bashrc లో ఉందో లేదో తనిఖీ చేయండి. ఇంటరాక్టివ్ షెల్స్ (tmux తో సహా) దీన్ని చదువుతాయి, కానీ cron మరియు ఇతర నాన్-ఇంటరాక్టివ్ షెల్స్ చదవవు. కీ వాల్యూలో అదనపు స్పేస్ లేదా కోట్ ఉన్నా కూడా API key not valid వస్తుంది.

429 / RESOURCE_EXHAUSTED / రేట్-లిమిట్ సందేశం. మీ auth ఏ టైర్ ఉపయోగిస్తుందో దాని కోటాను మీరు దాటారు. విండో రీసెట్ అయ్యే వరకు వేచి ఉండండి, ఏజెంట్ వేగాన్ని తగ్గించండి, లేదా పెయిడ్ API కీకి మారండి. రీట్రై లూప్‌లో చిక్కుకున్న ఏజెంట్ పదేపదే దీన్ని హిట్ చేస్తూనే ఉంటుంది, కాబట్టి దాన్ని ఆపి అది ఏమి చేస్తుందో తనిఖీ చేయండి.

FAQ

Headless సర్వర్‌లో Gemini CLI ని ఎలా authenticate చేయాలి?

Browser login కు బదులుగా API key ని ఉపయోగించండి. Google AI Studio లో ఒక key ని సృష్టించి, దానిని మీ shell source చేసే export GEMINI_API_KEY=... ఫైల్‌లో mode-600 పర్మిషన్లతో భద్రపరచండి. అప్పుడు CLI పూర్తిగా OAuth browser flow ను దాటవేస్తుంది. ఒకవేళ మీకు ప్రత్యేకంగా personal-account free tier కావాలంటే, OAUTH_CALLBACK_PORT=8085 తో loopback port ను pin చేసి, ssh -L 8085:localhost:8085 user@server ద్వారా మీ laptop కు forward చేసి, అక్కడ కనిపించే URL ను local browser లో తెరవండి. అయితే దీనికి మీరు browser వద్ద ఉండాలి కాబట్టి, ఇది scripts కు అనువైనది కాదు.

npm global install కు sudo ఎందుకు అడుగుతుంది, దానిని ఎలా నివారించాలి?

ఎందుకంటే npm యొక్క default global prefix /usr/lib/node_modules, దీనిపై మీ user కు write permission ఉండదు. కాబట్టి సాధారణ npm install -g కమాండ్ EACCES ఎర్రర్‌తో విఫలమవుతుంది. sudo npm -g వాడటం తప్పు, ఎందుకంటే ఇది root-owned ఫైళ్లను సృష్టిస్తుంది, దీనివల్ల భవిష్యత్తులో ఇతర installs విఫలమవుతాయి. సరైన పద్ధతి ఏమిటంటే, prefix ను మీ home directory కి (npm config set prefix ~/.npm-global) మార్చి, దాని bin ను PATH కు జోడించడం. లేదా nvm వాడండి, ఇది global packages ను మీ home directory లోనే ఆటోమేటిక్‌గా ఇన్‌స్టాల్ చేస్తుంది.

నేను disconnect అయిన తర్వాత కూడా Gemini CLI ని ఎలా రన్ చేయాలి?

దీనిని tmux లోపల రన్ చేయండి. SSH shell నుండి ప్రారంభించిన process, connection కట్ అవ్వగానే ఆగిపోతుంది, ఎందుకంటే అది ఆ shell కు child process గా ఉంటుంది. tmux ఒక detached server కింద shell ను రన్ చేస్తుంది, కాబట్టి connection కట్ అయినా అది ఆగిపోదు. tmux new -A -s gemini వాడండి, లోపల gemini రన్ చేయండి, Ctrl-b d తో detach అవ్వండి, మరియు తర్వాత tmux attach -t gemini తో తిరిగి reattach అవ్వండి.

Production సర్వర్‌లో Gemini CLI ని రన్ చేయడం సురక్షితమేనా?

జాగ్రత్తగా ఉంటేనే సురక్షితం, ఎందుకంటే shell access ఉన్న agent, అది ఏ user గా రన్ అవుతుందో ఆ user చేయగలిగిన పనులన్నీ చేయగలదు. దీనిని sudo లేని, ప్రత్యేకమైన unprivileged user తో రన్ చేయండి. Production credentials ను ఆ machine లో ఉంచకండి, --yolo auto-approval ను నివారించండి, మరియు tool calls ను host నుండి వేరు చేయడానికి --sandbox (Docker లేదా Podman) వాడండి. మీరు సెట్ చేసే ఏ ఒక్క flag కంటే, అది ఏ account తో రన్ అవుతుందనేదే ముఖ్యం.

Gemini CLI కోసం నేను ఏదైనా firewall ports తెరవాలా?

అవసరం లేదు. ఇది Google APIs కు outbound HTTPS అభ్యర్థనలను పంపే client మాత్రమే. కాబట్టి దీనికి outbound port 443 అవసరం, కానీ inbound ports అవసరం లేదు. మీరు OAuth tunnel ఉపయోగిస్తే, ఆ pinned callback port (ఉదాహరణకు 8085) localhost లోనే ఉంటుంది మరియు అది మీ SSH forward ద్వారా చేరుకోబడుతుంది, అంతే తప్ప open inbound port ద్వారా కాదు. Inbound ports ను locked down లోనే ఉంచండి.