Flujo de trabajo con IA

Los comandos de Zeltro están pensados para el desarrollo con IA. La idea es darle a un agente un entorno fijo en el que trabajar, para que construya tu app en lugar de inventarse la infraestructura.

Zeltro no vende IA. Controla una CLI de agente que tú instalas y en la que inicias sesión, y le pagas directamente a ese proveedor (o nada, con un modelo local).

¿Todavía no tienes uno? La primera vez que abres la app de Zeltro, puedes usar nuestra clave para probarlo: Claude Code con Claude Haiku, sin cuenta, sin tarjeta y sin clave propia, suficiente para probarlo en un primer proyecto (uno por equipo, mientras dure). Pasa por el servidor de Zeltro (consulta la privacidad). Después, conecta tu propia IA como se explica arriba; a partir de ahí nada pasa por Zeltro.

Elegir un agente#

zeltro ai-set --agent claude --model claude-opus-5-5
zeltro ai-set --agent codex  --model gpt-6-sol
zeltro ai-set --agent agy
zeltro ai-set --agent aider  --model anthropic/claude-sonnet-5 --api-key sk-ant-...
zeltro ai-set --agent qwen   --model qwen/qwen3-coder-30b-a3b-instruct --api-base https://openrouter.ai/api/v1 --api-key sk-or-...
zeltro ai-set --agent opencode --model openai/gpt-5.4-mini --api-key sk-...
zeltro ai-set --agent hermes   --model openrouter/qwen/qwen3-coder --api-key sk-or-...
zeltro ai-set --json-output          # inspect current settings (read-only)

Una instalación nueva no tiene ningún agente configurado, y los comandos de IA te indican que primero ejecutes zeltro ai-set. Si no lo tienes claro, elige claude y deja el modelo en blanco para que Claude Code use su propio modelo predeterminado.

Opción Descripción
--agent <name> codex, claude, agy, qwen, aider, opencode o hermes. gemini sigue funcionando, pero está obsoleto (consulta Antigravity CLI). Cambiar de agente borra el modelo y el endpoint guardados.
--model <name> Nombre del modelo. Opcional para Codex, Claude, agy, Gemini, OpenCode y Hermes; necesario para Qwen Code y Aider, y para OpenCode y Hermes con --api-base. OpenCode y Hermes usan provider/model, por ejemplo openai/gpt-5.4-mini
--api-key <key> Clave de API. Opcional para Codex, Claude, agy, OpenCode y Hermes, que pueden usar su propio inicio de sesión; necesaria para Aider y para un modelo alojado de Qwen Code. --api-key "" borra una clave guardada
--api-base <url> Endpoint personalizado. Compatible con OpenAI para qwen, aider, opencode y hermes; compatible con Anthropic para claude. none lo borra. Para Codex, consulta Modelos baratos y locales
--install-only Con --agent: instala la CLI de ese agente si falta, sin convertirlo en el predeterminado
--allow-unattended / --no-allow-unattended Desactiva o vuelve a activar las solicitudes de aprobación del agente en su propia configuración, para usarlo desde la terminal. En la app, decide en cambio el interruptor "Trabaja sin preguntar" de cada proyecto (activado de forma predeterminada) (consulta Modo desatendido)

Cuando eliges un agente que no está instalado, zeltro ai-set lo instala con:

curl -fsSL https://claude.ai/install.sh | bash     # Claude Code
npm install -g @openai/codex                       # Codex
curl -fsSL https://antigravity.google/cli/install.sh | bash   # Antigravity CLI (agy)
npm install -g @qwen-code/qwen-code                # Qwen Code
curl -LsSf https://aider.chat/install.sh | sh      # Aider
npm install -g opencode-ai                         # OpenCode
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- \
  --non-interactive --skip-browser --skip-computer-use   # Hermes Agent

