Gemini CLI na serwerze VPS: konfiguracja headless

Co budujesz

Zawsze uruchomiony interfejs CLI dla Gemini na własnym serwerze, dostępny przez SSH, wykonujący długotrwałe zadania agenta, które kontynuują pracę po zamknięciu laptopa. Instalacja składa się z trzech poleceń. Nakładu pracy wymaga wszystko, co zakłada środowisko graficzne: CLI Google próbuje otworzyć przeglądarkę w celu zalogowania, a serwer jej nie posiada. Dlatego większość tego przewodnika dotyczy pracy w trybie headless, instalacji aktualnej wersji Node, której nie dostarcza dystrybucja, globalnej instalacji npm niewymagającej uprawnień root, uwierzytelniania bez przeglądarki przy użyciu klucza API przechowywanego poza historią powłoki oraz użycia tmux, aby zerwane połączenie SSH nie przerywało działającego zadania.

Gemini CLI to program Node typu open-source (Apache-2.0) (@google/gemini-cli), który komunikuje się z modelami Gemini firmy Google i potrafi odczytywać oraz zapisywać pliki, wykonywać polecenia powłoki i obsługiwać narzędzia w katalogu roboczym. Na serwerze VPS jest to niewielki, zawsze dostępny agent, którego można pozostawić w trakcie pracy, dlatego konto, na którym działa, oraz poświadczenia znajdujące się na maszynie mają większe znaczenie niż jakiekolwiek pojedyncze ustawienie opisane w tym dokumencie.

Wymagania wstępne i istotne uwagi

• Świeża instancja Ubuntu 24.04 KVM VPS z dostępem root lub sudo. Każdy plan KVM jest wystarczający; sam interfejs CLI jest lekki i w spoczynku zajmuje kilkaset MB pamięci RAM.
• Node.js w wersji 20 lub nowszej. Jest to sztywny wymóg minimalny, a pakiet dystrybucyjny jest starszy, co wyjaśniono w kolejnej sekcji. Wsparcie dla Node 20 zakończyło się 30 kwietnia 2026 r., dlatego należy zainstalować wersję 24.
• Ruch wychodzący HTTPS (port 443) do API Google. Porty przychodzące nie są wymagane; narzędzie działa jako klient, a nie serwer, więc nie ma potrzeby otwierania portów w zaporze sieciowej.
• Metoda uwierzytelniania niewymagająca przeglądarki na serwerze: płatny klucz Gemini API z Google AI Studio lub logowanie przez konto Google, które w środowisku bez interfejsu graficznego wymaga wklejenia kodu w terminalu. Ścieżka z kluczem API jest rozwiązaniem skalowalnym dla skryptów i zadań wykonywanych bez nadzoru.
• Docker lub Podman, tylko jeśli wymagana jest izolacja --sandbox. Opcjonalne, opisane pod koniec dokumentacji.

Najczęstszym problemem jest obecnie kwestia konta, a nie przeglądarki. Google ogłosiło 19 maja 2026 r., że od 18 czerwca 2026 r. Gemini CLI przestanie obsługiwać żądania dla subskrybentów Google AI Pro i Ultra oraz użytkowników korzystających z wersji bezpłatnej, kierując ich do następcy, czyli Antigravity CLI (agy). Gemini CLI nadal współpracuje z płatnymi kluczami Gemini API, kluczami Gemini Enterprise Agent Platform API oraz licencjami Gemini Code Assist Standard lub Enterprise w ramach organizacji. Wybierz metodę uwierzytelniania przed rozpoczęciem pracy.

Uwaga: pakiet dystrybucyjny jest zbyt stary

Ubuntu 24.04 dostarcza Node 18.19.1 w swoich repozytoriach wraz z npm 9.2.0. Plik package.json narzędzia Gemini CLI deklaruje engines: { node: ">=20" }, a npm domyślnie nie przerywa instalacji w przypadku niezgodności; instaluje pakiet mimo wszystko i wyświetla ostrzeżenie wskazujące na różnicę:

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 }

Zignorowanie tego ostrzeżenia powoduje, że CLI działa w nieobsługiwanym środowisku wykonawczym, co prowadzi do błędów lub awarii w momencie wywołania API z Node 20+, którego CLI oczekuje. Node 18 osiągnął status end-of-life w kwietniu 2025 roku, więc jest to rozwiązanie nieprzyszłościowe. Przed instalacją CLI należy zainstalować aktualną wersję LTS. Dostępne są dwie poprawne metody: NodeSource (podpisane repozytorium apt dla całego systemu) lub nvm (menedżer wersji dla poszczególnych użytkowników). Należy wybrać jedną z nich.

