Headless VPS-ல் Gemini CLI-ஐ இயக்குவது எப்படி?

நீங்கள் உருவாக்குவது என்ன

நீங்கள் சொந்தமாக வைத்திருக்கும் server-ல் எப்போதும் இயங்கக்கூடிய Gemini CLI-ஐ உருவாக்குவதே இதன் நோக்கம். இதை SSH மூலம் அணுகலாம். உங்கள் மடிக்கணினியை மூடினாலும், நீண்ட கால முகவர் (agent) பணிகள் தொடர்ந்து இயங்கும். இதை நிறுவுவதற்கு மூன்று கட்டளைகள் மட்டுமே தேவை. டெஸ்க்டாப் சூழலை எதிர்பார்க்கும் அம்சங்களைச் சரிசெய்வதே இதில் உள்ள சவால்: Google-ன் CLI உள்நுழைவதற்கு browser-ஐத் திறக்க முயலும், ஆனால் உங்கள் server-ல் browser இருக்காது. எனவே, இந்த வழிகாட்டியின் பெரும்பகுதி headless முறையில் செயல்படுவது, உங்கள் distro-வில் இல்லாத தற்போதைய Node பதிப்பைப் பெறுவது, root அனுமதி தேவையில்லாத global npm நிறுவல், shell history-ல் சேமிக்கப்படாத API key மூலம் browserless authentication, மற்றும் SSH இணைப்பு துண்டிக்கப்பட்டாலும் பணி நின்றுவிடாமல் இருக்க tmux ஆகியவற்றைப் பற்றியது.

Gemini CLI என்பது ஒரு open-source (Apache-2.0) Node நிரலாகும் (@google/gemini-cli). இது Google-ன் Gemini மாதிரிகளுடன் தொடர்புகொண்டு, கோப்புகளைப் படிக்கவும் எழுதவும், shell கட்டளைகளை இயக்கவும், பணிபுரியும் கோப்பகத்தில் (working directory) கருவிகளை இயக்கவும் கூடியது. ஒரு VPS-ல் இது எப்போதும் கிடைக்கக்கூடிய சிறிய முகவராகச் செயல்படும். எனவே, இது எந்தக் கணக்கின் கீழ் இயங்குகிறது மற்றும் அதில் உள்ள நற்சான்றிதழ்கள் (credentials) ஆகியவை மிக முக்கியமானவை.

முன்நிபந்தனைகள் மற்றும் கவனிக்க வேண்டிய சிக்கல்கள்

• root அல்லது sudo வசதி கொண்ட புதிய Ubuntu 24.04 KVM VPS. எந்தவொரு KVM திட்டமும் இதற்குப் பொருந்தும்; CLI மிகக் குறைந்த வளங்களையே பயன்படுத்தும், சும்மா இருக்கும்போது சில நூறு MB RAM மட்டுமே தேவைப்படும்.
• Node.js 20 அல்லது அதற்குப் பிந்தைய பதிப்பு. இது கட்டாயமான குறைந்தபட்ச பதிப்பாகும், distro-வில் உள்ள package இதைவிடப் பழையதாக இருக்கலாம், எனவே அடுத்த பகுதியைப் பார்க்கவும்.
• Google-ன் API-களுக்கு outbound HTTPS (port 443) இணைப்பு. inbound ports எதையும் திறக்க வேண்டிய அவசியமில்லை; இது ஒரு client, server அல்ல, எனவே இதற்காக firewall-ல் எந்தத் துளையும் இட வேண்டியதில்லை.
• server-ல் browser இல்லாமலேயே authenticate செய்யும் வசதி: Google AI Studio-விலிருந்து பெறப்பட்ட Gemini API key அல்லது உங்கள் கணினியில் உள்ள browser-க்கு ஒரு SSH tunnel. API-key முறைதான் scripts மற்றும் தானியங்கி செயல்பாடுகளுக்கு ஏற்றது.
• Docker அல்லது Podman, --sandbox isolation தேவைப்பட்டால் மட்டும். இது விருப்பத்தேர்வுதான், இறுதியில் விளக்கப்பட்டுள்ளது.