Zeltro solo pasa una clave guardada cuando encaja. Codex recibe la clave solo si empieza por sk- (cualquier clave si hay un endpoint personalizado), y Claude la recibe como ANTHROPIC_API_KEY solo si empieza por sk-ant-. Codex ignora OPENAI_API_KEY, así que Zeltro inicia su sesión con la clave (codex login --with-api-key) en un directorio de Codex propio, ~/.zeltro/codex/<hash of the key>, con tu config.toml enlazado dentro. Tu propio ~/.codex, y cualquier sesión de ChatGPT que tengas ahí, nunca se toca, y cada clave conserva su propio historial de sesiones para zeltro resume. Cualquier otra clave se ignora con un aviso, y la CLI usa su propio inicio de sesión. agy y Gemini reciben una clave guardada como GEMINI_API_KEY (una clave de API de Gemini de aistudio.google.com); agy no admite endpoints personalizados.

zeltro ai-set --json-output por sí solo es de solo lectura. No instala ni escribe nada, e informa del agente, el modelo, el endpoint, si hay una clave guardada, el ajuste de modo desatendido y qué agentes están instalados.

¿Usas modelos más baratos o locales? Consulta Modelos baratos y locales. Qwen Coder en OpenRouter cuesta unas 30 veces menos por token que Claude Sonnet 5, y un modelo local de Ollama no cuesta nada.

La configuración se guarda en /etc/zeltro-cli/.env. Cámbiala siempre con zeltro ai-set en lugar de editar el archivo.

Antigravity CLI (agy)#

agy es la CLI de agente de programación de Google, y reemplaza a Gemini CLI. Google dejó de ofrecer Gemini CLI a las cuentas personales de Google (gratuitas, AI Pro y Ultra) el 2026-06-18. Gemini CLI sigue funcionando con una clave de API de Gemini de pago, así que zeltro ai-set --agent gemini sigue funcionando, pero está obsoleto en Zeltro.

zeltro ai-set --agent agy                        # sign in with Google the first time you run agy
zeltro ai-set --agent agy --api-key AIza...      # or a Gemini API key (aistudio.google.com)

Se instala como un único programa en ~/.local/bin (no necesita Node) y se actualiza solo. Para iniciar sesión con Google, abre una terminal y ejecuta agy una vez. Su primer arranque interactivo también te pide un esquema de colores y muestra las condiciones de Google, donde eliges si Google puede usar tus conversaciones; Zeltro deja esa decisión en tus manos. Con una clave, Zeltro define "modelProvider": "gemini" en ~/.gemini/antigravity-cli/settings.json (sin eso, agy ignora la clave), y lo vuelve a quitar cuando borras la clave, para que el inicio de sesión con Google funcione de nuevo. agy no admite endpoints personalizados, así que no puede usar modelos baratos o locales mediante --api-base.

Aider#

Codex, Claude y agy inician sesión cada uno con su propia cuenta. Aider no. Se comunica directamente con la API de un proveedor, así que necesita un modelo y una clave antes de poder ejecutarse:

# a hosted provider (the model prefix picks it)
zeltro ai-set --agent aider --model anthropic/claude-sonnet-5 --api-key sk-ant-...

# a local OpenAI-compatible server
zeltro ai-set --agent aider --model openai/qwen3-coder:30b \
  --api-key ollama --api-base http://localhost:11434/v1

Zeltro etiqueta la clave con el proveedor del prefijo del modelo (anthropic=sk-ant-...), o con openai si no hay prefijo. --api-base es solo para servidores compatibles con OpenAI (Ollama, LM Studio, OpenRouter, vLLM); déjalo en blanco para usar la API alojada del propio proveedor. Normalmente Aider hace un commit por cada edición. Zeltro lo ejecuta con --no-auto-commits para que sus cambios queden en tu árbol de trabajo, como los de cualquier otro agente.

Qwen Code#

Qwen Code es un agente de terminal de código abierto que nació como fork de Gemini CLI y está construido en torno a los modelos Qwen Coder. Zeltro lo instala con npm install -g @qwen-code/qwen-code.

