Gemini CLI на VPS без GUI: встановлення та запуск

Що ви створюєте

Gemini CLI, який постійно працює на вашому сервері, доступний через SSH і виконує тривалі завдання агента навіть після закриття ноутбука. Встановлення складається з трьох команд. Складність пов’язана з усім, що передбачає наявність графічного робочого середовища: CLI від Google намагається відкрити браузер для входу, а на сервері браузера немає. Тому більша частина цього посібника присвячена роботі без графічного інтерфейсу, встановленню актуальної версії Node, якої немає в репозиторіях дистрибутива, глобальному встановленню npm без root, автентифікації без браузера за допомогою API key, який не потрапляє до історії shell, а також tmux, щоб розірване SSH-з’єднання не зупинило поточне завдання.

Gemini CLI — це open-source програма на Node за ліцензією Apache-2.0 (@google/gemini-cli), яка взаємодіє з моделями Gemini від Google, може читати й записувати файли, виконувати shell-команди та використовувати інструменти в робочому каталозі. На VPS це невеликий агент, доступний постійно й здатний працювати без нагляду. Тому обліковий запис, від імені якого він запускається, і облікові дані, що зберігаються на сервері, важливіші за будь-який окремий параметр у цьому посібнику.

Передумови та важливі обмеження

• Чистий Ubuntu 24.04 KVM VPS із root або sudo. Підійде будь-який тариф KVM; сам CLI невимогливий і в стані спокою використовує кількасот MB RAM.
• Node.js 20 або новіший. Це єдина жорстка вимога до версії, а пакет дистрибутива має старішу версію — див. наступний розділ. Node 20 досяг кінця життєвого циклу 30 квітня 2026 року, тому встановіть 24.
• Вихідний HTTPS (порт 443) до API Google. Вхідні порти не потрібні; це клієнт, а не сервер, тому відкривати для нього порт у firewall не потрібно.
• Спосіб автентифікації, який не потребує браузера на сервері: платний Gemini API key від Google AI Studio або вхід через Google, під час якого на headless-сервері потрібно вставити код назад у термінал. Варіант з API key підходить для скриптів і запусків без нагляду.
• Docker або Podman, лише якщо потрібна ізоляція --sandbox. Необов’язково; це розглянуто наприкінці.

Тепер головна проблема пов’язана не з браузером, а з обліковим записом. 19 травня 2026 року Google оголосила, що з 18 червня 2026 року Gemini CLI припинить обслуговувати запити від передплатників Google AI Pro та Ultra, а також від усіх користувачів, які використовують його безкоштовно. Таким користувачам Google рекомендує заміну — Antigravity CLI (agy). Gemini CLI і далі працює з платними Gemini API keys, Gemini Enterprise Agent Platform API keys, а також із ліцензією Gemini Code Assist Standard або Enterprise організації. Визначте спосіб автентифікації до початку роботи.

Node: пакет дистрибутива застарий

Ubuntu 24.04 постачає Node 18.19.1 у власних репозиторіях разом із npm 9.2.0. package.json Gemini CLI оголошує 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 працюватиме в непідтримуваному середовищі виконання. Він може працювати неправильно або аварійно завершуватися, щойно звернеться до API Node 20+, яке має бути доступним. Node 18 також завершив життєвий цикл у квітні 2025 року, тому в будь-якому разі це тупиковий варіант. Встановіть поточну LTS-версію до встановлення CLI. Є два коректні способи: 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 або новішу версію, щоб CLI відповідав вимогам. Однак Node 20 завершив життєвий цикл 30 квітня 2026 року, тому орієнтуйтеся на v24.x — поточну активну LTS-версію. Очікується, що Node 26 стане активною LTS-версією 28 жовтня 2026 року. Перевірте сторінку NodeSource із поточним скриптом налаштування. Значення setup_24.x у URL потрібно змінити, коли з’явиться нова 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

Значення v0.40.1 у цьому URL було актуальним на момент написання матеріалу. Перевірте README nvm, щоб отримати найновіший випуск, і замініть у команді номер версії перед запуском. nvm має реальну перевагу для цього завдання: він встановлює Node і його глобальні пакети в ~/.nvm, тому описана в наступному розділі проблема з правами під час глобального встановлення взагалі не виникає. Якщо ви обрали nvm, крок із налаштуванням npm-prefix можна пропустити.