அனைவரையும் பாதிக்கும் சிக்கல்: gemini முதல்முறை login செய்யும் முறை desktop-க்காக உருவாக்கப்பட்டது. இது browser-ஐத் திறக்க முயற்சிக்கும், headless server-ல் இது தோல்வியடையும் அல்லது வேலை செய்யாத link-ஐக் கொடுக்கும். தொடங்குவதற்கு முன்பே auth முறையை முடிவு செய்யவும்.

குறிப்பு: distro package மிகவும் பழையது

Ubuntu 24.04 அதன் சொந்த repositories-ல் 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-ஐ அது அணுக முயலும்போது, அந்த API இல்லாததால் CLI தவறாகச் செயல்படும் அல்லது செயலிழக்கும். மேலும், Node 18 ஏப்ரல் 2025-ல் அதன் ஆயுட்காலத்தை (end-of-life) முடித்துவிட்டது, எனவே இது எந்த வகையிலும் பயனளிக்காது. CLI-ஐ நிறுவுவதற்கு முன்பே தற்போதைய LTS பதிப்பை நிறுவவும். இதற்கான இரண்டு தெளிவான வழிகள் உள்ளன: NodeSource (system-wide signed apt repo) அல்லது nvm (per-user version manager). ஏதேனும் ஒன்றை தேர்வு செய்யவும்.

NodeSource, நீங்கள் server-ல் உள்ள அனைத்து பயனர்களுக்கும் Node கிடைக்க வேண்டும் என்று விரும்பினால்:

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 என்பது தற்போதைய active LTS ஆகும். தற்போதைய setup script-க்கு NodeSource பக்கத்தைச் சரிபார்க்கவும்; புதிய LTS வரும்போது URL-ல் உள்ள setup_24.x பகுதியை மாற்ற வேண்டியிருக்கும்.

nvm, நீங்கள் Node-ஐ ஒரு பயனரின் home directory-க்குள்ளேயே வைத்திருக்க விரும்பினால் மற்றும் sudo-வைப் பயன்படுத்தாமல் இருக்க விரும்பினால்:

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 மற்றும் அதன் global packages-ஐ ~/.nvm-ன் கீழ் நிறுவுகிறது. எனவே, அடுத்த பகுதியில் குறிப்பிடப்பட்டுள்ள global-install அனுமதிச் சிக்கல்கள் இதில் ஏற்படாது. நீங்கள் 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'

இது /usr/lib கோப்பகத்தில் எழுத npm முயற்சிப்பதைக் குறிக்கிறது, இதற்கு உங்கள் பயனர் கணக்கிற்கு அனுமதி இல்லை. இதற்குத் தீர்வு 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 கட்டளை பதிப்பு எண்ணை அச்சிடுவது மட்டுமே முழுமையான சோதனை. அதற்குப் பதிலாக gemini: command not found என்று வந்தால், உங்கள் PATH export வேலை செய்யவில்லை என்று பொருள்; தோல்விக்கான காரணங்களைப் பார்க்கவும். நீங்கள் nvm பயன்படுத்தினால், prefix வரிகளைத் தவிர்க்கவும்: அது ஏற்கனவே global கோப்புகளை உங்கள் home directory-க்குள்ளேயே நிறுவுகிறது.

நீங்கள் முன்னதாக sudo npm கட்டளையை இயக்கி, இப்போது Your cache folder contains root-owned files என்று பிழை வந்தால், sudo chown -R $(id -u):$(id -g) ~/.npm கட்டளையைப் பயன்படுத்தி அதை ஒருமுறை சரிசெய்யவும்.

Headless அங்கீகாரச் சிக்கல் மற்றும் அதைத் தீர்க்கும் முறை

முதல்முறை gemini-ஐ interactive முறையில் இயக்கும்போது, அது உங்கள் Google கணக்கின் மூலம் உள்நுழையக் கேட்கும். டெஸ்க்டாப் கணினியில் இது ஒரு browser tab-ஐத் திறக்கும். ஆனால் headless VPS-ல் browser இல்லாததால், அது ஒரு 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-க்கு, அதாவது server-ல் உள்ள localhost-க்கு திருப்பிவிடும். உங்கள் மடிக்கணினியால் அந்த port-ஐ அணுக முடியாது என்பதால், உள்நுழைவு முழுமையடையாது.

