Crush + JoinGonka Gateway: agente Charm em modelos da rede Gonka

Passo 1: instalar o Crush. Os métodos oficiais do README do projeto:

# Homebrew
brew install charmbracelet/tap/crush

# npm
npm install -g @charmland/crush

# Arch Linux
yay -S crush-bin

# Windows
winget install charmbracelet.crush

# Go
go install github.com/charmbracelet/crush@latest

Lá também estão descritos os repositórios de pacotes para Debian, Ubuntu, Fedora e RHEL, Nix e Scoop, e na página de releases ficam os binários prontos. Para conferir, use crush --version; a resposta virá como uma linha do tipo crush version v0.96.1.

Passo 2: obter uma chave. Cadastre-se em gate.joingonka.ai/register, confirme o endereço e crie uma chave com o prefixo jg- na seção «Chaves de API». Uma única chave e um único saldo valem para todos os modelos da rede.

Passo 3: rodar o instalador.

npx @joingonka/setup --tool crush

O instalador vai pedir a chave — ela não é passada como argumento de linha de comando, para não ficar no histórico do shell — e faz quatro coisas:

• grava o provedor joingonka em ~/.config/crush/crush.json: tipo openai-compat, endereço do gateway, chave literal e três modelos da rede com janelas de contexto, tetos de resposta e preços por milhão de tokens, que no momento da instalação ele busca ao vivo no gateway, e com os quais o Crush calcula o custo da sessão. O arquivo receberá permissões 600;
• define os modelos: no slot large, DeepSeek V4 Flash; no small, MiniMax M2.7, e o GLM-5.3 Flash fica na lista para seleção manual. Ele só faz isso se o slot large estiver vazio ou apontar para o nosso modelo que saiu da rede; uma escolha de terceiros é mantida, e na saída aparecerá uma dica de como trocar;
• verifica se a escolha vai valer: o modelo da interface do Crush fica num arquivo de estado, e esse arquivo sobrepõe a configuração — é sobre isso a seção sobre large e small;
• faz um backup, deixa os outros provedores e ajustes como estavam e termina com uma requisição ao vivo ao gateway, para já testar a chave, o endereço e o modelo.

Outro modelo é definido com a flag --model e as abreviações deepseek, glm ou minimax; o modelo indicado explicitamente é sempre gravado. Diretórios fora do padrão o instalador considera igual ao próprio Crush: CRUSH_GLOBAL_CONFIG para a configuração, CRUSH_GLOBAL_DATA para o arquivo de estado, além de XDG_CONFIG_HOME e XDG_DATA_HOME. Para servidores e scripts existe um modo sem perguntas, no qual a chave vem de uma variável de ambiente:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool crush --model glm --non-interactive

O formato principal do Crush agora é o crushrc, mas o instalador grava crush.json: todas as versões o entendem. Se você já tem um crushrc, o Crush vai mesclar os dois arquivos; em caso de chaves iguais, o crushrc vence, e o instalador não o toca.

Dá para escrever à mão tudo o que o instalador faz. Aqui vai um ~/.config/crush/crush.json que funciona — esse arquivo a gente passou pelo gateway:

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "joingonka": {
      "name": "JoinGonka (Gonka)",
      "type": "openai-compat",
      "base_url": "https://gate.joingonka.ai/v1",
      "api_key": "jg-your-key",
      "models": [
        { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek V4 Flash (Gonka)",
          "context_window": 380000, "default_max_tokens": 32768,
          "can_reason": true, "supports_attachments": false },
        { "id": "MiniMaxAI/MiniMax-M2.7", "name": "MiniMax M2.7 (Gonka)",
          "context_window": 200000, "default_max_tokens": 8192,
          "can_reason": false, "supports_attachments": false },
        { "id": "zai-org/GLM-5.3-Flash", "name": "GLM-5.3 Flash (Gonka)",
          "context_window": 390000, "default_max_tokens": 8192,
          "can_reason": true, "supports_attachments": false }
      ]
    }
  },
  "models": {
    "large": { "provider": "joingonka", "model": "deepseek-ai/DeepSeek-V4-Flash-0731" },
    "small": { "provider": "joingonka", "model": "MiniMaxAI/MiniMax-M2.7" }
  }
}

O Crush só aceita JSON estrito: um comentário ou uma vírgula sobrando e ele não inicia. Os campos de preço (cost_per_1m_in, cost_per_1m_out e os dois campos de cache) só servem para o contador de custo: o instalador grava ali o preço real do gateway, e sem eles o Crush funciona e mostra zero — só o editor com o schema do $schema vai marcá-los como obrigatórios.

