Referencia CLI

Name: Mentat
Author: Mentat

mt es la entrada operativa de Mentat. Habla conmentat-server por HTTP y cubre el ciclo normal de una plataforma privada de workloads: desplegar, inspeccionar, escalar, actualizar y recuperar.

opciones globales

mt [--server <URL>] <comando>

Opciones:
  --server <SERVER>  Direccion del servidor Mentat [default: http://127.0.0.1:4646]
  -h, --help         Mostrar ayuda

Comandos Principales

mt up <up.yaml>

Levanta un servicio Hull desde un solo YAML — bootstrap o actualizacion. Sintetiza el manifest, registra el ServiceSpec, genera el bloque de ingress de Condor, buildea, reempaqueta el rootfs, lo extrae en el host y escala. Idempotente, sin SSH. Un preflight ajusta el deploy al proyecto antes de converger: refleja runtime.port en PORT/HOSTNAME para servicios lanzados con node (un valor puesto por el operador siempre gana), se niega a converger si otro servicio ya ocupa el puerto — y dice cual —, y se niega a empaquetar binarios nativos de macOS (.node Mach-O) que abortarian en el host Linux. Despues del submit verifica que el cluster haya guardado el puerto del YAML, para que un ServiceSpec viejo no siga ruteando el anterior con el deploy reportando exito.

mt up up.yaml
mt --server https://www.getmentat.run up up.yaml

# forma del up.yaml
name: stil-site
domain: stil.gitweave.run
aliases: [gitweave.run]
replicas: 2
build:
  cwd: ./
  cmd: stil run build
  output: dist
runtime:
  serve: static    # preset: static | node | argv
  port: 3007
  memory: 64M
  cpu: 0.5
  pids: 16
health: /

mt deploy <deploy.yaml>

Actualiza el contenido de un servicio Hull ya existente. Se saltea la escritura del manifest y el registro del spec: solo buildea, reempaqueta, sube, extrae y bouncea. Usalo cuando el servicio ya esta registrado (el bootstrap lo hizo mt up).

mt deploy deploy.yaml

# forma del deploy.yaml
service: stil-site
build:
  cwd: /ruta/al/landing
  cmd: stil run build
  output_dir: dist
target:
  www_path: /www
  preserve: [/www/releases]
replicas: 2

mt run <archivo.yaml>

Envia una definicion de workloads al control plane. Es la entrada de bajo nivel para drivers que no son Hull (Firecracker, Sandbox, Docker, Exec). Los servicios Hull normalmente van por mt up.

mt run services.yaml
mt run --server http://10.0.0.1:4646 production.yaml

mt status [job-id]

Inspecciona jobs y asignaciones. Usa un job ID para detalle.

mt status
mt status abc123-def456

mt deploy-image <servicio> --image <tag>

Publica una nueva imagen usando la estrategia de despliegue del servicio (flujo legacy de un solo flag, se mantiene para servicios que no son Hull y para scripts de CI).

mt deploy-image api-gateway --image registry.example/api-gateway:v2
mt deploy-image streamforge --image streamforge:v2 --strategy canary

mt ps

Muestra todos los workloads corriendo con metricas en vivo de cgroups v2: nombre, driver, endpoints, RAM, tiempo de CPU, PIDs y estado de salud. Con color por tipo de driver.

mt ps

SERVICE                DRIVER        EP   ADDRESS          RAM     CPU     PIDS   STATUS
streamforge-node1      firecracker   1    172.16.0.2:8080  256M    —       —      healthy
oxidestore-node1       firecracker   1    172.16.0.5:9000  256M    —       —      healthy
mentat-web             sandbox       1    127.0.0.1:3001   2/32M   12ms    3      healthy
nextjs-ssr             sandbox       1    127.0.0.1:3002   45/256M 890ms   8      healthy
api-jarvis             docker        1    172.17.0.3:5001  512M    —       —      healthy

mt scale <servicio> <cantidad>

Cambia la cantidad objetivo de replicas de un servicio.

mt scale api-gateway 5
mt scale api-service 3

mt rollback <servicio>

Regresa un servicio a la version desplegable anterior.

mt rollback api-service

mt canary promote <servicio>

Promueve un canary a rollout completo.

mt canary promote streamforge

mt canary abort <servicio>

Aborta un canary y revierte el cambio.

mt canary abort streamforge

mt diagnose <servicio>

Por que el servicio esta como esta. Prueba cada endpoint en el momento en vez de esperar el proximo tick del monitor, muestra los contadores de fallo detras de cada status, trae la salida reciente del workload a traves del agente, y lista hallazgos — cada uno con que hacer al respecto. Read-only: no cambia nada. Es el trabajo que un operador hace por SSH con journalctl y el directorio de logs del runtime.

mt diagnose mentat-web

mentat-web  0/1 healthy  ·  1 desired
  probe: http /
  last auto-restart: 40s

  ✖ 10.88.0.2:3001  mentat-web-e7585c4c  unhealthy  (2/3 failed probes)
      probe now: fail http://10.88.0.2:3001/ (12ms) — connection refused

  critical  www.getmentat.run no tiene upstream sano — el ingress dara 502
            → el ingress solo emite ruta para endpoints sanos; arregla el
              endpoint y la ruta vuelve sola.
  info      auto-restarted 40s ago (cooldown 60s)
            → el workload puede seguir booteando.

mt diagnose mentat-web --json   # el mismo reporte, legible por maquina

mt get <mt://recurso>

Lee el estado del cluster como JSON — la contraparte para maquinas de las tablas con color que mt ps y mt nodes imprimen para humanos. Nada de esto escribe, asi que es seguro darselo a un script o a un agente. El esquema mt:// es opcional.

mt get mt://services                 # todos los ServiceSpec
mt get mt://services/titan           # un servicio y sus endpoints
mt get mt://services/titan/health    # status mas los contadores detras
mt get mt://nodes                    # nodos con su condicion de lifecycle
mt get mt://registry                 # el registro completo de endpoints
mt get mt://sandboxes                # sandboxes efimeros vivos

# mt://services/{name}/health, abreviado
{
  "endpoints_registered": 1,
  "endpoints_healthy": 1,
  "health_check": { "probe": "http", "path": "/", "max_failures": 3 },
  "last_restart_secs_ago": null,
  "endpoints": [
    { "ip": "10.88.0.2", "port": 3001, "status": "healthy",
      "consecutive_failures": 0, "restart_in_flight": false,
      "node_condition": "ready" }
  ]
}

mt snapshot <servicio>

Toma un snapshot de una microVM Firecracker en ejecucion: la pausa, captura el estado completo de memoria y disco, y la reanuda en el lugar. El servicio sigue sirviendo — la pausa dura lo que dura la captura, no es un restart. Ese snapshot es desde donde reanudan fork y sandbox.

mt snapshot api-janus
mt snapshot api-janus --name antes-de-migrar

mt fork <servicio> --count <n>

Forkea N replicas de una microVM desde un snapshot. Cada replica reanuda desde la imagen de memoria congelada exacta en bastante menos de un segundo — sin boot de kernel, sin arranque de la aplicacion, sin cache que calentar. Captura un snapshot fresco salvo que --snapshot nombre uno existente. Cada fork es direccionable en su propia IP.

mt fork api-janus --count 8
mt fork api-janus --count 4 --snapshot antes-de-migrar

mt sandbox <create|list|exec|fork|rm|pool>

Sandboxes efimeros para agentes: forkea una microVM descartable desde un servicio template, la alcanzas en su propia IP clon, corres comandos dentro del guest por vsock y se auto-destruye al vencer su TTL. Es la contraparte soberana de E2B / Modal / Daytona — la misma primitiva, sobre hardware propio, con el aislamiento de una VM real y no el de un contenedor compartido. Un warm pool mantiene sandboxes pre-forkeados por template para que create devuelva al instante.

mt sandbox create python-base --ttl 900
mt sandbox list
mt sandbox exec sbx-4f21 python3 -c "print(1+1)"
mt sandbox fork sbx-4f21 --count 5     # ramifica el mismo estado vivo
mt sandbox rm sbx-4f21

# manten 4 sandboxes pre-forkeados para que create sea instantaneo
mt sandbox pool python-base 4
mt sandbox pool                         # lista los pools y que tan llenos estan

mt nodes

Lista los nodos registrados con su condicion de ciclo de vida, razon, antiguedad y endpoints corriendo. Alias de mt host list.

mt nodes

NODE          ADDRESS            CONDITION            SINCE   ENDPTS
mentat-gcp    10.128.0.4:4647    Ready                14d     23
mentat-falp   10.0.1.9:4647      MaintenancePlanned   6m      7

mt host cordon|drain|uncordon <nodo>

Ciclo de vida de nodos con el vocabulario de condiciones de Kubernetes v1.37 (Ready, MaintenancePlanned, DrainInProgress, Drained, GracefulNodeShutdownInProgress). cordon deja de colocar trabajo nuevo sin tocar lo que corre; drain para todos los workloads en orden — sin kill -9 —, los desregistra y mantiene el nodo cerrado, guardando exactamente que servicios paro; uncordon vuelve a Ready y repone precisamente esas replicas, nunca un reschedule global. El scheduler saltea nodos no programables y el monitor de health ya no reinicia sobre ellos. El agente anuncia shutdown graceful en SIGTERM. El nodo se indica por id, prefijo de id o direccion.

mt host cordon mentat-falp -r KernelPatch -m "apt upgrade + reboot"
mt host drain mentat-falp -r KernelPatch
mt host list          # mira DrainInProgress -> Drained
# ... mantenimiento ...
mt host uncordon mentat-falp

mt logs <servicio>

Inspecciona logs de un servicio. Usa -f para seguir.

mt logs api-gateway
mt logs api-gateway -f

Flujo Tipico de Operacion

# Iniciar control plane y host agent
mentat-server --bind 0.0.0.0:4646
mentat-agent --kvm --server http://localhost:4646

# Enviar la definicion del stack
mt run services.yaml

# Ver que esta corriendo
mt status
mt nodes

# Cambiar un servicio de forma segura
mt deploy-image api-gateway --image registry.example/api-gateway:v2
mt rollback api-gateway

Salida Observada en Produccion

mt run services.yaml

$ mt run services.yaml
  scheduling 4 services...
  driver: firecracker  x2 services
  driver: exec         x1 services
  driver: docker       x1 services

  streamforge-broker x2  8ms   <- trafico real
  oxidestore        x1  6ms   <- API S3 activa
  mentat-agent      x1  2ms
  api-jarvis        x1  380ms

  all services healthy
  firecracker + docker + exec  ·  private control plane

Interfaces

TUI

mt lens --server your-host:4646

App Desktop

Mentat Desktop se conecta al API por HTTPS para monitoreo grafico y operacion del dia a dia. Sirve cuando el equipo quiere visibilidad sin vivir completamente en la terminal.

Manejo Seguro de Cambios

# Canary primero
mt deploy-image streamforge --image streamforge:v2 --strategy canary

# Evaluar y decidir
mt canary promote streamforge
# o: mt canary abort streamforge

Snapshots, Forks y Sandboxes

Una microVM Firecracker se puede congelar y reanudar, y eso convierte a un servicio corriendo en algo que podes ramificar. snapshot captura el estado, fork reanuda N copias en bastante menos de un segundo cada una, y sandbox envuelve la misma primitiva como entorno descartable con TTL — el tipo de cosa que las plataformas de agentes alquilan, corriendo sobre tu propio hardware.

# Ramificar un servicio corriendo
mt snapshot api-janus --name antes-de-migrar
mt fork api-janus --count 8 --snapshot antes-de-migrar

# Entorno descartable para un agente
mt sandbox pool python-base 4            # 4 tibios, create es instantaneo
id=$(mt sandbox create python-base --ttl 900)
mt sandbox exec $id python3 -c "print(1+1)"
mt sandbox fork $id --count 5            # ramifica el mismo estado vivo
mt sandbox rm $id                        # o deja que el TTL lo destruya

Mantenimiento de Nodos

Parchar un host es una operacion de primera clase, no una secuencia improvisada de mt scale 0. Cerra el nodo, draenalo en orden, hace el trabajo y abrilo de nuevo — Mentat recuerda que paro y repone exactamente eso.

mt host cordon mentat-falp -r KernelPatch   # no se coloca trabajo nuevo
mt host drain  mentat-falp -r KernelPatch   # para y desregistra, en orden
mt host list                                # Drained
# reboot, upgrade, cambio de disco
mt host uncordon mentat-falp                # Ready + vuelven las mismas replicas