Headless VPS-এ Gemini CLI চালানোর নিয়ম

আপনি যা তৈরি করছেন

আপনার নিজস্ব সার্ভারে একটি সর্বদা সচল Gemini CLI, যা SSH-এর মাধ্যমে অ্যাক্সেস করা যায়। ল্যাপটপ বন্ধ করার পরেও এটি দীর্ঘমেয়াদী agent task সম্পন্ন করতে থাকবে। ইন্সটলেশন প্রক্রিয়াটি মাত্র তিনটি কমান্ডের। মূল চ্যালেঞ্জ হলো ডেস্কটপ নির্ভর বিষয়গুলো সামলানো: Google-এর CLI লগ-ইন করার জন্য একটি browser ওপেন করতে চায়, কিন্তু আপনার সার্ভারে কোনো browser নেই। তাই এই গাইডের বেশিরভাগ অংশই headless পদ্ধতি নিয়ে—যেখানে ডিস্ট্রোতে ডিফল্টভাবে পাওয়া যায় না এমন একটি আধুনিক Node প্রয়োজন, root ছাড়া global npm install প্রয়োজন, shell history-তে না রাখা একটি API key দিয়ে browserless auth প্রয়োজন, এবং tmux প্রয়োজন যাতে SSH session বিচ্ছিন্ন হয়ে গেলেও চলমান task বন্ধ না হয়।

Gemini CLI হলো একটি open-source (Apache-2.0) Node program (@google/gemini-cli) যা Google-এর Gemini models-এর সাথে যোগাযোগ করতে পারে। এটি ফাইল পড়া ও লেখা, shell commands চালানো এবং working directory-র টুলস পরিচালনা করতে পারে। একটি VPS-এ এটি একটি ছোট এবং সর্বদা উপলব্ধ agent হিসেবে কাজ করে যা আপনি চলমান অবস্থায় রেখে দিতে পারেন—তাই এটি যে account দিয়ে চলে এবং সার্ভারে থাকা credentials গুলো এখানে অন্য যেকোনো সেটিংসের চেয়ে বেশি গুরুত্বপূর্ণ।

পূর্বশর্ত এবং সম্ভাব্য সমস্যাসমূহ

• root বা sudo অ্যাক্সেসসহ একটি নতুন Ubuntu 24.04 KVM VPS। যেকোনো KVM প্ল্যান ব্যবহার করা যাবে; CLI অত্যন্ত হালকা, যা স্থির অবস্থায় মাত্র কয়েকশ MB RAM ব্যবহার করে।
• Node.js 20 বা তার পরবর্তী ভার্সন। এটি একটি অপরিহার্য ভার্সন সীমা, কারণ ডিস্ট্রো প্যাকেজটি এর নিচের ভার্সন — পরবর্তী বিভাগটি দেখুন।
• Google-এর APIs-এর জন্য Outbound HTTPS (port 443)। কোনো Inbound port প্রয়োজন নেই; এটি একটি ক্লায়েন্ট, সার্ভার নয়, তাই এর জন্য ফায়ারওয়াল ওপেন করার প্রয়োজন নেই।
• সার্ভারে ব্রাউজার ছাড়াই অথেন্টিকেশন করার একটি পদ্ধতি: হয় Google AI Studio থেকে একটি Gemini API key, অথবা আপনার নিজের মেশিনের ব্রাউজারে একটি SSH tunnel। স্ক্রিপ্ট এবং unattended রান করার জন্য API-key পদ্ধতিটি সবচেয়ে উপযোগী।
• Docker অথবা Podman, শুধুমাত্র যদি আপনি --sandbox isolation চান। এটি ঐচ্ছিক এবং নিবন্ধের শেষে আলোচনা করা হয়েছে।