இதைச் சரிசெய்ய இரண்டு முறைகள் உள்ளன.

முதல் முறை API key பயன்படுத்துவது; இதுவே server-களுக்குச் சரியான முறையாகும். Google AI Studio-வில் (aistudio.google.com) ஒரு key-ஐ உருவாக்கி, அதை environment variable-ஆக CLI-க்கு வழங்கவும். இது GEMINI_API_KEY-ஐ வாசித்து, browser flow-ஐத் தவிர்க்கும். இப்போது, "இதை history-லிலும் பிறர் வாசிக்கக்கூடிய கோப்புகளிலும் வைக்காதீர்கள்" என்ற விதியைப் பின்பற்றவும். prompt-ல் export GEMINI_API_KEY=AIza... என்று தட்டச்சு செய்யாதீர்கள், அது ~/.bash_history-ல் plain text-ஆகச் சேமிக்கப்படும். பிறர் வாசிக்கக்கூடிய கோப்புகளிலும் இதைப் போடாதீர்கள். shell தொடங்கும்போதே source செய்யும் வகையில், mode-600 கோப்பில் இதைச் சேமிக்கவும்:

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 என்பது உங்கள் user மட்டுமே அந்தக் கோப்பை வாசிக்க முடியும் என்பதைக் குறிக்கிறது. printenv GEMINI_API_KEY மூலம் key சரியாக environment-ல் உள்ளதா என்பதை உறுதிப்படுத்தவும்; அது எதையும் காட்டவில்லை என்றால், CLI மீண்டும் browser flow-க்குச் சென்று தோல்வியடையும். நீங்கள் விரும்பினால் ~/.gemini/-ல் உள்ள .env கோப்பையும் பயன்படுத்தலாம், அதே விதிதான், எனவே chmod 600 ~/.gemini/.env.

இரண்டாவது முறை, OAuth callback-ஐ உங்கள் மடிக்கணினிக்கு tunnel செய்வதன் மூலம் தனிப்பட்ட Google கணக்கு உள்நுழைவை (மற்றும் அதன் free tier-ஐ) தக்கவைப்பது. இதில் உள்ள சிக்கல் என்னவென்றால், CLI-ன் loopback server ஒவ்வொரு முறையும் ஒரு random port-ஐப் பயன்படுத்தும். எனவே OAUTH_CALLBACK_PORT environment variable மூலம் அதை முன்கூட்டியே நிர்ணயம் (pin) செய்யாவிட்டால், port forwarding செய்ய முடியாது:

# 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-ஆல் browser-ஐத் திறக்க முடியாது என்பதால், அது auth URL-ஐக் காட்டும். அதை உங்கள் மடிக்கணினி browser-ல் திறந்து அனுமதி அளிக்கவும். Google http://localhost:8085/...-க்குத் திருப்பிவிடும்போது, SSH forward அதை VPS-ல் உள்ள loopback server-க்குக் கொண்டு செல்லும், உள்நுழைவு முழுமையடையும். port-ஐ நிர்ணயம் செய்யாவிட்டால், ஒவ்வொரு முறையும் அது புதிய random port-ல் அமையும், அதை முன்கூட்டியே ssh -L மூலம் பிடிக்க முடியாது. இது வேலை செய்யும், ஆனால் இதற்கு நீங்கள் browser-க்கு முன்னால் இருக்க வேண்டும், எனவே scripts-க்கு இது உகந்ததல்ல. எப்போதும் இயங்க வேண்டியவற்றுக்கு API key-யையே பயன்படுத்தவும்.

AI Studio-க்கு பதிலாக Vertex AI அல்லது Google Cloud project-ஐப் பயன்படுத்தினால், GOOGLE_GENAI_USE_VERTEXAI=true-உடன் சேர்த்து GOOGLE_API_KEY-ஐ அமைக்கவும், அல்லது Code Assist உரிமத்திற்கு GOOGLE_CLOUD_PROJECT-ஐப் பயன்படுத்தவும். இதற்கும் அதே environment-variable நடைமுறைகள் மற்றும் mode-600 கோப்பு முறையே பொருந்தும்.

