Cara Install Gemini CLI di VPS Headless

Apa yang Anda bangun

Sebuah Gemini CLI yang selalu aktif pada server milik Anda, dapat diakses melalui SSH, dan menjalankan tugas agen jangka panjang yang tetap berjalan setelah laptop ditutup. Proses instalasi hanya memerlukan tiga perintah. Bagian yang sulit adalah semua hal yang memerlukan antarmuka desktop: CLI Google mencoba membuka browser untuk login, sedangkan server Anda tidak memilikinya. Oleh karena itu, sebagian besar panduan ini menggunakan metode headless — versi Node terbaru yang tidak tersedia secara default di distro Anda, instalasi npm global tanpa root, autentikasi tanpa browser menggunakan API key agar tidak tersimpan di riwayat shell, dan tmux agar sesi SSH yang terputus tidak menghentikan tugas yang sedang berjalan.

Gemini CLI adalah program Node open-source (Apache-2.0) (@google/gemini-cli) yang terhubung ke model Gemini Google. Program ini dapat membaca dan menulis file, menjalankan perintah shell, serta mengoperasikan alat di direktori kerja. Pada VPS, ini adalah agen kecil yang selalu tersedia untuk bekerja — itulah sebabnya akun pengguna yang menjalankan program ini, serta kredensial yang tersimpan di server, jauh lebih penting daripada pengaturan lainnya di sini.

Prasyarat dan kendala teknis

• VPS Ubuntu 24.04 KVM baru dengan akses root atau sudo. Semua paket KVM dapat digunakan; CLI ini sangat ringan, hanya membutuhkan beberapa ratus MB RAM saat idle.
• Node.js versi 20 atau yang lebih baru. Ini adalah batas versi minimum yang mutlak, karena paket distribusi (distro) memiliki versi di bawah ini — lihat bagian berikutnya.
• Akses HTTPS keluar (port 443) ke Google APIs. Tidak diperlukan port masuk (inbound); ini adalah klien, bukan server, jadi Anda tidak perlu membuka celah firewall.
• Metode autentikasi yang tidak memerlukan browser di server: menggunakan Gemini API key dari Google AI Studio, atau SSH tunnel ke browser di mesin lokal Anda. Metode API-key lebih disarankan untuk penggunaan skrip dan proses otomatis.
• Docker atau Podman, hanya jika Anda menginginkan isolasi --sandbox. Opsional, dibahas di bagian akhir.

Kendala yang sering dialami pengguna: alur login gemini saat penggunaan pertama dirancang untuk desktop. Sistem akan mencoba membuka browser dan, pada sistem headless, proses ini akan gagal atau memberikan tautan yang tidak dapat dibuka. Tentukan metode autentikasi sebelum memulai.

Node: paket distro terlalu lama

Ubuntu 24.04 menyertakan Node 18.19.1 dalam repositorinya, bersama dengan npm 9.2.0. package.json pada Gemini CLI mendeklarasikan engines: { node: ">=20" }, dan npm tidak menghentikan proses secara otomatis jika terjadi ketidakcocokan — npm tetap menginstal dan menampilkan peringatan mengenai perbedaan versi tersebut:

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 }

Jika Anda mengabaikan peringatan tersebut, CLI akan berjalan pada runtime yang tidak didukung. Hal ini menyebabkan malfungsi atau crash saat CLI memanggil API Node 20+ yang seharusnya tersedia. Node 18 juga telah mencapai akhir masa dukungan (end-of-life) pada April 2025, sehingga versi ini tidak dapat digunakan. Instal versi LTS terbaru sebelum Anda menginstal CLI. Ada dua cara yang bersih: NodeSource (repositori apt bertanda di seluruh sistem) atau nvm (pengelola versi per-pengguna). Pilih salah satu.

NodeSource, jika Anda ingin Node tersedia untuk setiap pengguna di sistem:

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 harus menampilkan v20.x atau lebih tinggi — v24.x adalah LTS aktif saat ini. Periksa halaman NodeSource untuk skrip pengaturan terbaru; setup_24.x pada URL adalah bagian yang harus diperbarui saat LTS baru tersedia.