সবচেয়ে সাধারণ সমস্যা: gemini-এর প্রথমবার লগইন করার সহজ পদ্ধতিটি ডেস্কটপ ইউজারদের জন্য তৈরি। এটি একটি ব্রাউজার খোলার চেষ্টা করে এবং headless সার্ভারের ক্ষেত্রে এটি ব্যর্থ হয় অথবা এমন একটি লিঙ্ক দেয় যা কাজ করে না। কাজ শুরু করার আগেই অথেন্টিকেশন পদ্ধতিটি নির্ধারণ করে নিন।

Node: distro package অত্যন্ত পুরনো

Ubuntu 24.04 এর নিজস্ব repositories এ Node 18.19.1 এবং npm 9.2.0 দেওয়া থাকে। Gemini CLI এর package.json এ engines: { node: ">=20" } উল্লেখ করা আছে। npm ডিফল্টভাবে ভার্সন অমিল (mismatch) হলে কাজ থামিয়ে দেয় না — এটি ইন্সটল করে এবং একটি warning দেয় যেখানে অমিলটি দেখানো হয়:

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 }

এই warning উপেক্ষা করে CLI চালালে এটি একটি unsupported runtime এ চলে। Node 20+ API ব্যবহার করার চেষ্টা করলে এটি ভুল আচরণ করে বা crash করে। Node 18 এর support 2025 এর এপ্রিল মাসে শেষ হয়ে গেছে, তাই এটি কোনোভাবেই কার্যকর নয়। CLI ইন্সটল করার আগে একটি বর্তমান LTS ইন্সটল করুন। এর দুটি সহজ উপায় হলো NodeSource (একটি system-wide signed apt repo) অথবা nvm (একটি per-user version manager)। যেকোনো একটি বেছে নিন।

আপনি যদি সার্ভারের প্রতিটি user এর জন্য 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 হলো বর্তমান active LTS। বর্তমান setup script এর জন্য NodeSource পেজটি দেখুন; নতুন LTS আসলে URL এর setup_24.x অংশটি পরিবর্তন করতে হবে।

আপনি যদি Node শুধুমাত্র একজন user এর home ডিরেক্টরিতে রাখতে চান এবং 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 এবং এর global packages গুলোকে ~/.nvm এর অধীনে ইন্সটল করে, তাই পরবর্তী সেকশনে বর্ণিত global-install permission সমস্যাটি আর হবে না। আপনি যদি nvm ব্যবহার করেন, তবে npm-prefix ধাপটি বাদ দিতে পারেন।

sudo npm -g ছাড়াই CLI install করুন

sudo npm install -g @google/gemini-cli কমান্ডটি আকর্ষণীয় মনে হতে পারে। কিন্তু এটি করবেন না। root-owned global prefix ব্যবহার করলে পরবর্তী প্রতিটি install-এ permission error দেখা দেবে এবং npm cache-এ root-owned ফাইল থেকে যাবে, যা কয়েক মাস পর সমস্যা তৈরি করবে। system Node-এর বিপরীতে একটি সাধারণ (no-sudo) npm install -g চালালে আপনি অন্য একটি 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'

npm এখানে /usr/lib-এ লিখার চেষ্টা করছে, যা আপনার user-এর পক্ষে সম্ভব নয়। এর সমাধান sudo নয় — বরং npm-এর global prefix আপনার home directory-তে নির্দেশ করা। এতে global install গুলো এমন জায়গায় জমা হবে যার মালিক আপনি:

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 দিয়ে version number প্রিন্ট করাটাই হলো মূল পরীক্ষা। যদি আপনি gemini: command not found পান, তবে বুঝতে হবে আপনার PATH export কাজ করেনি — failure modes দেখুন। nvm ব্যবহার করলে prefix সংক্রান্ত লাইনগুলো পুরোপুরি এড়িয়ে চলুন: এটি ইতিমধ্যে আপনার home-এর অধীনে globals install করে।

আপনি যদি আগে sudo npm চালিয়ে থাকেন এবং এখন Your cache folder contains root-owned files দেখেন, তবে sudo chown -R $(id -u):$(id -g) ~/.npm দিয়ে এটি একবার মেরামত করে নিন।

