Menú
Español
TemasSoporteGitHub ↗
GUÍA DE USUARIO · MANUAL DE REFERENCIA

Todo lo que necesitas para tener tu máquina siempre a mano.

Muqun conecta tu teléfono directamente a tu propio ordenador o servidor. Aprende a instalar y configurar el Gateway, navegar por tus terminales, dirigir el agente autónomo OpenCode, instalar temas y resolver problemas de conexión.
Empezar ↓Diagnóstico ↓Abrir una incidencia ↗

muqun-gateway

Instala el Gateway y empareja tu teléfono.

Muqun se comunica con un único programa en tu propio ordenador: el Gateway. Lo instalas allí, lo inicias y vinculas el teléfono una sola vez. No se requiere cuenta y nada tuyo pasa por nuestros servidores.
PRE-FLIGHT REQUIREMENTScheck before installing
  • macOS o Linux en un ordenador propio (Windows no está soportado todavía).
  • tmux o Herdr 0.7.5 o superior ya instalado (el Gateway los maneja, no los sustituye).
  • Ambos dispositivos en la misma red privada. Tailscale es la opción recomendada (usa Tailscale Serve, nunca Funnel).
  • Sin cuentas, sin suscripciones y sin servidores intermediarios nuestros.

  1. Ejecuta el instalador en tu ordenador

    Coloca un binario único en ~/.local/bin/muqun-gateway, lo configura y abre la pantalla de emparejamiento en la primera ejecución. Compatible con macOS y Linux (Windows aún no está soportado).
    install
    curl -fsSL https://muqun.dev/gateway.sh | sh

  2. Inícialo de una de estas dos formas

    Puedes iniciarlo tú mismo o dejar que el sistema lo mantenga activo en segundo plano. Ambas opciones dejan el Gateway en funcionamiento; difieren en cómo responden al reiniciar el equipo.
    OPTION A · DIRECT

    Inicio manual directo

    Se ejecuta en segundo plano y continúa activo tras cerrar el terminal, hasta que el ordenador se reinicie. muqun-gateway stop lo detiene.
    direct
    muqun-gateway start
    OPTION B · SERVICE

    Como servicio del sistema

    Lo registra en el sistema de inicio de tu usuario (systemd en Linux, LaunchAgent en macOS). Arranca al iniciar sesión y se recupera tras reinicios o caídas. muqun-gateway service uninstall elimina el servicio conservando los emparejamientos.
    service
    muqun-gateway service install
    Elige solo una: si el servicio está instalado, detenerlo con stop será revertido de inmediato por el supervisor.

  3. Abre el administrador de emparejamiento

    Sin importar el modo de inicio, este es el siguiente paso. El administrador es un panel a pantalla completa en el terminal que muestra el código QR, los procesos y los dispositivos con token activo.
    pair
    muqun-gateway manage

  4. Escanea e introduce el código

    Escanea el código QR desde Muqun. El ordenador mostrará un código corto en formato XXXX-XXXX; introducirlo en la app completa el emparejamiento. Escanear no basta por sí solo: el código confirma tu identidad.
MANUAL ADDRESS PAIRING
¿No puedes escanear? Escribe la dirección del Gateway manualmente en la app (el administrador muestra la dirección pública) e introduce el mismo código corto.
CODE VALIDITY & RETRIES
El código es válido durante 5 minutos y se anula tras 8 intentos fallidos. Pulsa p en el administrador para generar un nuevo QR y código.
RED PRIVADA RECOMENDADA

Usa Tailscale en ambos dispositivos.

Recomendamos encarecidamente conectar el teléfono y el ordenador del Gateway a la misma tailnet de Tailscale. Evita abrir puertos en el router y protege el Gateway de la red pública. Tailscale Serve puede añadir una dirección HTTPS privada (no utilices Tailscale Funnel con Muqun).

workspace · group.panel

Tu terminal de verdad.

Es tu terminal real y no una simple captura o transcripción. El Gateway maneja tmux o Herdr en tu equipo y la aplicación dibuja su contenido en pantalla con total fidelidad.
WORKSPACE ARCHITECTURE

Espacios, grupos y terminales

