Gemini CLI کو Headless VPS پر کیسے چلائیں

آپ کیا بنا رہے ہیں

آپ کے اپنے سرور پر ایک ہمیشہ فعال رہنے والا Gemini CLI، جو SSH کے ذریعے قابل رسائی ہو، اور ایسے طویل ایجنٹ ٹاسک چلا رہا ہو جو آپ کے لیپ ٹاپ بند کرنے کے بعد بھی جاری رہیں۔ اس کی تنصیب صرف 3 کمانڈز پر مشتمل ہے۔ اصل کام وہ ہے جو ڈیسک ٹاپ ماحول کو فرض کر لیتا ہے: Google کا CLI لاگ ان کے لیے براؤزر کھولنا چاہتا ہے، جبکہ آپ کے سرور پر براؤزر موجود نہیں ہوتا۔ لہذا اس گائیڈ کا زیادہ تر حصہ headless طریقہ کار، Node کا جدید ورژن جو آپ کی ڈسٹرو میں دستیاب نہیں، ایک global npm انسٹال جسے root کی ضرورت نہیں، API key کے ساتھ بغیر براؤزر کے تصدیق (auth) جسے آپ اپنی shell history سے دور رکھتے ہیں، اور tmux کے بارے میں ہے تاکہ SSH سیشن منقطع ہونے سے چلتا ہوا ٹاسک ختم نہ ہو۔

Gemini CLI ایک اوپن سورس (Apache-2.0) Node پروگرام (@google/gemini-cli) ہے جو Google کے Gemini ماڈلز سے بات کرتا ہے اور فائلیں پڑھنے، لکھنے، shell کمانڈز چلانے، اور ورکنگ ڈائریکٹری میں ٹولز کو کنٹرول کرنے کی صلاحیت رکھتا ہے۔ VPS پر یہ ایک چھوٹا، ہمیشہ دستیاب ایجنٹ ہے جسے آپ کام پر چھوڑ سکتے ہیں، اسی لیے جس اکاؤنٹ سے یہ چلتا ہے اور جو اسناد (credentials) سرور پر موجود ہوتی ہیں، وہ یہاں موجود کسی بھی ایک سیٹنگ سے زیادہ اہم ہیں۔

تقاضے اور اہم تکنیکی نکات

• ایک نیا Ubuntu 24.04 KVM VPS جس پر root یا sudo رسائی حاصل ہو۔ کوئی بھی KVM پلان کارآمد ہے؛ CLI خود ہلکا ہے اور idle حالت میں چند سو MB RAM استعمال کرتا ہے۔
• Node.js 20 یا اس سے نیا ورژن۔ یہ ایک لازمی ورژن کی حد ہے، اور ڈسٹرو کا پیکیج اس سے پرانا ہے، تفصیلات اگلے سیکشن میں دیکھیں۔
• Google APIs کے لیے آؤٹ باؤنڈ HTTPS (port 443)۔ کسی ان باؤنڈ پورٹ کی ضرورت نہیں ہے؛ یہ ایک کلائنٹ ہے، سرور نہیں، لہذا اس کے لیے فائر وال میں کوئی سوراخ کرنے کی ضرورت نہیں ہے۔
• تصدیق (authentication) کا ایسا طریقہ جس کے لیے سرور پر براؤزر کی ضرورت نہ ہو: یا تو Google AI Studio سے حاصل کردہ Gemini API key، یا اپنی مشین پر موجود براؤزر تک SSH ٹنل۔ API-key کا راستہ اسکرپٹس اور خودکار رن (unattended runs) کے لیے موزوں ہے۔
• Docker یا Podman، صرف تب اگر آپ --sandbox آئسولیشن چاہتے ہیں۔ یہ اختیاری ہے اور آخر میں اس کا احاطہ کیا گیا ہے۔

وہ تکنیکی رکاوٹ جو سب کو درپیش آتی ہے: دوستانہ gemini فرسٹ رن لاگ ان فلو ڈیسک ٹاپ کے لیے بنایا گیا ہے۔ یہ براؤزر کھولنے کی کوشش کرتا ہے اور headless مشین پر یا تو ناکام ہو جاتا ہے یا آپ کو ایسا لنک دیتا ہے جو کام نہیں کرتا۔ شروع کرنے سے پہلے تصدیق کے راستے کا تعین کر لیں۔