Headless auth সমস্যা এবং এটি সমাধানের উপায়

প্রথমবার যখন আপনি gemini ইন্টারঅ্যাক্টিভলি চালাবেন, তখন এটি আপনার Google account দিয়ে লগ-ইন করার প্রস্তাব দেবে। ডেস্কটপে এটি একটি ব্রাউজার ট্যাব ওপেন করে। কিন্তু 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 টি ওপেন করে অনুমোদন (approve) প্রদান করেন, তবুও Google আপনাকে http://localhost:PORT-এ রিডাইরেক্ট করবে — যা সার্ভারের localhost, এবং আপনার ল্যাপটপ থেকে এই পোর্টটি অ্যাক্সেস করা সম্ভব নয়। ফলে লগ-ইন প্রক্রিয়াটি সম্পন্ন হয় না।

এটি সমাধানের দুটি সঠিক উপায় আছে।

প্রথম উপায়টি হলো API key ব্যবহার করা, যা সার্ভারের জন্য আদর্শ। Google AI Studio (aistudio.google.com) থেকে একটি key তৈরি করুন এবং CLI-কে একটি environment variable হিসেবে প্রদান করুন; এটি GEMINI_API_KEY রিড করবে এবং ব্রাউজার ফ্লো সম্পূর্ণ এড়িয়ে যাবে। এখন "কিভাবে এটি history এবং world-readable ফাইল থেকে দূরে রাখা যায়" তা দেখা যাক। প্রম্পটে সরাসরি 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 মানে হলো শুধুমাত্র আপনার ইউজার ফাইলটি পড়তে পারবে। printenv GEMINI_API_KEY দিয়ে নিশ্চিত হোন যে key টি environment-এ পৌঁছেছে; যদি এটি কিছু প্রিন্ট না করে, তবে CLI পুনরায় ব্রাউজার ফ্লো ব্যবহার করার চেষ্টা করবে এবং ব্যর্থ হবে। আপনি চাইলে ~/.gemini/-এ একটি .env ফাইলও ব্যবহার করতে পারেন — সেক্ষেত্রেও একই নিয়ম প্রযোজ্য, অর্থাৎ chmod 600 ~/.gemini/.env।

দ্বিতীয় উপায়টি হলো OAuth callback-টিকে আপনার ল্যাপটপে টানেল করার মাধ্যমে ব্যক্তিগত Google account (এবং এর free tier) ব্যবহার করা। সমস্যা হলো, CLI-এর loopback server প্রতিটি রান-এ একটি র‍্যান্ডম পোর্ট বাইন্ড করে। তাই OAUTH_CALLBACK_PORT environment variable দিয়ে পোর্টটি ফিক্সড না করলে ফরোয়ার্ড করার মতো কোনো স্থায়ী পোর্ট থাকবে না। পোর্টটি ফিক্সড করার নিয়মটি হলো:

# 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 server-এ পৌঁছে দেবে এবং লগ-ইন সম্পন্ন হবে। পোর্টটি ফিক্সড না রাখলে এটি প্রতিবার একটি নতুন র‍্যান্ডম পোর্টে চলে যাবে, যা আগে থেকে করা কোনো ssh -L দিয়ে ধরা সম্ভব নয়। এটি কাজ করে, কিন্তু এর জন্য আপনার ব্রাউজারের সামনে বসে থাকতে হবে, তাই এটি স্ক্রিপ্টের জন্য উপযোগী নয়। যেকোনো দীর্ঘমেয়াদী কাজের জন্য API key ব্যবহার করুন।

AI Studio-এর পরিবর্তে Vertex AI বা Google Cloud project ব্যবহার করলে, GOOGLE_API_KEY এবং GOOGLE_GENAI_USE_VERTEXAI=true একসাথে সেট করুন, অথবা Code Assist licence-এর জন্য GOOGLE_CLOUD_PROJECT ব্যবহার করুন — এক্ষেত্রেও একই environment-variable নিয়ম এবং mode-600 ফাইল ব্যবহার করতে হবে।