Tres niveles: espacio · grupo.panel. Un espacio es tu directorio de trabajo, un grupo reúne terminales y un terminal es una shell. Muqun muestra un terminal a la vez a pantalla completa para garantizar una lectura óptima.

Moverte entre vistas

Desliza la barra superior de título para cambiar de espacio. Las etiquetas sobre el campo de texto cambian de terminal dentro del mismo grupo.

Procesos y panel lateral

El panel lateral enumera todos los espacios, grupos y terminales de la máquina. Una pulsación prolongada abre opciones para cerrar de forma segura.
Un panel de nvim con un archivo TypeScript abierto, pestañas para Claude Code, nvim y zsh, y la barra de teclas sobre la entrada.Un panel de nvim con un archivo TypeScript abierto, pestañas para Claude Code, nvim y zsh, y la barra de teclas sobre la entrada.
CONTROLS, EDITORS & DEVELOPER TOOLS

Barra de teclas del terminal

La barra sobre la entrada de texto incluye teclas esenciales que faltan en el teclado móvil: Esc, Tab, ⌃C, flechas, y teclas contextuales que cambian según el programa en ejecución (⇧TAB y ⌃O en Claude Code, :w y gg en nvim). Se puede desactivar en Ajustes → Terminal.

Editor de comandos (Composer)

Fuente monoespaciada, soporte multilínea y la tecla Intro añade saltos de línea: el envío se realiza mediante un botón para evitar pulsar comandos no deseados.

Historial de salida

Tira hacia abajo desde la parte superior del terminal para cargar el historial anterior. Si dejas el extremo en vivo, un botón flotante te devuelve al final al instante.

Cambios (Changes)

Estado de Git para el directorio del panel actual: archivos modificados, filtros de Staged/Unstaged y diffs completos. Solo visible en repositorios Git compatibles.

Archivos (Files)

Accede a los archivos creados durante tus sesiones (imágenes, código y documentos), legibles sin salir de la app.

Abrir en el navegador

Introduce el puerto de tu servidor de desarrollo y Muqun lo abrirá mediante la conexión segura existente sin exponerlo a Internet.

Acciones rápidas

Comandos guardados, prompts habituales y atajos de teclado, ordenados por frecuencia de uso. Personalizables en cualquier momento.
●
Muqun actúa siempre como un observador seguro: abrir una sesión no altera tus ventanas y cerrar la app no interrumpe ninguna tarea.

opencode serve --service

El agente OpenCode.

Una interfaz creada específicamente para OpenCode en vez de un simple chatbot en consola: cambia de sesión con rapidez, visualiza diffs reales en tarjetas y responde a preguntas con un solo toque.
EJECUCIÓN LOCAL · SIN CUENTA

Tu ordenador habla directamente con tus proveedores de IA.

No requiere iniciar sesión. Muqun no maneja cuentas ni solicita claves API. Quien se comunica con los modelos es OpenCode en tu propio ordenador. El Gateway no almacena ni reenvía tus credenciales.
REQUISITOS
  • OpenCode 2.0.1 o superior instalado en el mismo ordenador que el Gateway.
  • Al menos un proveedor configurado en OpenCode (con opción para filtrar solo modelos gratuitos).
  • El servicio OpenCode en ejecución (el Gateway lo inicia o conecta automáticamente).
  • Un Gateway reciente que admita la interfaz del agente.
AGENT CAPABILITIES & WORKFLOW

Sesiones y subagentes

Cada sesión tiene su propio contexto. Si una tarea delega en subagentes, estos se muestran indentados debajo de la sesión principal para una lectura cómoda.

Proyectos

Cambia el directorio de trabajo del agente al instante. Al elegir un proyecto se reanuda automáticamente su última sesión activa.

Modelos y agentes

Consulta los modelos disponibles según tus proveedores configurados, con tamaño de ventana de contexto e indicador Free. Alterna entre perfiles Build, Plan, Explore o agentes propios.

Comandos / y habilidades

Escribe / en la entrada de texto. Comandos como /new, /models o /undo son resueltos directamente por la app; el resto se ejecutan en el ordenador anfitrión.

Adjuntos y menciones con @