SSH இணைப்பு துண்டிக்கப்பட்டாலும் செயல்முறை நின்றுவிடாமல் இருக்க tmux-க்குள் இயக்கவும்

நீங்கள் நேரடியாக SSH shell-லிருந்து தொடங்கும் ஒரு gemini செயல்முறை, அந்த shell-ன் child process ஆகும். இணைப்பு துண்டிக்கப்பட்டாலோ, மடிக்கணினி மூடப்பட்டாலோ, Wi-Fi துண்டிக்கப்பட்டாலோ அல்லது idle timeout ஏற்பட்டாலோ, sshd pseudo-terminal-ஐ நீக்கிவிடும். இதனால் shell-க்கு SIGHUP சிக்னல் அனுப்பப்பட்டு, CLI-ல் இயங்கும் செயல்முறை முடிவுக்கு வரும். கோப்புகளைத் திருத்திக் கொண்டிருக்கும்போது இத்தகைய இடையூறு ஏற்பட்டால், அந்தப் பணி பாதியிலேயே நின்றுவிடும்; மீண்டும் இணைக்கும்போது அந்தச் செயல்முறையை மீட்டெடுக்க முடியாது.

sshd-க்கு பதிலாக tmux-ஐ shell-ன் உரிமையாளராக மாற்றுவதன் மூலம் இந்தச் சிக்கலைத் தவிர்க்கலாம். இது remote VPS-ல் tmux-க்குள் AI coding agent-ஐ இயக்குவது போன்ற அதே முறையே ஆகும், இது இங்கும் அதேபோல் செயல்படுகிறது:

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 என்ற பெயரில் ஒரு session இருந்தால் அதனுடன் இணையும், இல்லையெனில் புதிய session-ஐ உருவாக்கும். எனவே, ஒவ்வொரு முறை login செய்த பிறகும் இயக்க வேண்டிய கட்டளை இதுவே. இதற்குள் இருக்கும் shell, உங்கள் SSH session-க்கு சொந்தமானது அல்ல, மாறாக detached tmux server-க்கு சொந்தமானது. எனவே, இணைப்பு துண்டிக்கப்பட்டாலும் CLI தொடர்ந்து இயங்கும். மீண்டும் இணைக்கும்போது, நீங்கள் விட்ட இடத்திலிருந்தே scrollback-ஐப் பெறலாம். ஒரே server-ல் பல agent session-களைத் தனித்தனி tmux session-களில் இயக்கினால், அவற்றுக்கிடையே தொடர்பு இருக்காது. Claude Code போலன்றி, ஒரே VPS-ல் ஒரு session மற்றொரு session-க்கு தகவலை அனுப்ப முடியாது, எனவே ஒவ்வொரு Gemini பணியையும் தனித்தனியாக வைத்திருக்கவும் அல்லது கோப்புகள் மூலம் ஒருங்கிணைக்கவும்.

Interactive அல்லாத, scripted பணிகளுக்கு, Gemini CLI-ல் headless mode உள்ளது: gemini -p "summarise the failing tests in this repo" ஒரு பதிலை அச்சிட்டு வெளியேறும், --output-format json கணினி வாசிக்கக்கூடிய வெளியீட்டைத் தரும், அதை நீங்கள் பிற இடங்களுக்கு pipe செய்யலாம். நீண்ட batch job-களை tmux session-க்குள் இயக்கும்போதோ அல்லது cron entry மூலம் இயக்கும்போதோ API key-உடன் கூடிய headless mode-ஐப் பயன்படுத்துவது சிறந்தது. இதில் ஒரு கவனிக்க வேண்டிய விஷயம்: cron job உங்கள் login கோப்புகளை source செய்யாது. எனவே, crontab வரியில் அதற்கான GEMINI_API_KEY-ஐ வழங்கவும் (அல்லது கட்டளையை ~/.gemini_env-ஐ source செய்ய வைக்கவும்), இல்லையெனில் CLI browser flow-க்குச் சென்று தோல்வியடையும்.

தயாரிப்புச் சூழல் (production) இயங்கும் server-ல் Sandboxing மற்றும் அனுமதிகள்