Zeltro lo ejecuta en modo compatible con OpenAI (--auth-type openai, con la clave y el endpoint en OPENAI_API_KEY y OPENAI_BASE_URL), así que es la vía más sencilla hacia un modelo alojado barato o uno local:

# hosted, pay-as-you-go
zeltro ai-set --agent qwen --model qwen/qwen3-coder-30b-a3b-instruct \
  --api-base https://openrouter.ai/api/v1 --api-key sk-or-...

# local Ollama
zeltro ai-set --agent qwen --model qwen3-coder:30b \
  --api-base http://localhost:11434/v1 --api-key ollama

El inicio de sesión gratuito por OAuth de Qwen se suspendió el 15 de abril de 2026, así que necesita una clave de API o un endpoint local. No hay ninguna vía alojada gratuita a través del propio Qwen. Además, pide Node 22+; funciona en Node 20 con un aviso EBADENGINE, pero no está soportado.

OpenCode#

OpenCode es un agente de terminal de código abierto que funciona con casi cualquier proveedor. Zeltro lo instala con npm install -g opencode-ai. Puede usar su propio inicio de sesión (opencode auth login) o una clave que le des a Zeltro:

# a hosted provider: the model is provider/model, as OpenCode names it
zeltro ai-set --agent opencode --model openai/gpt-5.4-mini --api-key sk-...
zeltro ai-set --agent opencode --model openrouter/deepseek/deepseek-v4.1-flash --api-key sk-or-...

# any OpenAI-compatible server (the model is the name that server uses)
zeltro ai-set --agent opencode --model qwen3-coder:30b \
  --api-base http://localhost:11434/v1 --api-key ollama

La clave va a la variable que lee el proveedor del modelo (OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY o GOOGLE_GENERATIVE_AI_API_KEY). Un endpoint se convierte en un proveedor compatible con OpenAI llamado zeltro, que se pasa en OPENCODE_CONFIG_CONTENT solo para esa ejecución, así que no se escribe nada en tu configuración de OpenCode. Zeltro también desactiva la actualización automática de OpenCode en sus ejecuciones. OpenCode lee el AGENTS.md del proyecto por sí solo.

Hermes Agent#

Hermes Agent, de Nous Research, es un agente de código abierto con un conjunto completo de herramientas de programación. Zeltro lo instala con su script oficial, sin los extras opcionales de navegador y uso del equipo, en ~/.local/bin/hermes.

# a provider prefix picks Hermes's provider: openai/, openrouter/, anthropic/ or gemini/
zeltro ai-set --agent hermes --model openai/gpt-5.4-mini --api-key sk-...
zeltro ai-set --agent hermes --model openrouter/qwen/qwen3-coder --api-key sk-or-...

# any OpenAI-compatible server
zeltro ai-set --agent hermes --model qwen3-coder:30b \
  --api-base http://localhost:11434/v1 --api-key ollama

Sin prefijo, el modelo va al proveedor que Hermes tenga configurado. Un endpoint usa el proveedor openai de Hermes con OPENAI_BASE_URL. Hermes lee el AGENTS.md del proyecto por sí solo. El motor de JavaScript Hermes de Meta también instala un comando llamado hermes; Zeltro comprueba que sea el agente (hermes --version dice "Hermes Agent") antes de ejecutarlo.

Modo desatendido#

Por sí solo, un agente de IA pregunta antes de cada edición de archivo o comando. Eso atasca zeltro create, que le entrega una tarea al agente y espera que la termine por su cuenta.

En la app de escritorio: activado de forma predeterminada, por proyecto#

Cada proyecto tiene un interruptor Trabaja sin preguntar en su panel, y está activado de forma predeterminada. Con él activado, la IA del proyecto trabaja sin detenerse a preguntar. Desactívalo en un proyecto para aprobar tú mismo cada paso en la terminal del agente.

La app lo hace sesión por sesión. Cuando inicia el agente de un proyecto, define ZELTRO_AI_UNATTENDED=1 (interruptor activado) o 0 (desactivado), y Zeltro lo convierte en la opción propia del agente para esa ejecución:

Agente Interruptor activado Interruptor desactivado
Claude Code --dangerously-skip-permissions --permission-mode manual
Codex --dangerously-bypass-approvals-and-sandbox --ask-for-approval on-request --sandbox workspace-write
Qwen Code --yolo --approval-mode default
Gemini CLI (obsoleto) --yolo --skip-trust --approval-mode default
OpenCode --auto OPENCODE_PERMISSION={"*":"ask"}
Aider --yes-always --no-yes-always
Antigravity CLI (agy) --dangerously-skip-permissions (no hay forma de forzarlo para una sola ejecución: decide su propia configuración)
Hermes Agent --yolo (no hay forma de forzarlo para una sola ejecución: decide su propia configuración)

No cambia los ajustes de aprobación de los agentes. Lo único que escribe es el consentimiento único de Claude Code, "skipDangerousModePermissionPrompt": true en ~/.claude/settings.json, para que Claude no se detenga en su pantalla de advertencia de "bypass permissions". La app no tiene un interruptor para todo el equipo.

En una terminal: el ajuste propio del agente#

zeltro ai, zeltro create y zeltro resume siguen la configuración propia del agente, salvo que ZELTRO_AI_UNATTENDED esté definido (1 o 0, para esa ejecución, como arriba). La primera vez que zeltro ai-set configura un agente en una terminal, te pregunta una sola vez, y si dices que sí, escribe el ajuste en el archivo de configuración propio del agente, donde puedes verlo y deshacerlo:

Agente Archivo Ajuste
Claude Code ~/.claude/settings.json "permissions": {"defaultMode": "bypassPermissions"}
Codex ~/.codex/config.toml approval_policy = "never", sandbox_mode = "danger-full-access"
Antigravity CLI (agy) ~/.gemini/antigravity-cli/settings.json "toolPermission": "always-proceed", "artifactReviewPolicy": "always-proceed"
Gemini CLI (obsoleto) ~/.gemini/settings.json "autoAccept": true
Qwen Code ~/.qwen/settings.json "autoAccept": true
Aider ~/.aider.conf.yml yes-always: true
OpenCode ~/.config/opencode/opencode.json "permission": "allow"
Hermes Agent ~/.hermes/config.yaml approvals.mode: off (se define con hermes config set; al volver a activarlo se restaura smart) 
zeltro ai-unattended                 # allow it for the current agent
zeltro ai-unattended codex --status  # report without changing anything
zeltro ai-unattended codex --revoke  # turn the prompts back on

zeltro ai-set --allow-unattended y --no-allow-unattended hacen lo mismo como parte de un cambio de configuración. En la app, el interruptor de un proyecto tiene prioridad sobre este ajuste, salvo para agy y Hermes con el interruptor desactivado.

Cuando trabaja sin preguntar, el agente puede cambiar cualquier cosa que pueda cambiar tu cuenta de usuario. Déjalo hacerlo solo en proyectos que estés dispuesto a dejar que una IA modifique libremente.

Ajustes por sesión#

zeltro ai-set es global. Para usar otro agente, modelo o clave en una sola ejecución sin cambiarlo, define estas variables en el entorno. Nunca se escriben en el .env:

Variable Reemplaza
ZELTRO_AI_AGENT El agente: codex, claude, agy, aider, qwen, opencode, hermes o gemini (obsoleto)
ZELTRO_AI_MODEL El modelo
ZELTRO_AI_API_BASE El endpoint
ZELTRO_AI_API_KEY La clave
ZELTRO_AI_API_KEY_FILE La clave, leída de la primera línea de este archivo para que nunca aparezca en una lista de procesos. Tiene prioridad sobre ZELTRO_AI_API_KEY. Conserva el archivo hasta que termine la sesión
ZELTRO_AI_LANGUAGE El idioma en el que responde el agente, por ejemplo Spanish. El código y los comandos quedan como están, y la salida propia de Zeltro sigue en inglés 
ZELTRO_AI_AGENT=qwen \
ZELTRO_AI_MODEL=qwen/qwen3-coder-30b-a3b-instruct \
ZELTRO_AI_API_BASE=https://openrouter.ai/api/v1 \
ZELTRO_AI_API_KEY_FILE="$HOME/.openrouter-key" \
  zeltro ai "Add a health-check endpoint at /ping"