Envía fotos o archivos. Las imágenes se recodifican para eliminar metadatos EXIF. Escribe @ para vincular rápidamente archivos del proyecto.

Permisos y preguntas

Cuando el agente desea ejecutar comandos o modificar ficheros, una tarjeta te permite elegir entre Permitir, Permitir siempre o Denegar (también desde las notificaciones).

Tareas en segundo plano y cola

Envía herramientas lentas a segundo plano y supervisa el progreso desde la bandeja superior. Tus mensajes nuevos pueden intervenir de inmediato o esperar su turno en la cola.

Contexto y compactación

Supervisa la ocupación del contexto del modelo, los tokens consumidos y el coste estimado. Las compactaciones automáticas se marcan con claridad en la línea de tiempo.

Deshacer (Undo)

/undo revierte el proyecto al estado previo a tu último mensaje; /redo lo restaura. Diseñado como comando para prevenir pulsaciones involuntarias.
●
Las llamadas a herramientas aparecen como tarjetas interactivas: las ediciones muestran su diff unificado en línea, igual que en el visor de Cambios.

config.json

Configurar el Gateway.

La mayoría de usuarios no necesitan abrir la configuración. Está disponible para casos concretos: cambiar de puerto, mantener el Gateway tras un reinicio o usar una ruta no estándar para OpenCode.

El archivo de configuración

JSON SCHEMA
Es un archivo JSON generado durante la instalación. Modifícalo manualmente solo cuando necesites ajustar las claves indicadas y reinicia el Gateway después. En macOS se ubica en ~/Library/Application Support/muqun-gateway/. Los dispositivos vinculados y registros se guardan en ~/.local/share/muqun-gateway/.
linux
~/.config/muqun-gateway/config.json
CONFIGURATION KEYS REFERENCE
label
El nombre que la aplicación muestra para este ordenador.
listen
El socket al que se vincula (host y puerto). Por defecto 0.0.0.0:23847 (o 127.0.0.1 si la dirección publicada es local).
public_url
La dirección codificada en el QR de emparejamiento. Es preferible modificarla pulsando u en el administrador.
transport_encryption
Cifrado de transporte, por defecto required. Se aplica a los dispositivos vinculados en el futuro sin alterar los existentes.
sessions
Los motores de terminal que este Gateway monta (tmux, Herdr o ambos). Se gestiona con muqun-gateway backend.
autostart_backends
Cuáles de ellos inician con el Gateway. Vacío por defecto para evitar lanzamientos involuntarios.
rich_agent_pushes
Desactivado por defecto. Si se activa, las preguntas del agente se insertan en el cuerpo de la notificación (mostrando texto del terminal en la pantalla de bloqueo).
opencode.autostart
Activado por defecto: el Gateway inicia OpenCode si no detecta ninguno en ejecución. Desactívalo con "opencode": { "autostart": false }.
opencode.binary
Ruta al binario de OpenCode. Si se omite, se busca en ~/.opencode/bin o en tu PATH.
PUERTOS Y ENLACES

Por defecto

Un único puerto TCP: 23847.

Cambiarlo

Ejecuta muqun-gateway setup --port N y reinicia.

Dónde escucha

127.0.0.1 si la dirección es loopback, 0.0.0.0 en los demás casos.

En una tailnet

No requiere abrir puertos en el router, por eso lo recomendamos.
DOS FORMAS DE MANTENERLO ACTIVO
DIRECT

Inicio manual directo

Inicio
Cuando ejecutas el comando.
Parada
muqun-gateway stop o al reiniciar el equipo.
Sobrevive al reinicio
No.
Desinstalación
Nada que hacer, solo detener con stop.
direct
muqun-gateway start
SERVICE

Como servicio del sistema

Inicio
Al iniciar sesión y tras caídas inesperadas.
Parada
Únicamente con service uninstall.
Sobrevive al reinicio
Sí.
Desinstalación
service uninstall (se conservan emparejamientos).
service
muqun-gateway service install
Unidad de usuario de systemd en Linux, LaunchAgent en macOS. Nunca requiere permisos de root ni sale de tu directorio de usuario.
CÓMO ARRANCA OPENCODE
  1. Comprueba si ya hay un servicio OpenCode sano en ejecución leyendo la dirección en ~/.local/state/opencode/service.json.
  2. Si lo encuentra, se conecta directamente a él y tus sesiones abiertas se mantienen intactas.
  3. En caso contrario, ejecuta opencode serve --service y supervisa el proceso detectando automáticamente cualquier cambio de puerto.