SSH session বিচ্ছিন্ন হয়ে গেলে যেন এটি বন্ধ না হয়, তাই tmux এর ভেতরে চালান

আপনি যদি সরাসরি আপনার SSH shell থেকে কোনো gemini process চালু করেন, তবে সেটি ওই shell এর একটি child process হিসেবে গণ্য হয়। সংযোগ বিচ্ছিন্ন হয়ে গেলে — যেমন ল্যাপটপ বন্ধ হয়ে যাওয়া, Wi-Fi সংযোগ বিচ্ছিন্ন হওয়া বা idle timeout হওয়া — sshd pseudo-terminal টি বন্ধ করে দেয়। এর ফলে shell একটি SIGHUP পায় এবং CLI সংযোগ বিচ্ছিন্ন হয়ে যায়। ফাইল এডিট করার দশ মিনিট পর কোনো কাজ চলাকালীন সংযোগ বিচ্ছিন্ন হলে সেটি বন্ধ হয়ে যায় এবং পুনরায় কানেক্ট করার পর সেই process টি আর খুঁজে পাওয়া যায় না।

tmux এই সমস্যাটি সমাধান করে কারণ এটি shell এর মালিক হিসেবে কাজ করে, sshd এর মতো নয়। এটি 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

যদি gemini নামে কোনো session বিদ্যমান থাকে তবে tmux new -A -s gemini সেটির সাথে attach হয়, আর না থাকলে নতুন একটি session তৈরি করে। তাই প্রতিটি login এর পর এটি চালানো একটি আদর্শ কমান্ড। এর ভেতরের shell টি detached tmux server এর অধীনে থাকে, আপনার SSH session এর অধীনে নয়। ফলে সংযোগ বিচ্ছিন্ন হলেও CLI সচল থাকে। পুনরায় কানেক্ট করে attach করলেই আপনি আগের স্ক্রলব্যাক (scrollback) ফিরে পাবেন।

non-interactive বা scripted কাজের জন্য Gemini CLI তে একটি headless mode আছে: gemini -p "summarise the failing tests in this repo" উত্তর প্রিন্ট করে প্রস্থান করে এবং --output-format json অন্য কোথাও pipe করার জন্য machine-readable output প্রদান করে। একটি দীর্ঘ batch job চালানোর সময় tmux session এর ভেতরে বা cron entry থেকে চালানোর জন্য API key সহ headless mode ব্যবহার করা সবচেয়ে উপযোগী। তবে একটি বিষয় মনে রাখতে হবে: cron job আপনার login ফাইলগুলো source করে না। তাই crontab লাইনে নিজস্ব GEMINI_API_KEY প্রদান করুন (অথবা কমান্ডটিকে ~/.gemini_env source করতে বলুন), অন্যথায় CLI ব্রাউজার flow এ ফিরে যাবে এবং কাজ ব্যর্থ হবে।

প্রোডাকশন চলাকালীন কোনো বক্সে Sandboxing এবং permissions

যে এজেন্টের shell access আছে, সেটি একটি shell। Gemini CLI কমান্ড চালাতে পারে, এবং ডিফল্টভাবে এটি প্রতিটি ঝুঁকিপূর্ণ কমান্ডের আগে অনুমতি চায় — কিন্তু ব্যবহারকারীরা --yolo (প্রতিটি tool call স্বয়ংক্রিয়ভাবে অনুমোদন করা) ব্যবহার করতে পারেন। এর ফলে এটি ফাইল ডিলিট করতে পারে, git-এ push করতে পারে, অথবা যে ব্যবহারকারীর নামে এটি চলছে তার পূর্ণ ক্ষমতা নিয়ে ইন্টারনাল সার্ভিসগুলোতে রিকোয়েস্ট পাঠাতে পারে। যে বক্সে প্রোডাকশনও চলে, সেখানে এটি একটি বাস্তব ঝুঁকি, কোনো তাত্ত্বিক বিষয় নয়।

