Crush + JoinGonka Gateway: agente Charm en modelos de la red Gonka

Paso 1: instalar Crush. Los métodos oficiales del README del proyecto:

# 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

Ahí mismo se describen los repositorios de paquetes para Debian, Ubuntu, Fedora y RHEL, Nix y Scoop, y en la página de releases están los binarios listos. Comprueba con crush --version; la respuesta será una línea como crush version v0.96.1.

Paso 2: obtener una clave. Regístrate en gate.joingonka.ai/register, confirma tu dirección y crea una clave con el prefijo jg- en la sección «Claves API». Una sola clave y un solo saldo sirven para todos los modelos de la red.

Paso 3: ejecutar el instalador.

npx @joingonka/setup --tool crush

El instalador te pedirá la clave —no se pasa como argumento de línea de comandos para que no quede en el historial del shell— y hará cuatro cosas:

• registrará el proveedor joingonka en ~/.config/crush/crush.json: tipo openai-compat, dirección de la puerta de enlace, clave literal y tres modelos de la red con ventanas de contexto, límites de respuesta y precios por millón de tokens, que en el momento de la instalación toma en vivo de la puerta de enlace, y con los que Crush calcula el coste de la sesión. El archivo tendrá permisos 600;
• asignará los modelos: en el slot large, DeepSeek V4 Flash; en el small, MiniMax M2.7, y GLM-5.3 Flash quedará en la lista para selección manual. Lo hace solo si el slot large está vacío o apunta a nuestro modelo que salió de la red; una elección ajena se respeta, y en la salida aparecerá una pista de cómo cambiarla;
• verificará que la elección surta efecto: el modelo de la interfaz de Crush se guarda en el archivo de estado, y este anula la configuración, de eso trata la sección sobre large y small;
• hará una copia de seguridad, dejará los demás proveedores y ajustes como estaban y terminará con una petición en vivo a la puerta de enlace para comprobar de inmediato la clave, la dirección y el modelo.

Otro modelo se define con el flag --model y las abreviaturas deepseek, glm o minimax; el modelo indicado explícitamente siempre se escribe. Los directorios no estándar el instalador los tiene en cuenta igual que el propio Crush: CRUSH_GLOBAL_CONFIG para la configuración, CRUSH_GLOBAL_DATA para el archivo de estado, y también XDG_CONFIG_HOME y XDG_DATA_HOME. Para servidores y scripts hay un modo sin preguntas, en el que la clave se toma de una variable de entorno:

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

El formato principal de Crush ahora es crushrc, pero el instalador escribe crush.json: todas las versiones lo entienden. Si ya tienes un crushrc, Crush fusionará ambos archivos, y si las claves coinciden ganará crushrc, que el instalador no toca.

Todo lo que hace el instalador se puede escribir a mano. Aquí tienes un ~/.config/crush/crush.json funcional: este archivo lo pasamos por el 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" }
  }
}

Crush solo acepta JSON estricto: un comentario o una coma colgante y no arranca. Los campos de precio (cost_per_1m_in, cost_per_1m_out y los dos campos de caché) solo son necesarios para el contador de coste: el instalador escribe ahí el precio real del gateway, y sin ellos Crush funciona y muestra cero; solo el editor con el esquema de $schema los marcará como obligatorios.

Ese mismo proveedor en formato crushrc es Bash normal con los comandos integrados de Crush. Archivo ~/.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

Aquí el modelo se nombra en la forma provider/model-id: antes de la primera barra va el nombre del proveedor y después el identificador de red tal cual. La forma ${JOINGONKA_API_KEY:?…} mantiene la clave fuera del archivo, pero sin la variable exportada Crush no arranca: mejor un error al inicio que solicitudes con la clave vacía.

En Crush, el modelo no se elige como algo único para todo, sino para dos ranuras (slots):

El tercer modelo de la red, el modelo de razonamiento GLM-5.3 Flash, se elige para lógica compleja, recordando que su límite de respuesta es 8192 y una parte se dedica al razonamiento; los detalles están en la revisión del modelo. Para una ejecución única, el modelo se especifica con su nombre completo: crush run -m joingonka/zai-org/GLM-5.3-Flash "…". Todos los nombres disponibles se imprimen con crush models joingonka.

Archivo de estado. El modelo elegido en la interfaz mediante ctrl+l no se guarda en crush.json, sino en el archivo de estado de la máquina: ~/.local/share/crush/crush.json, en Windows — %LOCALAPPDATA%\crush\crush.json. Este archivo tiene prioridad sobre la configuración del usuario y crushrc: Crush los lee en orden /etc/crush/crush.json → ~/.config/crush/crush.json → ~/.config/crush/crushrc → archivo de estado, y cada uno subsiguiente sobrescribe al anterior. Por encima solo están los ajustes del proyecto: crush.json o crushrc en su directorio. Dónde se encuentran los archivos en su máquina se muestra con crush dirs.

En nuestra ejecución, abrimos la selección de modelos —el proveedor "JoinGonka (Gonka)" aparece allí con la marca "✓ Configured"— y seleccionamos MiniMax M2.7. Crush respondió "Large model changed to MiniMax M2.7 (Gonka)" y escribió en el archivo de estado:

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