نوٹ: ڈسٹرو کا پیکیج بہت پرانا ہے

Ubuntu 24.04 اپنی ریپوزٹریز میں Node 18.19.1 فراہم کرتا ہے، جس کے ساتھ npm 9.2.0 ہوتا ہے۔ Gemini CLI کی package.json میں engines: { node: ">=20" } کا اعلان کیا گیا ہے، اور npm بائی ڈیفالٹ اس عدم مطابقت (mismatch) پر انسٹالیشن کو نہیں روکتا، بلکہ یہ انسٹال کر کے ایک وارننگ دیتا ہے جو اس فرق کو ظاہر کرتی ہے:

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 چلانے سے یہ غیر تعاون یافتہ (unsupported) رن ٹائم پر چلے گا، جہاں یہ غلط برتاؤ کرے گا یا جیسے ہی اسے کسی ایسے Node 20+ API کی ضرورت پڑے گی جو موجود نہیں، یہ کریش ہو جائے گا۔ Node 18 اپریل 2025 میں اپنی مدت پوری کر چکا ہے (end-of-life)، لہذا یہ ہر صورت میں ایک بند گلی ہے۔ CLI انسٹال کرنے سے پہلے ایک موجودہ LTS انسٹال کریں۔ دو صاف ستھرے راستے یہ ہیں: NodeSource (ایک سسٹم وائیڈ سائنڈ apt ریپو) یا nvm (ایک فی صارف ورژن مینیجر)۔ کسی ایک کا انتخاب کریں۔

NodeSource، اگر آپ چاہتے ہیں کہ 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 موجودہ فعال LTS ہے۔ موجودہ سیٹ اپ اسکرپٹ کے لیے NodeSource کا صفحہ چیک کریں؛ URL میں موجود setup_24.x وہ لائن ہے جسے نئے LTS کے آنے پر اپ ڈیٹ کرنا ہوتا ہے۔

nvm، اگر آپ Node کو صرف ایک صارف کی ہوم ڈائریکٹری میں رکھنا چاہتے ہیں اور اسے کبھی 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 اور اس کے گلوبل پیکیجز کو ~/.nvm کے تحت انسٹال کرتا ہے، لہذا اگلے سیکشن میں گلوبل انسٹالیشن کی اجازت کا مسئلہ کبھی پیش نہیں آتا۔ اگر آپ nvm کا راستہ اختیار کرتے ہیں، تو آپ npm-prefix والا مرحلہ چھوڑ سکتے ہیں۔

بغیر sudo npm -g کے CLI انسٹال کرنا

ایک پرکشش کمانڈ sudo npm install -g @google/gemini-cli ہے۔ اسے ہرگز نہ چلائیں۔ root کی ملکیت والا global prefix بعد میں ہر انسٹالیشن پر permission errors پیدا کرتا ہے اور آپ کے npm cache میں root کی ملکیت والی فائلیں چھوڑ دیتا ہے جو مہینوں بعد مسائل کا باعث بنتی ہیں۔ اگر آپ سسٹم 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 ڈائریکٹری کی طرف موڑنا ہے تاکہ 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

~/.bashrc کا استعمال، نہ کہ ~/.profile کا، جان بوجھ کر ہے: tmux، جس کے اندر آپ دو سیکشنز کے بعد CLI چلائیں گے، ایک non-login shell شروع کرتا ہے جو ~/.bashrc کو پڑھتا ہے اور ~/.profile کو چھوڑ دیتا ہے، لہذا غلط فائل میں PATH لائن آپ کو ٹھیک اسی جگہ gemini سے محروم کر دے گی جہاں اس کی ضرورت ہے۔ gemini --version کا ورژن نمبر پرنٹ کرنا ہی مکمل ٹیسٹ ہے۔ اگر اس کے بجائے آپ کو gemini: command not found موصول ہو، تو اس کا مطلب ہے کہ آپ کا PATH ایکسپورٹ لاگو نہیں ہوا، ناکامی کی وجوہات دیکھیں۔ اگر آپ nvm استعمال کر رہے ہیں تو prefix والی لائنوں کو مکمل طور پر چھوڑ دیں: یہ پہلے ہی globals کو آپ کی home ڈائریکٹری میں انسٹال کرتا ہے۔