●
¿No tienes OpenCode instalado? El sistema no conecta nada y solo la pantalla del agente mostrará desconexión; el terminal no se ve afectado.
config.json
"opencode": { "autostart": false }
PANEL DE EMPAREJAMIENTO
Se abre con muqun-gateway manage. Muestra procesos y dispositivos autorizados y admite estas teclas:
p
Mostrar de nuevo el QR para vincular otro dispositivo.
x
Revocar el acceso a un dispositivo seleccionado.
u
Editar la dirección codificada en el QR (a para volver a detectarla).
s / t
Iniciar o detener el Gateway sin salir del administrador.
m / h
Añadir backend tmux o Herdr (f elige el predeterminado, d elimina).
e
Cambiar el modo de cifrado para emparejamientos futuros.
q
Cerrar el administrador (nunca interrumpe tus sesiones de terminal).

Compatibilidad con versiones anteriores

La app consulta directamente al Gateway qué funciones soporta en lugar de adivinar por su versión, ocultando lo no disponible sin dar fallos. Un Gateway más antiguo sigue siendo un terminal perfecto. Solo la colaboración de agentes requiere Herdr 0.9.0 o más reciente.

Actualizaciones

Vuelve a ejecutar el comando de instalación original. Reemplaza el binario respetando tu identidad, claves, configuración y vinculaciones. Si tenías el servicio activo, vuelve a ejecutar service install tras la actualización.

Registros

DIAGNOSTICS
En modo directo y con LaunchAgent en macOS, los registros van a ~/.local/share/muqun-gateway/gateway.log. En Linux con systemd, se consultan con journalctl. Para mayor nivel de detalle define MUQUN_LOG=debug (o RUST_LOG=debug) antes de iniciar.
linux · modo servicio
journalctl --user -u dev.osuki.muqun-gateway

muqun.dev/themes

Temas.

Un tema transforma tanto la interfaz de la aplicación como los colores del terminal. Cada pack incluye versión clara y oscura. Incluye 24 packs y acceso al catálogo comunitario.

24 paquetes incluidos

En Ajustes → Apariencia → Tema encontrarás opciones como Catppuccin, Gruvbox, Kanagawa, Rosé Pine, Tokyo Night y Everforest.

Explorar el catálogo

Explora los temas publicados en muqun.dev. La descarga no comienza hasta que abres un tema, mostrándote el tamaño del paquete de antemano.

Estructura de un tema

Un archivo .muqun-theme es un zip con un theme.json y una carpeta assets de imágenes. .muqun-theme.json es la versión solo de colores sin imágenes.

Alcance de personalización

17 colores de interfaz por modo, colores de terminal (cursor, enlaces, 16 ranuras ANSI), ilustraciones para 11 pantallas e iconos personalizados.

Límites de tamaño

Manifiesto de hasta 256 KiB, hasta 32 imágenes de máximo 8 MiB cada una y 25 MiB para el archivo comprimido final.

Instalar desde archivo

Abre un .muqun-theme desde Archivos, AirDrop o compartir, o usa «Importar archivo» en la pantalla de temas de la app.

Instalar desde enlace

Introduce una URL pública o un repositorio de GitHub. Se verifica la procedencia de las imágenes antes de descargar nada.

Instalar desde el terminal

Toca en una ruta .muqun-theme que aparezca en la salida de consola para ver una tarjeta de previsualización al instante.

Vista previa antes de aplicar

El tema se aplica temporalmente a toda la app para que puedas inspeccionarlo con total libertad antes de pulsar «Aplicar tema».

Opacidad del fondo

Ajusta de forma independiente la opacidad del fondo de la app y del terminal para lograr transparencias agradables.

Crear tu propio tema

Los temas se escriben en archivos. Puedes pedirle a tu agente de IA mediante la habilidad integrada que cree la apariencia que deseas.

Publicar en el catálogo