NodeSource, jeśli Node ma być dostępny dla każdego użytkownika w systemie:

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

Polecenie node --version musi zwrócić v20.x lub wyższą wartość, aby spełnić wymagania CLI, jednak Node 20 osiągnął status end-of-life 30 kwietnia 2026 roku, dlatego należy celować w v24.x, czyli aktualną wersję LTS. Node 26 ma stać się aktywną wersją LTS 28 października 2026 roku. Należy sprawdzić stronę NodeSource w celu uzyskania aktualnego skryptu instalacyjnego; setup_24.x w adresie URL to parametr, który należy zaktualizować po wydaniu nowszej wersji LTS.

nvm, jeśli Node ma pozostać w katalogu domowym użytkownika bez użycia sudo:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node --version

Wersja v0.40.1 w powyższym adresie URL była aktualna w momencie tworzenia dokumentacji; przed uruchomieniem skryptu należy sprawdzić plik README projektu nvm w celu znalezienia najnowszego wydania i podstawić odpowiednią wersję. nvm posiada istotną zaletę w tym zastosowaniu: instaluje Node oraz pakiety globalne wewnątrz ~/.nvm, dzięki czemu problem z uprawnieniami przy instalacji globalnej, opisany w następnej sekcji, w ogóle nie występuje. W przypadku wyboru nvm można pominąć krok dotyczący npm-prefix.

Instalacja CLI bez sudo npm -g

Kuszącym poleceniem jest sudo npm install -g @google/gemini-cli. Nie należy go używać. Globalny prefiks należący do root powoduje błędy uprawnień przy każdej kolejnej instalacji i pozostawia w pamięci podręcznej npm pliki należące do root, co wywoła problemy w przyszłości. Uruchomienie zwykłego (bez sudo) npm install -g w systemowym Node prowadzi do innego błędu:

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'

Jest to próba zapisu przez npm do /usr/lib, do czego użytkownik nie posiada uprawnień. Rozwiązaniem nie jest sudo, lecz wskazanie globalnego prefiksu npm na katalog domowy, aby globalne instalacje trafiały do lokalizacji, do której użytkownik ma pełne prawa:

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

Użycie ~/.bashrc, a nie ~/.profile, jest celowe: tmux, w którym CLI będzie uruchamiane za dwie sekcje, inicjuje powłokę typu non-login, która odczytuje ~/.bashrc i pomija ~/.profile. W rezultacie linia PATH w niewłaściwym pliku sprawi, że gemini będzie niewidoczne dokładnie tam, gdzie jest wymagane. Wyświetlenie numeru wersji przez gemini --version stanowi pełny test. Jeśli zamiast tego pojawi się gemini: command not found, eksport PATH nie został zastosowany; należy sprawdzić tryby awarii. W przypadku nvm należy całkowicie pominąć linie z prefiksem: instaluje on pakiety globalne w katalogu domowym automatycznie.

Jeśli wcześniej uruchomiono sudo npm i widoczny jest błąd Your cache folder contains root-owned files, należy go jednorazowo naprawić za pomocą sudo chown -R $(id -u):$(id -g) ~/.npm.

Problem uwierzytelniania bez interfejsu graficznego i sposoby jego rozwiązania

Uruchomienie gemini w trybie interaktywnym za pierwszym razem oferuje logowanie przez konto Google. Na komputerze stacjonarnym otwiera to kartę przeglądarki. Na serwerze VPS z systemem Linux bez interfejsu graficznego, CLI najpierw sprawdza dostępność wyświetlacza. Gdy zmienne DISPLAY, WAYLAND_DISPLAY lub MIR_SOCKET nie są ustawione, narzędzie nie próbuje uruchamiać przeglądarki. Wyświetla link do logowania i oczekuje na wklejenie kodu zwrotnego:

Please visit the following URL to authorize the application:

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

Enter the authorization code:

Ten proces działa przez standardowe połączenie SSH, lecz wymaga każdorazowej obecności przy przeglądarce. Od 18 czerwca 2026 r. logowanie powiodzie się tylko wtedy, gdy konto Google jest obsługiwane przez Gemini CLI.

Istnieją dwa poprawne rozwiązania tego problemu.