nvm, jika Anda lebih memilih menyimpan Node di dalam direktori home pengguna dan tidak ingin menggunakan 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 pada URL tersebut adalah versi terbaru saat tulisan ini dibuat; periksa README nvm untuk rilis terbaru dan ganti versinya sebelum dijalankan. nvm memiliki keunggulan untuk tugas ini: nvm menginstal Node dan paket globalnya di bawah ~/.nvm, sehingga masalah izin global-install pada bagian berikutnya tidak akan terjadi. Jika Anda menggunakan nvm, Anda dapat melewati langkah npm-prefix.

Install the CLI tanpa sudo npm -g

Perintah sudo npm install -g @google/gemini-cli terlihat menjanjikan. Jangan gunakan. Prefix global milik root akan menyebabkan error izin pada setiap instalasi berikutnya. Hal ini juga meninggalkan file milik root di dalam npm cache yang akan menyulitkan Anda beberapa bulan kemudian. Menjalankan npm install -g biasa (tanpa sudo) pada Node sistem akan menyebabkan kegagalan lain:

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 mencoba menulis ke /usr/lib, namun user Anda tidak memiliki izin. Solusinya bukan menggunakan sudo — solusinya adalah mengarahkan global prefix npm ke direktori home Anda agar instalasi global tersimpan di lokasi yang Anda miliki:

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, bukan ~/.profile, dilakukan secara sengaja: tmux — yang akan Anda gunakan untuk menjalankan CLI dalam dua bagian ke depan — memulai non-login shell yang membaca ~/.bashrc dan melewati ~/.profile. Akibatnya, baris PATH pada file yang salah akan membuat gemini tidak terlihat di tempat yang Anda butuhkan. Mencetak nomor versi dengan gemini --version adalah pengujian utamanya. Jika Anda mendapatkan gemini: command not found, maka export PATH Anda gagal — lihat mode kegagalan. Pada nvm, lewati baris prefix sepenuhnya: nvm sudah menginstal paket global di bawah direktori home Anda.

Jika Anda menjalankan sudo npm sebelumnya dan sekarang melihat Your cache folder contains root-owned files, perbaiki dengan sudo chown -R $(id -u):$(id -g) ~/.npm.

Masalah autentikasi headless, dan cara mengatasinya

Jalankan gemini secara interaktif untuk pertama kalinya dan program akan menawarkan login menggunakan akun Google Anda. Pada komputer desktop, ini akan membuka tab browser. Pada VPS headless tidak ada browser, sehingga alur kerja akan mencetak URL localhost yang harus Anda buka, atau gagal sepenuhnya dengan pesan seperti:

Failed to open browser. Please visit the following URL to authorize:
https://accounts.google.com/o/oauth2/v2/auth?...&redirect_uri=http://localhost:PORT

Masalahnya terletak pada redirect_uri=http://localhost:PORT. Meskipun Anda membuka URL tersebut di laptop dan menyetujuinya, Google akan mengalihkan ke http://localhost:PORT — localhost di server, sebuah port yang tidak dapat dijangkau oleh laptop Anda. Login tidak akan pernah selesai.

Ada dua cara yang valid untuk mengatasinya.

Cara pertama adalah menggunakan API key, dan ini adalah pilihan default yang tepat untuk server. Buatlah key di Google AI Studio (aistudio.google.com) dan berikan ke CLI sebagai variabel lingkungan; CLI akan membaca GEMINI_API_KEY dan melewati alur browser sepenuhnya. Sekarang perhatikan bagian "menjaga agar key tidak tersimpan di history dan file yang bisa dibaca publik". Jangan mengetik export GEMINI_API_KEY=AIza... pada prompt — data tersebut akan tersimpan di ~/.bash_history dalam bentuk teks biasa, dan jangan menaruhnya di file yang dapat dibaca orang lain. Tulis ke file dengan mode-600 yang di-source oleh shell saat mulai:

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 berarti hanya user Anda yang dapat membaca file tersebut. Pastikan key telah masuk ke lingkungan dengan printenv GEMINI_API_KEY; jika tidak ada output yang muncul, CLI akan kembali ke alur browser dan gagal. CLI juga membaca file .env di ~/.gemini/ jika Anda lebih menyukai tata letak tersebut — aturan yang sama berlaku, jadi gunakan chmod 600 ~/.gemini/.env.

