Как запустить Gemini CLI на headless VPS

Что вы создаёте

Постоянно работающий Gemini CLI на вашем собственном сервере, доступный по SSH, который выполняет длительные задачи агента, продолжающиеся после закрытия ноутбука. Установка состоит из трёх команд. Сложность заключается в том, что обычно такие инструменты рассчитаны на десктоп: CLI от Google требует открытия браузера для входа, а на сервере его нет. Поэтому большая часть этого руководства посвящена работе в headless-режиме: установке актуальной версии Node, которую не предоставляет дистрибутив, глобальной установке npm без прав root, аутентификации без браузера с использованием API-ключа, который не попадает в историю командной оболочки, и использованию tmux, чтобы разрыв SSH-сессии не прерывал выполнение задачи.

Gemini CLI — это программа на Node с открытым исходным кодом (Apache-2.0) (@google/gemini-cli), которая взаимодействует с моделями Gemini от Google, умеет читать и записывать файлы, выполнять команды оболочки и запускать инструменты в рабочей директории. На VPS это компактный и всегда доступный агент, который можно оставить в фоновом режиме. Именно поэтому учётная запись, от имени которой он работает, и учётные данные, хранящиеся на сервере, важнее любого отдельного параметра настройки.

Предварительные требования и важные нюансы

• Свежий VPS на базе Ubuntu 24.04 с виртуализацией KVM и доступом root или sudo. Подойдет любой тариф KVM; сам CLI потребляет мало ресурсов, в состоянии покоя ему достаточно нескольких сотен МБ оперативной памяти.
• Node.js версии 20 или новее. Это жесткое требование к минимальной версии, а пакет из репозитория дистрибутива ему не соответствует, см. следующий раздел. Поддержка Node 20 завершилась 30 апреля 2026 года, поэтому устанавливайте версию 24.
• Исходящий HTTPS-трафик (порт 443) к API Google. Входящие порты открывать не нужно; это клиент, а не сервер, поэтому настраивать брандмауэр не требуется.
• Способ аутентификации, не требующий браузера на сервере: платный ключ Gemini API из Google AI Studio или вход через учетную запись Google, при котором на headless-системе нужно будет вставить код в терминал. Вариант с API-ключом лучше подходит для скриптов и автоматизированного запуска.
• Docker или Podman, только если вам нужна изоляция --sandbox. Это опционально, рассматривается ближе к концу.

Нюанс, на котором сейчас все спотыкаются, связан с учетной записью, а не с браузером. 19 мая 2026 года Google объявила, что с 18 июня 2026 года Gemini CLI прекращает обслуживание запросов для подписчиков Google AI Pro и Ultra, а также для всех пользователей бесплатной версии, и перенаправляет их на замену — Antigravity CLI (agy). Gemini CLI по-прежнему работает с платными ключами Gemini API, ключами Gemini Enterprise Agent Platform API и лицензиями Gemini Code Assist Standard или Enterprise для организаций. Определитесь со способом аутентификации до начала работы.

Примечание: пакет в дистрибутиве слишком старый

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. Не используйте её. Глобальный префикс, принадлежащий root, приводит к ошибкам прав доступа при каждой последующей установке и оставляет в кэше npm файлы, принадлежащие root, которые вызовут проблемы спустя месяцы. Запуск обычной команды npm install -g (без sudo) для системного 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, а в перенаправлении глобального префикса 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, является намеренным: tmux, внутри которого вы запустите CLI через два раздела, открывает неавторизованный (non-login) shell, который считывает ~/.bashrc и пропускает ~/.profile. Поэтому строка PATH в неверном файле сделает gemini невидимым именно там, где он вам нужен. Вывод номера версии командой gemini --version — это полная проверка. Если вместо этого вы получаете gemini: command not found, значит, ваш экспорт PATH не применился; ознакомьтесь с режимами сбоя. При использовании nvm пропустите строки с префиксом полностью: он уже устанавливает глобальные пакеты в ваш домашний каталог.