Pierwszym jest użycie klucza API, co stanowi zalecaną metodę dla serwerów. Należy utworzyć klucz w Google AI Studio (aistudio.google.com) w ramach projektu z włączonym rozliczaniem, ponieważ Gemini CLI nie obsługuje już darmowego dostępu. Klucz należy przekazać do CLI jako zmienną środowiskową; narzędzie odczytuje GEMINI_API_KEY i całkowicie pomija proces logowania przez przeglądarkę. Należy pamiętać o zasadzie nieprzechowywania klucza w historii powłoki ani w plikach dostępnych dla innych użytkowników. Nie należy wpisywać export GEMINI_API_KEY=AIza... bezpośrednio w wierszu poleceń, ponieważ zapisuje to klucz w postaci jawnej w ~/.bash_history. Nie należy również umieszczać go w plikach z uprawnieniami do odczytu dla innych osób. Klucz należy zapisać w pliku z uprawnieniami 600, który powłoka wczytuje przy starcie:

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 oznacza, że tylko dany użytkownik może odczytać plik. Należy potwierdzić obecność klucza w środowisku za pomocą printenv GEMINI_API_KEY; jeśli polecenie nie zwraca wartości, CLI powróci do wyboru metody uwierzytelniania zamiast użyć klucza. Narzędzie odczytuje również plik .env w ~/.gemini/, jeśli preferowana jest taka struktura; obowiązuje ta sama zasada, więc należy wykonać chmod 600 ~/.gemini/.env.

Drugim sposobem jest logowanie przez konto Google, które na serwerze bez interfejsu graficznego nie wymaga tunelowania ani otwierania portów. Od 18 czerwca 2026 r. metoda ta jest przydatna głównie w przypadku licencji Gemini Code Assist Standard lub Enterprise w organizacji (należy również ustawić GOOGLE_CLOUD_PROJECT); darmowe konta osobiste oraz subskrypcje Google AI Pro lub Ultra nie są już obsługiwane. Należy uruchomić CLI w standardowej sesji SSH i wybrać opcję logowania przez Google:

gemini

Wyświetlony adres URL należy skopiować do przeglądarki na komputerze lokalnym i zatwierdzić. Google przekieruje użytkownika na https://codeassist.google.com/authcode, gdzie wyświetlony zostanie kod autoryzacyjny; należy go wkleić w wierszu poleceń Enter the authorization code: na serwerze VPS, aby zakończyć logowanie. Żaden proces na serwerze nie oczekuje na wywołanie zwrotne, więc nie ma potrzeby blokowania portów ani konfigurowania ssh -L. Zmienna OAUTH_CALLBACK_PORT ma znaczenie tylko dla przepływu lokalnego (loopback), używanego przez CLI po wykryciu wyświetlacza. W przypadku połączenia z przekierowaniem X11 (ssh -X), zmienna DISPLAY jest ustawiona, a CLI wybiera przepływ lokalny z przekierowaniem na http://127.0.0.1:PORT/oauth2callback na serwerze; należy uruchomić NO_BROWSER=true gemini, aby wymusić przepływ z wklejaniem kodu. Metoda ta działa, lecz wymaga dostępu do przeglądarki, więc nie nadaje się do skryptów. W przypadku usług działających w tle należy użyć klucza API.

W przypadku korzystania z Vertex AI lub projektu Google Cloud zamiast AI Studio, należy ustawić GOOGLE_API_KEY wraz z GOOGLE_GENAI_USE_VERTEXAI=true lub GOOGLE_CLOUD_PROJECT dla licencji Code Assist. Obowiązują te same zasady dotyczące zmiennych środowiskowych oraz pliku z uprawnieniami 600.

Uruchomienie wewnątrz tmux, aby zerwane połączenie SSH nie przerywało pracy

Proces gemini uruchomiony bezpośrednio z powłoki SSH jest procesem potomnym tej powłoki. Utrata połączenia, zamknięcie laptopa, zerwanie Wi-Fi lub przekroczenie limitu czasu bezczynności powoduje, że sshd zamyka pseudo-terminal, powłoka otrzymuje sygnał SIGHUP i kończy działanie. Zadanie edycji plików trwające dziesięć minut zostaje przerwane, a po ponownym połączeniu proces jest nie do odzyskania.

