MeshLLM: inferencia LLM distribuida en malla P2P

¿Alguna vez has sentido que tienes un «cementerio de GPUs» en casa? Tienes un portátil con Apple Silicon, un sobremesa con una NVIDIA potente y quizás un mini-PC haciendo de servidor, pero cada uno por separado solo puede cargar modelos pequeños. El hardware está ahí, ocioso, pero te falta esa capacidad de cómputo masiva que solo obtendrías con una tarjeta de miles de euros.

Aquí es donde entra Mesh LLM. Su objetivo es ambicioso pero directo: agrupa la potencia de cómputo y la memoria de varias máquinas para exponer el resultado como una sola API compatible con OpenAI en http://localhost:9337/v1. Lo mejor es que puedes empezar con un solo nodo y añadir más conforme los necesites; la malla es lo suficientemente inteligente para decidir si un modelo se ejecuta localmente, se enruta a un compañero (peer) o se reparte mediante stage splits para modelos que simplemente no caben en una sola máquina.

Es software libre (Apache-2.0), escrito principalmente en Rust y construido sobre iroh para gestionar toda la complejidad de la capa de red peer-to-peer.

🎯 Qué problema resuelve

Si trabajas en un homelab o en un equipo de investigación, sabes lo que es tener hardware infrautilizado. Mesh LLM ataca este problema desde tres ángulos estratégicos:

Como dice su eslogan: «run bigger models without buying bigger GPUs».

🧭 Cómo encaja frente a lo que ya conoces

Para no perdernos, es importante situar a Mesh LLM en el ecosistema actual de IA local:

• Ollama y LM Studio: Son soluciones de un único nodo, cero red y arranque inmediato. Es lo correcto para el 90 % de los casos.
• llama.cpp: Es el motor de inferencia. Mesh LLM mantiene la paridad de familias de modelos de llama.cpp mediante el formato GGUF.
• Despliegue con Kubernetes: Esto es para inferencia en clústeres gestionados (vLLM y similares) con nodos homogéneos y red de datacenter.
• Mesh LLM: Es cómputo distribuido entre tus propias máquinas heterogéneas, sin necesidad de un orquestador central ni un servidor de coordinación en el plano de datos.

Consulta también Ecosistemas locales para situar todas estas piezas.

🏗️ Arquitectura P2P sobre iroh

Cada nodo levanta un endpoint de iroh cuya clave pública es su identidad de red. Gracias a iroh, el sistema se encarga del hole-punching, el NAT traversal y el fallback a relays. Esto permite que los nodos establezcan conexiones QUIC directas entre sí sin un servidor central en el plano de datos.

Sobre QUIC, Mesh LLM define varios ALPN según la documentación de iroh:

• mesh-llm/1 — gossip, routing, túneles HTTP y canales de plugins.
• mesh-llm-control/1 — plano de control: configuración y ownership del operador.
• skippy-stage/2 — transporte de activaciones, sensible a latencia.

📦 Instalación

El instalador oficial descarga el ejecutable de release. El binario se llama mesh-llm (mesh-llm.exe en Windows).

curl -fsSL https://raw.githubusercontent.com/Mesh-LLM/mesh-llm/main/install.sh | bash

En Windows, usando PowerShell:

irm https://raw.githubusercontent.com/Mesh-LLM/mesh-llm/main/install.ps1 | iex

Una vez instalado, completa la configuración inicial:

mesh-llm setup

El comando mesh-llm setup configura el runtime nativo y puede instalar el servicio en segundo plano en máquinas macOS y Linux compatibles.

git clone https://github.com/Mesh-LLM/mesh-llm
cd mesh-llm
just build

Si necesitas desinstalarlo más adelante, puedes previsualizar la limpieza primero:

mesh-llm uninstall --dry-run
mesh-llm uninstall --yes

Ten en cuenta que la desinstalación preserva la configuración e identidad en ~/.mesh-llm a menos que utilices el flag --purge-config.

🚀 Primeros pasos

Unirse a la malla pública

Si quieres empezar ya mismo, este comando hace casi todo el trabajo sucio:

mesh-llm serve --auto

Este comando elige un backend flavor, descarga un modelo adecuado si es necesario, se une a la mejor malla pública descubierta, arranca la API local en el puerto 9337 y la consola web en el 3131.

Para despliegues en servidores donde no necesites interfaz, usa --headless para ocultar la UI web pero mantener la API de gestión:

mesh-llm serve --auto --headless

Consultar modelos y lanzar una petición

Para ver qué modelos tienes disponibles:

curl -s http://localhost:9337/v1/models | jq '.data[].id'

Y para lanzar tu primera petición de chat:

curl http://localhost:9337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"GLM-4.7-Flash-Q4_K_M","messages":[{"role":"user","content":"hello"}]}'

Como es compatible con OpenAI, puedes usar cualquier SDK, plugin de IDE o herramienta de agentes apuntando simplemente a http://localhost:9337/v1.

Malla privada entre tus máquinas

Si prefieres no estar en la malla pública, puedes montar tu propia red privada de forma sencilla:

1. Crear la malla en el primer nodo (esto te imprimirá un token de invitación):

   mesh-llm serve --model Qwen3-8B-Q4_K_M
   

2. Unir otro nodo con GPU:

   mesh-llm serve --join <token>
   

3. Unir un nodo que solo actúe como cliente (sin servir modelos):

   mesh-llm client --join <token>
   

