Fluxo de trabalho com IA

Os comandos do Zeltro foram pensados para o desenvolvimento conduzido por IA. A ideia é dar ao agente um ambiente fixo para trabalhar, para que ele construa o seu app em vez de inventar infraestrutura.

O Zeltro não vende IA. Ele controla um CLI de agente que você instala e no qual faz login, e você paga diretamente a esse provedor (ou nada, com um modelo local).

Ainda não tem um? Na primeira vez que você abre o app Zeltro, pode usar nossa chave para experimentar: o Claude Code com o Claude Haiku, sem conta, sem cartão e sem chave própria, o suficiente para testar em um primeiro projeto (um por computador, enquanto durar). Ele passa pelo servidor do Zeltro (veja a privacidade). Depois disso, conecte a sua própria IA do mesmo jeito descrito acima; aí nada passa pelo Zeltro.

Escolhendo um 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)

Uma instalação nova não tem agente definido, e os comandos de IA pedem para você rodar zeltro ai-set primeiro. Se estiver em dúvida, escolha claude e deixe o modelo em branco para que o Claude Code use o próprio padrão.

Quando você escolhe um agente que não está instalado, o zeltro ai-set o instala com:

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

O Zeltro só repassa uma chave guardada onde ela serve. O Codex só recebe uma chave se ela começar com sk- (qualquer chave, com um endpoint personalizado), e o Claude a recebe como ANTHROPIC_API_KEY só se ela começar com sk-ant-. O Codex ignora OPENAI_API_KEY, então o Zeltro faz o login dele com a chave (codex login --with-api-key) em uma pasta home do Codex só dele, ~/.zeltro/codex/<hash of the key>, com o seu config.toml vinculado. O seu próprio ~/.codex, e qualquer login do ChatGPT que esteja nele, nunca é tocado, e cada chave mantém o próprio histórico de sessões para o zeltro resume. Qualquer outra coisa é ignorada com um aviso, e o CLI usa o próprio login. O agy e o Gemini recebem uma chave guardada como GEMINI_API_KEY (uma chave de API do Gemini, de aistudio.google.com); o agy não aceita endpoint personalizado.

O zeltro ai-set --json-output sozinho é somente leitura. Ele não instala nem escreve nada, e informa o agente, o modelo, o endpoint, se há uma chave guardada, a configuração de modo autônomo e quais agentes estão instalados.

Vai usar modelos mais baratos ou locais? Veja Modelos baratos e locais. O Qwen Coder no OpenRouter custa cerca de 30x menos por token que o Claude Sonnet 5, e um modelo local no Ollama não custa nada para rodar.

As configurações ficam em /etc/zeltro-cli/.env. Sempre as altere com zeltro ai-set em vez de editar o arquivo.

Antigravity CLI (agy)#

O agy é o CLI de agente de programação do Google, e ele substitui o Gemini CLI. O Google deixou de oferecer o Gemini CLI para contas pessoais do Google (gratuitas, AI Pro e Ultra) em 18/06/2026. O Gemini CLI ainda funciona com uma chave de API paga do Gemini, então zeltro ai-set --agent gemini continua funcionando, mas está obsoleto no 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)

Ele é instalado como um único programa em ~/.local/bin (sem precisar de Node) e se atualiza sozinho. Para fazer login com o Google, abra um terminal e rode agy uma vez. Na primeira execução interativa ele também pede um esquema de cores e mostra os termos do Google, onde você escolhe se o Google pode usar suas conversas; o Zeltro deixa essa escolha com você. Com uma chave, o Zeltro define "modelProvider": "gemini" em ~/.gemini/antigravity-cli/settings.json (sem isso o agy ignora a chave) e remove essa linha de novo quando você apaga a chave, para que o login com o Google volte a funcionar. O agy não aceita endpoint personalizado, então não consegue rodar modelos baratos ou locais via --api-base.

Aider#

Codex, Claude e agy fazem login cada um com a própria conta. O Aider não. Ele fala direto com a API de um provedor, então precisa de um modelo e de uma chave antes de rodar:

# 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

O Zeltro marca a chave com o provedor indicado pelo prefixo do modelo (anthropic=sk-ant-...), ou com openai quando não há prefixo. O --api-base é só para servidores compatíveis com OpenAI (Ollama, LM Studio, OpenRouter, vLLM); deixe-o em branco para usar a API hospedada do próprio provedor. Normalmente o Aider faz um commit de cada edição por conta própria. O Zeltro o roda com --no-auto-commits para que as alterações dele fiquem na sua árvore de trabalho, como as de qualquer outro agente.

Qwen Code#

O Qwen Code é um agente de terminal de código aberto que começou como um fork do Gemini CLI e foi construído em torno dos modelos Qwen Coder. O Zeltro o instala com npm install -g @qwen-code/qwen-code.

O Zeltro o roda no modo compatível com OpenAI (--auth-type openai, com a chave e o endpoint em OPENAI_API_KEY e OPENAI_BASE_URL), então ele é o caminho mais simples para um modelo hospedado barato ou um modelo 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