তিনটি নিয়ন্ত্রণ ব্যবস্থা, গুরুত্বের ক্রমানুসারে:

• একটি ডেডিকেটেড, unprivileged user হিসেবে এটি চালান। root বা sudo-এর সদস্য হিসেবে নয়। নিজস্ব home ডিরেক্টরি সহ একটি agent ইউজার তৈরি করুন, সেখানে Node এবং CLI ইনস্টল করুন; এতে ভুল নির্দেশনা শুধুমাত্র সেই অ্যাকাউন্টের মধ্যেই সীমাবদ্ধ থাকবে। এটি সবচেয়ে গুরুত্বপূর্ণ সিদ্ধান্ত।
• প্রোডাকশন credentials সেই বক্সে রাখবেন না। কোনো প্রোডাকশন ~/.aws/credentials বা প্রোডাকশন থেকে কপি করা .env রাখবেন না, অথবা এমন কোনো ডাটাবেস পাসওয়ার্ড দেবেন না যার write access আছে গুরুত্বপূর্ণ কোনো কিছুর ওপর। একে শুধুমাত্র staging বা read-only credential দিন।
• বিল্ট-ইন sandbox ব্যবহার করুন। Docker বা Podman ইনস্টল করা থাকলে, gemini --sandbox (বা GEMINI_SANDBOX=docker) এজেন্টের tool call গুলো হোস্ট filesystem এবং network থেকে বিচ্ছিন্ন একটি container-এর ভেতরে চালায়। এটি unprivileged user-এর বিকল্প নয়, কিন্তু একই VPS যখন গুরুত্বপূর্ণ কাজ করে, তখন এটি একটি শক্তিশালী দ্বিতীয় স্তর হিসেবে কাজ করে।

আপনি যদি Gemini CLI-কে অন্যান্য self-hosted টুলিং-এর সাথে চালান — যেমন একই VPS-এ এজেন্টের জন্য টুলস এক্সপোজ করা একটি MCP server — তবে প্রতিটি নতুন সক্ষমতাকে এজেন্টের জন্য একটি বর্ধিত surface হিসেবে বিবেচনা করুন। এজেন্টের কাছে থাকা token-এর পরিধি শুধুমাত্র একটি নির্দিষ্ট কাজের মধ্যে সীমাবদ্ধ রাখুন।

Quota, cost, and which auth path you chose

Auth path নির্ধারণ করে আপনার বিলিং কীভাবে হবে। একটি ব্যক্তিগত Google account (OAuth path) Gemini Code Assist-এর free tier ব্যবহার করে, যেখানে প্রতি মিনিট এবং প্রতি দিনের জন্য নির্দিষ্ট সীমা থাকে; সীমা অতিক্রম করলে window reset না হওয়া পর্যন্ত request-এ rate-limit error দেখাবে। AI Studio থেকে নেওয়া API key প্রজেক্টের ওপর ভিত্তি করে free-tier বা billed হতে পারে — billed key-তে সীমা বেশি থাকে এবং প্রতি token-এর জন্য চার্জ করা হয়। Vertex এবং Cloud-project auth-এর বিলিং Google Cloud-এর মাধ্যমে সম্পন্ন হয়।

দুটি ব্যবহারিক নোট। একটি unattended agent যদি loop-এ চলে, তবে তা দ্রুত quota শেষ করে দিতে পারে; তাই এটি কোনো cron job-এ দেওয়ার আগে প্রথম কয়েকবার পর্যবেক্ষণ করুন। আর যদি Google-এর hosted model-এর পরিবর্তে privacy বা unmetered inference-এর জন্য server-side model ব্যবহার করতে চান, তবে সেটি ভিন্ন একটি টুল — VPS-এ Ollama দিয়ে একটি open LLM self-hosting করলে weights এবং prompts আপনার নিজস্ব box-এই থাকবে, তবে Gemini-এর তুলনায় অনেক ছোট model চালাতে হবে।