Если вы ранее запускали sudo npm и теперь видите Your cache folder contains root-owned files, исправьте это один раз с помощью sudo chown -R $(id -u):$(id -g) ~/.npm.

Проблема headless-аутентификации и способы её решения

Запустите gemini в интерактивном режиме в первый раз, и программа предложит войти через аккаунт Google. На десктопе это открывает вкладку браузера. На headless Linux VPS CLI сначала проверяет наличие дисплея, и если переменные DISPLAY, WAYLAND_DISPLAY или MIR_SOCKET не заданы, он не пытается запустить браузер. Вместо этого он выводит ссылку для входа и ожидает, пока вы вставите код:

Please visit the following URL to authorize the application:

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

Enter the authorization code:

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

Существует два надежных способа решения этой задачи.

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

Второй способ — вход через аккаунт Google, который на headless-системе не требует туннелей или открытых портов. С 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, и вход будет завершен. На сервере не требуется ожидание обратного вызова, поэтому нет необходимости открывать порты или настраивать 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. При повторном подключении вы присоединяетесь к сессии и возвращаетесь к тому же состоянию терминала. Если вы запускаете несколько сессий агентов на одном сервере, по одной на сессию tmux, они не смогут взаимодействовать друг с другом, в отличие от Claude Code, где одна сессия может передавать текст другой на том же VPS. Поэтому держите каждую задачу Gemini независимой или координируйте их через файлы на диске.

Для неинтерактивных скриптовых запусков у Gemini CLI есть headless-режим: gemini -p "summarise the failing tests in this repo" выводит ответ и завершает работу, а --output-format json предоставляет машиночитаемый вывод для передачи в другие инструменты. Headless-режим с API-ключом — это именно то, что нужно для длительных пакетных задач внутри tmux или при запуске через cron. Есть один нюанс: задание cron не считывает ваши файлы инициализации оболочки, поэтому укажите в строке crontab собственный GEMINI_API_KEY (или настройте команду на считывание ~/.gemini_env), иначе выполнение завершится ошибкой из-за отсутствия учетных данных.

Песочницы и права доступа на сервере с рабочими сервисами

Агент с доступом к оболочке — это и есть оболочка. Gemini CLI может выполнять команды, и по умолчанию он запрашивает подтверждение перед каждой потенциально опасной операцией. Однако пользователи часто используют --yolo (автоматическое подтверждение всех вызовов инструментов), после чего агент может удалять файлы, отправлять изменения в git или обращаться к внутренним сервисам с полными правами пользователя, от имени которого он запущен. На сервере, где работают продуктовые сервисы, это создает реальный радиус поражения, а не гипотетическую угрозу.

Три уровня контроля, в порядке их эффективности:

• Запуск от имени выделенного пользователя с ограниченными правами. Не используйте root и не добавляйте пользователя в группу sudo. Создайте пользователя agent с собственным домашним каталогом, установите туда Node и CLI. В случае неверно интерпретированной инструкции последствия будут ограничены только этой учетной записью. Это самое важное решение для обеспечения безопасности.
• Хранение продуктовых учетных данных вне сервера. Не размещайте на сервере продуктовые ~/.aws/credentials, не копируйте .env из продакшена и не используйте пароли от баз данных с правами на запись для критически важных ресурсов. Используйте учетные данные для staging-окружения или права только на чтение.
• Использование встроенной песочницы. При установленном Docker или Podman, gemini --sandbox (или GEMINI_SANDBOX=docker) выполняет вызовы инструментов агента внутри контейнера. Этот контейнер монтирует только текущий каталог проекта, а не всю файловую систему хоста. Это не замена запуску от непривилегированного пользователя, но надежный второй уровень защиты, если на том же VPS выполняются реальные рабочие задачи.

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

Квоты, стоимость и выбор пути аутентификации