El catálogo es un repositorio público de GitHub. Envía un Pull Request con tu carpeta para aparecer en muqun.dev en pocos minutos.

Eliminar temas

Desliza sobre un tema en la lista para desinstalarlo. En Ajustes → Almacenamiento puedes limpiar los temas en desuso.
Explorar el catálogo de temas

when it does not connect

Resolución de problemas.

La inmensa mayoría de incidencias se reducen a cuatro causas: el Gateway no está corriendo, la dirección no es accesible, se perdió el emparejamiento o OpenCode no está activo.
COMPROBACIONES RÁPIDAS

Emparejar ordenador

Instala el Gateway (compatible con tmux o Herdr), abre el panel de control, escanea el QR con Muqun e introduce el código que aparece en pantalla.

Corregir conexión

Verifica que tmux o Herdr 0.7.5+ y el Gateway están en ejecución y que ambos dispositivos pueden comunicarse en la misma red privada.

Eliminar dispositivo

Borra el servidor en la pantalla de inicio de Muqun para retirar el acceso. También puedes revocarlo desde el administrador del Gateway.

Restablecer notificaciones

Activa los permisos de notificación en los ajustes del sistema y en Muqun. Vuelve a abrir el servidor para actualizar el token en el Gateway.
DIAGNOSTIC SOLUTIONS

No se puede emparejar

El error «Could not reach the gateway» significa que el teléfono no llega a la IP indicada en el QR. Comprueba muqun-gateway status y asegúrate de compartir la misma red Wi-Fi o tailnet de Tailscale. Si el Gateway está vinculado a 127.0.0.1 será inaccesible desde el exterior; cámbialo con u en el administrador.

Código rechazado o caducado

El código de 8 caracteres caduca a los 5 minutos o tras 8 intentos incorrectos. Pulsa p en el administrador para generar un nuevo QR y código. Se omiten caracteres confusos como 0, 1, I, L y O.

Significado del punto de estado

Un punto relleno indica respuesta comprobada (verde para ONLINE, gris para OFFLINE). Un círculo vacío con NOT CONNECTED indica que aún no se ha comprobado la conexión; pulsa en el servidor para conectar.

Pide volver a emparejar

El token del dispositivo se ha eliminado en el Gateway o su estado se ha reiniciado. Vuelve a escanear el QR; los demás ajustes de la app se mantendrán.

No se encuentra OpenCode

Si la pantalla del agente muestra OpenCode service offline, ejecuta opencode serve --service en el ordenador y pulsa Reintentar. Si ya está corriendo, define la ruta completa en config.json bajo opencode.binary.

Modelos atenuados o sin gratuitos

«Configurar en el host» indica que falta parametrizar ese proveedor en OpenCode. Si no ves modelos gratuitos, apaga el filtro de «Solo gratuitos» para ver toda la lista disponible.

El agente solicita salir del proyecto

Las tarjetas de solicitud muestran la ruta exacta involucrada para leer o escribir fuera del proyecto. Revisa la ruta con atención antes de conceder permiso.

Falta el botón de Cambios

Solo aparece si el terminal se encuentra dentro de un repositorio Git y el Gateway admite la función de Diff. Actualiza el Gateway si es necesario.

Requiere un Gateway más reciente

Las versiones anteriores conservan su utilidad como terminal. La colaboración entre agentes requiere Herdr 0.9.0 o superior en esa sesión.

El host está tras un proxy

Tu ordenador es el que conecta con los proveedores de IA. Si necesitas proxy para acceder a la red, configúralo en OpenCode dentro de esa máquina.

github · issues

¿Sigues con dudas?

Abre una incidencia en GitHub. Es el canal principal para recibir sugerencias y corregir incidencias.
USEFUL REPORT CHECKLIST
Incluye la versión de la app, la del Gateway y la acción realizada justo antes del problema.
Abrir una incidencia en GitHub ↗
PRIVACY GUARANTEE

Privacidad e informes seguros

El equipo de soporte nunca te solicitará tokens de acceso, transcripciones completas de terminal, código fuente confidencial ni códigos QR. Elimina cualquier dato sensible antes de adjuntar capturas o registros.
Leer la política de privacidad