আপডেট রাখা

Gemini CLI নিয়মিত আপডেট করা হয়। যেহেতু আপনি এটি একটি user-owned prefix-এ ইনস্টল করেছেন, তাই আপডেট করার জন্য কখনো sudo প্রয়োজন হবে না:

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

এখানে বিভিন্ন release channel রয়েছে: @latest হলো stable, @preview হলো weekly preview, এবং @nightly হলো bleeding edge — আপনি যেটির ওপর নির্ভর করেন সেটির জন্য @latest ব্যবহার করুন। nvm ব্যবহার করলে, global packages গুলো active Node version-এর অধীনে থাকে। তাই Node পরিবর্তন করতে nvm use করার পর আপনার CLI পুনরায় ইনস্টল করার প্রয়োজন হতে পারে। প্রতিটি patch অনুসরণ করার পরিবর্তে release notes পড়ুন।

Failure modes, with the exact strings

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, তারপর runtime-এ CLI crash করা। 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-owned prefix-এ একটি global install করা হয়েছে। sudo ব্যবহার করবেন না — npm config set prefix ~/.npm-global সেট করুন, PATH-এ ~/.npm-global/bin রাখুন, এবং আপনার সাধারণ user হিসেবে পুনরায় ইনস্টল করুন। যদি আগের কোনো sudo npm root-owned cache ফাইল (Your cache folder contains root-owned files) রেখে থাকে, তবে sudo chown -R $(id -u):$(id -g) ~/.npm চালান।

Failed to open browser, একটি login যা hangs হয়ে যায়, অথবা একটি redirect_uri=http://localhost:PORT যা আপনি reach করতে পারছেন না। OAuth flow-এর জন্য এমন একটি browser প্রয়োজন যা সার্ভারে নেই, এবং এর localhost callback সার্ভারের দিকে পয়েন্ট করে, আপনার laptop-এর দিকে নয়। API-key পাথ (GEMINI_API_KEY) ব্যবহার করুন, অথবা OAUTH_CALLBACK_PORT pin করুন, SSH-এর মাধ্যমে ssh -L দিয়ে forward করুন, এবং URL-টি locally ওপেন করুন।

SSH সংযোগ বিচ্ছিন্ন হওয়ার সাথে সাথে process টি বন্ধ হয়ে গেছে। আপনি সরাসরি SSH shell থেকে gemini চালিয়েছিলেন, তাই এটি ওই shell-এর একটি child process ছিল এবং disconnect হওয়ার সাথে সাথে pty সহ বন্ধ হয়ে গেছে। রিকভার করার কিছু নেই। প্রতিটি session tmux new -A -s gemini দিয়ে শুরু করুন এবং এর ভেতরে CLI চালান।

Key সেট করার পরেও Auth ব্যর্থ হচ্ছে — CLI পুনরায় auth picker-এ ফিরে যাচ্ছে, অথবা একটি request HTTP 400 সহ API key not valid রিটার্ন করছে। Key-টি CLI দেখতে পায় এমন environment-এ নেই। printenv GEMINI_API_KEY দিয়ে নিশ্চিত করুন; যদি এটি খালি থাকে, তবে আপনার ~/.gemini_env কখনো source করা হয়নি — চেক করুন লাইনটি ~/.bashrc-এ আছে কি না, যা interactive shells (tmux সহ) পড়ে কিন্তু cron এবং অন্যান্য non-interactive shells পড়ে না। Key value-এর ভেতরে একটি অতিরিক্ত space বা quote থাকলে API key not valid হতে পারে।