Shell access கொண்ட ஒரு agent என்பது ஒரு shell-க்கு சமமானது. Gemini CLI கட்டளைகளை இயக்க முடியும். இயல்பாக, ஆபத்தான ஒவ்வொரு கட்டளைக்கு முன்பும் இது அனுமதி கேட்கும். ஆனால், பயனர்கள் --yolo-ஐப் பயன்படுத்தும்போது (ஒவ்வொரு tool அழைப்பையும் தானாகவே அனுமதிக்கும்), அது கோப்புகளை நீக்கலாம், git-க்கு push செய்யலாம் அல்லது அந்தப் பயனர் பெற்றுள்ள முழு அதிகாரத்துடன் உள்நாட்டுச் சேவைகளை (internal services) அணுகலாம். தயாரிப்புச் சூழல் இயங்கும் ஒரு server-ல், இது வெறும் கற்பனை அல்ல, மிக மோசமான பாதிப்பை ஏற்படுத்தக்கூடிய நிஜமான ஆபத்து.

இதைக் கட்டுப்படுத்த மூன்று வழிகள் உள்ளன, அவற்றின் முக்கியத்துவ வரிசையில் கீழே கொடுக்கப்பட்டுள்ளன:

• அதிகாரங்கள் இல்லாத ஒரு பிரத்யேகப் பயனராக (dedicated, unprivileged user) இயக்கவும். root பயனராகவோ அல்லது sudo குழுவில் உள்ள பயனராகவோ இயக்க வேண்டாம். சொந்த home directory கொண்ட ஒரு agent பயனரை உருவாக்கி, அங்கு Node மற்றும் CLI-ஐ நிறுவவும். தவறான கட்டளை ஒன்று இயக்கப்பட்டாலும், அது அந்தப் பயனர் கணக்கிற்குள்ளேயே கட்டுப்படுத்தப்படும். இதுவே மிக முக்கியமான பாதுகாப்பு நடவடிக்கையாகும்.
• தயாரிப்புச் சூழலுக்கான (production) credentials-ஐ அந்த server-ல் வைக்க வேண்டாம். தயாரிப்புச் சூழலுக்கான ~/.aws/credentials, அங்கிருந்து நகலெடுக்கப்பட்ட .env அல்லது முக்கியமான எதையும் மாற்றக்கூடிய database கடவுச்சொற்கள் எதையும் அங்கு வைத்திருக்க வேண்டாம். அதற்குப் பதிலாக, staging அல்லது read-only அனுமதிகள் கொண்ட credentials-ஐ மட்டும் வழங்கவும்.
• உள்ளமைக்கப்பட்ட sandbox-ஐப் பயன்படுத்தவும். Docker அல்லது Podman நிறுவப்பட்டிருந்தால், gemini --sandbox (அல்லது GEMINI_SANDBOX=docker) மூலம் agent-ன் tool அழைப்புகளை host filesystem மற்றும் network-லிருந்து தனிமைப்படுத்தப்பட்ட container-க்குள் இயக்கலாம். இது unprivileged user-க்கு மாற்றாகாது, ஆனால் அதே VPS-ல் முக்கியமான பணிகள் நடக்கும்போது இது ஒரு வலுவான இரண்டாவது பாதுகாப்பு அடுக்காகச் செயல்படும்.

அதே VPS-ல் பிற self-hosted கருவிகளுடன் Gemini CLI-ஐ நீங்கள் இயக்குகிறீர்கள் என்றால், உதாரணமாக agent-க்கு கருவிகளை வழங்கும் MCP server, சேர்க்கப்படும் ஒவ்வொரு கூடுதல் வசதியையும் agent அணுகக்கூடிய ஒரு பரப்பாகக் கருத வேண்டும். மேலும், அதற்கு வழங்கப்படும் tokens-ஐ ஒரு குறிப்பிட்ட பணிக்கு மட்டும் கட்டுப்படுத்த வேண்டும்.

Quota, cost, மற்றும் நீங்கள் தேர்ந்தெடுக்கும் auth path