Cara kedua adalah tetap menggunakan login akun Google pribadi (dan kuota gratisnya) dengan cara melakukan tunneling OAuth callback kembali ke laptop Anda. Kendalanya adalah server loopback CLI menggunakan port acak setiap kali dijalankan, sehingga tidak ada port stabil untuk diteruskan kecuali Anda menetapkannya terlebih dahulu dengan variabel lingkungan OAUTH_CALLBACK_PORT, lalu meneruskan port tersebut secara spesifik:

# 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 tidak dapat membuka browser, jadi ia akan mencetak URL autentikasi; buka URL tersebut di browser laptop Anda, setujui, dan saat Google mengalihkan ke http://localhost:8085/..., SSH forwarding akan membawanya ke server loopback di VPS dan login selesai. Jika port tidak ditetapkan, ia akan mendarat di port acak baru setiap kali dijalankan, yang tidak dapat ditangkap oleh ssh -L mana pun yang disiapkan sebelumnya. Cara ini berhasil, tetapi memerlukan Anda untuk tetap membuka browser, sehingga tidak cocok untuk skrip. Untuk proses yang dibiarkan berjalan otomatis, gunakan API key.

Untuk Vertex AI atau proyek Google Cloud sebagai pengganti AI Studio, atur GOOGLE_API_KEY bersama dengan GOOGLE_GENAI_USE_VERTEXAI=true, atau GOOGLE_CLOUD_PROJECT untuk lisensi Code Assist — terapkan disiplin variabel lingkungan yang sama, dan gunakan file mode-600 yang sama.

Jalankan di dalam tmux agar sesi SSH yang terputus tidak menghentikannya

Proses gemini yang Anda jalankan langsung dari shell SSH adalah anak dari shell tersebut. Jika koneksi terputus — laptop tertutup, Wi-Fi terputus, atau timeout karena tidak ada aktivitas — sshd akan menghapus pseudo-terminal, shell menerima SIGHUP, dan akhirnya memutus koneksi CLI. Tugas yang sedang berjalan selama sepuluh menit saat mengedit file akan ikut mati, dan saat Anda masuk kembali, proses tersebut tidak dapat dipulihkan.

tmux mengatasi masalah ini dengan memiliki shell tersebut alih-alih sshd yang memilikinya. Pola ini sama dengan menjalankan AI coding agent pada VPS remote di dalam tmux, dan cara kerjanya identik di sini:

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 akan menyambung ke sesi bernama gemini jika sesi tersebut ada, atau membuatnya jika belum ada. Ini adalah satu perintah yang harus dijalankan segera setelah setiap login. Shell di dalamnya milik server tmux yang terlepas (detached), bukan milik sesi SSH Anda, sehingga koneksi yang terputus tidak akan menghentikan CLI. Masuk kembali, sambungkan kembali, dan Anda akan kembali ke riwayat scrollback yang sama.

Untuk eksekusi skrip non-interaktif, Gemini CLI memiliki mode headless: gemini -p "summarise the failing tests in this repo" mencetak jawaban lalu keluar, dan --output-format json memberikan output yang dapat dibaca mesin untuk diteruskan ke tempat lain. Mode headless dengan API key adalah solusi yang tepat di dalam sesi tmux yang menjalankan tugas batch jangka panjang, atau dijalankan dari entri cron — dengan satu catatan: tugas cron tidak memuat file login Anda, jadi berikan baris crontab GEMINI_API_KEY sendiri (atau buat perintah memuat ~/.gemini_env), jika tidak, CLI akan kembali ke alur browser dan gagal.

Sandboxing dan izin pada sistem yang juga menjalankan produksi

Agen dengan akses shell adalah sebuah shell. Gemini CLI dapat menjalankan perintah, dan secara default ia akan meminta konfirmasi sebelum menjalankan perintah berisiko — namun pengguna sering menggunakan --yolo (persetujuan otomatis untuk setiap pemanggilan tool), sehingga agen dapat menghapus file, melakukan push ke git, atau mengakses layanan internal dengan otoritas penuh dari user yang menjalankannya. Pada sistem yang juga menjalankan produksi, hal ini merupakan risiko nyata, bukan sekadar hipotesis.

Tiga kontrol, diurutkan berdasarkan tingkat efektivitasnya:

• Jalankan sebagai user khusus yang tidak memiliki hak istimewa. Bukan root, bukan anggota dari sudo. Buat user agent dengan direktori home sendiri, instal Node dan CLI di sana, sehingga kesalahan instruksi tetap terbatas pada akun tersebut. Ini adalah keputusan dengan nilai tertinggi.
• Jangan simpan kredensial produksi di sistem tersebut. Tidak ada ~/.aws/credentials produksi, tidak ada .env yang disalin dari produksi, tidak ada kata sandi database dengan akses tulis ke aset penting. Berikan kredensial staging atau kredensial read-only.
• Gunakan sandbox bawaan. Dengan Docker atau Podman terinstal, gemini --sandbox (atau GEMINI_SANDBOX=docker) menjalankan pemanggilan tool agen di dalam container yang terisolasi dari filesystem dan jaringan host. Ini bukan pengganti user tanpa hak istimewa, tetapi merupakan lapisan kedua yang kuat saat VPS yang sama melakukan pekerjaan nyata.

Jika Anda menjalankan Gemini CLI berdampingan dengan tooling self-hosted lainnya — misalnya server MCP yang mengekspos tool ke agen pada VPS yang sama — anggap setiap kemampuan tambahan sebagai perluasan permukaan akses yang dapat dijangkau agen, dan batasi token yang diberikan hanya untuk satu tugas spesifik.

Kuota, biaya, dan jalur autentikasi yang Anda pilih

Jalur autentikasi menentukan metode penagihan Anda. Akun Google pribadi (jalur OAuth) menggunakan tingkatan Gemini Code Assist gratis, dengan batasan per menit dan per hari yang nyata; jika melampaui batasan tersebut, permintaan akan menghasilkan error rate-limit hingga jendela waktu direset. API key dari AI Studio dapat berupa tingkatan gratis atau berbayar tergantung pada proyeknya — kunci berbayar meningkatkan batasan dan mengenakan biaya per token. Autentikasi Vertex dan Cloud-project ditagih melalui Google Cloud.

Dua catatan praktis. Agen yang berjalan otomatis dalam sebuah loop dapat menghabiskan kuota dengan cepat, jadi pantau proses tersebut pada beberapa kali percobaan pertama sebelum Anda mempercayakannya pada cron job. Dan jika alasan Anda menggunakan model sisi server adalah untuk privasi atau inferensi tanpa batas alih-alih menggunakan model hosting Google, itu adalah alat yang berbeda — self-hosting open LLM dengan Ollama pada VPS menjaga bobot model dan prompt tetap berada di mesin Anda sendiri, dengan konsekuensi menjalankan model yang jauh lebih kecil daripada Gemini.

Menjaga pembaruan tetap tersedia

Gemini CLI sering diperbarui. Karena Anda menginstalnya ke dalam prefix milik pengguna, pembaruan tidak memerlukan sudo:

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

Terdapat saluran rilis: @latest adalah versi stabil, @preview adalah pratinjau mingguan, @nightly adalah versi paling mutakhir — gunakan @latest untuk sistem apa pun yang Anda andalkan. Pada nvm, paket global berada di bawah versi Node yang aktif, jadi setelah melakukan nvm use untuk beralih Node, Anda mungkin perlu menginstal ulang CLI. Bacalah catatan rilis daripada mengejar setiap patch.

Mode kegagalan, dengan string yang tepat

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }, kemudian CLI crash saat runtime. Node terlalu lama — versi distro adalah 18.19.1, yang sudah melewati masa akhir dukungan (end-of-life). Instal Node 20+ dari NodeSource atau nvm, konfirmasi dengan node --version, dan jika Anda memiliki beberapa Node yang terinstal, pastikan which node mengarah ke versi baru dan bukan /usr/bin/node.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. Instalasi global ke dalam prefix milik root. Jangan gunakan sudo — atur npm config set prefix ~/.npm-global, letakkan ~/.npm-global/bin pada PATH, dan instal ulang sebagai user biasa Anda. Jika sudo npm sebelumnya meninggalkan file cache milik root (Your cache folder contains root-owned files), jalankan sudo chown -R $(id -u):$(id -g) ~/.npm.

Failed to open browser, login yang macet, atau redirect_uri=http://localhost:PORT yang tidak dapat diakses. Alur OAuth memerlukan browser yang tidak tersedia di server, dan callback localhost-nya mengarah ke server, bukan laptop Anda. Gunakan jalur API-key (GEMINI_API_KEY), atau pin OAUTH_CALLBACK_PORT, teruskan melalui SSH dengan ssh -L, dan buka URL tersebut secara lokal.