tmux rozwiązuje ten problem, przejmując kontrolę nad powłoką zamiast sshd. Jest to ten sam schemat, co w przypadku uruchamiania agenta programistycznego AI na zdalnym VPS wewnątrz tmux, i działa tutaj identycznie:

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 dołącza do sesji o nazwie gemini, jeśli ta istnieje, lub tworzy ją, jeśli nie istnieje. Jest to zatem polecenie, które warto wykonać zaraz po każdym zalogowaniu. Powłoka wewnątrz należy do odłączonego serwera tmux, a nie do sesji SSH, więc zerwanie połączenia nie przerywa pracy CLI. Po ponownym połączeniu i dołączeniu do sesji użytkownik wraca do tego samego stanu terminala. Jeśli na jednej maszynie uruchomionych jest kilka sesji agenta, po jednej na sesję tmux, nie mają one możliwości komunikacji między sobą, w przeciwieństwie do Claude Code, gdzie jedna sesja może przekazać tekst do drugiej na tym samym VPS. Należy zatem traktować każde zadanie Gemini jako niezależne lub koordynować je za pomocą plików na dysku.

W przypadku uruchomień skryptowych, nieinteraktywnych, Gemini CLI posiada tryb bezgłowy (headless): gemini -p "summarise the failing tests in this repo" wypisuje odpowiedź i kończy działanie, a --output-format json generuje wynik w formacie czytelnym dla maszyny, który można przekierować dalej. Tryb bezgłowy z kluczem API jest rozwiązaniem zalecanym wewnątrz sesji tmux przy długotrwałych zadaniach wsadowych lub wywoływanych z poziomu cron, z jednym zastrzeżeniem: zadanie cron nie ładuje plików konfiguracyjnych powłoki użytkownika. Należy zatem zapewnić w linii crontab własną zmienną GEMINI_API_KEY (lub wywołać polecenie ładujące ~/.gemini_env), w przeciwnym razie uruchomienie zakończy się niepowodzeniem z powodu braku poświadczeń.

Izolacja (sandboxing) i uprawnienia na serwerze produkcyjnym

Agent z dostępem do powłoki jest powłoką. Gemini CLI może wykonywać polecenia i domyślnie pyta o zgodę przed każdym ryzykownym działaniem, jednak użytkownicy często korzystają z --yolo (automatyczne zatwierdzanie każdego wywołania narzędzia). W takim przypadku agent może usuwać pliki, wypychać zmiany do git lub łączyć się z usługami wewnętrznymi z pełnymi uprawnieniami użytkownika, na którym działa. Na serwerze, który obsługuje środowisko produkcyjne, stanowi to realne zagrożenie, a nie teoretyczne ryzyko.

Trzy mechanizmy kontroli, uszeregowane według skuteczności:

• Uruchamianie jako dedykowany, nieuprzywilejowany użytkownik. Nie root, nie członek grupy sudo. Należy utworzyć użytkownika agent z własnym katalogiem domowym, zainstalować tam Node oraz CLI. Dzięki temu błędnie zinterpretowane polecenie pozostanie ograniczone do tego konta. Jest to najważniejsza decyzja pod kątem bezpieczeństwa.
• Przechowywanie poświadczeń produkcyjnych poza serwerem. Brak produkcyjnych kluczy ~/.aws/credentials, brak plików .env skopiowanych z produkcji, brak haseł do baz danych z uprawnieniami zapisu do istotnych zasobów. Należy używać poświadczeń środowiska staging lub z dostępem tylko do odczytu.
• Wykorzystanie wbudowanego mechanizmu izolacji. Przy zainstalowanym Docker lub Podman, gemini --sandbox (lub GEMINI_SANDBOX=docker) uruchamia wywołania narzędzi agenta wewnątrz kontenera, który montuje tylko bieżący katalog projektu, a nie resztę systemu plików hosta. Nie zastępuje to pracy na nieuprzywilejowanym użytkowniku, ale stanowi silną drugą warstwę ochrony, gdy ten sam VPS wykonuje rzeczywiste zadania.

W przypadku uruchamiania Gemini CLI obok innych narzędzi self-hosted, na przykład serwera MCP udostępniającego narzędzia agentowi na tym samym VPS, każdą dodaną funkcjonalność należy traktować jako zwiększenie powierzchni ataku, do której agent ma dostęp. Tokeny przekazywane agentowi powinny być ograniczone do zakresu jednego zadania.

Limit, koszt i wybrana ścieżka autoryzacji

