Cómo ejecutar Gemini CLI en un VPS sin interfaz gráfica

Qué está construyendo

Un Gemini CLI siempre activo en un servidor que usted administra, accesible mediante SSH y capaz de ejecutar tareas largas del agente que siguen funcionando después de cerrar el portátil. La instalación requiere tres comandos. El trabajo está en todo lo que presupone un entorno de escritorio: la CLI de Google intenta abrir un navegador para iniciar sesión, pero el servidor no tiene ninguno. Por eso, la mayor parte de esta guía cubre el procedimiento sin interfaz gráfica, una versión actual de Node que la distribución no proporciona, una instalación global de npm que no requiere root, autenticación sin navegador mediante una clave de API que se mantiene fuera del historial del shell y tmux, para que una sesión SSH interrumpida no detenga la tarea en ejecución.

Gemini CLI es un programa de Node de código abierto (Apache-2.0) (@google/gemini-cli) que se comunica con los modelos Gemini de Google y puede leer y escribir archivos, ejecutar comandos de shell y utilizar herramientas en el directorio de trabajo. En un VPS, es un agente pequeño y siempre disponible que puede dejar ejecutándose. Por eso, la cuenta con la que se ejecuta y las credenciales almacenadas en el servidor son más importantes que cualquier ajuste concreto de esta guía.

Requisitos previos y advertencias importantes

• Un VPS KVM nuevo con Ubuntu 24.04 y acceso como root o mediante sudo. Cualquier plan KVM sirve; la CLI consume pocos recursos y usa unos cientos de MB de RAM cuando está inactiva.
• Node.js 20 o posterior. Este es el único requisito estricto de versión y el paquete de la distribución no lo cumple; consulte la sección siguiente. Node 20 llegó al final de su vida útil el April 30, 2026, por lo que debe instalar Node 24.
• HTTPS saliente (puerto 443) hacia las API de Google. No se necesitan puertos entrantes; es un cliente, no un servidor, por lo que no debe abrir ninguna regla del firewall.
• Un método de autenticación que no requiera un navegador en el servidor: una clave de API de Gemini de pago de Google AI Studio o el inicio de sesión de Google, que en un sistema sin interfaz gráfica requiere pegar un código en el terminal. La opción de la clave de API es la adecuada para scripts y ejecuciones desatendidas.
• Docker o Podman, sólo si quiere el aislamiento de --sandbox. Es opcional y se explica cerca del final.

El problema que ahora afecta a todo el mundo está en la cuenta, no en el navegador. Google anunció el May 19, 2026 que, a partir del June 18, 2026, Gemini CLI dejaría de atender solicitudes de los suscriptores de Google AI Pro y Ultra y de cualquier usuario que lo utilice de forma gratuita, y dirige a esos usuarios a su sustituto, Antigravity CLI (agy). Gemini CLI sigue funcionando con claves de API de Gemini de pago, claves de API de Gemini Enterprise Agent Platform y una licencia Gemini Code Assist Standard o Enterprise de una organización. Decida el método de autenticación antes de empezar.

Node: el paquete de la distribución es demasiado antiguo

Ubuntu 24.04 incluye Node 18.19.1 en sus propios repositorios, junto con npm 9.2.0. package.json de Gemini CLI declara engines: { node: ">=20" }, y npm no detiene por defecto la instalación cuando hay una discrepancia. La instalación continúa y muestra una advertencia que indica la diferencia:

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 }

Si ignora esa advertencia, la CLI se ejecuta en un runtime no compatible. Puede comportarse de forma incorrecta o bloquearse cuando llegue a una API de Node 20+ que espera que exista. Además, Node 18 llegó al final de su vida útil en abril de 2025, por lo que no es una opción viable. Instale una versión LTS actual antes de instalar la CLI. Las dos opciones adecuadas son NodeSource, un repositorio apt firmado para todo el sistema, o nvm, un gestor de versiones por usuario. Elija una.

NodeSource, si quiere que Node esté disponible para todos los usuarios del equipo:

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 debe mostrar v20.x o una versión posterior para cumplir los requisitos de la CLI. Sin embargo, Node 20 llegó al final de su vida útil el 30 de abril de 2026, por lo que debe elegir v24.x, la versión LTS activa actual. Está previsto que Node 26 se convierta en la versión LTS activa el 28 de octubre de 2026. Consulte la página de NodeSource para obtener el script de configuración actual. El valor setup_24.x de la URL es el que debe actualizar cuando se publique una versión LTS más reciente.