Proses hilang saat koneksi SSH terputus. Anda menjalankan gemini langsung dari shell SSH, sehingga proses tersebut menjadi child dari shell tersebut dan mati bersama pty saat koneksi terputus. Tidak ada yang bisa dipulihkan. Mulai setiap sesi dengan tmux new -A -s gemini dan jalankan CLI di dalamnya.

Autentikasi tetap gagal meski kunci sudah diatur — CLI kembali ke pemilih autentikasi, atau permintaan mengembalikan API key not valid dengan HTTP 400. Kunci tidak ada dalam environment yang dilihat oleh CLI. Konfirmasi dengan printenv GEMINI_API_KEY; jika kosong, ~/.gemini_env Anda belum di-source — periksa apakah baris tersebut ada di dalam ~/.bashrc, yang dibaca oleh shell interaktif (termasuk tmux) tetapi tidak oleh cron dan shell non-interaktif lainnya. Spasi atau tanda kutip yang salah di dalam nilai kunci juga menyebabkan API key not valid.

429 / RESOURCE_EXHAUSTED / pesan rate-limit. Anda telah mencapai kuota untuk tier autentikasi yang digunakan. Tunggu hingga jendela waktu reset, perlambat agen, atau pindah ke API key berbayar. Agen yang terjebak dalam loop retry akan terus mengalami ini — hentikan agen tersebut dan periksa apa yang sedang dilakukan.

FAQ

Bagaimana cara autentikasi Gemini CLI pada server headless?

Gunakan API key, bukan login browser. Buat key di Google AI Studio, simpan di file mode-600 yang di-source oleh shell Anda (export GEMINI_API_KEY=...), maka CLI akan melewati alur browser OAuth sepenuhnya. Jika Anda secara khusus ingin menggunakan tier gratis akun pribadi, kunci loopback port dengan OAUTH_CALLBACK_PORT=8085, teruskan kembali ke laptop Anda dengan ssh -L 8085:localhost:8085 user@server, dan buka URL yang muncul secara lokal — namun cara ini memerlukan browser aktif, sehingga tidak cocok untuk skrip.

Mengapa instalasi npm global meminta sudo, dan bagaimana cara menghindarinya?

Karena prefix global default npm adalah /usr/lib/node_modules, di mana user Anda tidak memiliki izin tulis, sehingga perintah npm install -g akan gagal dengan EACCES. Solusi yang salah adalah sudo npm -g, karena akan meninggalkan file milik root yang merusak instalasi berikutnya. Solusi yang benar adalah mengarahkan prefix ke direktori home Anda (npm config set prefix ~/.npm-global) dan menambahkan bin ke PATH, atau gunakan nvm, yang secara otomatis menginstal paket global di bawah direktori home Anda.

Bagaimana cara agar Gemini CLI tetap berjalan setelah saya memutuskan koneksi?

Jalankan di dalam tmux. Proses yang dimulai dari shell SSH akan mati saat koneksi terputus karena merupakan child dari shell tersebut; tmux menjalankan shell di bawah server terpisah (detached server) yang tetap berjalan setelah koneksi terputus. Gunakan tmux new -A -s gemini, jalankan gemini di dalamnya, lepas dengan Ctrl-b d, dan sambungkan kembali nanti dengan tmux attach -t gemini.

Apakah aman menjalankan Gemini CLI pada server produksi?

Hanya jika dilakukan dengan hati-hati, karena agen dengan akses shell dapat melakukan apa pun yang diizinkan oleh user yang menjalankannya. Jalankan sebagai user khusus tanpa hak akses sudo, jangan simpan kredensial produksi di mesin tersebut, hindari auto-approval --yolo, dan gunakan --sandbox (Docker atau Podman) untuk mengisolasi pemanggilan tool dari host. Akun yang menjalankan proses tersebut lebih penting daripada flag apa pun yang Anda atur.

Apakah saya perlu membuka port firewall untuk Gemini CLI?

Tidak. Ini adalah client yang melakukan panggilan HTTPS outbound ke API Google, sehingga hanya memerlukan port outbound 443 dan tidak memerlukan port inbound. Jika Anda menggunakan tunnel OAuth, port callback yang dikunci (misalnya 8085) berada di localhost dan diakses melalui SSH forward, bukan melalui port inbound yang terbuka. Tetap kunci semua akses inbound.