Встановлення CLI без sudo npm -g

Спокуслива команда — sudo npm install -g @google/gemini-cli. Не використовуйте її. Глобальний prefix, власником якого є root, спричинятиме помилки доступу під час кожного наступного встановлення. Він також залишає файли, власником яких є root, у кеші npm. Через кілька місяців це може спричинити проблеми. Якщо виконати звичайний (без sudo) npm install -g для системного Node, виникне інша помилка:

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, а налаштувати глобальний prefix npm на каталог у вашому домашньому каталозі. Тоді глобальні пакети встановлюватимуться в каталог, власником якого ви є:

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 є навмисним. Через два розділи ви запускатимете CLI у tmux. Він запускає non-login shell, який читає ~/.bashrc і пропускає ~/.profile. Тому рядок PATH у неправильному файлі залишить gemini невидимим саме там, де він потрібен. Виведення gemini --version з номером версії є повною перевіркою. Якщо натомість ви отримали gemini: command not found, експорт PATH не застосувався. Дивіться способи усунення помилок. У nvm повністю пропустіть рядки з prefix: nvm уже встановлює глобальні пакети у ваш домашній каталог.

Якщо раніше ви виконували sudo npm і тепер бачите Your cache folder contains root-owned files, один раз виправте це за допомогою sudo chown -R $(id -u):$(id -g) ~/.npm.

Проблема автентифікації без графічного інтерфейсу та способи її обійти

Першого разу запустіть gemini в інтерактивному режимі. Команда запропонує увійти за допомогою облікового запису Google. На настільному комп’ютері відкриється вкладка браузера. На headless Linux VPS CLI спочатку перевіряє наявність дисплея. Якщо не задано жодну з DISPLAY, WAYLAND_DISPLAY або MIR_SOCKET, браузер не запускається. Натомість CLI виводить посилання для входу й очікує, що ви вставите код:

Please visit the following URL to authorize the application:

https://accounts.google.com/o/oauth2/v2/auth?...

Enter the authorization code:

Цей процес працює через звичайний SSH, але щоразу потребує браузера. Крім того, з June 18, 2026 він дає змогу увійти лише тоді, коли ваш обліковий запис Google належить до тих, які Gemini CLI ще обслуговує.

Є два коректні способи.

Перший — API key. Для сервера це рекомендований варіант за замовчуванням. Створіть ключ у Google AI Studio (aistudio.google.com) у проєкті з увімкненим білінгом, оскільки Gemini CLI більше не обслуговує безкоштовне використання. Передайте ключ CLI через змінну середовища: CLI читає GEMINI_API_KEY і повністю пропускає процес входу через браузер. Тепер подбайте про те, щоб ключ не потрапив до історії команд або файлів, доступних для читання всіма користувачами. Не вводьте export GEMINI_API_KEY=AIza... у командному рядку: значення буде збережено у ~/.bash_history у відкритому вигляді. Також не зберігайте ключ у файлі, який можуть прочитати інші користувачі. Запишіть його у файл із режимом 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. Якщо команда нічого не виведе, CLI повернеться до вибору способу автентифікації замість використання ключа. CLI також читає файл .env у ~/.gemini/, якщо ви віддаєте перевагу такій структурі. Правило те саме: chmod 600 ~/.gemini/.env.

Другий спосіб — безпосередній вхід через Google. На headless-сервері для цього не потрібні тунель або відкритий порт. З June 18, 2026 цей варіант переважно потрібен для ліцензій Gemini Code Assist Standard або Enterprise в організаціях. У такому разі також задайте GOOGLE_CLOUD_PROJECT. Безкоштовні особисті облікові записи та підписки Google AI Pro або Ultra більше не обслуговуються. Запустіть CLI у звичайному SSH-сеансі та виберіть Sign in with Google:

gemini