اگر آپ نے پہلے کسی موقع پر 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) میں ایک کی (key) بنائیں اور اسے بطور environment variable CLI کو فراہم کریں؛ یہ GEMINI_API_KEY کو پڑھتا ہے اور براؤزر والے عمل کو مکمل طور پر چھوڑ دیتا ہے۔ اب "اسے ہسٹری اور سب کے لیے قابلِ مطالعہ فائلوں سے دور رکھنے" والے حصے پر توجہ دیں۔ کمانڈ پرامپٹ پر export GEMINI_API_KEY=AIza... ہرگز ٹائپ نہ کریں، کیونکہ یہ ~/.bash_history میں سادہ متن (cleartext) کی صورت میں محفوظ ہو جائے گا، اور اسے ایسی فائل میں بھی نہ رکھیں جسے دوسرے پڑھ سکیں۔ اسے mode-600 والی فائل میں لکھیں جسے شیل (shell) شروع ہوتے وقت لوڈ کرے:

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 کا مطلب ہے کہ صرف آپ کا صارف ہی اس فائل کو پڑھ سکتا ہے۔ printenv GEMINI_API_KEY کے ذریعے تصدیق کریں کہ کی (key) ماحول (environment) تک پہنچ گئی ہے؛ اگر یہ کچھ پرنٹ نہ کرے، تو CLI واپس براؤزر والے عمل پر چلا جائے گا اور ناکام ہو جائے گا۔ اگر آپ اس لے آؤٹ کو ترجیح دیتے ہیں تو یہ ~/.gemini/ میں موجود .env فائل کو بھی پڑھتا ہے، اصول وہی ہے، اس لیے chmod 600 ~/.gemini/.env کا استعمال کریں۔

دوسرا طریقہ OAuth کال بیک کو اپنے لیپ ٹاپ پر ٹنل (tunnel) کر کے ذاتی Google اکاؤنٹ لاگ ان (اور اس کے فری ٹائر) کو برقرار رکھتا ہے۔ مسئلہ یہ ہے کہ CLI کا لوپ بیک سرور ہر بار ایک بے ترتیب پورٹ پر بائنڈ ہوتا ہے، اس لیے جب تک آپ اسے OAUTH_CALLBACK_PORT environment variable کے ساتھ پن (pin) نہ کر دیں، فارورڈ کرنے کے لیے کوئی مستقل پورٹ نہیں ہوتی، پھر اسی پورٹ کو فارورڈ کریں:

# 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 فارورڈ اسے VPS پر لوپ بیک سرور تک پہنچا دے گا اور لاگ ان مکمل ہو جائے گا۔ اگر آپ پورٹ کو پن نہیں کریں گے تو یہ ہر بار ایک نئی بے ترتیب پورٹ پر لینڈ کرے گا، جسے پہلے سے سیٹ کیا گیا کوئی ssh -L نہیں پکڑ سکتا۔ یہ کام تو کرتا ہے، لیکن اس کے لیے آپ کا براؤزر کے سامنے موجود ہونا ضروری ہے، اس لیے یہ اسکرپٹس کے لیے موزوں نہیں ہے۔ ایسی کسی بھی چیز کے لیے جو آپ مستقل چلانا چاہتے ہیں، API key استعمال کریں۔

AI Studio کے بجائے Vertex AI یا Google Cloud پروجیکٹ کے لیے، GOOGLE_GENAI_USE_VERTEXAI=true کے ساتھ GOOGLE_API_KEY سیٹ کریں، یا Code Assist لائسنس کے لیے GOOGLE_CLOUD_PROJECT سیٹ کریں، طریقہ کار اور environment-variable کا اصول وہی رہے گا، اور mode-600 والی فائل کا استعمال بھی ویسا ہی ہوگا۔

اسے tmux کے اندر چلائیں تاکہ SSH سیشن منقطع ہونے پر یہ بند نہ ہو