nvm, si prefiere mantener Node en el directorio personal de un usuario y no modificarlo nunca con sudo:

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

El valor v0.40.1 de esa URL era el actual cuando se redactó este texto. Consulte el README de nvm para conocer la versión más reciente y sustituya la versión de la URL antes de ejecutar el comando. nvm ofrece una ventaja importante en este caso: instala Node y sus paquetes globales en ~/.nvm, por lo que el problema de permisos de la instalación global de la siguiente sección no se produce. Si elige nvm, puede omitir el paso de configuración de npm-prefix.

Instale la CLI sin sudo npm -g

El comando tentador es sudo npm install -g @google/gemini-cli. No lo use. Un prefijo global propiedad de root provoca errores de permisos en cada instalación posterior y deja archivos propiedad de root en la caché de npm que causarán problemas meses después. Si ejecuta un npm install -g normal, sin sudo, contra un Node del sistema, aparecerá el otro 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 intenta escribir en /usr/lib, pero su usuario no tiene permisos. La solución no es usar sudo. Debe indicar a npm que use su directorio personal como prefijo global, para que las instalaciones globales se guarden en una ubicación de su propiedad:

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, y no ~/.profile, es intencionado: tmux, que ejecutará la CLI dentro de dos secciones, inicia un shell que no es de inicio de sesión. Ese shell lee ~/.bashrc y omite ~/.profile. Por eso, una línea PATH en el archivo incorrecto deja gemini invisible exactamente donde lo necesita. Que gemini --version muestre un número de versión es la prueba completa. Si obtiene gemini: command not found, la exportación de PATH no se aplicó. Consulte las causas de error. Con nvm, omita por completo las líneas del prefijo: nvm ya instala los paquetes globales en su directorio personal.

Si ejecutó sudo npm anteriormente y ahora ve Your cache folder contains root-owned files, corríjalo una vez con sudo chown -R $(id -u):$(id -g) ~/.npm.

El problema de autenticación sin interfaz gráfica y cómo resolverlo

Ejecute gemini de forma interactiva la primera vez. El programa le ofrecerá iniciar sesión con su cuenta de Google. En un equipo de escritorio, abrirá una pestaña del navegador. En un VPS Linux sin interfaz gráfica, la CLI comprueba primero si hay una pantalla disponible. Si ninguna de DISPLAY, WAYLAND_DISPLAY o MIR_SOCKET está definida, no intenta abrir un navegador. Muestra un enlace de inicio de sesión y espera a que pegue un código:

Please visit the following URL to authorize the application:

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

Enter the authorization code:

Este flujo funciona mediante SSH normal, pero requiere que tenga un navegador disponible cada vez. Además, desde el 18 de junio de 2026 sólo permite iniciar sesión si su cuenta de Google pertenece al grupo de cuentas que Gemini CLI sigue admitiendo.

Hay dos formas válidas de resolverlo.

La primera es usar una clave de API. Es la opción predeterminada adecuada para un servidor. Cree una clave en Google AI Studio (aistudio.google.com) dentro de un proyecto con la facturación activada, porque Gemini CLI ya no admite el uso gratuito. Después, proporciónela a la CLI mediante una variable de entorno; la CLI lee GEMINI_API_KEY y omite por completo el flujo del navegador. Ahora debe evitar que la clave quede en el historial y en archivos legibles por otros usuarios. No escriba export GEMINI_API_KEY=AIza... en el indicador, porque se guardará en ~/.bash_history en texto sin cifrar. Tampoco la incluya en un archivo que otros usuarios puedan leer. Escríbala en un archivo con permisos 600 que el shell cargue al iniciarse:

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 significa que sólo su usuario puede leer el archivo. Confirme que la clave haya llegado al entorno con printenv GEMINI_API_KEY. Si no muestra nada, la CLI vuelve al selector de autenticación en lugar de usar la clave. También lee un archivo .env en ~/.gemini/ si prefiere esa estructura. Se aplica la misma regla, por lo que chmod 600 ~/.gemini/.env.

La segunda opción es el inicio de sesión de Google. En un servidor sin interfaz gráfica no requiere un túnel ni un puerto abierto. Desde el 18 de junio de 2026, resulta principalmente útil para la licencia Gemini Code Assist Standard o Enterprise de una organización (defina también GOOGLE_CLOUD_PROJECT). Las cuentas personales gratuitas y las suscripciones Google AI Pro o Ultra ya no son compatibles. Inicie la CLI mediante una sesión SSH normal y seleccione Sign in with Google:

gemini

Copie la URL mostrada en el navegador de su equipo portátil y apruebe el acceso. Google redirige a https://codeassist.google.com/authcode, que muestra un código de autorización. Péguelo en el indicador Enter the authorization code: del VPS y el inicio de sesión finalizará. El servidor no espera ninguna devolución de llamada, por lo que no es necesario reservar ningún puerto ni configurar ssh -L. OAUTH_CALLBACK_PORT sólo es relevante para el flujo de loopback que usa la CLI cuando detecta una pantalla. Si se conectó mediante el reenvío X11 (ssh -X), DISPLAY estará definida y la CLI usará ese flujo de loopback en su lugar, con una redirección a http://127.0.0.1:PORT/oauth2callback en el servidor. Ejecute NO_BROWSER=true gemini para forzar el flujo de pegar un código. Funciona, pero requiere que tenga un navegador disponible, por lo que no sirve para scripts. Para cualquier proceso que vaya a dejar ejecutándose, use la clave de API.

Para usar Vertex AI o un proyecto de Google Cloud en lugar de AI Studio, defina GOOGLE_API_KEY junto con GOOGLE_GENAI_USE_VERTEXAI=true, o GOOGLE_CLOUD_PROJECT para una licencia de Code Assist. Mantenga la misma disciplina con las variables de entorno y use el mismo archivo con permisos 600.

Ejecutarlo dentro de tmux para que una sesión SSH interrumpida no lo finalice

Un proceso de gemini que se inicia directamente desde el shell SSH es hijo de ese shell. Si se pierde la conexión, se cierra el portátil, se interrumpe la red Wi-Fi o se alcanza un tiempo de espera por inactividad, sshd desmonta el pseudo-terminal, el shell recibe SIGHUP y, a su vez, lo propaga al CLI. Una tarea que lleva diez minutos editando archivos termina con él, y al volver a conectarse no hay ningún proceso que recuperar.

tmux soluciona esto porque controla el shell, en lugar de que sshd lo controle a él. Es el mismo patrón que ejecutar un agente de programación con IA en un VPS remoto dentro de tmux, y aquí funciona de la misma forma:

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 se conecta a una sesión llamada gemini si existe y la crea si no existe, por lo que es el único comando que debe ejecutar justo después de cada inicio de sesión. El shell interno pertenece al servidor tmux desconectado, no a la sesión SSH, por lo que una interrupción de la conexión no detiene el CLI. Vuelva a conectarse, conéctese a la sesión y recuperará el mismo historial desplazable. Si termina ejecutando varias sesiones del agente en un mismo equipo, use una sesión de tmux por cada una. En este caso no pueden comunicarse entre sí, a diferencia de Claude Code, donde una sesión puede pasar texto a otra en el mismo VPS. Mantenga cada trabajo de Gemini independiente o coordínelos mediante archivos en disco.

Para ejecuciones no interactivas mediante scripts, Gemini CLI tiene un modo sin interfaz: gemini -p "summarise the failing tests in this repo" muestra una respuesta y termina, y --output-format json genera una salida legible por máquinas para canalizarla a otro proceso. El modo sin interfaz con una clave API es exactamente lo que necesita dentro de una sesión tmux que ejecute un trabajo por lotes largo, o al iniciarlo desde una entrada de cron, con una salvedad: un trabajo de cron no carga ninguno de los archivos de inicio de sesión. Por tanto, asigne a la línea de crontab su propio GEMINI_API_KEY (o haga que el comando cargue ~/.gemini_env); de lo contrario, la ejecución falla porque faltan las credenciales.

Aislamiento y permisos en un servidor que también ejecuta producción

Un agente con acceso al shell tiene acceso al shell. Gemini CLI puede ejecutar comandos y, de forma predeterminada, solicita confirmación antes de cada comando de riesgo. Sin embargo, es fácil usar --yolo (aprobación automática de todas las llamadas a herramientas). En ese caso, puede borrar archivos, hacer push a git o acceder a servicios internos con todos los permisos del usuario con el que se ejecuta. En un servidor que también ejecuta producción, el impacto potencial es real, no hipotético.

Tres controles, ordenados según el beneficio que aportan:

• Ejecútelo con un usuario dedicado y sin privilegios. No lo ejecute como root ni con un usuario que pertenezca a sudo. Cree un usuario agent con su propio directorio personal e instale allí Node y la CLI. Así, una instrucción interpretada de forma incorrecta queda limitada a esa cuenta. Esta es la decisión individual con mayor impacto.
• Mantenga las credenciales de producción fuera del servidor. No almacene ~/.aws/credentials de producción, no copie .env desde producción y no use una contraseña de base de datos con permisos de escritura sobre recursos importantes. Proporcione credenciales de staging o de sólo lectura.
• Use el sandbox integrado. Si Docker o Podman están instalados, gemini --sandbox (o GEMINI_SANDBOX=docker) ejecuta las llamadas a herramientas del agente dentro de un contenedor que monta únicamente el directorio del proyecto actual, no el resto del sistema de archivos del host. No sustituye al usuario sin privilegios, pero proporciona una segunda capa sólida cuando el mismo VPS ejecuta servicios reales.

Si ejecuta Gemini CLI junto con otras herramientas autoalojadas, por ejemplo un servidor MCP que expone herramientas al agente en el mismo VPS, trate cada capacidad adicional como una ampliación de la superficie a la que puede acceder el agente y limite los tokens que recibe a una única tarea.

Cuota, coste y la ruta de autenticación elegida

La ruta de autenticación determina cómo se factura el servicio y, desde el 18 de junio de 2026, también si se atienden las solicitudes. Desde esa fecha, según el anuncio de Google, Gemini CLI dejó de atender solicitudes de los suscriptores de Google AI Pro y Ultra, así como de quienes lo usan de forma gratuita. Esto incluye el nivel gratuito de las cuentas personales y las claves de API sin facturación. Sigue disponible mediante claves de API de Gemini de pago y claves de API de Gemini Enterprise Agent Platform, que cobran por token, y para organizaciones con una licencia de Gemini Code Assist Standard o Enterprise u otro acceso a Google Cloud, cuya facturación se realiza mediante Google Cloud. Cada nivel mantiene límites por minuto y por día. Si los supera, las solicitudes devuelven un error de límite de tasa hasta que se restablece la ventana.

Hay dos aspectos prácticos. Un agente desatendido dentro de un bucle puede consumir la cuota rápidamente, así que monitorícelo las primeras veces antes de confiarle una tarea de cron. Además, si necesita un modelo en el servidor por motivos de privacidad o para ejecutar inferencia sin medición, en lugar de usar los modelos alojados de Google, se trata de otra herramienta. Alojar un LLM abierto con Ollama en un VPS mantiene los pesos y las solicitudes en su propio servidor, pero obliga a ejecutar un modelo mucho más pequeño que Gemini.

Mantenerlo actualizado

Gemini CLI publica versiones con frecuencia. Como lo instaló en un prefijo propiedad del usuario, las actualizaciones no necesitan sudo:

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

Hay varios canales de publicación: @latest es el estable, @preview es la versión preliminar semanal y @nightly es la versión más reciente en desarrollo. Fije la versión en @latest para cualquier entorno del que dependa. Con nvm, los paquetes globales se almacenan en la versión activa de Node. Por eso, después de nvm use para cambiar de versión de Node, es posible que deba volver a instalar la CLI. Lea las notas de la versión en lugar de instalar cada parche inmediatamente.

Modos de fallo, con las cadenas exactas

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' } y, después, el fallo de la CLI durante la ejecución. Node es demasiado antiguo: la distribución incluye la versión 18.19.1, que también está fuera de soporte. Instale una versión LTS actual desde NodeSource o nvm (Node 20 cumple la versión mínima de la CLI, pero también quedó fuera de soporte en abril de 2026), confirme la versión con node --version y, si tiene varias versiones de Node instaladas, compruebe que which node apunta a la nueva y no a /usr/bin/node.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. Se ha realizado una instalación global en un prefijo propiedad de root. No use sudo para esa instalación. Configure npm config set prefix ~/.npm-global, añada ~/.npm-global/bin a PATH y vuelva a instalar como usuario normal. Si un sudo npm anterior dejó archivos de caché propiedad de root (Your cache folder contains root-owned files), ejecute sudo chown -R $(id -u):$(id -g) ~/.npm.

Failed to open browser o un redirect_uri que apunta a http://127.0.0.1:PORT y que no puede alcanzar. La CLI encontró una variable de display, normalmente procedente de ssh -X, y usó el flujo de loopback, cuyo callback llega al servidor. Ejecute NO_BROWSER=true gemini para obtener el flujo de copiar y pegar un código, o use la ruta de la clave de API (GEMINI_API_KEY). En una sesión SSH normal debería ver Enter the authorization code:. Apruebe la URL en el navegador de su portátil y pegue el código que muestra Google.

