Túneles Cruma

¿Qué hace Túneles Cruma?

Usa esta habilidad cuando el usuario quiera publicar algo desde su máquina, gestionar lo que Cruma ya sirve, o instalar o detener Cruma. Cualquier cosa compartida es pública: pregunta antes de compartir y di exactamente qué puerto o carpeta se vuelve accesible. Los túneles anónimos no requieren registro.

La cuenta de Cruma del usuario

Las funciones de la cuenta, incluidos los detalles del plan, los túneles y sitios de la cuenta, el tablero y la memoria, vienen con el complemento opcional cruma-cloud. Usa su habilidad cloud para esas solicitudes. Compartir un puerto o carpeta y los agentes en ejecución del usuario permanecen en el servidor local cruma.

Con las herramientas MCP de Cruma

Este complemento inicia cruma mcp a través de su lanzador (mcp/cruma-mcp.mjs), un servidor MCP local llamado cruma que ejecuta el binario cruma instalado. Cuando sus herramientas estén en tu lista de herramientas, úsalas, no comandos de shell. El servidor se inicia sin nada expuesto.

Averigua; no adivines

Este archivo es un mapa, no el manual. Para una compartición simple de un puerto o carpeta, usa las herramientas a continuación. Para cualquier otra cosa (autenticación, filtros, dominios, enrutamiento, procesos, reglas, una configuración que no hayas usado antes), primero lee lo que Cruma dice sobre sí mismo, luego usa la herramienta a la que apunta:

1. El recurso cruma://about (o describe_cruma): qué puede hacer Cruma y qué herramienta lo hace. Luego get_config_model_reference con una section (middleware_model para control de acceso y filtros de solicitud, backend_kinds, listener_model, recommended_mcp_usage; la referencia completa es grande) y get_cruma_glossary para términos. En el agente del usuario (ver más abajo), get_runtime_inventory muestra lo que ya está configurado. Carga los esquemas de las herramientas que llamarás.
2. Si eso no es suficiente, los documentos en Markdown: https://cruma.io/llms.txt, la lista de capítulos https://cruma.io/book/cruma-tunnels.md, y cualquier capítulo en https://cruma.io/book/cruma-tunnels/<chapter>.md. Están escritos para la línea de comandos (cruma serve, cruma proxy): toma lo que Cruma puede hacer de ellos y aplícalo a través de las herramientas MCP.
3. Para una ruta solo de CLI, cruma --help y cruma <command> --help.

Los atajos como expose_local_port cubren el caso común. Lo que no cubran se hace con las herramientas generales upsert_*; nunca presentes los límites de un atajo como límites de Cruma. Si la referencia y los documentos no respaldan lo que el usuario pidió, dilo; no inventes una configuración o una herramienta.

Nunca sirvas cosas tú mismo. No inicies python3 -m http.server, npx serve ni ningún otro servidor de archivos, y no ejecutes cruma serve o cruma proxy: con MCP conectado, inician un segundo agente con su propio túnel.

El Cruma de quién

Las herramientas se inician adjuntas a un agente de sesión temporal: un túnel anónimo que comparten tus ventanas y que no contiene nada que el usuario haya guardado. No es el propio Cruma del usuario.

Antes de la primera compartición en una sesión, llama a list_agents una vez (no lee nada de ningún agente, por lo que está bien primero). Busca un agente en ejecución que no sea el agente de sesión y cuyo tunnel_account sea registered (la aplicación de escritorio o un agente headless, con sesión iniciada o con credenciales de túnel). Un agente en ejecución con tunnel_account anonymous no lo es.

• Existe un agente de este tipo: pregunta una vez, antes de compartir cualquier cosa. Nombra la elección con su tipo, perfil, dominio y qué significa la otra opción, por ejemplo: "¿Usar tu Cruma en ejecución (escritorio, perfil work, acme.tun.example.test) o un túnel anónimo temporal (dirección aleatoria, página de advertencia del navegador, con límite de tiempo, desaparece con la sesión)?" No compartas nada y no llames a ninguna otra herramienta que lea o modifique un agente, hasta que respondan. Si hay varios en ejecución, enuméralos en la misma pregunta.
  • Eligen el suyo: llama a use_agent en ese agente (esta es la confirmación que Preguntar antes de use_agent solicita) y haz todas las comparticiones de la sesión allí. Menciona la limitación conocida cuando corresponda: una compartición hecha en un agente de un túnel al que sirven varios agentes solo es accesible a través de ese agente.
  • Eligen el túnel temporal: permanece en el agente de sesión.
  • Recuerda la respuesta para el resto de la sesión. No vuelvas a preguntar para comparticiones posteriores y no llames a list_agents de nuevo por ellas. Pregunta de nuevo solo si el usuario lo plantea.