آپ کے SSH شیل سے براہ راست شروع کیا گیا gemini عمل اسی شیل کا ایک ذیلی عمل (child process) ہوتا ہے۔ کنکشن کا ٹوٹنا، لیپ ٹاپ کا بند ہونا، Wi-Fi کا منقطع ہونا، یا idle timeout کی صورت میں sshd سیوڈو ٹرمینل کو ختم کر دیتا ہے، شیل کو SIGHUP سگنل موصول ہوتا ہے، اور یہ CLI کو بند کر دیتا ہے۔ فائل ایڈیٹنگ کے دوران دس منٹ کا کام اس کے ساتھ ہی ضائع ہو جاتا ہے، اور دوبارہ کنیکٹ ہونے پر کوئی عمل بحالی کے لیے موجود نہیں ہوتا۔

tmux اس مسئلے کو حل کرتا ہے کیونکہ یہ شیل کا مالک بن جاتا ہے، نہ کہ sshd۔ یہ وہی طریقہ کار ہے جو کسی ریموٹ 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 نامی سیشن موجود ہو تو اس سے منسلک ہو جاتا ہے، اور اگر نہ ہو تو اسے تخلیق کر دیتا ہے، لہذا ہر بار لاگ ان ہونے کے بعد چلانے کے لیے یہ واحد کمانڈ ہے۔ اس کے اندر موجود شیل کا تعلق detached tmux سرور سے ہوتا ہے، نہ کہ آپ کے SSH سیشن سے، اس لیے کنکشن ٹوٹنے کے باوجود CLI کام کرتا رہتا ہے۔ دوبارہ کنیکٹ کریں، منسلک ہوں، اور آپ اسی اسکرول بیک (scrollback) پر واپس آ جائیں گے۔ اگر آپ ایک ہی مشین پر کئی ایجنٹ سیشنز چلاتے ہیں، ہر ایک الگ tmux سیشن میں، تو ان کا آپس میں رابطہ ممکن نہیں ہوتا، برخلاف Claude Code کے جہاں ایک سیشن اسی VPS پر دوسرے سیشن کو ٹیکسٹ بھیج سکتا ہے، اس لیے ہر Gemini جاب کو آزاد رکھیں یا ڈسک پر موجود فائلوں کے ذریعے ان میں ہم آہنگی پیدا کریں۔

غیر انٹرایکٹو اور اسکرپٹڈ رنز کے لیے، Gemini CLI میں ایک ہیڈلیس موڈ موجود ہے: gemini -p "summarise the failing tests in this repo" جواب پرنٹ کر کے بند ہو جاتا ہے، اور --output-format json مشین کے پڑھنے کے قابل آؤٹ پٹ دیتا ہے جسے کہیں اور پائپ (pipe) کیا جا سکتا ہے۔ API کی کے ساتھ ہیڈلیس موڈ وہی ہے جو آپ کو ایک طویل بیچ جاب چلانے والے tmux سیشن کے اندر، یا cron انٹری سے چلانے کے لیے درکار ہوتا ہے، ایک انتباہ کے ساتھ: cron جاب آپ کی لاگ ان فائلز کو سورس (source) نہیں کرتی، اس لیے crontab لائن کو اس کی اپنی GEMINI_API_KEY دیں (یا کمانڈ کو ~/.gemini_env سورس کروائیں)، ورنہ CLI براؤزر فلو پر واپس چلا جائے گا اور ناکام ہو جائے گا۔

پروڈکشن چلانے والے سرور پر سینڈ باکسنگ اور اجازتیں

شیل تک رسائی رکھنے والا ایجنٹ بذات خود ایک شیل ہے۔ Gemini CLI کمانڈز چلا سکتا ہے، اور بائی ڈیفالٹ یہ ہر خطرناک کمانڈ سے پہلے پوچھتا ہے، لیکن لوگ --yolo (ہر ٹول کال کو خودکار طور پر منظور کرنا) استعمال کرنے لگتے ہیں، اور پھر یہ فائلیں ڈیلیٹ کر سکتا ہے، git پر پش کر سکتا ہے، یا اس صارف کے مکمل اختیارات کے ساتھ اندرونی سروسز تک رسائی حاصل کر سکتا ہے جس کے طور پر یہ چل رہا ہے۔ ایسے سرور پر جو پروڈکشن بھی چلا رہا ہو، یہ ایک حقیقی خطرہ ہے، نہ کہ صرف فرضی۔

تین کنٹرولز، ان کی افادیت کی ترتیب کے مطابق:

• اسے ایک مخصوص، غیر مراعات یافتہ (unprivileged) صارف کے طور پر چلائیں۔ نہ root، نہ sudo کا ممبر۔ ایک agent صارف بنائیں جس کی اپنی ہوم ڈائریکٹری ہو، وہاں Node اور CLI انسٹال کریں، اور غلطی سے پڑھی گئی کوئی ہدایت اسی اکاؤنٹ تک محدود رہے گی۔ یہ واحد سب سے اہم فیصلہ ہے۔
• پروڈکشن کی اسناد (credentials) کو سرور پر نہ رکھیں۔ کوئی پروڈکشن ~/.aws/credentials نہیں، پروڈکشن سے کاپی کی گئی کوئی .env نہیں، اور نہ ہی کوئی ایسا ڈیٹا بیس پاس ورڈ جس کے پاس کسی اہم چیز تک رائٹ (write) رسائی ہو۔ اسے صرف سٹیجنگ یا ریڈ اونلی (read-only) اسناد دیں۔
• بلٹ ان سینڈ باکس کا استعمال کریں۔ Docker یا Podman انسٹال ہونے کے ساتھ، gemini --sandbox (یا GEMINI_SANDBOX=docker) ایجنٹ کی ٹول کالز کو ایک ایسے کنٹینر کے اندر چلاتا ہے جو ہوسٹ فائل سسٹم اور نیٹ ورک سے الگ تھلگ ہوتا ہے۔ یہ غیر مراعات یافتہ صارف کا متبادل نہیں ہے، لیکن جب ایک ہی VPS حقیقی کام کر رہا ہو تو یہ ایک مضبوط دوسری تہہ ہے۔

اگر آپ Gemini CLI کو دیگر self-hosted ٹولز کے ساتھ چلا رہے ہیں، مثلاً ایک MCP سرور جو اسی VPS پر ایجنٹ کو ٹولز فراہم کرتا ہے، تو ہر شامل کردہ صلاحیت کو ایجنٹ کی پہنچ میں آنے والی مزید سطح سمجھیں، اور اسے دیے گئے ٹوکنز کو صرف ایک کام تک محدود رکھیں۔

کوٹہ، لاگت، اور آپ کا منتخب کردہ تصدیقی راستہ

تصدیقی راستہ (auth path) یہ طے کرتا ہے کہ آپ کو بل کیسے بھیجا جائے گا۔ ایک ذاتی Google اکاؤنٹ (OAuth راستہ) مفت Gemini Code Assist ٹائر استعمال کرتا ہے، جس میں فی منٹ اور فی دن کی واضح حدود ہوتی ہیں۔ ان حدود سے تجاوز کرنے پر درخواستیں rate-limit ایرر دیتی ہیں جب تک کہ وقت کا دورانیہ دوبارہ شروع نہ ہو جائے۔ AI Studio سے حاصل کردہ API key پروجیکٹ کے لحاظ سے مفت ٹائر یا بلنگ والی ہو سکتی ہے؛ بلنگ والی key حدود کو بڑھا دیتی ہے اور فی ٹوکن چارج کرتی ہے۔ Vertex اور Cloud-project کی تصدیق Google Cloud کے ذریعے بلنگ کرتی ہے۔

دو عملی نکات: ایک خودکار ایجنٹ (unattended agent) جو لوپ میں چل رہا ہو، تیزی سے کوٹہ ختم کر سکتا ہے، لہذا اسے cron job کے حوالے کرنے سے پہلے چند بار خود نگرانی کریں۔ اور اگر سرور سائیڈ ماڈل استعمال کرنے کی وجہ Google کے ہوسٹڈ ماڈلز کے بجائے پرائیویسی یا لامحدود inference ہے، تو یہ ایک مختلف ٹول ہے۔ Ollama کے ساتھ VPS پر اوپن LLM کی self-hosting ماڈل کے ویٹس اور پرامپٹس کو آپ کے اپنے سرور پر رکھتی ہے، جس کی قیمت یہ ہے کہ آپ Gemini کے مقابلے میں بہت چھوٹا ماڈل استعمال کرتے ہیں۔

اپ ڈیٹ رکھنا

Gemini CLI کے نئے ورژنز اکثر ریلیز ہوتے رہتے ہیں۔ چونکہ آپ نے اسے user-owned prefix میں انسٹال کیا ہے، اس لیے اپ ڈیٹس کے لیے کبھی بھی sudo کی ضرورت نہیں پڑتی:

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