O mesmo provedor no formato crushrc é Bash comum com os comandos embutidos do Crush. Arquivo ~/.config/crush/crushrc:

provider add joingonka \
  --name "JoinGonka (Gonka)" \
  --type openai-compat \
  --base-url "https://gate.joingonka.ai/v1" \
  --api-key "${JOINGONKA_API_KEY:?set JOINGONKA_API_KEY}"

model add joingonka/deepseek-ai/DeepSeek-V4-Flash-0731 \
  --name "DeepSeek V4 Flash (Gonka)" \
  --context-window 380000 --default-max-tokens 32768 --can-reason true

model add joingonka/MiniMaxAI/MiniMax-M2.7 \
  --name "MiniMax M2.7 (Gonka)" \
  --context-window 200000 --default-max-tokens 8192

model add joingonka/zai-org/GLM-5.3-Flash \
  --name "GLM-5.3 Flash (Gonka)" \
  --context-window 390000 --default-max-tokens 8192 --can-reason true

model large joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
model small joingonka/MiniMaxAI/MiniMax-M2.7

Aqui o modelo é referenciado na forma provider/model-id: antes da primeira barra vai o nome do provedor, depois vem o identificador de rede como ele é. A forma ${JOINGONKA_API_KEY:?…} mantém a chave fora do arquivo, mas sem a variável exportada o Crush não inicia — melhor um erro na largada do que requisições com chave vazia.

No Crush, o modelo não é escolhido como algo único para tudo, mas para dois slots:

O terceiro modelo da rede, o modelo de raciocínio GLM-5.3 Flash, é escolhido para lógica complexa, lembrando que seu limite de resposta é 8192 e parte dele é dedicada ao raciocínio; detalhes estão na revisão do modelo. Para uma execução, o modelo é especificado pelo nome completo: crush run -m joingonka/zai-org/GLM-5.3-Flash "…". Todos os nomes disponíveis são listados com crush models joingonka.

Arquivo de estado. O modelo escolhido na interface via ctrl+l não é gravado em crush.json, mas no arquivo de estado da máquina: ~/.local/share/crush/crush.json, no Windows — %LOCALAPPDATA%\crush\crush.json. Este arquivo tem prioridade sobre a configuração do usuário e o crushrc: o Crush os lê na ordem /etc/crush/crush.json → ~/.config/crush/crush.json → ~/.config/crush/crushrc → arquivo de estado, e cada um subsequente sobrescreve o anterior. Acima deles estão apenas as configurações do projeto — crush.json ou crushrc no seu diretório. O comando crush dirs mostra onde os arquivos estão localizados na sua máquina.

Em nossa execução, abrimos a seleção de modelos — o provedor "JoinGonka (Gonka)" aparece lá com a marca "✓ Configured" — e selecionamos o MiniMax M2.7. O Crush respondeu "Large model changed to MiniMax M2.7 (Gonka)" e gravou no arquivo de estado:

{"models":{"large":{"model":"MiniMaxAI/MiniMax-M2.7","provider":"joingonka","max_tokens":8192}}, …}

Agora, este modelo é mais importante do que o que está escrito em crush.json. O instalador reconhece essa situação e se comporta de forma diferente:

• sem --model ele não altera o arquivo de estado — essa é a sua escolha de trabalho —, mas avisa diretamente com qual modelo o Crush realmente abrirá: Heads-up: Crush will still start with joingonka/MiniMaxAI/MiniMax-M2.7, not joingonka/deepseek-ai/DeepSeek-V4-Flash-0731. Ele fará o mesmo se o GLM-5.3 Flash ou um modelo de outro provedor for escolhido na interface;
• com --model explícito ele corrige exatamente uma entrada no arquivo de estado — models.large —, após salvar uma cópia, e escreve o que era e o que passou a ser. Caso contrário, a flag não teria efeito silenciosamente. Após esse lançamento, o Crush em nossa execução abriu com o modelo especificado na flag.

Primeiro, garanta que o Crush enxergue o provedor:

crush models joingonka

A resposta traz três linhas:

joingonka/MiniMaxAI/MiniMax-M2.7
joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
joingonka/zai-org/GLM-5.3-Flash

Depois, faça uma execução única sem interface. Coloque no diretório do projeto um arquivo com um erro óbvio e peça para encontrá-lo:

crush run -q "Read calc.py and tell me in one sentence whether it has a bug."

O agente deve chamar sozinho a ferramenta de leitura de arquivo e responder com objetividade, indicando o número da linha. Na nossa execução, os três modelos da rede encontraram o erro, e a tarefa levou de 20 a 40 segundos. A flag -q esconde o indicador de espera. No modo crush run, todas as chamadas de ferramentas são aprovadas automaticamente, então execute-o no seu próprio projeto. Na interface normal (comando crush), o modelo ativo aparece na barra de status: ◇ DeepSeek V4 Flash (Gonka) via JoinGonka (Gonka). O Crush guarda as sessões e o log no diretório .crush do projeto, protegido do git pelo próprio .gitignore; o log é exibido com crush logs. Do lado do gateway, a requisição aparece no painel: seção «Uso», detalhamento «Por modelos» e «Por chaves».

Se algo deu errado, o diagnóstico normalmente se lê direto na mensagem:

Um agente gasta tokens de forma diferente de um chat: para cada frase sua, o Crush adiciona um prompt de sistema e as descrições de suas ferramentas, e uma tarefa geralmente leva vários passos. Em nossa execução, cada solicitação ao modelo carregou cerca de 11,5 mil tokens de entrada, e a tarefa de "ler um arquivo e encontrar o erro" levou de duas a três solicitações e 23-35 mil tokens, quase tudo de entrada. Portanto, o preço por token aqui é determinante.

Através do JoinGonka Gateway, os tokens custam $0.0069 por milhão na entrada e $0.021 por milhão na saída — o preço é o mesmo para todos os modelos da rede e é fornecido nesta página a partir de uma fonte em tempo real.

As estimativas na coluna à direita baseiam-se nos preços de setembro de 2026. Para comparação, como você pode pagar pelos modelos no Crush:

O contador de custos na interface do Crush calcula de acordo com os campos de preço da configuração. O preço do gateway no momento da instalação é incluído lá, mas o preço em dólares na rede flutua com a taxa de câmbio do GNK, portanto, o contador é uma referência. O consumo exato e o saldo restante estão no painel, nas seções "Uso" e "Faturamento". O motivo pelo qual o DeepSeek V4 Flash é definido no slot large por padrão é detalhado na análise do modelo.

Permissões. Por padrão, a interface do Crush pede permissão antes de invocar uma ferramenta. A flag --yolo desativa todas as perguntas de uma vez, enquanto as ferramentas de confiança pontual são listadas no config:

# crushrc
permissions allow view ls grep

# crush.json
"permissions": { "allowed_tools": ["view", "ls", "grep"] }

Vale lembrar que crush run aprova tudo sozinho. Isso é uma característica do Crush, não depende do provedor do modelo.

Timeout da requisição. O Crush interrompe a requisição se nenhum fragmento de resposta chegar do modelo por muito tempo: na versão 0.96.1 são dois minutos de silêncio (a documentação fala em 60 segundos, mas no código e no nosso teste são dois minutos). Os pings internos com que o gateway mantém a conexão não zeram esse contador — verificamos em um ambiente local. Já o gateway, em horários de pico, espera o primeiro token da rede por até 150 segundos, então vale aumentar a margem:

# crushrc
option request-timeout 300

# crush.json
"options": { "request_timeout": 300 }

Assinaturas nos commits. Os commits e pull requests criados pelo Crush recebem, por padrão, a linha Assisted-by: Crush:<model> e o complemento «Generated with Crush». Se isso não for necessário:

# crushrc
option attribution-trailer-style none
option attribution-generated-with false

# crush.json
"options": { "attribution": { "trailer_style": "none", "generated_with": false } }

Métricas. O Crush envia aos desenvolvedores estatísticas de uso pseudônimas — apenas metadados, sem prompts nem respostas. Desativa-se com a variável CRUSH_DISABLE_METRICS=1 ou DO_NOT_TRACK=1. O gateway, por sua vez, não armazena o conteúdo dos prompts nem das respostas — nas estatísticas ficam apenas agregados de consumo.

O config é código. Tanto o crushrc quanto o crush.json são executados pelo Crush com as permissões do seu shell: $(…) em um campo de chave será executado ao carregar, e o crushrc do projeto entrará em ação assim que você abrir o Crush nesse diretório. Não rode o agente em um repositório de terceiros sem antes ler os configs dele.