Auth path என்பது உங்களுக்கு எவ்வாறு கட்டணம் வசூலிக்கப்படும் என்பதைத் தீர்மானிக்கிறது. ஒரு தனிப்பட்ட Google account (OAuth path) இலவச Gemini Code Assist tier-ஐப் பயன்படுத்துகிறது; இதில் நிமிடத்திற்கு மற்றும் ஒரு நாளைக்கு எனத் தெளிவான வரம்புகள் உள்ளன. இந்த வரம்புகளைத் தாண்டினால், குறிப்பிட்ட கால இடைவெளி முடியும் வரை கோரிக்கைகள் rate-limit பிழையைத் தரும். AI Studio-விலிருந்து பெறப்படும் API key, project-ஐப் பொறுத்து இலவசமாகவோ அல்லது கட்டண அடிப்படையிலோ இருக்கலாம். கட்டண அடிப்படையிலான key வரம்புகளை உயர்த்துவதுடன், ஒவ்வொரு token-க்கும் கட்டணம் வசூலிக்கும். Vertex மற்றும் Cloud-project auth ஆகியவை Google Cloud வழியாகக் கட்டணம் வசூலிக்கின்றன.

இரண்டு நடைமுறை குறிப்புகள். ஒரு loop-ல் இயங்கும் unattended agent மிக வேகமாக quota-வைச் செலவிடக்கூடும். எனவே, அதை ஒரு cron job-ல் நம்பி ஒப்படைக்கும் முன், முதல் சில முறை அதைக் கண்காணிப்பது அவசியம். Google-ன் hosted models-க்கு மாற்றாக, தனியுரிமை (privacy) அல்லது வரம்பற்ற inference தேவைக்காக நீங்கள் server-side model-ஐத் தேடுகிறீர்கள் என்றால், அது ஒரு வேறுபட்ட கருவியாகும். Ollama மூலம் VPS-ல் open LLM-ஐ self-hosting செய்தல் என்பது weights மற்றும் prompts-ஐ உங்கள் சொந்த server-லேயே வைத்திருக்கும். ஆனால், இதற்குப் பதிலாக Gemini-யை விட மிகச் சிறிய model-ஐ மட்டுமே உங்களால் இயக்க முடியும்.

புதுப்பித்தல்

Gemini CLI அடிக்கடி புதிய பதிப்புகளை வெளியிடுகிறது. நீங்கள் இதை பயனர் உரிமையுள்ள prefix-ல் நிறுவியுள்ளதால், புதுப்பிப்புகளுக்கு sudo தேவைப்படாது:

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

இதில் பல்வேறு release channels உள்ளன: @latest என்பது நிலையான பதிப்பு, @preview என்பது வாராந்திர முன்னோட்டப் பதிப்பு, @nightly என்பது புதிய மாற்றங்கள் கொண்ட பதிப்பு. நீங்கள் சார்ந்திருக்கும் எதற்கும் @latest-ஐப் பயன்படுத்தவும். nvm-ல், global packages அனைத்தும் தற்போதுள்ள Node பதிப்பின் கீழ் இயங்கும். எனவே, Node-ஐ மாற்ற nvm use கட்டளையைப் பயன்படுத்திய பிறகு, CLI-ஐ மீண்டும் நிறுவ வேண்டியிருக்கலாம். ஒவ்வொரு சிறிய மாற்றத்தையும் (patch) பின்தொடர்வதை விட, release notes-ஐப் படித்துப் புரிந்துகொள்வது சிறந்தது.