اس کے ریلیز چینلز موجود ہیں: @latest مستحکم (stable) ورژن ہے، @preview ہفتہ وار پریویو ہے، @nightly سب سے نیا (bleeding edge) ورژن ہے، لہذا کسی بھی ایسی چیز پر جو آپ کے لیے اہم ہو، @latest کو پن (pin) کریں۔ nvm پر، global packages فعال Node ورژن کے تحت رہتے ہیں، اس لیے Node کو تبدیل کرنے کے لیے nvm use کے بعد آپ کو CLI دوبارہ انسٹال کرنے کی ضرورت پڑ سکتی ہے۔ ہر چھوٹی اپ ڈیٹ (patch) کے پیچھے بھاگنے کے بجائے ریلیز نوٹس پڑھیں۔

ناکام ہونے کے طریقے، درست strings کے ساتھ

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }، اور پھر runtime پر CLI کا کریش ہونا۔ Node کا ورژن بہت پرانا ہے، ڈسٹرو کا 18.19.1 ورژن اب end-of-life ہو چکا ہے۔ NodeSource یا nvm سے Node 20+ انسٹال کریں، node --version سے تصدیق کریں، اور اگر آپ کے پاس ایک سے زیادہ Nodes انسٹال ہیں تو چیک کریں کہ which node نئے ورژن کی طرف اشارہ کر رہا ہے نہ کہ /usr/bin/node کی۔

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'۔ root-owned prefix میں گلوبل انسٹالیشن۔ اسے sudo کے ساتھ نہ چلائیں، npm config set prefix ~/.npm-global سیٹ کریں، ~/.npm-global/bin کو PATH پر رکھیں، اور اپنے عام صارف کے طور پر دوبارہ انسٹال کریں۔ اگر کسی پچھلے sudo npm نے root-owned کیش فائلیں (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 کے ذریعے ssh -L کے ساتھ فارورڈ کریں، اور URL کو مقامی طور پر کھولیں۔

SSH منقطع ہونے پر پروسیس کا غائب ہو جانا۔ آپ نے gemini کو براہ راست SSH شیل سے چلایا، لہذا یہ اس شیل کا چائلڈ تھا اور کنکشن ٹوٹنے پر pty کے ساتھ ختم ہو گیا۔ اسے بحال کرنے کا کوئی طریقہ نہیں۔ ہر سیشن کو tmux new -A -s gemini کے ساتھ شروع کریں اور CLI کو اس کے اندر چلائیں۔

کی (key) سیٹ ہونے کے باوجود Auth کا ناکام ہونا، CLI کا واپس auth picker پر آ جانا، یا کسی درخواست کا HTTP 400 کے ساتھ API key not valid واپس کرنا۔ کی (key) اس ماحول (environment) میں موجود نہیں ہے جسے CLI دیکھتا ہے۔ printenv GEMINI_API_KEY کے ساتھ تصدیق کریں؛ اگر یہ خالی ہے تو آپ کا ~/.gemini_env کبھی سورس (source) نہیں ہوا تھا۔ چیک کریں کہ یہ لائن ~/.bashrc میں موجود ہے، جسے انٹرایکٹو شیلز (بشمول tmux) پڑھتے ہیں لیکن cron اور دیگر نان-انٹرایکٹو شیلز نہیں پڑھتے۔ کی (key) کی ویلیو میں ایک اضافی اسپیس یا کوٹ (quote) بھی API key not valid کا باعث بنتا ہے۔

429 / RESOURCE_EXHAUSTED / ریٹ-لمٹ کا پیغام۔ آپ نے اپنے auth ٹیر (tier) کا کوٹہ مکمل کر لیا ہے۔ ونڈو کے ری سیٹ ہونے کا انتظار کریں، ایجنٹ کی رفتار کم کریں، یا پیڈ (billed) API کی (key) پر منتقل ہو جائیں۔ ری ٹرائی لوپ میں پھنسا ہوا ایجنٹ بار بار یہ ایرر دیتا رہے گا، اسے روکیں اور چیک کریں کہ وہ کیا کر رہا ہے۔

FAQ

میں headless سرور پر Gemini CLI کو کیسے authenticate کروں؟