Путь аутентификации определяет порядок оплаты, а с 18 июня 2026 года — и возможность доступа к сервису. Согласно заявлению Google, с этой даты Gemini CLI прекратил обработку запросов для подписчиков Google AI Pro и Ultra, а также для всех пользователей бесплатного уровня, включая личные аккаунты и API-ключи без привязанного биллинга. Сервис остается доступен через платные API-ключи Gemini и API-ключи Gemini Enterprise Agent Platform, где оплата взимается за каждый токен, а также для организаций с лицензией Gemini Code Assist Standard или Enterprise или другим доступом к Google Cloud, оплата за которые проходит через Google Cloud. Для каждого уровня по-прежнему действуют лимиты на количество запросов в минуту и в день; при их превышении возвращается ошибка rate-limit до момента сброса временного окна.

Два практических замечания. Автономный агент в цикле может быстро исчерпать квоту, поэтому наблюдайте за его работой первые несколько раз, прежде чем доверять его выполнение cron job. Если ваша цель при использовании серверной модели — конфиденциальность или безлимитный инференс, а не использование облачных моделей Google, то для этого существуют другие инструменты. Самостоятельный хостинг открытых LLM с помощью Ollama на VPS позволяет хранить веса моделей и промпты на вашем собственном сервере, однако потребует использования модели значительно меньшего размера, чем Gemini.

Поддержание актуальной версии

Gemini CLI выпускается часто. Поскольку вы установили его в префикс, принадлежащий пользователю, для обновлений никогда не требуется 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/...'. Глобальная установка в директорию, принадлежащую 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 обнаружил переменную окружения display (часто из ssh -X) и выбрал поток аутентификации через loopback, обратный вызов которого направляется на сервер. Выполните NO_BROWSER=true gemini, чтобы использовать поток с вводом кода, или используйте путь с API-ключом (GEMINI_API_KEY). В обычном SSH-сеансе вы должны увидеть Enter the authorization code:; откройте URL в браузере на локальном компьютере, подтвердите запрос и вставьте код, который отобразит Google.

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

Аутентификация не проходит даже с установленным ключом, CLI возвращается к выбору метода аутентификации или запрос возвращает API key not valid с кодом HTTP 400. Ключ отсутствует в окружении, которое видит CLI. Проверьте это с помощью printenv GEMINI_API_KEY; если переменная пуста, ваш файл ~/.gemini_env не был загружен. Убедитесь, что строка добавлена в ~/.bashrc, который считывается интерактивными оболочками (включая tmux), но не считывается cron и другими неинтерактивными оболочками. Лишний пробел или кавычка внутри значения ключа также вызывают API key not valid.

429 / RESOURCE_EXHAUSTED / сообщение об ограничении частоты запросов (rate-limit). Вы исчерпали квоту для вашего уровня аутентификации. Дождитесь сброса окна ограничений, снизьте интенсивность работы агента или перейдите на платный API-ключ. Агент, застрявший в цикле повторных попыток, продолжает расходовать лимит; остановите его и проверьте выполняемые действия.

FAQ

Как аутентифицировать Gemini CLI на headless-сервере?

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

Почему npm global install требует sudo и как этого избежать?

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

Как оставить Gemini CLI запущенным после отключения от сервера?

Запускайте его внутри tmux. Процесс, запущенный из SSH-сессии, завершается при разрыве соединения, так как является дочерним процессом этой оболочки; tmux запускает оболочку внутри отсоединенного сервера, который продолжает работать после отключения. Используйте tmux new -A -s gemini, запустите gemini внутри, отсоединитесь с помощью Ctrl-b d и вернитесь к сессии позже командой tmux attach -t gemini.

Безопасно ли запускать Gemini CLI на production-сервере?

Только при соблюдении мер предосторожности, так как агент с доступом к оболочке может выполнять любые действия от имени пользователя, под которым он запущен. Запускайте его от имени выделенного непривилегированного пользователя без прав sudo, не храните на машине production-учетные данные, избегайте автоматического подтверждения --yolo и используйте --sandbox (Docker или Podman) для изоляции вызовов инструментов от хоста. Учетная запись, под которой работает процесс, важнее любого отдельного флага.

Нужно ли открывать какие-либо порты на фаерволе для Gemini CLI?

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