• No existe tal agente (ninguno, o solo anónimos como el agente de sesión): sin pregunta. Usa el agente de sesión tal cual e informa las URLs.
• No puedes preguntar (una ejecución no interactiva, o no hay forma de obtener una respuesta): usa el agente de sesión y di en la entrega que lo hiciste, y que un Cruma en ejecución con sesión iniciada estaba disponible cuando list_agents mostró uno.
• La pregunta no es necesaria cuando el usuario ya nombra dónde va la compartición ("en mi Cruma de escritorio", "usa un túnel temporal"): sigue eso.

Las comparticiones permanecen propiedad de la sesión y se retiran cuando la sesión termina; nunca establezcas persist para ellas.

Cuando la solicitud trata sobre su Cruma (su app, sitios, rutas, dominios, procesos o registros: "¿por qué mi sitio devuelve 502?", "añade una contraseña a mi sitio de staging", "¿qué se está ejecutando en mi Cruma?"), o quieren compartir a través de su propio túnel, un dominio personalizado o un perfil con nombre, llama a list_agents antes de cualquier herramienta que lea o modifique un agente (describe_cruma, cruma://about, get_config_model_reference y get_cruma_glossary están bien primero). Leer el agente de sesión responde sobre una configuración que no es la suya, así que nunca lo leas para tal solicitud. Listar o crear los túneles en su cuenta es de la cuenta (ver arriba), no de list_agents.

• Pregunta antes de use_agent, nombrando el tipo del agente (escritorio, headless), perfil y dominio, y espera la respuesta. Para una compartición simple, la pregunta anterior es esa pregunta; nunca cambies sin ella. Las herramientas de compartición entonces funcionan en ese agente. Cambiar retira las comparticiones que hiciste en el anterior.
• Antes del cambio, di solo a qué agente cambiarías y pregunta. No describas lo que contiene cada agente (incluido el del agente de sesión), y no afirmes ni insinúes una causa, un diagnóstico o qué está configurado, incluso cuando list_agents muestre un resumen del proceso (una fase como Failed) o nombres de sitios: eso es un listado, no un diagnóstico. Nombra el destino (tipo, perfil, dominio), pregunta, di que nada se cambia hasta que respondan, y detente. Diagnostica después del cambio, desde el agente del usuario.
• use_agent nunca inicia un agente. Si ninguno se está ejecutando para lo que el usuario quiere, díselo y pídele que abra la aplicación de escritorio, o ejecute cruma --profile <name> (usa el nombre que list_agents da para un perfil detenido). No recurras al túnel temporal para una solicitud sobre sus propios sitios.
• Di solo lo que devolvió una herramienta. list_agents enumera los agentes que conoce; a partir de él puedes decir qué agentes se están ejecutando y su tipo, perfil y dominio. No afirmes que existen o faltan perfiles, sitios, configuraciones o una cuenta a menos que un resultado de la herramienta lo diga (por ejemplo, nunca "no aparecieron perfiles guardados" o "nada está configurado").
• No hay list_agents entre tus herramientas significa un agente más antiguo: usa el túnel temporal para comparticiones y di que se necesita un cruma más nuevo para el propio del usuario (Actualizar tiene el comando de actualización).
• Un servidor MCP HTTP de Cruma ya en el cliente del usuario (por ejemplo cruma-app) es su propio agente. Usa sus herramientas para solicitudes sobre su Cruma y las de este complemento para comparticiones temporales. Si falló la conexión, dilo en lugar de usar el agente de sesión. list_agents marca el agente que sirve HTTP /mcp.

En el agente propio del usuario, después de que acepten el cambio:

• Un resultado exitoso de use_agent es el estado del agente al que ahora estás adjunto (dominio, frontends, procesos, allow_persistent_changes). Trabaja a partir de él; no llames a list_agents de nuevo solo para confirmar el cambio.

• Leer es gratis: get_health_summary, get_site_summary, get_proxy_routes, probe_route, get_process_logs, list_recorded_requests.

• Los cambios se aplican al agente en ejecución y desaparecen cuando se reinicia. Dilo.

• Los cambios permanentes ("configurar un sitio para siempre") necesitan persist: true, y el agente lo rechaza a menos que el usuario active "Permitir que guarden cambios" (mcp.local_socket.allow_persistent_changes; página MCP del escritorio, "Agentes de Codificación en Este Computador"). Nunca hagas silenciosamente un cambio en memoria en su lugar. Explica la configuración y pídeles que la activen, o que hagan el cambio en la aplicación. Una vez que esté activada (allow_persistent_changes es true en el resultado de use_agent, o en list_agents antes del cambio), no llames a una herramienta de escritura con persist: true todavía: primero describe el cambio exacto (frontend, backend, middleware) como tu respuesta y pregunta si guardarlo, diciendo claramente que se guardaría en disco en la configuración del agente y permanecería después de un reinicio. Pasa persist: true solo después de que el usuario haya aprobado claramente ese cambio exacto: un sí a tu descripción en un turno posterior, o, en el mismo mensaje, una aprobación explícita que nombre el backend y el frontend por tipo y nombre como un cambio guardado ("Apruebo exactamente este cambio guardado: ..."). Preguntar por un sitio "permanente" o "guardado", incluso con un nombre y una ruta, es una solicitud, no una aprobación: describe el cambio y pregunta. Nunca reenvíes una configuración existente con persist: true para hacerla permanente sin la misma aprobación. Este es el único uso de persist, y nunca en el agente de sesión.

Protege lo que parezca privado

Antes de exponer algo que parezca privado (una interfaz de administración, una herramienta de base de datos, documentación interna, una carpeta con credenciales, archivos .env o datos personales), pregunta si protegerlo y sugiere una contraseña. Espera la respuesta; no expongas primero. Si el usuario ya pidió protección, no vuelvas a preguntar.

• Una contraseña o una lista de IPs permitidas: pasa access a expose_local_port o expose_local_directory (el esquema de la herramienta enumera los tipos). Una contraseña generada se devuelve una vez. Sin un argumento access en el esquema (un agente más antiguo), construye el sitio con upsert_backend y upsert_frontend y un middleware basic_auth; lee middleware_model para su forma.
• Inicio de sesión con una cuenta o un proveedor (Google, GitHub): access sign_in no está disponible para comparticiones todavía. No lo intentes ni lo evadas. El inicio de sesión va a través de upsert_frontend con un middleware oauth2 que haga referencia a un proveedor que el agente del usuario ya tenga. Encuentra los IDs de proveedor en los middlewares oauth2 de los frontends existentes (get_runtime_inventory con full: true y sections: ["frontends"]), o pregunta al usuario qué proveedor usar. Lee middleware_model para la forma del middleware. Si no hay proveedor, di que el inicio de sesión necesita uno configurado primero y ofrece una contraseña.

Qué usar para qué

El usuario quiere compartir	Haz esto
Archivos: una página que escribiste, una salida de compilación, documentación	expose_local_directory con la carpeta y un name. Escribe los archivos primero si es necesario.
Un servidor de desarrollo que ya se está ejecutando	expose_local_port con su puerto y un name.
Una aplicación que aún no se está ejecutando	Haz que el agente la aloje: upsert_process (el agente asigna PORT; haz que el comando escuche en él), luego upsert_frontend en <name>.<assigned_domain> con process_id establecido. Los registros llegan a través de get_process_logs. Solo si eso no encaja, iníciala en segundo plano tú mismo y dilo.
Varias cosas	Una llamada por compartición. Un agente sirve muchos sitios y puertos a la vez, cada uno en <name>.<assigned domain>: frontend y API, documentación y aplicación, dos versiones lado a lado. Nombra cada uno por lo que es (docs, api, preview-v2).

Si expose_local_directory o expose_local_port falta (un agente más antiguo), usa upsert_backend (http para un puerto, local-directory para una carpeta) y upsert_frontend en <name>.<assigned_domain>, sin persist. Obtén assigned_domain de get_runtime_summary; es null durante unos segundos mientras el túnel se conecta, así que vuelve a llamarlo. No te detengas en "actualiza cruma".

Después de exponer, llama a get_health_summary; status debería ser ok. Usa list_shares para informar cada URL activa. Una vez por sesión, también llama a get_runtime_summary y lee su bloque version (ver Versiones más abajo).

Entrega

Di todo esto en el mensaje final:

1. Cada URL pública (public_url, o https://<name>.<assigned_domain>/ en la ruta alternativa) y qué sirve cada una, incluido el puerto o carpeta local. No des ninguna otra URL.
2. Que get_health_summary informó ok, llamado después del paso de exponer; si no, el estado y los problemas en lugar de reclamar éxito.
3. Qué ruta usaste: expose_local_port, expose_local_directory, upsert_process (el agente aloja y supervisa la aplicación, por lo que sus registros están disponibles a través de get_process_logs), o upsert_backend/upsert_frontend.
4. En qué agente actuaste: tipo (escritorio, headless o sesión temporal), perfil y dominio, para que una compartición temporal nunca se tome como un cambio en la aplicación del usuario. Cuando usaste el agente de sesión porque no pudiste preguntar, dilo.
5. Para el agente de sesión: las URLs terminan con la sesión, un túnel anónimo también termina en su límite de tiempo (elemento 7), y no se escribe nada en el disco. Para el agente propio del usuario: si el cambio es temporal o guardado.
6. Cómo eliminar uno: pídelo, y tú llamas a unexpose con su nombre para una compartición expose_*, o remove_frontend, remove_backend y remove_process para una upsert_*. Para una compartición de carpeta, editar los archivos actualiza el sitio inmediatamente.
7. Para una compartición protegida: qué la protege (contraseña, redes permitidas o inicio de sesión), la credencial una vez si la generaste (nombre de usuario cruma), y que la protección termina con la compartición. Una compartición sin protección es pública: dilo.
8. El aviso de cuenta, una vez por sesión, cuando el account.state de un resultado de herramienta sea anonymous: el túnel es anónimo y con límite de tiempo, con el tiempo restante de account.remaining_secs en horas y minutos (o account.expires_at) cuando esté disponible; además, los túneles anónimos son limitados a un sitio, mientras que una cuenta registrada puede tener varios sitios y puertos, dominios personalizados y cuentas de servicio.

Instalación

Cuando el usuario necesite instalar o actualizar Cruma:

curl -fsSL https://cruma.io/install.sh | sh

(Las opciones de instalación están en https://cruma.io/book/install.md.) Pregunta primero; no ejecutes el comando de inmediato.

Directorios de instalación típicos

Sistema	Binario	Archivos de datos	Configuración
macOS (Homebrew)	/opt/homebrew/bin/cruma	/opt/homebrew/share/cruma	/Users//Library/Application Support/cruma
Linux (sistema)	/usr/local/bin/cruma	/usr/local/share/cruma	/home//.config/cruma
Linux (usuario)	~/.local/bin/cruma	~/.local/share/cruma	~/.config/cruma
Windows	%USERPROFILE%.cruma\bin	%USERPROFILE%.cruma\share	%USERPROFILE%.cruma\config
Variable de entorno	CRUMA_BIN	CRUMA_DATA	CRUMA_CONFIG

Versiones

Cuando se use por primera vez en una sesión (get_runtime_summary arriba), muestra la versión (version y latest_release de get_runtime_summary). Si la versión local está desactualizada (no es la más reciente), di que una actualización está disponible. Si está en la última versión, dilo también. "Desactualizada" significa local < latest.

Hacer cumplir user_agent con fines de facturación

Cuando llames a cualquier herramienta Cruma y el esquema de la herramienta tenga un parámetro user_agent de tipo string, pásalo como cloud/mcp. El agente del usuario en list_agents informa qué user_agent se pasó cuando se estableció la conexión. Las herramientas sin user_agent en su esquema no necesitan esto (es un agente más antiguo).

Error común y siguiente paso

• Docker en macOS: si el puerto o la carpeta son de un contenedor Docker, el túnel no es accesible para el agente de sesión.
• El firewall puede bloquear conexiones entrantes; expose_local_port puede fallar con un registro de "handshake refused". El agente de escritorio maneja esto configurando excepciones de cortafuegos; el agente de sesión no puede.
• cruma no encontrado / comando no encontrado: el binario no está en el PATH o no está instalado. Ofrece instalar.