Скопіюйте виведений URL у браузер на ноутбуці та підтвердьте вхід. Google перенаправить вас до https://codeassist.google.com/authcode, де відобразиться код авторизації. Вставте його в запит Enter the authorization code: на VPS. Після цього вхід буде завершено. Сервер не очікує callback, тому не потрібно закріплювати порт або налаштовувати ssh -L. OAUTH_CALLBACK_PORT має значення лише для loopback-процесу, який CLI використовує за наявності дисплея. Якщо ви підключилися з X11 forwarding (ssh -X), DISPLAY буде задано, і CLI натомість використає цей loopback-процес із перенаправленням на http://127.0.0.1:PORT/oauth2callback на сервері. Виконайте NO_BROWSER=true gemini, щоб примусово вибрати процес із вставленням коду. Це працює, але потребує браузера, відкритого перед вами, тому не підходить для скриптів. Для тривалих процесів використовуйте API key.

Для Vertex AI або проєкту Google Cloud замість AI Studio задайте GOOGLE_API_KEY разом із GOOGLE_GENAI_USE_VERTEXAI=true або GOOGLE_CLOUD_PROJECT для ліцензії Code Assist. Дотримуйтеся тієї самої дисципліни щодо змінних середовища та використовуйте файл із режимом 600.

Запускайте в tmux, щоб розрив SSH-сеансу не зупинив процес

Процес gemini, запущений безпосередньо з SSH-оболонки, є дочірнім процесом цієї оболонки. Якщо з’єднання розірвалося через закриття ноутбука, втрату Wi-Fi або тайм-аут бездіяльності, sshd закриває псевдотермінал, оболонка отримує SIGHUP, а потім передає цей сигнал CLI. Завдання, яке вже десять хвилин редагувало файли, завершується разом із ним. Після повторного підключення відновити процес уже неможливо.

tmux вирішує цю проблему, оскільки керує оболонкою, а не sshd. Це той самий підхід, що й запуск AI-агента для написання коду на віддаленому VPS усередині tmux, і тут він працює так само:

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, якщо він існує, і створює його, якщо його немає. Тому цю команду слід виконувати одразу після кожного входу в систему. Оболонка всередині належить від’єднаному серверу tmux, а не SSH-сеансу. Тому розрив з’єднання не зупиняє CLI. Після повторного підключення виконайте attach і поверніться до того самого буфера прокручування. Якщо на одному сервері ви запускаєте кілька сеансів агента, використовуйте окремий сеанс tmux для кожного. У цьому режимі вони не можуть взаємодіяти між собою, на відміну від Claude Code, де один сеанс може передати текст іншому на тому самому VPS. Тому запускайте кожне завдання Gemini незалежно або координуйте їх через файли на диску.

Для неінтерактивних запусків за сценаріями Gemini CLI має headless mode: gemini -p "summarise the failing tests in this repo" виводить відповідь і завершує роботу, а --output-format json передає машиночитний результат для подальшого перенаправлення. Headless mode з API key підходить для запуску всередині сеансу tmux під час тривалого пакетного завдання або з cron. Є один нюанс: cron job не завантажує жодного з ваших login-файлів. Тому в рядку crontab потрібно окремо задати GEMINI_API_KEY або змусити команду завантажити ~/.gemini_env. Інакше запуск завершиться помилкою через відсутні облікові дані.

Пісочниця та дозволи на сервері, який також обслуговує production

Агент із доступом до shell має доступ до shell. Gemini CLI може виконувати команди. За замовчуванням він запитує підтвердження перед кожною потенційно небезпечною командою. Але користувачі часто вмикають --yolo (автоматичне підтвердження кожного виклику інструмента). Після цього агент може видаляти файли, виконувати push до git або звертатися до внутрішніх сервісів із повними повноваженнями користувача, від імені якого він працює. На сервері, який також обслуговує production, це реальний радіус ураження, а не теоретичний ризик.

Ось три засоби контролю в порядку зменшення їхньої користі:

• Запускайте його від імені окремого непривілейованого користувача. Не від root і не від користувача, який входить до sudo. Створіть користувача agent з окремим home-каталогом, встановіть Node і CLI для цього користувача. Тоді неправильно інтерпретована інструкція залишиться в межах цього облікового запису. Це рішення дає найбільший ефект.
• Не зберігайте production-облікові дані на сервері. Не зберігайте production ~/.aws/credentials, не копіюйте з production .env і не використовуйте пароль бази даних із правом запису до важливих даних. Надайте облікові дані staging або доступ лише для читання.
• Використовуйте вбудовану пісочницю. Якщо встановлено Docker або Podman, gemini --sandbox (або GEMINI_SANDBOX=docker) виконує виклики інструментів агента всередині контейнера. Контейнер монтує лише поточний каталог проєкту, а не решту файлової системи хоста. Це не замінює непривілейованого користувача, але є надійним другим рівнем захисту, якщо той самий VPS виконує реальні робочі завдання.

Якщо ви запускаєте Gemini CLI поруч з іншими self-hosted інструментами, наприклад MCP-сервером, який надає агенту інструменти на тому самому VPS, вважайте кожну додаткову можливість додатковою поверхнею, до якої агент може отримати доступ. Обмежуйте передані йому токени рівно одним завданням.

Квота, вартість і вибраний шлях автентифікації

Шлях автентифікації визначає спосіб виставлення рахунків, а з June 18, 2026 — також те, чи обслуговуватимуться ваші запити взагалі. З цієї дати, згідно з оголошенням Google, Gemini CLI припинив обслуговувати запити підписників Google AI Pro і Ultra та всіх, хто користувався ним безкоштовно. Це стосується безкоштовного рівня для особистих облікових записів і API keys, за якими не стягується плата. Сервіс і надалі доступний через платні Gemini API keys і Gemini Enterprise Agent Platform API keys, для яких плата стягується за кількістю токенів, а також для організацій із ліцензією Gemini Code Assist Standard або Enterprise чи іншим доступом до Google Cloud, де оплата проходить через Google Cloud. Для кожного рівня діють обмеження за кількістю запитів за хвилину та за день. Після перевищення цих обмежень запити повертають помилку перевищення ліміту, доки не завершиться відповідне вікно.

Є два практичні моменти. Агент без нагляду, який працює в циклі, може швидко витратити квоту, тому перші кілька разів контролюйте його, перш ніж передавати запуск через cron job. Якщо ж вам потрібна модель на сервері через вимоги до приватності або для інференсу без лічильника, а не через використання hosted models Google, це інший сценарій: self-hosting відкритої LLM за допомогою Ollama на VPS зберігає ваги моделі та промпти на вашому власному сервері, але доведеться використовувати значно меншу модель, ніж Gemini.

Підтримка актуальної версії

Gemini CLI часто випускає нові версії. Оскільки ви встановили його в prefix, власником якого є користувач, для оновлення не потрібен sudo:

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

Доступні такі канали релізів: @latest — стабільний, @preview — щотижнева попередня версія, @nightly — найновіша експериментальна версія. Для всього, від чого залежить ваша робота, зафіксуйте @latest. У nvm глобальні пакети зберігаються в активній версії Node, тому після nvm use для перемикання Node може знадобитися повторно встановити CLI. Читайте примітки до релізів, а не встановлюйте кожен патч без потреби.

Режими відмови з точними рядками

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, після чого CLI аварійно завершує роботу під час виконання. Node застарілий: у дистрибутиві встановлено версію 18.19.1, яка також уже вийшла з підтримки. Встановіть актуальну LTS-версію з NodeSource або через nvm (Node 20 відповідає мінімальній вимозі CLI, але сама ця версія вийшла з підтримки у квітні 2026 року), перевірте її командою node --version. Якщо встановлено кілька версій Node, переконайтеся, що which node вказує на нову версію, а не на /usr/bin/node.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. Глобальне встановлення виконано в prefix, власником якого є 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://127.0.0.1:PORT, до якого немає доступу. CLI виявив змінну дисплея, часто успадковану від ssh -X, і вибрав сценарій із loopback, у якому callback повертається на сервер. Виконайте NO_BROWSER=true gemini, щоб перейти до сценарію з копіюванням коду, або використайте шлях через API key (GEMINI_API_KEY). У звичайному SSH-сеансі ви маєте побачити Enter the authorization code:. Відкрийте URL у браузері на ноутбуці та вставте код, який покаже Google.