O login OAuth gratuito do Qwen foi descontinuado em 15 de abril de 2026, então ele precisa de uma chave de API ou de um endpoint local. Não existe caminho hospedado gratuito pelo próprio Qwen. Ele também pede Node 22+; roda no Node 20 com um aviso EBADENGINE, mas isso não é suportado.

OpenCode#

O OpenCode é um agente de terminal de código aberto que funciona com quase qualquer provedor. O Zeltro o instala com npm install -g opencode-ai. Ele pode usar o próprio login (opencode auth login) ou uma chave que você passa ao 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

A chave vai para a variável que o provedor do modelo lê (OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY ou GOOGLE_GENERATIVE_AI_API_KEY). Um endpoint vira um provedor compatível com OpenAI chamado zeltro, passado em OPENCODE_CONFIG_CONTENT só para aquela execução, então nada é escrito na sua configuração do OpenCode. O Zeltro também desativa a atualização automática do OpenCode nas execuções dele. O OpenCode lê o AGENTS.md do projeto sozinho.

Hermes Agent#

O Hermes Agent, da Nous Research, é um agente de código aberto com um conjunto completo de ferramentas de programação. O Zeltro o instala com o script oficial, sem os extras opcionais de navegador e de uso do computador, em ~/.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

Sem prefixo, o modelo vai para o provedor que estiver configurado no Hermes. Um endpoint usa o provedor openai do Hermes com OPENAI_BASE_URL. O Hermes lê o AGENTS.md do projeto sozinho. O motor JavaScript Hermes, da Meta, também instala um comando chamado hermes; o Zeltro confere se é o agente (hermes --version diz "Hermes Agent") antes de rodá-lo.

Modo autônomo#

Por conta própria, um agente de IA pede permissão antes de cada edição de arquivo ou comando. Isso trava o zeltro create, que entrega uma tarefa ao agente e espera que ele a termine sozinho.

No app desktop: ligado por padrão, por projeto#

Cada projeto tem um botão Trabalha sem perguntar no seu painel, e ele vem ligado por padrão. Com ele ligado, a IA do projeto trabalha sem parar para perguntar. Desligue-o em um projeto para aprovar cada passo você mesmo no terminal do agente.

O app faz isso uma sessão por vez. Quando inicia o agente de um projeto, ele define ZELTRO_AI_UNATTENDED=1 (botão ligado) ou 0 (botão desligado), e o Zeltro transforma isso na flag própria do agente para aquela execução:

Ele não muda as configurações de aprovação dos agentes. A única coisa que ele escreve é o consentimento único do Claude Code, "skipDangerousModePermissionPrompt": true em ~/.claude/settings.json, para que o Claude não pare na tela de aviso de "bypass permissions". O app não tem um botão para a máquina inteira.

No terminal: a configuração do próprio agente#

zeltro ai, zeltro create e zeltro resume seguem a configuração do próprio agente, a menos que ZELTRO_AI_UNATTENDED esteja definida (1 ou 0, para aquela execução, como acima). Na primeira vez que o zeltro ai-set configura um agente em um terminal, ele pergunta uma vez e, se você disser sim, escreve a configuração no próprio arquivo de configuração do agente, onde você pode vê-la e desfazê-la:

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 e --no-allow-unattended fazem a mesma coisa como parte de uma mudança de configuração. No app, o botão de um projeto vale mais que essa configuração, exceto para agy e Hermes com o botão desligado.

Substituições por sessão#

O zeltro ai-set é global. Para usar outro agente, modelo ou chave em uma execução sem mudar a configuração, defina estas variáveis no ambiente. Elas nunca são escritas no .env:

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"

Não definida significa "usar o valor do ai-set"; definida mas vazia significa "apagar nesta execução". Um agente desconhecido, um arquivo de chave ilegível ou um agente que não está instalado interrompe o comando antes de qualquer coisa rodar. Nada é instalado para você; use zeltro ai-set --install-only --agent <name> para adicionar um agente sem torná-lo o padrão.

A instrução de idioma chega ao Claude Code e ao Qwen Code via --append-system-prompt, ao Codex via -c developer_instructions=..., ao Aider via --chat-language e ao Hermes via HERMES_EPHEMERAL_SYSTEM_PROMPT, então ela também vale no zeltro resume. O agy, o Gemini CLI e o OpenCode não têm como acrescentar algo ao prompt de sistema, então o zeltro ai coloca a instrução no topo do prompt, e uma sessão retomada do agy, do Gemini ou do OpenCode não recebe nenhuma.

No app Zeltro, os Perfis de IA (Configurações → Perfis de IA) são combinações nomeadas de agente, modelo, endpoint e chave que você escolhe por sessão. As chaves são guardadas criptografadas, e um perfil chega ao CLI por meio dessas mesmas variáveis. O perfil padrão embutido usa a configuração zeltro ai-set do host.