Sin definir significa "usa el valor de ai-set"; definida pero vacía significa "bórralo para esta ejecución". Un agente desconocido, un archivo de clave ilegible o un agente que no está instalado detienen el comando antes de que se ejecute nada. No se instala nada por ti; usa zeltro ai-set --install-only --agent <name> para agregar un agente sin convertirlo en el predeterminado.

La instrucción de idioma llega a Claude Code y Qwen Code mediante --append-system-prompt, a Codex mediante -c developer_instructions=..., a Aider mediante --chat-language y a Hermes mediante HERMES_EPHEMERAL_SYSTEM_PROMPT, así que también se mantiene con zeltro resume. agy, Gemini CLI y OpenCode no tienen forma de añadir nada a su prompt del sistema, así que zeltro ai pone la instrucción al principio de la instrucción que envía, y una sesión reanudada de agy, Gemini u OpenCode no la recibe.

En la app de Zeltro, los perfiles de IA (Configuración → Perfiles de IA) son combinaciones con nombre de agente, modelo, endpoint y clave que eliges en cada sesión. Las claves se guardan cifradas, y un perfil llega a la CLI mediante estas mismas variables. El perfil predeterminado incorporado usa la configuración de zeltro ai-set del host.

zeltro create: de la idea al proyecto en marcha#

zeltro create "A timeclock for employees in Django"
zeltro create "Set up n8n and configure a webhook that posts to Slack"
zeltro create "https://github.com/monicahq/monica"

create funciona en tres pasos:

  1. Clasificar. A tu agente solo se le pregunta qué stack encaja, y responde en JSON: un framework para construirlo desde cero, las apps ya hechas del catálogo de Zeltro que de verdad encajen, una base de datos y un nombre de proyecto. En una terminal eliges en un menú. Los scripts y --one-off toman la primera recomendación.
  2. Crear. El propio Zeltro ejecuta zeltro new o zeltro install. En este paso no interviene ninguna IA.
  3. Construir. Zeltro escribe el AGENTS.md del proyecto y le entrega tu idea original al agente dentro del proyecto, como una ejecución puntual de zeltro ai. El agente construye con las convenciones propias del framework, actualiza el README, reinicia la app y comprueba que responde antes de terminar.

Si la idea solo pide instalar una app ("set up Grafana"), el paso 3 se omite: el instalador ya comprobó que la app responde y mostró su URL y sus datos de acceso.

Opciones de entrada#

zeltro create "an idea"                  # argument
zeltro create -f spec.md                 # from a file
zeltro create < spec.md                  # stdin
cat spec.md | zeltro create              # pipe
zeltro create --one-off "..."            # no menus; take the top recommendation
zeltro create --classify-only "..."      # print the recommendation and stop; creates nothing

--classify-only nunca pregunta nada. Agrega --json-output para obtener un resultado legible por máquinas, que es lo que usa la app de Zeltro. Si falla el propio agente (una clave incorrecta, un modelo que tu cuenta no puede usar, sin saldo), el resultado es {"status":"error","error":"agent_failed","message":"Codex: <the agent's own error>"}, y Zeltro se detiene en cuanto el agente informa de un 400, 401, 403 o 404 en lugar de esperar a que agote sus reintentos. "error":"no_stack" significa que el agente respondió, pero no dio ninguna recomendación utilizable. create informa con los mismos códigos.

La entrega con AGENTS.md#