Процес зник після розриву SSH-з’єднання. Ви запустили gemini безпосередньо з SSH shell, тому процес був дочірнім процесом цього shell і завершився разом із pty після роз’єднання. Відновлювати нічого. Починайте кожен сеанс командою tmux new -A -s gemini і запускайте CLI всередині нього.

Автентифікація не працює навіть із заданим ключем, CLI повертається до меню вибору способу автентифікації або запит повертає API key not valid з HTTP-кодом 400. Ключ відсутній у середовищі, яке бачить CLI. Перевірте його командою printenv GEMINI_API_KEY. Якщо результат порожній, ваш ~/.gemini_env не було завантажено. Перевірте, що цей рядок міститься у ~/.bashrc. Цей файл читають інтерактивні shell, зокрема tmux, але його не читають cron та інші неінтерактивні shell. Зайвий пробіл або лапки всередині значення ключа також спричиняють API key not valid.

429 / RESOURCE_EXHAUSTED / повідомлення про обмеження частоти запитів. Ви вичерпали квоту відповідного рівня, який використовує ваша автентифікація. Дочекайтеся скидання квоти, зменште швидкість роботи агента або перейдіть на платний API key. Агент, який застряг у циклі повторних спроб, продовжує досягати цього обмеження. Зупиніть його та перевірте, що саме він робить.

FAQ

Як автентифікувати Gemini CLI на headless-сервері?

Використовуйте платний API key, а не вхід через браузер. Створіть key у Google AI Studio в проєкті з увімкненим білінгом, збережіть його у файлі з правами 600, який підключає ваша shell (export GEMINI_API_KEY=...), і CLI повністю пропустить браузерний OAuth flow. Якщо замість цього виконати вхід через Google, наприклад за ліцензією Code Assist Standard або Enterprise, CLI на headless-сервері виведе URL. Відкрийте його на ноутбуці, підтвердьте вхід і вставте код, який покаже Google, у запит Enter the authorization code:. Закріплювати порт або налаштовувати тунель не потрібно, але потрібна ваша присутність біля браузера, тому цей спосіб не підходить для скриптів. Безкоштовні персональні облікові записи Gemini CLI не обслуговує з June 18, 2026.

Чому глобальне встановлення npm запитує sudo і як цього уникнути?

Тому що стандартний глобальний prefix npm — /usr/lib/node_modules. Ваш користувач не має права запису до цього каталогу, тому звичайна команда npm install -g завершується помилкою EACCES. Неправильне рішення — sudo npm -g. Воно залишає файли, власником яких є root, і спричиняє помилки під час наступних встановлень. Правильне рішення — вказати prefix у вашому домашньому каталозі (npm config set prefix ~/.npm-global) і додати його bin до PATH. Також можна використовувати nvm, який автоматично встановлює глобальні пакети у вашому домашньому каталозі.

Як залишити Gemini CLI запущеним після розриву з’єднання?

Запускайте його всередині tmux. Процес, запущений з вашої SSH shell, завершується після розриву з’єднання, оскільки є дочірнім процесом цієї shell. tmux запускає shell у detached server, який продовжує працювати після розриву. Виконайте tmux new -A -s gemini, запустіть усередині нього gemini, від’єднайтеся за допомогою Ctrl-b d, а пізніше підключіться знову командою tmux attach -t gemini.

Чи безпечно запускати Gemini CLI на production-сервері?

Лише за умови обережного налаштування, оскільки агент із доступом до shell може виконати будь-яку дію, доступну користувачу, від імені якого він працює. Запускайте його від імені окремого непривілейованого користувача без sudo, не зберігайте production credentials на цьому сервері, не використовуйте автоматичне підтвердження --yolo і застосовуйте --sandbox (Docker або Podman), щоб ізолювати виклики інструментів від host. Права облікового запису, від імені якого працює агент, важливіші за будь-який окремий flag.

Чи потрібно відкривати порти firewall для Gemini CLI?

Ні. Це клієнт, який виконує вихідні HTTPS-запити до API Google, тому йому потрібен вихідний порт 443, але не потрібні вхідні порти. Вхід через Google на headless-сервері також не потребує порту: ви вставляєте код назад у terminal замість отримання callback на сервері. Не відкривайте вхідні підключення без потреби.