zeltro create: da ideia ao projeto rodando#

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"

O create roda em três etapas:

1. Classificar. O seu agente só é perguntado sobre qual stack serve, e responde em JSON: um framework para construir do zero, os apps prontos do catálogo do Zeltro que realmente servirem, um banco de dados e um nome de projeto. Em um terminal, você escolhe em um menu. Scripts e --one-off ficam com a primeira recomendação.
2. Criar. O próprio Zeltro roda zeltro new ou zeltro install. Nenhuma IA participa desta etapa.
3. Construir. O Zeltro escreve o AGENTS.md do projeto e entrega a sua ideia original ao agente dentro do projeto, como uma execução única de zeltro ai. O agente constrói seguindo as convenções nativas do framework, atualiza o README, reinicia o app e confere se ele responde antes de terminar.

Se a ideia só pede a instalação de um app ("set up Grafana"), a etapa 3 é pulada: o instalador já conferiu que o app responde e mostrou a URL e o login.

Opções 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

O --classify-only nunca pergunta nada. Acrescente --json-output para um resultado legível por máquina, que é o que o app Zeltro usa. Se o próprio agente falhar (uma chave errada, um modelo que a sua conta não pode usar, sem crédito), o resultado é {"status":"error","error":"agent_failed","message":"Codex: <the agent's own error>"}, e o Zeltro para assim que o agente informa um 400, 401, 403 ou 404, em vez de esperar as novas tentativas dele. "error":"no_stack" significa que o agente respondeu, mas não deu nenhuma recomendação utilizável. O create informa os mesmos códigos.

A entrega via AGENTS.md#

Quando um projeto é criado por create, new, clone ou install, o Zeltro escreve um AGENTS.md no diretório do projeto. Em new, clone e install, ele então entra (cd) no projeto e entrega ao seu agente um prompt cuja única tarefa é ler esse arquivo. --one-off, --json-output ou uma execução fora de um terminal pulam essa entrega.

O AGENTS.md registra o que um agente precisa para assumir o projeto do zero:

• URL local, nome do contêiner, diretório do projeto
• O banco de dados definido, lido do .env do projeto
• Padrões de comando que funcionam dentro do contêiner
• Nomes de host e credenciais dos serviços compartilhados
• Regras (nunca --json-output, python3 e não python, conferir com curl antes de dar por concluído)

Como esse contexto fica no disco e não em uma sessão de chat, ele sobrevive a fechar o terminal, reiniciar e trocar de agente.

O arquivo é gerado de novo a cada entrega, mas só entre os marcadores dele. Tudo o que você escrever fora do bloco gerado é preservado.

zeltro ai: um prompt no projeto atual#

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

O padrão é execução única: o agente recebe o prompt, faz o trabalho e sai. O contexto duradouro fica no AGENTS.md, então cada prompt é independente.

Uma flag desconhecida gera erro em vez de ser acrescentada ao prompt.

zeltro resume#

zeltro resume my-project

Inicia o projeto se ele não estiver rodando e depois reabre a sessão mais recente do agente nesse diretório de projeto. Se o agente não conseguir retomar, ele inicia uma nova sessão.

Mensagens entre sessões de agentes#

Quando o app Zeltro hospeda sessões de agentes em vários projetos, em um host ou em vários, elas podem trocar mensagens. Rode estes comandos de dentro do diretório do seu projeto:

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 os destinos precisam estar ativos, senão nada é enviado. As mensagens têm limite de 16 KB. Uma mensagem recebida aparece no terminal como [Zeltro message from shop@shawn to blog, api] .... Ela vem de outro agente, não de você.

No app Zeltro, os agentes também podem usar a janela do app para duas coisas: avisos (zeltro gui notify), como o login de uma conta de administrador que eles criaram ou "sua alteração está pronta", que aparecem na tela e ficam na lista de Avisos do projeto; e chaves de API ou senhas (zeltro gui secret), que vão direto para o .env do projeto e nunca aparecem na conversa. Veja os detalhes na referência de comandos.

Notas para agentes#

Se você é um agente trabalhando com o Zeltro, leia /usr/local/share/zeltro-cli/AGENTS.md. É a referência condensada da plataforma, mantida curta de propósito porque cada byte é pago em toda execução.

As regras que mais importam:

• Nunca passe --json-output. Ele suprime toda a saída legível por pessoas, inclusive a distinção entre sucesso e falha, então você não consegue saber se um comando funcionou. Ele existe só para scripts externos e interfaces gráficas.
• Sempre passe argumentos explícitos. Nada pergunta; um argumento obrigatório que falta é um erro imediato, com uma dica de uso.
• Prefira zeltro exec às variantes com TTY (zeltro bash, zeltro exec-tty*). Elas alocam um terminal e não combinam com automação.
• zeltro supervisor restart all, nunca zeltro exec supervisorctl ....
• python3, não python. No Django, prefira zeltro django manage <args>.

Achou um erro nesta tradução? Avise a gente no GitHub.