Cuando un proyecto se crea con create, new, clone o install, Zeltro escribe un AGENTS.md en el directorio del proyecto. Con new, clone e install, después hace cd al proyecto y le entrega a tu agente una instrucción cuyo único fin es que lea ese archivo. --one-off, --json-output o una ejecución fuera de una terminal omiten esa entrega.

AGENTS.md recoge lo que un agente necesita para retomar el proyecto desde cero:

  • URL local, nombre del contenedor, directorio del proyecto
  • La base de datos resuelta, leída del .env del proyecto
  • Patrones de comandos que funcionan dentro del contenedor
  • Nombres de host y credenciales de los servicios compartidos
  • Reglas (nunca --json-output, python3 y no python, verificar con curl antes de dar algo por terminado)

Como este contexto vive en el disco y no en una sesión de chat, sobrevive a que cierres la terminal, reinicies o cambies de agente.

El archivo se regenera en cada entrega, pero solo entre sus marcadores. Todo lo que escribas fuera del bloque generado se conserva.

zeltro ai: una instrucción en el proyecto actual#

cd ~/zeltro-projects/my-app
zeltro ai "Add a health-check endpoint at /ping"
zeltro ai --interactive "Let's refactor the auth flow"

El modo puntual es el predeterminado: el agente recibe la instrucción, hace el trabajo y termina. El contexto duradero vive en AGENTS.md, así que cada instrucción es independiente.

Opción Descripción
--interactive, -i Abre una sesión persistente en su lugar
--one-off Se acepta por compatibilidad (ahora es el comportamiento predeterminado)

Una opción desconocida da error en lugar de añadirse a la instrucción.

zeltro resume#

zeltro resume my-project

Arranca el proyecto si no está en ejecución y luego vuelve a abrir la sesión más reciente del agente en ese directorio de proyecto. Si el agente no puede reanudarla, inicia una sesión nueva.

Mensajes entre sesiones de agentes#

Cuando la app de Zeltro aloja sesiones de agentes en varios proyectos, en uno o varios hosts, pueden enviarse mensajes entre sí. Ejecuta esto desde dentro del directorio de tu proyecto:

zeltro peers                                   # live sessions, as project@host
zeltro send blog api@shop -- "API is on v2 now"
zeltro send --all -- "Shared Postgres restarting in 5 minutes"
cat notes.md | zeltro send blog -- -           # message from stdin

Todos los destinatarios tienen que estar activos o no se envía nada. Los mensajes tienen un límite de 16 KB. Un mensaje entrante aparece en la terminal como [Zeltro message from shop@shawn to blog, api] .... Viene de otro agente, no de ti.

En la app de Zeltro, los agentes también pueden usar la ventana de la app para dos cosas: avisos (zeltro gui notify), como el acceso de una cuenta de administrador que hayan creado o "tu cambio está listo", que aparecen en pantalla y se quedan en la lista de Avisos del proyecto; y claves de API o contraseñas (zeltro gui secret), que van directamente al .env del proyecto para que nunca aparezcan en la conversación. Consulta la referencia de comandos para ver los detalles.

Notas para agentes#

Si eres un agente que trabaja con Zeltro, lee /usr/local/share/zeltro-cli/AGENTS.md. Es la referencia condensada de la plataforma, deliberadamente breve porque cada byte se paga en cada ejecución.

Las reglas más importantes:

  • Nunca pases --json-output. Suprime toda la salida legible para personas, incluida la distinción entre éxito y fallo, así que no puedes saber si un comando funcionó. Solo existe para scripts externos e interfaces gráficas.
  • Pasa siempre argumentos explícitos. Nada pregunta; si falta un argumento obligatorio, es un error inmediato con una pista de uso.
  • Prefiere zeltro exec a las variantes con TTY (zeltro bash, zeltro exec-tty*). Esas asignan una terminal y no se prestan a la automatización.
  • zeltro supervisor restart all, nunca zeltro exec supervisorctl ....
  • python3, no python. Para Django, prefiere zeltro django manage <args>.

¿Encontraste un error en esta traducción? Avísanos en GitHub.