Ścieżka autoryzacji decyduje o sposobie naliczania opłat, a od 18 czerwca 2026 roku również o tym, czy usługa będzie w ogóle dostępna. Zgodnie z komunikatem Google, od tej daty Gemini CLI przestało obsługiwać żądania dla subskrybentów Google AI Pro i Ultra oraz dla użytkowników korzystających z wersji bezpłatnej, co obejmuje darmowy plan kont osobistych oraz klucze API bez przypisanej metody płatności. Narzędzie pozostaje dostępne poprzez płatne klucze Gemini API oraz Gemini Enterprise Agent Platform API, w których opłaty naliczane są za token, a także dla organizacji posiadających licencję Gemini Code Assist Standard lub Enterprise bądź inny dostęp do Google Cloud, rozliczany przez Google Cloud. Każdy poziom dostępu posiada limity na minutę i na dobę; ich przekroczenie skutkuje zwracaniem błędu rate-limit do momentu zresetowania okna czasowego.

Dwie praktyczne uwagi. Zautomatyzowany agent działający w pętli może szybko wyczerpać limit, dlatego należy monitorować jego pracę przy pierwszych uruchomieniach, zanim zostanie powierzony zadaniu typu cron job. Jeśli powodem wyboru modelu po stronie serwera jest prywatność lub nielimitowane wnioskowanie, a nie korzystanie z modeli hostowanych przez Google, należy użyć innego narzędzia; samodzielne hostowanie otwartego modelu LLM za pomocą Ollama na VPS pozwala przechowywać wagi i prompty na własnym serwerze, kosztem uruchomienia znacznie mniejszego modelu niż Gemini.

Aktualizacja oprogramowania

Gemini CLI otrzymuje częste wydania. Ponieważ instalacja została przeprowadzona w katalogu użytkownika, aktualizacje nie wymagają użycia sudo:

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

Dostępne są kanały wydań: @latest to wersja stabilna, @preview to cotygodniowa wersja zapoznawcza, @nightly to wersja rozwojowa (bleeding edge). W przypadku każdego narzędzia, na którym polegasz, przypnij wersję do @latest. W środowisku nvm pakiety globalne znajdują się wewnątrz aktywnej wersji Node, więc po użyciu nvm use w celu zmiany wersji Node może zaistnieć konieczność ponownej instalacji CLI. Zaleca się czytanie informacji o wydaniach zamiast instalowania każdej poprawki.

Tryby awarii i dokładne komunikaty

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, a następnie awaria CLI w trakcie działania. Wersja Node jest zbyt stara; dystrybucja oferuje 18.19.1, co jest wersją po zakończeniu wsparcia. Zainstaluj aktualne wydanie LTS z NodeSource lub nvm (Node 20 spełnia wymagania minimalne CLI, choć samo wsparcie dla niego zakończyło się w kwietniu 2026), potwierdź wersję za pomocą node --version. Jeśli zainstalowano kilka wersji Node, sprawdź, czy which node wskazuje na nową wersję, a nie na /usr/bin/node.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. Instalacja globalna w prefiksie należącym do root. Nie używaj sudo, ustaw npm config set prefix ~/.npm-global, dodaj ~/.npm-global/bin do PATH i zainstaluj ponownie jako zwykły użytkownik. Jeśli wcześniejsza instalacja sudo npm pozostawiła pliki pamięci podręcznej należące do root (Your cache folder contains root-owned files), wykonaj sudo chown -R $(id -u):$(id -g) ~/.npm.

Failed to open browser lub redirect_uri wskazujący na http://127.0.0.1:PORT, do którego nie ma dostępu. CLI wykryło zmienną wyświetlania (często z ssh -X) i wybrało przepływ loopback, którego wywołanie zwrotne trafia na serwer. Uruchom NO_BROWSER=true gemini, aby uzyskać przepływ z wklejeniem kodu, lub użyj ścieżki z kluczem API (GEMINI_API_KEY). W zwykłej sesji SSH powinieneś zobaczyć Enter the authorization code:; zatwierdź adres URL w przeglądarce na laptopie i wklej kod wyświetlony przez Google.

Proces zniknął po zerwaniu połączenia SSH. Uruchomiłeś gemini bezpośrednio z powłoki SSH, więc był to proces potomny tej powłoki, który zakończył się wraz z pty przy rozłączeniu. Nie ma możliwości odzyskania procesu. Rozpoczynaj każdą sesję od tmux new -A -s gemini i uruchamiaj w niej CLI.

Uwierzytelnianie kończy się niepowodzeniem mimo ustawionego klucza, CLI wraca do wyboru metody uwierzytelniania lub żądanie zwraca API key not valid z kodem HTTP 400. Klucz nie znajduje się w środowisku widocznym dla CLI. Potwierdź to za pomocą printenv GEMINI_API_KEY; jeśli zmienna jest pusta, plik ~/.gemini_env nie został wczytany. Sprawdź, czy odpowiednia linia znajduje się w ~/.bashrc, który jest odczytywany przez powłoki interaktywne (w tym tmux), ale nie przez cron i inne powłoki nieinteraktywne. Zbędna spacja lub cudzysłów wewnątrz wartości klucza również powoduje API key not valid.