தோல்வி முறைகள் மற்றும் துல்லியமான சரங்கள் (strings)

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, மற்றும் runtime-ல் CLI செயலிழத்தல். Node பதிப்பு மிகவும் பழையது, distro-வில் உள்ள 18.19.1 பதிப்பு ஏற்கனவே காலாவதியாகிவிட்டது (end-of-life). NodeSource அல்லது nvm மூலம் Node 20+ பதிப்பை நிறுவி, node --version மூலம் உறுதிப்படுத்தவும். பல Node பதிப்புகள் நிறுவப்பட்டிருந்தால், which node புதிய பதிப்பைச் சுட்டிக்காட்டுகிறதா என்பதைச் சரிபார்க்கவும், /usr/bin/node-ஐ அல்ல.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. root உரிமையுள்ள prefix-ல் global நிறுவல் செய்யப்பட்டுள்ளது. இதற்கு sudo பயன்படுத்த வேண்டாம்; npm config set prefix ~/.npm-global-ஐ அமைக்கவும், ~/.npm-global/bin-ஐ PATH-ல் சேர்க்கவும், பின்னர் உங்கள் சாதாரண பயனர் கணக்கில் மீண்டும் நிறுவவும். முன்னதாக sudo npm மூலம் root உரிமையுள்ள cache கோப்புகள் (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 flow-க்கு server-ல் இல்லாத ஒரு browser தேவைப்படுகிறது, மேலும் அதன் localhost callback உங்கள் laptop-ஐ அல்லாமல் server-ஐச் சுட்டிக்காட்டுகிறது. API-key வழியைப் பயன்படுத்தவும் (GEMINI_API_KEY), அல்லது OAUTH_CALLBACK_PORT-ஐ pin செய்து, ssh -L மூலம் SSH வழியாக forward செய்து, URL-ஐ உள்ளூரில் திறக்கவும்.

SSH துண்டிக்கப்பட்டபோது செயல்முறை (process) மறைந்துவிட்டது. நீங்கள் gemini-ஐ நேரடியாக SSH shell-லிருந்து இயக்கியுள்ளீர்கள், எனவே அது அந்த shell-ன் child process ஆக இருந்து, இணைப்பு துண்டிக்கப்பட்டபோது pty-யுடன் சேர்ந்து முடிந்துவிட்டது. மீட்டெடுக்க எதுவும் இல்லை. ஒவ்வொரு அமர்வையும் tmux new -A -s gemini உடன் தொடங்கி, CLI-ஐ அதற்குள் இயக்கவும்.

Key அமைக்கப்பட்டிருந்தும் அங்கீகாரம் (auth) தோல்வியடைதல், CLI மீண்டும் auth picker-க்கு திரும்புதல், அல்லது கோரிக்கை 400 HTTP குறியீட்டுடன் API key not valid-ஐத் தருதல். CLI பார்க்கும் environment-ல் key இல்லை. printenv GEMINI_API_KEY மூலம் உறுதிப்படுத்தவும்; அது காலியாக இருந்தால், உங்கள் ~/.gemini_env source செய்யப்படவில்லை என்று அர்த்தம். அந்த வரி ~/.bashrc-ல் உள்ளதா எனச் சரிபார்க்கவும்; இதை interactive shells (tmux உட்பட) படிக்கும், ஆனால் cron மற்றும் பிற non-interactive shells படிக்காது. Key மதிப்பில் உள்ள தேவையற்ற இடைவெளி அல்லது மேற்கோள் குறி (quote) கூட API key not valid-ஐ உருவாக்கலாம்.

429 / RESOURCE_EXHAUSTED / rate-limit செய்தி. உங்கள் அங்கீகாரம் பயன்படுத்தும் tier-க்கான ஒதுக்கீட்டை (quota) நீங்கள் கடந்துவிட்டீர்கள். window reset ஆகும் வரை காத்திருக்கவும், agent-ன் வேகத்தைக் குறைக்கவும், அல்லது கட்டண API key-க்கு மாறவும். Retry loop-ல் சிக்கியிருக்கும் ஒரு agent தொடர்ந்து இதைத் தூண்டும், எனவே அதை நிறுத்திவிட்டு அது என்ன செய்கிறது என்பதைச் சரிபார்க்கவும்.

FAQ

Headless server-ல் Gemini CLI-ஐ எவ்வாறு authenticate செய்வது?

Browser login-க்கு பதிலாக API key-ஐப் பயன்படுத்தவும். Google AI Studio-வில் ஒரு key-ஐ உருவாக்கி, அதை உங்கள் shell source செய்யும் mode-600 கோப்பில் (export GEMINI_API_KEY=...) சேமிக்கவும். இவ்வாறு செய்தால், CLI ஆனது OAuth browser flow-ஐ முழுமையாகத் தவிர்க்கும். நீங்கள் தனிப்பட்ட கணக்கின் free tier-ஐப் பயன்படுத்த விரும்பினால், OAUTH_CALLBACK_PORT=8085 மூலம் loopback port-ஐ pin செய்து, அதை ssh -L 8085:localhost:8085 user@server மூலம் உங்கள் laptop-க்கு forward செய்து, திரையில் தோன்றும் URL-ஐ உள்ளூரில் திறக்கவும். ஆனால், இதற்கு நீங்கள் browser-க்கு முன்னால் இருக்க வேண்டும் என்பதால், இது scripts-க்கு உகந்ததல்ல.

npm global install-க்கு ஏன் sudo தேவைப்படுகிறது, அதை எவ்வாறு தவிர்ப்பது?

npm-ன் default global prefix /usr/lib/node_modules என்பதால், அதில் உங்கள் user-ஆல் எழுத முடியாது. எனவே, சாதாரண npm install -g கட்டளை EACCES பிழையுடன் தோல்வியடையும். sudo npm -g-ஐப் பயன்படுத்துவது தவறான தீர்வாகும், ஏனெனில் இது root-க்குச் சொந்தமான கோப்புகளை உருவாக்கி, பிற்கால install-களைப் பாதிக்கும். சரியான தீர்வு, prefix-ஐ உங்கள் home directory-க்கு (npm config set prefix ~/.npm-global) மாற்றி, அதன் bin-ஐ PATH-ல் சேர்ப்பது அல்லது nvm-ஐப் பயன்படுத்துவது ஆகும்; இது global packages-ஐ உங்கள் home-க்குள்ளேயே தானாகவே நிறுவும்.

நான் disconnect செய்த பிறகும் Gemini CLI-ஐ எவ்வாறு தொடர்ந்து இயங்க வைப்பது?

அதை tmux-க்குள் இயக்கவும். SSH shell-லிருந்து தொடங்கப்படும் ஒரு process, connection துண்டிக்கப்படும்போது நின்றுவிடும், ஏனெனில் அது அந்த shell-ன் child process ஆகும். tmux, disconnect ஆனாலும் இயங்கக்கூடிய ஒரு detached server-ன் கீழ் shell-ஐ இயக்குகிறது. tmux new -A -s gemini-ஐப் பயன்படுத்தவும், உள்ளே gemini-ஐ இயக்கவும், Ctrl-b d மூலம் detach செய்யவும், பின்னர் tmux attach -t gemini மூலம் மீண்டும் இணைக்கவும்.

Production server-ல் Gemini CLI-ஐ இயக்குவது பாதுகாப்பானதா?

கவனத்துடன் இருந்தால் மட்டுமே பாதுகாப்பானது. ஏனெனில், shell access கொண்ட ஒரு agent, அது இயங்கும் user-க்கு என்னென்ன அதிகாரங்கள் உள்ளனவோ, அவை அனைத்தையும் செய்ய முடியும். இதை sudo அதிகாரம் இல்லாத, பிரத்யேகமான unprivileged user-ஆக இயக்கவும். Production credentials-ஐ அந்த machine-ல் வைக்க வேண்டாம். --yolo auto-approval-ஐத் தவிர்க்கவும், மேலும் tool calls-ஐ host-லிருந்து பிரிக்க --sandbox (Docker அல்லது Podman) பயன்படுத்தவும். நீங்கள் அமைக்கும் எந்தவொரு flag-ஐ விடவும், அது எந்த user கணக்கின் கீழ் இயங்குகிறது என்பதே முக்கியமானது.

Gemini CLI-க்காக firewall-ல் ஏதேனும் port-களைத் திறக்க வேண்டுமா?

தேவையில்லை. இது Google-ன் API-களுக்கு outbound HTTPS அழைப்புகளைச் செய்யும் ஒரு client ஆகும். எனவே, இதற்கு outbound port 443 தேவை, ஆனால் inbound port-கள் தேவையில்லை. நீங்கள் OAuth tunnel-ஐப் பயன்படுத்தினால், அந்த callback port (உதாரணமாக 8085) localhost-ல் மட்டுமே இருக்கும். அது உங்கள் SSH forward வழியாகவே அணுகப்படும், திறந்த நிலையில் உள்ள inbound port வழியாக அல்ல. Inbound port-களைப் பாதுகாப்பாக மூடி வைக்கவும்.