Ahora, este modelo tiene prioridad sobre lo que está escrito en crush.json. El instalador reconoce esta situación y se comporta de manera diferente:

• sin --model no toca el archivo de estado —es su elección de trabajo—, pero advierte directamente con qué modelo se abrirá realmente Crush: Heads-up: Crush will still start with joingonka/MiniMaxAI/MiniMax-M2.7, not joingonka/deepseek-ai/DeepSeek-V4-Flash-0731. Hará lo mismo si en la interfaz se elige GLM-5.3 Flash o un modelo de otro proveedor;
• con --model explícito corrige exactamente una entrada en el archivo de estado —models.large—, tras guardar una copia, y escribe lo que había y lo que pasó a ser. De lo contrario, la bandera no habría surtido efecto silenciosamente. Después de tal lanzamiento, Crush en nuestra ejecución se abrió con el modelo indicado en la bandera.

Primero, asegúrate de que Crush ve al proveedor:

crush models joingonka

La respuesta son tres líneas:

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

Después, haz una ejecución única sin interfaz. Coloca en el directorio del proyecto un archivo con un error obvio y pídele que lo encuentre:

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

El agente debe llamar por sí solo a la herramienta de lectura de archivos y responder con fundamento, indicando el número de línea. En nuestra prueba, los tres modelos de la red encontraron el error y la tarea tardó entre 20 y 40 segundos. El flag -q oculta el indicador de espera. En el modo crush run, todas las llamadas a herramientas se aprueban automáticamente, así que ejecútalo en tu propio proyecto. En la interfaz normal (comando crush), el modelo activo se ve en la barra de estado: ◇ DeepSeek V4 Flash (Gonka) via JoinGonka (Gonka). Crush guarda las sesiones y el registro en el directorio .crush del proyecto, protegido de git por su propio .gitignore; el registro se imprime con crush logs. Del lado de la pasarela, la solicitud se ve en el panel: sección «Uso», desglose «Por modelos» y «Por claves».

Si algo salió mal, el diagnóstico normalmente se lee directamente en el mensaje:

Un agente gasta tokens de manera diferente a un chat: por cada frase suya, Crush añade un prompt del sistema y las descripciones de sus herramientas, y una tarea suele llevar varios pasos. En nuestra ejecución, cada solicitud al modelo cargó cerca de 11,500 tokens de entrada, y la tarea de "leer un archivo y encontrar el error" tomó de dos a tres solicitudes y entre 23,000 y 35,000 tokens, casi todo de entrada. Por lo tanto, el precio por token aquí es determinante.

A través de JoinGonka Gateway, los tokens cuestan $0.0069 por millón de entrada y $0.021 por millón de salida; el precio es igual para todos los modelos de la red y se muestra en esta página desde una fuente en tiempo real.

Las estimaciones en la columna derecha se basan en los precios de septiembre de 2026. Para comparar, cómo se puede pagar por los modelos en Crush:

El contador de costos en la interfaz de Crush calcula según los campos de precio del archivo de configuración. Ahí se incluye el precio del gateway al momento de la instalación, pero el precio en dólares en la red fluctúa con el tipo de cambio de GNK, por lo que el contador es una referencia. El consumo exacto y el saldo restante están en el panel de control, en las secciones "Uso" y "Facturación". Por qué DeepSeek V4 Flash se coloca en el slot large por defecto, se analiza en detalle en la revisión del modelo.

Permisos. Por defecto, la interfaz de Crush pide permiso antes de invocar una herramienta. El flag --yolo desactiva todas las preguntas de golpe, mientras que las herramientas de confianza puntual se listan en el config:

# crushrc
permissions allow view ls grep

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

Recordemos que crush run aprueba todo por su cuenta. Esto es una característica de Crush, no depende del proveedor del modelo.

Timeout de la petición. Crush corta la petición si del modelo no llega ningún fragmento de respuesta durante mucho tiempo: en la versión 0.96.1 son dos minutos de silencio (la documentación dice 60 segundos, pero en el código y en nuestra prueba son dos minutos). Los pings internos con los que el gateway mantiene la conexión no reinician este contador — lo comprobamos en un entorno local. El gateway, por su parte, en horas de carga espera el primer token de la red hasta 150 segundos, por lo que conviene subir el margen:

# crushrc
option request-timeout 300

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

Firmas en los commits. Los commits y pull requests que crea Crush reciben por defecto la línea Assisted-by: Crush:<model> y la coletilla «Generated with Crush». Si no lo necesitas:

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

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

Métricas. Crush envía a los desarrolladores estadísticas de uso seudónimas — solo metadatos, sin prompts ni respuestas. Se desactiva con la variable CRUSH_DISABLE_METRICS=1 o DO_NOT_TRACK=1. El gateway, por su parte, no almacena el contenido de los prompts ni de las respuestas — en las estadísticas solo quedan agregados de consumo.

El config es código. Tanto crushrc como crush.json los ejecuta Crush con los permisos de tu shell: $(…) en un campo de clave se ejecutará al cargar, y el crushrc del proyecto se activará en cuanto abras Crush en ese directorio. No ejecutes el agente en un repositorio ajeno sin haber leído antes sus configs.