429 / RESOURCE_EXHAUSTED / komunikat o przekroczeniu limitu zapytań (rate-limit). Osiągnięto limit dla poziomu uwierzytelniania, z którego korzystasz. Poczekaj na zresetowanie okna czasowego, zmniejsz częstotliwość zapytań agenta lub przejdź na płatny klucz API. Agent zablokowany w pętli ponownych prób stale wyczerpuje limit; zatrzymaj go i sprawdź przyczynę działania.

FAQ

Jak uwierzytelnić Gemini CLI na serwerze bez interfejsu graficznego?

Należy użyć płatnego klucza API, a nie logowania przez przeglądarkę. Klucz należy utworzyć w Google AI Studio w ramach projektu z aktywnym rozliczaniem, a następnie umieścić go w pliku z uprawnieniami 600, z którego korzysta powłoka (export GEMINI_API_KEY=...). Dzięki temu CLI całkowicie pomija proces OAuth w przeglądarce. W przypadku logowania przez konto Google, na przykład w ramach licencji Code Assist Standard lub Enterprise, CLI na serwerze bez interfejsu wyświetli adres URL. Należy go otworzyć na komputerze lokalnym, zatwierdzić dostęp i wkleić kod wygenerowany przez Google w wierszu poleceń Enter the authorization code:. Nie ma potrzeby otwierania portów ani tworzenia tuneli, jednak proces ten wymaga dostępu do przeglądarki, więc nie nadaje się do automatyzacji w skryptach. Od 18 czerwca 2026 r. darmowe konta osobiste nie są obsługiwane przez Gemini CLI.

Dlaczego instalacja globalna npm wymaga sudo i jak tego uniknąć?

Domyślny globalny prefiks npm to /usr/lib/node_modules, do którego użytkownik nie ma uprawnień zapisu, dlatego zwykłe polecenie npm install -g kończy się błędem EACCES. Błędnym rozwiązaniem jest użycie sudo npm -g, co prowadzi do powstania plików należących do roota, które powodują problemy przy kolejnych instalacjach. Prawidłowym rozwiązaniem jest wskazanie prefiksu w katalogu domowym (npm config set prefix ~/.npm-global) i dodanie ścieżki bin do zmiennej PATH lub użycie narzędzia nvm, które automatycznie instaluje pakiety globalne w katalogu użytkownika.

Jak utrzymać działanie Gemini CLI po rozłączeniu sesji?

Należy uruchomić proces wewnątrz tmux. Proces uruchomiony z powłoki SSH kończy się po zerwaniu połączenia, ponieważ jest procesem potomnym tej powłoki. tmux uruchamia powłokę wewnątrz odseparowanego serwera, który działa niezależnie od połączenia. Należy użyć tmux new -A -s gemini, uruchomić gemini, odłączyć się za pomocą Ctrl-b d i powrócić do sesji później za pomocą tmux attach -t gemini.

Czy uruchamianie Gemini CLI na serwerze produkcyjnym jest bezpieczne?

Tylko przy zachowaniu odpowiednich środków ostrożności, ponieważ agent z dostępem do powłoki może wykonać dowolne operacje w ramach uprawnień użytkownika, na którym działa. Należy uruchamiać go jako dedykowany użytkownik bez uprawnień sudo, nie przechowywać na maszynie poświadczeń produkcyjnych, unikać automatycznego zatwierdzania --yolo i używać --sandbox (Docker lub Podman) w celu odizolowania wywołań narzędzi od hosta. Uprawnienia konta, na którym działa proces, są ważniejsze niż jakakolwiek pojedyncza flaga.

Czy muszę otwierać porty w zaporze sieciowej dla Gemini CLI?

Nie. Jest to klient wykonujący wychodzące połączenia HTTPS do API Google, więc wymaga jedynie otwartego portu 443 dla ruchu wychodzącego i żadnych portów dla ruchu przychodzącego. Logowanie Google na serwerze bez interfejsu również nie wymaga otwierania portów: kod wkleja się bezpośrednio do terminala, zamiast oczekiwać na wywołanie zwrotne na serwerze. Ruch przychodzący powinien pozostać zablokowany.