Espaços, grupos e terminais
Três níveis: espaço · grupo.painel. Um espaço é a tua pasta de trabalho, um grupo reúne terminais e um terminal é uma shell. O Muqun exibe um terminal de cada vez em ecrã inteiro para assegurar máxima legibilidade.
GUIA DO UTILIZADOR · MANUAL DE REFERÊNCIA
Tudo o que precisas para manter a tua máquina sempre à mão.
O Muqun liga o teu telemóvel diretamente ao teu próprio computador ou servidor. Descobre como instalar e configurar o Gateway, navegar por terminais, guiar o agente autónomo OpenCode, instalar temas e resolver falhas de ligação.
muqun-gateway
Instala o Gateway e emparelha o teu telemóvel.
O Muqun comunica com um único programa no teu próprio computador: o Gateway. Instala-o lá, inicia-o e emparelha o telemóvel uma única vez. Não é preciso criar conta e nada passa pelos nossos servidores.
PRE-FLIGHT REQUIREMENTScheck before installing
- macOS ou Linux num computador teu (Windows ainda não é suportado).
- tmux ou Herdr 0.7.5 ou mais recente instalado (o Gateway controla-os, não os substitui).
- Ambos os dispositivos na mesma rede privada. Recomendamos o Tailscale (usa o Tailscale Serve, nunca Funnel).
- Sem contas, sem assinaturas e sem intermediários nossos.
Executa o instalador no teu computador
Coloca um binário único em ~/.local/bin/muqun-gateway, configura-o e abre o ecrã de emparelhamento na primeira execução. Suporta macOS e Linux (Windows ainda não é suportado).install curl -fsSL https://muqun.dev/gateway.sh | shInicia-o de uma de duas formas
Podes iniciá-lo manualmente ou entregá-lo ao sistema para o manter sempre ativo. Ambos deixam o Gateway operacional; a diferença é o comportamento após reiniciar a máquina.Escolhe apenas um: com o serviço instalado, pará-lo com stop será desfeito pelo supervisor.Abre o gestor de emparelhamento
Independentemente do modo de início, este é o passo seguinte. O gestor é um painel em ecrã inteiro no terminal que mostra o código QR, processos e dispositivos autorizados.pair muqun-gateway manageLê o código QR e digita o código
Lê o código QR com o Muqun. O computador apresentará um código curto no formato XXXX-XXXX; introduzi-lo na aplicação conclui o processo. Ler o QR não basta por si só: o código confirma a tua presença física.
MANUAL ADDRESS PAIRING
Não consegues ler o QR? Escreve o endereço do Gateway na aplicação à mão (indicado no gestor) e introduz o mesmo código curto.
CODE VALIDITY & RETRIES
O código é válido durante 5 minutos e expira após 8 tentativas erradas. Prime p no gestor para gerar um novo QR e código.
REDE PRIVADA RECOMENDADA
Usa o Tailscale nos dois dispositivos.
Recomendamos vivamente colocar o telemóvel e o computador do Gateway na mesma tailnet do Tailscale. Evita o reencaminhamento de portas no router e mantém o Gateway fora da Internet pública. O Tailscale Serve permite adicionar um endereço HTTPS privado (não uses o Tailscale Funnel para o Muqun).
workspace · group.panel
O teu terminal real.
É o teu terminal verdadeiro, e não uma transcrição estática. O Gateway gere o tmux ou Herdr no teu computador e a app desenha o conteúdo em direto — o trabalho que deixaste na secretária continua na tua mão.
WORKSPACE ARCHITECTURE
Alternar entre vistas
Desliza a barra superior para mudar de espaço de trabalho. Os botões acima do campo de escrita alternam entre os terminais do mesmo grupo.
Processos e painel lateral
O painel lateral lista todos os espaços, grupos e terminais na máquina. Pressionar demoradamente permite fechar janelas com segurança.
CONTROLS, EDITORS & DEVELOPER TOOLS
Barra de teclas do terminal
A faixa acima da escrita disponibiliza teclas essenciais em falta nos telemóveis: Esc, Tab, ⌃C, setas e teclas contextuais (atalhos de shell, ⇧TAB e ⌃O no Claude Code, :w e gg no nvim). Pode ser desativada em Definições → Terminal.
Compositor de texto (Composer)
Fonte monoespaçada, suporte para várias linhas e a tecla Enter insere quebras de linha: o envio é acionado por botão para evitar execuções acidentais.
Histórico de visualização
Puxa para baixo no topo do terminal para carregar o histórico anterior. Se saíres do fim da emissão ao vivo, surge um botão para voltar instantaneamente.
Alterações Git (Changes)
Estado do Git para a pasta do painel: contagem de ficheiros modificados, filtros de Staged/Unstaged e diffs completos.
Ficheiros (Files)
Explora ficheiros gerados na sessão (imagens, código e documentos) sem precisares de sair da aplicação.
Abrir no navegador
Digita a porta do teu servidor de desenvolvimento e o Muqun abre-o através do túnel existente sem o expor à Internet.
Ações rápidas
Comandos guardados, prompts frequentes e combinações de teclas, ordenados por relevância e editáveis a qualquer momento.
●
O Muqun é sempre um observador: abrir uma sessão não mexe no layout e fechar a app não encerra nenhum processo em segundo plano.
opencode serve --service
O agente OpenCode.
Uma interface criada especificamente para o OpenCode em vez de um simples chatbot em terminal: alterna entre sessões, visualiza diffs em cartões e responde a pedidos com um toque.
EXECUÇÃO LOCAL · SEM CONTA
O teu computador comunica diretamente com os teus modelos.
Sem início de sessão. O Muqun não gere contas nem pede chaves de API. Quem conversa com os fornecedores é o OpenCode no teu computador. O Gateway não armazena credenciais.
REQUISITOS
- OpenCode 2.0.1 ou superior no mesmo computador que o Gateway.
- Pelo menos um fornecedor configurado no OpenCode (com filtro para modelos gratuitos).
- Serviço OpenCode ativo (o Gateway inicia ou liga-se automaticamente).
- Gateway recente compatível com o ecrã de agente.
AGENT CAPABILITIES & WORKFLOW
Sessões e subagentes
Cada sessão tem o seu contexto independente. Quando uma tarefa cria subagentes, estes aparecem indentados sob a sessão principal para fácil leitura.
Projetos
Muda a pasta de trabalho do agente com facilidade. Escolher um projeto reabre a sua última sessão ativa de imediato.
Modelos e agentes
Consulta os modelos disponíveis nos teus fornecedores com indicação da janela de contexto e selo Free. Alterna entre perfis Build, Plan, Explore ou agentes personalizados.
Comandos / e habilidades
Digita / no campo de escrita. Comandos como /new, /models ou /undo são resolvidos diretamente pela app; os restantes correm no anfitrião.
Anexos e menções com @
Envia fotografias ou ficheiros. As imagens são recodificadas para eliminar metadados EXIF. Usa @ para referenciar ficheiros do projeto.
Permissões e perguntas
Quando o agente precisa de executar comandos ou alterar ficheiros, surge um cartão com opções: Permitir, Permitir sempre ou Negar (também a partir do ecrã de bloqueio).
Tarefas em segundo plano e fila
Separa ferramentas longas para segundo plano. As tuas novas mensagens podem intervir no momento ou aguardar na fila.
Contexto e compactação
Acompanha a ocupação da janela de contexto, os tokens gastos e o custo estimado. A compactação automática do histórico é indicada na cronologia.
Anular (Undo)
/undo repõe o projeto no estado anterior à tua última mensagem; /redo cancela o recuo. Pensado como comando para evitar toques acidentais.
●
As chamadas a ferramentas surgem como cartões: as edições mostram o seu diff unificado, exatamente como na vista Alterações.
config.json
Configurar o Gateway.
A maioria dos utilizadores nunca precisa de editar esta configuração. Está disponível para casos específicos: mudar de porta, sobreviver a reinícios ou definir caminhos invulgares para o OpenCode.
O ficheiro de configuração
JSON SCHEMAEm formato JSON, é criado automaticamente durante a instalação. Edita-o apenas se precisares de alterar as chaves abaixo e reinicia o Gateway depois. No macOS fica em ~/Library/Application Support/muqun-gateway/. Os dispositivos emparelhados e os registos ficam em ~/.local/share/muqun-gateway/.
~/.config/muqun-gateway/config.jsonCONFIGURATION KEYS REFERENCE
labelO nome que a aplicação apresenta para este computador.
listenO socket a que se associa (anfitrião e porta). Padrão 0.0.0.0:23847 (ou 127.0.0.1 se for endereço local).
public_urlO endereço codificado no QR de emparelhamento. É preferível alterá-lo com a tecla u no gestor.
transport_encryptionCifragem de transporte, por defeito required. Afeta os próximos dispositivos a emparelhar, mantendo os atuais.
sessionsMotores de terminal suportados por este Gateway (tmux, Herdr ou ambos). Gerido via muqun-gateway backend.
autostart_backendsQuais destes iniciam com o Gateway. Vazio por defeito para evitar arranques automáticos imprevistos.
rich_agent_pushesDesativado por defeito. Se ativo, as perguntas do agente vão no texto da notificação, expondo o terminal no ecrã de bloqueio.
opencode.autostartAtivado por defeito: o Gateway inicia o OpenCode caso não encontre nenhum a correr. Podes desativar com "opencode": { "autostart": false }.
opencode.binaryCaminho do binário do OpenCode a executar. Se omitido, procura em ~/.opencode/bin ou no PATH.
PORTAS E ESCUTA
Padrão
Uma única porta TCP: 23847.
Alterar
Executa muqun-gateway setup --port N e reinicia.
Associação
127.0.0.1 se o endereço for loopback, 0.0.0.0 nos restantes casos.
Numa tailnet
Não requer abrir portas no router, daí a nossa recomendação.
DUAS FORMAS DE MANTER EM EXECUÇÃO
DIRECT
Início manual direto
Inicia
Quando executas o comando.
Para
muqun-gateway stop ou quando o sistema reinicia.
Sobrevive a reinício
Não.
Reversão
Basta executar stop.
muqun-gateway startSERVICE
Como serviço do sistema
Inicia
Ao iniciar sessão e recupera de falhas.
Para
Apenas através de service uninstall.
Sobrevive a reinício
Sim.
Reversão
service uninstall (emparelhamentos guardados).
muqun-gateway service installUnidade de utilizador systemd no Linux, LaunchAgent no macOS. Nunca utiliza privilégios de root nem sai da tua pasta de utilizador.
COMO O OPENCODE É INICIADO
- Procura um serviço OpenCode saudável em execução lendo ~/.local/state/opencode/service.json.
- Se encontrar, liga-se diretamente a ele e mantém as sessões existentes ativas.
- Caso contrário, inicia opencode serve --service e monitoriza o processo adaptando-se a novas portas.
●
Sem OpenCode no computador? Nada se liga e apenas a vista do agente mostra o estado offline; o terminal não é afetado.
"opencode": { "autostart": false }GESTOR DE EMPARELHAMENTO
Aberto com muqun-gateway manage. Mostra processos e dispositivos autorizados com os seguintes atalhos:
p
Apresentar novamente o QR code para associar outro telemóvel.
x
Revogar o acesso de um dispositivo selecionado.
u
Editar o endereço do QR (a para voltar a detetar automaticamente).
s / t
Iniciar ou parar o Gateway sem sair do gestor.
m / h
Adicionar backend tmux ou Herdr (f seleciona padrão, d remove).
e
Alterar a política de cifragem de transporte para futuros emparelhamentos.
q
Fechar o gestor (nunca interrompe as tuas sessões de terminal).
Compatibilidade com versões antigas
A aplicação pergunta ao Gateway que funcionalidades suporta em vez de adivinhar pela versão, ocultando suavemente o que não existir. Gateways mais antigos continuam a ser excelentes terminais. Apenas a colaboração de agentes exige Herdr 0.9.0 ou mais recente na sessão.
Atualização
Basta executar o mesmo comando de instalação original. Substitui o binário sem mexer nas tuas chaves, configuração e dispositivos emparelhados. Se tinhas o serviço instalado, volta a executar service install.
Registos e diagnósticos
DIAGNOSTICSEm modo direto e com LaunchAgent no macOS, os registos são gravados em ~/.local/share/muqun-gateway/gateway.log. No Linux com systemd, consulta o journalctl. Para mais detalhe usa MUQUN_LOG=debug (ou RUST_LOG=debug).
journalctl --user -u dev.osuki.muqun-gatewaymuqun.dev/themes
Temas.
Um tema transforma em simultâneo o aspeto da app e as cores do terminal. Cada pacote inclui uma versão clara e uma escura. Inclui 24 pacotes e acesso ao catálogo da comunidade.
24 pacotes incluídos
Em Definições → Aspeto → Tema encontrarás opções consagradas como Catppuccin, Gruvbox, Kanagawa, Rosé Pine, Tokyo Night e Everforest.
Explorar o catálogo
Consulta o catálogo oficial em muqun.dev. As transferências só começam quando abres um item, com o tamanho do ficheiro indicado previamente.
Estrutura de um tema
Um ficheiro .muqun-theme é um zip com theme.json e uma pasta assets de imagens. .muqun-theme.json é a variante sem imagens.
Personalizações suportadas
17 cores de interface por modo, cores do terminal (cursor, links, 16 slots ANSI), ilustrações para 11 ecrãs e ícones personalizados.
Limites de tamanho
Manifesto até 256 KiB, até 32 imagens com máximo de 8 MiB cada e 25 MiB para o pacote final.
Instalar a partir de ficheiro
Abre um .muqun-theme a partir dos Ficheiros, AirDrop ou partilha, ou usa «Importar ficheiro» nas definições de tema.
Instalar a partir de ligação
Insere um URL público ou repositório do GitHub. O domínio de origem das imagens é validado antes da transferência.
Instalar a partir do terminal
Toca num caminho .muqun-theme na saída do terminal para abrir um cartão de pré-visualização imediata.
Pré-visualização antes de aplicar
O tema é aplicado temporariamente a toda a aplicação para que possas navegar à vontade antes de tocar em «Aplicar tema».
Opacidade do fundo
Ajusta de forma independente a opacidade do fundo da interface e do terminal para criar efeitos de transparência agradáveis.
Cria o teu próprio tema
Os temas são ficheiros de configuração. Podes pedir ao teu agente através da habilidade incluída que crie o estilo que pretendes.
Publicar no catálogo
O catálogo é um repositório público no GitHub. Envia um Pull Request para apareceres em muqun.dev em poucos minutos.
Remover temas
Desliza sobre um tema na lista para o remover. Em Definições → Armazenamento podes limpar todos os temas não utilizados.
when it does not connect
Resolução de problemas.
A grande maioria das falhas de ligação deve-se a uma de quatro razões: o Gateway não está a correr, o endereço está inacessível, o emparelhamento foi perdido ou o OpenCode está em baixo.
VERIFICAÇÕES RÁPIDAS
Emparelhar computador
Instala o Gateway (compatível com tmux ou Herdr), abre o gestor, lê o QR no Muqun e introduz o código exibido no computador.
Corrigir ligação
Verifica se o tmux ou Herdr 0.7.5+ e o Gateway estão ativos e se ambos os aparelhos se alcançam no mesmo endereço privado.
Remover dispositivo
Apaga o servidor no ecrã inicial do Muqun para retirar a autorização. Também o podes fazer no gestor do Gateway.
Restabelecer notificações
Ativa as permissões de notificação no telemóvel e no Muqun. Abre novamente o servidor para registar o novo token.
DIAGNOSTIC SOLUTIONS
Não consegue emparelhar
O erro «Could not reach the gateway» significa que o telemóvel não alcança o IP do QR. Verifica o comando muqun-gateway status e certifica-te de estar no mesmo Wi-Fi ou na mesma tailnet do Tailscale. Se o Gateway estiver associado a 127.0.0.1 não receberá ligações externas; corrige com u no gestor.
Código recusado ou expirado
O código de 8 caracteres expira ao fim de 5 minutos ou 8 tentativas erradas. Prime p no gestor para gerar um novo código. Os caracteres dúbios (0, 1, I, L, O) foram omitidos.
Significado da luz de estado
Ponto preenchido significa resposta confirmada (verde: ONLINE, cinzento: OFFLINE). Círculo vazio com NOT CONNECTED indica que ainda não foi efetuado o teste; basta tocar para abrir.
Pede novo emparelhamento
O token deste aparelho foi revogado ou perdido numa limpeza do Gateway. Basta ler o código QR novamente.
OpenCode não encontrado
Se o ecrã do agente indicar OpenCode service offline, corre opencode serve --service no computador e toca em Tentar de novo. Se já estiver a correr, especifica o caminho absoluto em config.json sob opencode.binary.
Modelos a cinzento ou sem opções grátis
«Configurar no anfitrião» indica que o fornecedor não está configurado no OpenCode. Se não vires modelos grátis, desliga o filtro «Apenas grátis». O Muqun não cobra nada pelo uso dos modelos.
O agente quer sair do projeto
Os pedidos de leitura ou escrita fora do projeto exibem o caminho exato. Avalia o caminho antes de conceder permissão.
Falta o botão Alterações
Apenas aparece se o terminal estiver dentro de um repositório Git e o Gateway suportar diffs. Atualiza o Gateway se necessário.
Requer um Gateway mais recente
Versões antigas mantêm as funções de terminal. A colaboração de agentes requer Herdr 0.9.0 ou mais recente na sessão.
O computador está atrás de proxy
É o teu computador que comunica com os fornecedores de IA. Se precisares de proxy, configura-o no OpenCode na própria máquina.
github · issues
Ainda com dúvidas?
Abre um problema no GitHub. É o canal principal para recolha de sugestões e resolução de falhas.
USEFUL REPORT CHECKLIST
Indica a versão da app, a versão do Gateway e a ação efetuada imediatamente antes do problema.
PRIVACY GUARANTEE
Privacidade e segurança nos relatórios
O suporte nunca te pedirá tokens de acesso, saídas completas de terminal, código confidencial ou códigos QR. Remove qualquer dado sensível antes de anexar imagens ou registos.