429 / RESOURCE_EXHAUSTED / একটি rate-limit মেসেজ। আপনার auth যে tier ব্যবহার করে তার quota শেষ হয়ে গেছে। window রিসেট হওয়ার জন্য অপেক্ষা করুন, agent-এর গতি কমিয়ে দিন, অথবা একটি billed API key ব্যবহার করুন। একটি agent যা retry loop-এ আটকে আছে সেটি বারবার এটি হিট করবে — এটি বন্ধ করুন এবং এটি কী করছে তা পরীক্ষা করুন।

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 এড়িয়ে যাবে। আপনি যদি বিশেষভাবে personal-account free tier ব্যবহার করতে চান, তবে OAUTH_CALLBACK_PORT=8085 দিয়ে loopback port pin করুন, ssh -L 8085:localhost:8085 user@server দিয়ে সেটি আপনার laptop-এ forward করুন, এবং লোকালি প্রিন্ট হওয়া URL-টি ওপেন করুন — তবে এর জন্য browser-এ আপনার উপস্থিতি প্রয়োজন, তাই এটি script-এর জন্য উপযোগী নয়।

npm global install করার সময় কেন sudo প্রয়োজন হয় এবং এটি কীভাবে এড়ানো যায়?

কারণ npm-এর default global prefix হলো /usr/lib/node_modules, যেখানে আপনার user-এর write করার অনুমতি নেই। তাই সাধারণ npm install -g কমান্ড EACCES error দেখাবে। ভুল সমাধান হলো sudo npm -g, যা root-owned ফাইল তৈরি করে যা পরবর্তীতে installation-এ সমস্যা সৃষ্টি করে। সঠিক সমাধান হলো prefix-টি আপনার home (npm config set prefix ~/.npm-global) ডিরেক্টরিতে সেট করা এবং এর bin পথটি PATH-এ যোগ করা, অথবা nvm ব্যবহার করা, যা স্বয়ংক্রিয়ভাবে আপনার home ডিরেক্টরিতে global packages install করে।

সংযোগ বিচ্ছিন্ন হওয়ার পরেও Gemini CLI কীভাবে সচল রাখা যায়?

এটি tmux-এর ভেতরে চালান। SSH shell থেকে শুরু করা কোনো process সংযোগ বিচ্ছিন্ন হয়ে গেলে বন্ধ হয়ে যায় কারণ এটি ওই shell-এর child process; tmux shell-টিকে একটি detached server-এর অধীনে চালায় যা সংযোগ বিচ্ছিন্ন হলেও সচল থাকে। tmux new -A -s gemini ব্যবহার করুন, এর ভেতরে gemini চালান, Ctrl-b d দিয়ে detach করুন, এবং পরে tmux attach -t gemini দিয়ে পুনরায় reattach করুন।

production box-এ Gemini CLI চালানো কি নিরাপদ?

শুধুমাত্র সতর্কতার সাথে চালানো সম্ভব, কারণ shell access আছে এমন একটি agent সেই user-এর সমস্ত কাজ করতে পারে যার অধীনে এটি চলছে। এটি একটি dedicated unprivileged user হিসেবে চালান যার sudo অ্যাক্সেস নেই, machine-এ production credentials রাখবেন না, --yolo auto-approval এড়িয়ে চলুন, এবং host থেকে tool calls আলাদা রাখতে --sandbox (Docker বা Podman) ব্যবহার করুন। আপনি কোন flag সেট করছেন তার চেয়ে এটি বেশি গুরুত্বপূর্ণ যে এটি কোন account-এর অধীনে চলছে।

Gemini CLI-এর জন্য কি কোনো firewall port ওপেন করতে হবে?

না। এটি একটি client যা Google-এর APIs-তে outbound HTTPS call পাঠায়, তাই এর জন্য শুধুমাত্র outbound port 443 প্রয়োজন, কোনো inbound port নয়। আপনি যদি OAuth tunnel ব্যবহার করেন, তবে pinned callback port (যেমন 8085) localhost-এ থাকে এবং এটি আপনার SSH forward-এর মাধ্যমে অ্যাক্সেস করা হয়, কোনো ওপেন inbound port-এর মাধ্যমে নয়। Inbound connection বন্ধ রাখুন।