El proceso desapareció al cerrarse la conexión SSH. Ejecutó gemini directamente desde el shell SSH, por lo que era un proceso hijo de ese shell y murió junto con el pty al desconectarse. No hay nada que recuperar. Inicie todas las sesiones con tmux new -A -s gemini y ejecute la CLI dentro de ella.

La autenticación sigue fallando con la clave configurada, la CLI vuelve a mostrar su selector de autenticación o una petición devuelve API key not valid con HTTP 400. La clave no está disponible en el entorno que ve la CLI. Confírmelo con printenv GEMINI_API_KEY. Si está vacío, nunca se cargó ~/.gemini_env. Compruebe que la línea esté en ~/.bashrc, que leen los shells interactivos, incluido tmux, pero no cron ni otros shells no interactivos. Un espacio o unas comillas sobrantes dentro del valor de la clave también producen API key not valid.

429 / RESOURCE_EXHAUSTED / un mensaje de límite de tasa. Ha alcanzado la cuota del nivel que utiliza su autenticación. Espere a que se restablezca la ventana, reduzca la velocidad del agente o cambie a una clave de API facturada. Un agente atascado en un bucle de reintentos seguirá alcanzando este límite. Deténgalo y compruebe qué está haciendo.

FAQ

¿Cómo autentico Gemini CLI en un servidor sin interfaz gráfica?

Use una clave de API de pago, no el inicio de sesión mediante navegador. Cree una clave en Google AI Studio dentro de un proyecto con facturación, guárdela en un archivo con permisos 600 que cargue su shell (export GEMINI_API_KEY=...) y la CLI omitirá por completo el flujo OAuth del navegador. Si inicia sesión con Google, por ejemplo con una licencia Code Assist Standard o Enterprise, la CLI en un servidor sin interfaz gráfica mostrará una URL; ábrala en su portátil, apruebe el acceso y pegue el código que muestra Google cuando aparezca el indicador Enter the authorization code:. No es necesario fijar ningún puerto ni usar un túnel, pero debe estar presente ante un navegador, por lo que no sirve para scripts. Las cuentas personales gratuitas no tienen acceso a Gemini CLI desde June 18, 2026.

¿Por qué la instalación global de npm solicita sudo y cómo puedo evitarlo?

Porque el prefijo global predeterminado de npm es /usr/lib/node_modules y su usuario no puede escribir en él, por lo que un npm install -g simple falla con EACCES. La solución incorrecta es sudo npm -g, porque deja archivos propiedad de root que causan errores en instalaciones posteriores. La solución correcta es establecer el prefijo en su directorio personal (npm config set prefix ~/.npm-global) y añadir su bin a PATH, o usar nvm, que instala automáticamente los paquetes globales en su directorio personal.

¿Cómo mantengo Gemini CLI en ejecución después de desconectarme?

Ejecútelo dentro de tmux. Un proceso iniciado desde su shell SSH termina cuando se pierde la conexión porque es hijo de ese shell; tmux ejecuta el shell dentro de un servidor separado que sobrevive a la desconexión. Use tmux new -A -s gemini, ejecute gemini dentro de la sesión, sepárese con Ctrl-b d y vuelva a conectarse más tarde con tmux attach -t gemini.

¿Es seguro ejecutar Gemini CLI en un servidor de producción?

Sólo si procede con cuidado, porque un agente con acceso al shell puede hacer cualquier cosa que pueda hacer el usuario con el que se ejecuta. Ejecútelo con un usuario dedicado sin privilegios y sin sudo, no guarde credenciales de producción en el equipo, evite --yolo para la aprobación automática y use --sandbox (Docker o Podman) para aislar las llamadas a herramientas del host. La cuenta con la que se ejecuta importa más que cualquier indicador individual que configure.

¿Necesito abrir puertos del firewall para Gemini CLI?

No. Es un cliente que realiza llamadas HTTPS salientes a las API de Google, por lo que necesita el puerto saliente 443, pero no puertos entrantes. El inicio de sesión de Google en un servidor sin interfaz gráfica tampoco necesita ningún puerto: pegue un código en el terminal en lugar de recibir una devolución de llamada en el servidor. Mantenga bloqueado el tráfico entrante.