Si aun así quieres que tu malla sea parte del descubrimiento público, simplemente añade el flag --publish:

mesh-llm serve --model Qwen3-8B-Q4_K_M --publish

🧩 Repartir un modelo grande: Skippy stage splits

Skippy es el runtime staged que hace la magia. Permite ejecutar modelos gigantes que no caben en una sola máquina cargando stages de capas respaldados por paquetes en varios peers. El proceso sigue estos pasos:

1. El coordinador resuelve el modelo o el layer package solicitado.
2. El planificador de topología elige peers y rangos de capas contiguos.
3. Los stages finales (downstream) cargan primero.
4. El stage 0 sólo se vuelve enrutable cuando todos los stages requeridos reportan ready.
5. Los clientes OpenAI siguen usando el endpoint normal en http://localhost:9337/v1.

Los layer packages son repositorios de Hugging Face con un manifiesto model-package.json y fragmentos GGUF, lo que permite que cada peer descargue sólo lo que necesita.

mesh-llm serve --model hf://meshllm/Qwen3-235B-A22B-UD-Q4_K_XL-layers@<revision> --split

🔀 Routing y modelos especializados

Al exponer la misma API /v1 en todos los nodos, el enrutamiento se hace de forma inteligente por el campo model. Esto te permite tener un patrón muy cómodo en un homelab: una máquina para código, otra para modelos generalistas grandes y otra para visión, todo bajo un único endpoint.

Además, tienes la opción Mixture-of-Agents (MoA). Si envías "model": "mesh", el proxy lanza la petición a todos los modelos disponibles en la malla en paralelo, arbitra las respuestas y te devuelve una única respuesta coherente. Requiere al menos dos modelos distintos.

curl http://localhost:9337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"mesh","messages":[{"role":"user","content":"What is the capital of Japan?"}]}'

⚡ Speculative decoding

Para mejorar la velocidad, Mesh LLM soporta speculative decoding en su runtime staged. Puedes optimizar esto con mesh-llm benchmark tune, que busca la mejor configuración midiendo tokens/s. Los tipos disponibles son auto, mtp, draft, ngram y disabled:

mesh-llm benchmark tune --model /models/qwen3-mtp.gguf --speculative-types auto
mesh-llm benchmark tune --model /models/qwen3-8b.gguf \
  --speculative-types draft,ngram,disabled \
  --spec-draft-models /models/qwen3-draft.gguf \
  --spec-draft-max-tokens 4,8,16

Con la opción auto, el sistema probará primero MTP nativo, luego modelos draft locales, luego candidatos ngram y finalmente una línea base sin speculation para comparar. Los cambios se guardan en ~/.mesh-llm/config.toml si usas --apply.

🔒 Seguridad y modelo de confianza

Las mallas se pueden asegurar con requisitos inmutables (versión mínima de nodo, política de release attestation, etc.). Cambiar estos requisitos genera un nuevo identificador de malla.

Puedes verificar la validez de un binario empaquetado así:

cargo run -p xtask -- release-attestation inspect \
  --binary <path-to-packaged-mesh-llm> \
  --public-key-file <release-signing-public-key.json>

Un binario de release reportará valid, uno de desarrollo dirá missing y uno modificado dirá invalid.

🧪 Casos de uso realistas

• Homelab multi-máquina: Unir un Apple Silicon, una NVIDIA y un mini-PC en una malla privada para servir un modelo de 70B+ mediante splits.
• Equipo de investigación: Compartir una malla privada donde cada investigador aporta su máquina y todos acceden a modelos especializados mediante el mismo endpoint local.
• Nodo cliente ligero: Usar un portátil sin GPU para consumir la potencia de una malla mediante mesh-llm client --join <token>.
• Aprovechar horas ociosas: Convertir máquinas de escritorio infrautilizadas en parte de la infraestructura de IA del equipo.

⚠️ Limitaciones y cuándo NO usarlo

Antes de lanzarte, hay algunas realidades técnicas que debes considerar.

No lo uses si:

• El modelo cabe en una sola máquina: Usa Ollama o llama.cpp.
• Necesitas throughput estable en producción: Usa vLLM sobre Kubernetes.
• Tus datos son ultra-sensibles y no controlas todos los nodos: Quédate en malla privada o usa soluciones locales tradicionales.
• Solo tienes una máquina: No hay nada que repartir.

🔗 Recursos relacionados

• Ollama: instalación y primeros pasos — el punto de partida de un solo nodo.
• llama.cpp — el motor GGUF subyacente.
• LM Studio — alternativa gráfica.
• Ecosistemas locales — panorama general.
• Despliegue a escala con Kubernetes — la alternativa para clústeres de datacenter.

📚 Referencias

Fuentes oficiales consultadas el 2026-07-18:

• Mesh LLM — sitio oficial
• Repositorio oficial: Mesh-LLM/mesh-llm (Apache-2.0)
• Mesh LLM: distributed AI computing on iroh — blog de iroh
• docs/MESHES.md — mallas privadas y publicación.
• docs/SKIPPY_SPLITS.md — splits por capas.
• docs/CLI.md — referencia de comandos.
• docs/USAGE.md — guía operativa.
• Documentación de iroh

Mesh LLM es una apuesta fascinante para quienes queremos democratizar el acceso a modelos gigantes sin tener que vender un riñón para comprar una nueva GPU. Si tienes hardware repartido por casa, ¡dale una oportunidad!