براؤزر لاگ ان کے بجائے API key استعمال کریں۔ Google AI Studio میں ایک key بنائیں، اسے mode-600 والی ایسی فائل میں رکھیں جسے آپ کی shell source کرتی ہو (export GEMINI_API_KEY=...)، اس طرح CLI مکمل طور پر OAuth براؤزر فلو کو چھوڑ دے گا۔ اگر آپ خاص طور پر ذاتی اکاؤنٹ کا free tier استعمال کرنا چاہتے ہیں تو loopback port کو OAUTH_CALLBACK_PORT=8085 کے ساتھ pin کریں، اسے ssh -L 8085:localhost:8085 user@server کے ذریعے اپنے لیپ ٹاپ پر forward کریں، اور پرنٹ شدہ URL کو مقامی طور پر کھولیں، لیکن اس کے لیے آپ کا براؤزر پر موجود ہونا ضروری ہے، لہذا یہ اسکرپٹس کے لیے موزوں نہیں ہے۔

npm global install کو sudo کیوں درکار ہوتا ہے، اور میں اس سے کیسے بچ سکتا ہوں؟

کیونکہ npm کا ڈیفالٹ global prefix /usr/lib/node_modules ہے، جس پر آپ کا صارف لکھ نہیں سکتا، اس لیے ایک سادہ npm install -g، EACCES کے ساتھ ناکام ہو جاتا ہے۔ غلط حل sudo npm -g ہے، جو root-owned فائلیں چھوڑ دیتا ہے اور بعد میں انسٹالیشنز کو خراب کرتا ہے۔ درست حل یہ ہے کہ prefix کو اپنی home ڈائریکٹری (npm config set prefix ~/.npm-global) کی طرف اشارہ کریں اور اس کے bin کو PATH میں شامل کریں، یا nvm استعمال کریں، جو خود بخود آپ کی home ڈائریکٹری کے تحت global پیکجز انسٹال کرتا ہے۔

میں disconnect ہونے کے بعد Gemini CLI کو کیسے چلتا رکھوں؟

اسے tmux کے اندر چلائیں۔ آپ کی SSH shell سے شروع ہونے والا عمل کنکشن ختم ہونے پر بند ہو جاتا ہے کیونکہ یہ اس shell کا child ہوتا ہے؛ tmux شیل کو ایک detached سرور کے تحت چلاتا ہے جو disconnect ہونے پر بھی برقرار رہتا ہے۔ tmux new -A -s gemini استعمال کریں، اس کے اندر gemini چلائیں، Ctrl-b d کے ساتھ detach کریں، اور بعد میں tmux attach -t gemini کے ساتھ دوبارہ reattach کریں۔

کیا پروڈکشن باکس پر Gemini CLI چلانا محفوظ ہے؟

صرف احتیاط کے ساتھ، کیونکہ shell تک رسائی رکھنے والا ایجنٹ وہ سب کچھ کر سکتا ہے جو وہ صارف کر سکتا ہے جس کے طور پر وہ چل رہا ہے۔ اسے کسی ایسے مخصوص غیر مراعات یافتہ (unprivileged) صارف کے طور پر چلائیں جس کے پاس sudo نہ ہو، پروڈکشن credentials کو مشین سے دور رکھیں، --yolo آٹو اپروول سے گریز کریں، اور ٹول کالز کو host سے الگ کرنے کے لیے --sandbox (Docker یا Podman) کا استعمال کریں۔ جس اکاؤنٹ کے تحت یہ چلتا ہے، وہ آپ کی سیٹ کردہ کسی بھی ایک flag سے زیادہ اہمیت رکھتا ہے۔

کیا مجھے Gemini CLI کے لیے کوئی firewall port کھولنے کی ضرورت ہے؟

نہیں۔ یہ ایک کلائنٹ ہے جو Google کی APIs کو outbound HTTPS کالز کرتا ہے، لہذا اسے outbound port 443 کی ضرورت ہوتی ہے لیکن کسی inbound port کی نہیں۔ اگر آپ OAuth ٹنل استعمال کرتے ہیں، تو pinned callback port (مثلاً 8085) localhost پر رہتی ہے اور آپ کی SSH forward کے ذریعے پہنچائی جاتی ہے، نہ کہ کسی کھلی inbound port کے ذریعے۔ inbound کو بند رکھیں۔