Menü
Deutsch
ThemesSupportGitHub ↗
BENUTZERHANDBUCH · REFERENZMANUAL

Alles, was du brauchst, um deinen Rechner stets griffbereit zu haben.

Muqun verbindet dein Smartphone direkt mit deinem eigenen Rechner oder Server. Erfahre, wie du das Gateway installierst und einrichtest, Terminal-Workspaces bedienst, den autonomen OpenCode-Agenten steuerst, Themes installierst und Verbindungsfehler behebst.
Erste Schritte ↓Fehlerdiagnose ↓Issue eröffnen ↗

muqun-gateway

Installiere das Gateway und kopple dein Handy.

Muqun kommuniziert mit einem einzigen Programm auf deinem eigenen Rechner: dem Gateway. Du installierst es dort, startest es und koppelst das Smartphone einmalig. Es gibt kein Benutzerkonto und nichts von dir passiert unsere Server.
PRE-FLIGHT REQUIREMENTScheck before installing
  • macOS oder Linux auf einem Rechner, den du selbst verwaltest (Windows wird noch nicht unterstützt).
  • tmux oder Herdr 0.7.5 oder neuer muss bereits installiert sein — das Gateway steuert eines davon, statt es zu ersetzen.
  • Beide Geräte im selben privaten Netzwerk. Tailscale ist der empfohlene Weg; verwende Tailscale Serve, niemals Funnel.
  • Kein Konto, kein Abonnement und kein zwischengeschaltetes Relais von uns.

  1. Starte das Installationsskript auf deinem Rechner

    Es legt eine einzelne Binärdatei unter ~/.local/bin/muqun-gateway ab, konfiguriert sie und öffnet beim ersten Start den Kopplungsbildschirm. Für macOS und Linux; Windows wird derzeit noch nicht unterstützt.
    install
    curl -fsSL https://muqun.dev/gateway.sh | sh

  2. Starte es auf eine von zwei Arten

    Entweder startest du es selbst oder übergibst es dem Betriebssystem zur permanenten Überwachung. Beide Wege führen zu einem laufenden Gateway; der Unterschied liegt im Verhalten bei einem Neustart.
    OPTION A · DIRECT

    Selbst im Hintergrund starten

    Läuft im Hintergrund und bleibt auch nach dem Schließen des Terminals aktiv — bis der Rechner neu startet. muqun-gateway stop beendet es.
    direct
    muqun-gateway start
    OPTION B · SERVICE

    Als Systemdienst registrieren

    Registriert es beim Init-System deines Benutzers — als systemd-User-Unit unter Linux oder LaunchAgent unter macOS. Startet bei der Anmeldung und kehrt nach einem Absturz oder Neustart automatisch zurück. muqun-gateway service uninstall entfernt die Registrierung und behält Kopplungen bei.
    service
    muqun-gateway service install
    Wähle genau eine Option: Wenn der Dienst installiert ist, wird ein manuelles stop vom Supervisor sofort wieder rückgängig gemacht.

  3. Öffne das Verwaltungsfenster

    Ganz gleich, wie du es gestartet hast: Das ist der nächste Schritt. Der Manager ist ein Vollbild-Panel in deinem Terminal, das den QR-Code, aktive Prozesse und jedes aktuell berechtigte Gerät anzeigt. Der Installer öffnet ihn beim ersten Mal automatisch; mit diesem Befehl kehrst du dorthin zurück.
    pair
    muqun-gateway manage

  4. Scanne den QR-Code und tippe den Code ein

    Scanne den QR-Code in Muqun. Der Rechner zeigt daraufhin einen kurzen Code im Format XXXX-XXXX an; die Eingabe in der App schließt die Kopplung ab. Das Scannen allein koppelt das Handy noch nicht — der Code beweist, dass die Person mit dem Handy du selbst bist.
MANUAL ADDRESS PAIRING
Kannst du nicht scannen? Gib die Gateway-Adresse in der App manuell ein (der Manager gibt die veröffentlichte Adresse aus) und tippe denselben Bestätigungscode ein.
CODE VALIDITY & RETRIES
Der Code ist fünf Minuten gültig und verfällt nach acht Fehlversuchen. Drücke im Manager p, um einen frischen QR-Code und Bestätigungscode zu generieren.
EMPFOHLENES PRIVATES NETZWERK

Nutze Tailscale auf beiden Geräten.

Wir empfehlen dringend, dein Handy und den Gateway-Rechner in dasselbe Tailscale-Tailnet zu holen. Das erspart Portfreigaben im Router und hält das Gateway aus dem öffentlichen Internet heraus. Tailscale Serve kann eine private HTTPS-Adresse ergänzen; nutze Tailscale Funnel nicht für Muqun.

workspace · group.panel

Dein echtes Terminal.

Kein Screenshot und kein nachträgliches Transkript, sondern dein lebendiges Terminal. Das Gateway steuert tmux oder Herdr auf deinem Rechner und die App zeichnet das Geschehen direkt nach — die Arbeit auf deinem Schreibtisch nimmst du nahtlos in die Hand, und das Schließen der App ändert daran nichts.
WORKSPACE ARCHITECTURE

Workspaces, Gruppen und Terminals

Drei Ebenen, adressiert als Workspace · Gruppe.Panel. Ein Workspace ist dein Projektverzeichnis, eine Gruppe bündelt Terminals darin, und ein Terminal ist eine Shell. Muqun zeigt jeweils ein Terminal formatfüllend an, ohne den mobilen Bildschirm unleserlich zu spalten.

Navigation zwischen Ebenen

Wische über die Titelleiste oben, um den Workspace zu wechseln. Die Chips über dem Eingabefeld wechseln zwischen den Terminals der aktuellen Gruppe. Für alles Weitere öffnest du die Panel-Übersicht.

Aktive Prozesse und Panel-Verwaltung

Das Panel-Sheet listet jeden Workspace, jede Gruppe und jedes Terminal auf deinem Rechner auf. Durch langes Drücken öffnest du Aktionen wie das sichere Schließen eines Fensters.
Ein nvim-Pane mit einer geöffneten TypeScript-Datei, Auswahltasten für Claude Code, nvim und zsh sowie der Tastaturleiste über dem Eingabefeld.Ein nvim-Pane mit einer geöffneten TypeScript-Datei, Auswahltasten für Claude Code, nvim und zsh sowie der Tastaturleiste über dem Eingabefeld.
CONTROLS, EDITORS & DEVELOPER TOOLS

Die Terminal-Tastenleiste

Die Leiste über dem Eingabefeld liefert Tasten, die auf Smartphone-Tastaturen fehlen: Esc, Tab, ⌃C, Pfeiltasten sowie kontextabhängige Tasten (Shell-Befehle, ⇧TAB und ⌃O unter Claude Code, :w und gg unter nvim). In nvim führt im Insert-Modus stets Esc. Unter Einstellungen → Terminal abschaltbar.

Das Eingabefeld (Composer)

Nichtproportional, mehrzeilig, und die Eingabetaste erzeugt einen Zeilenumbruch — gesendet wird per Button, da versehentlich ausgeführte Befehle vermieden werden müssen.

Frühere Ausgaben nachladen

Ziehe vom oberen Rand des Terminals nach unten, um mehr Scrollback zu laden. Sobald du das Live-Ende verlässt, bringt dich ein „Neueste“-Pill sofort zurück. Neue Ausgaben reißen den Bildschirm niemals weg, während du liest.

Änderungen (Changes)

Git-Status für das Verzeichnis des aktuellen Fensters: Geänderte Dateien mit Zähler, Filter nach Alle, Staged oder Unstaged sowie vollständige Diffs.

Dateien (Files)

Alles, was die Sitzung geschrieben hat — Bilder, Code und Dokumente — durchsuchbar und direkt in der App lesbar.

Im Browser öffnen

Tippe den Port deines lokalen Entwicklungsservers ein und Muqun öffnet ihn über die bestehende sichere Verbindung, ohne Freigabe im Internet.

Schnellaktionen (Quick actions)

Gespeicherte Befehle, Prompts und Tastenkombinationen, sortiert nach deiner Nutzungshäufigkeit. Frei anpassbar.
●
Muqun beobachtet stets sicher: Das Öffnen einer Sitzung verändert deine Fensteranordnung nicht, und das Schließen der App stoppt keine Hintergrundprozesse.

opencode serve --service

Der OpenCode-Agent.

Ein Interface, das speziell für OpenCode entwickelt wurde, statt ein einfacher Terminal-Chatbot: Schneller Sitzungswechsel, Werkzeugaufrufe als visuelle Karten mit echten Unified Diffs und interaktive Freigaben.
LOKALE LAUFZEIT · KEIN BENUTZERKONTO

Dein Rechner spricht direkt mit deinen Modellanbietern.

Kein Login erforderlich. Muqun führt keine Konten und verlangt keine API-Schlüssel. Der Rechner selbst kommuniziert über OpenCode mit deinen KI-Anbietern. Das Gateway leitet keinerlei Anmeldedaten weiter.
VORAUSSETZUNGEN
  • OpenCode 2.0.1 oder neuer auf demselben Rechner wie das Gateway installiert.
  • Mindestens ein konfigurierter Modellanbieter in OpenCode (inklusive Filter für kostenlose Modelle).
  • Laufender OpenCode-Dienst (wird vom Gateway automatisch gestartet oder angebunden).
  • Ein aktuelles Gateway, das die Agenten-Oberfläche unterstützt.
AGENT CAPABILITIES & WORKFLOW

Sitzungen und Subagents

Jede Sitzung besitzt ihren eigenen Kontext. Wenn ein Task Subagents startet, werden diese eingerückt darunter dargestellt, sodass parallele Arbeitsabläufe übersichtlich bleiben.

Projects wechseln

Wechsle das Arbeitsverzeichnis des Agenten oder öffne ein neues. Bei der Auswahl eines Projekts wird die letzte Sitzung nahtlos fortgesetzt.

Modelle und Agentenrollen

Modellübersicht mit Kontextfenstergröße und Hinweisen auf kostenlose Modelle. Schneller Wechsel zwischen Rollen wie Build, Plan, Explore oder eigenen Agenten.

Slash-Befehle und Skills

Tippe / im Eingabefeld. Befehle wie /new, /models, /compact, /undo werden direkt beantwortet; andere laufen auf dem Host-Rechner.

Anhänge und @-Erwähnungen

Sende Fotos, Bilder oder Dateien. Bilder werden beim Senden neu encodiert, um EXIF-Metadaten zu entfernen. Mit @ referenzierst du Projektdateien direkt.

Berechtigungen und Rückfragen

Möchte der Agent Befehle ausführen oder Dateien verändern, entscheidest du per Tippen auf Erlauben, Immer erlauben oder Ablehnen — direkt auch auf dem Sperrbildschirm.

Hintergrundaufgaben & Warteschlange

Langwierige Tool-Ausführungen können in den Hintergrund verschoben werden. Neue Eingaben können sofort intervenieren oder für den nächsten Durchlauf eingereiht werden.

Kontext & automatische Verdichtung

Echtzeit-Einblick in Kontextfenster-Auslastung, Token-Verbrauch und geschätzte Kosten. Automatische Verlaufskomprimierung wird in der Timeline klar markiert.

Rückgängig machen (Undo)

/undo setzt das Projekt auf den Zustand vor deiner letzten Nachricht zurück; /redo hebt dies wieder auf. Bewusst als Befehl statt Button umgesetzt.
●
Werkzeugaufrufe erscheinen als Karten: Dateiänderungen zeigen ein direktes Unified Diff, genau wie in der Changes-Ansicht.

config.json

Das Gateway konfigurieren.

Die meisten Benutzer müssen die Konfiguration nie manuell öffnen. Sie existiert für Sonderfälle: ein anderer Port, ein Gateway, das Neustarts überleben soll, oder wenn OpenCode an einem unüblichen Pfad liegt.

Die Konfigurationsdatei

JSON SCHEMA
Sie ist im JSON-Format verfasst und wird beim Setup automatisch erzeugt. Bearbeite sie nur von Hand, wenn du einen der unten stehenden Schlüssel anpassen musst, und starte das Gateway danach neu — die Konfiguration wird nur beim Start eingelesen. Unter macOS liegt die Datei unter ~/Library/Application Support/muqun-gateway/. Daneben liegt pairing.json; gekoppelte Geräte, Push-Tokens und Logs befinden sich im Statusverzeichnis ~/.local/share/muqun-gateway/.
linux
~/.config/muqun-gateway/config.json
CONFIGURATION KEYS REFERENCE
label
Der Name, den die App für diesen Rechner anzeigt.
listen
Der Socket, an den gebunden wird (Host und Port). Standard ist 0.0.0.0:23847, oder Loopback, wenn die veröffentlichte Adresse eine Loopback-Adresse ist.
public_url
Die im Kopplungs-QR codierte Adresse — das, was das Handy tatsächlich anruft. Ändere sie vorzugsweise im Manager mit u statt von Hand.
transport_encryption
Transportverschlüsselung, standardmäßig auf required (erforderlich). Geräte behalten den Modus, in dem sie gekoppelt wurden; Änderungen wirken sich erst auf künftig gekoppelte Geräte aus.
sessions
Die Terminal-Backends, die dieses Gateway einbindet — tmux, Herdr oder beide gleichzeitig. Wird über muqun-gateway backend verwaltet.
autostart_backends
Welche davon mit dem Gateway gestartet werden sollen. Standardmäßig leer, um unbeabsichtigte Serverstarts zu vermeiden.
rich_agent_pushes
Standardmäßig aus. Wenn aktiv, fließen Agent-Fragen und Optionen direkt in den Benachrichtigungstext ein — was Terminaltext auf den Sperrbildschirm und über Apple/Google-Server leitet.
opencode.autostart
Standardmäßig aktiv: Das Gateway startet OpenCode selbst, wenn es keinen laufenden Dienst findet. Mit "opencode": { "autostart": false } abschaltbar.
opencode.binary
Welche OpenCode-Binärdatei gestartet werden soll. Falls weggelassen, wird OpenCode in ~/.opencode/bin oder im System-PATH gesucht.
PORTS & BINDUNG

Standard

Ein TCP-Port: 23847.

Ändern

muqun-gateway setup --port N ausführen und neu starten.

Bindung

127.0.0.1 wenn die publizierte Adresse Loopback ist, andernfalls 0.0.0.0.

Im Tailnet

Keine Portweiterleitung im Router erforderlich — daher unsere Empfehlung.
ZWEI WEGE ZUR PERMANENTEN AUSFÜHRUNG
DIRECT

Selbst im Hintergrund starten

Startet
Wenn du den Befehl ausführst.
Stoppt
muqun-gateway stop oder bei Rechner-Neustart.
Übersteht Neustart
Nein.
Rückgängig
Nichts nötig, einfach stop.
direct
muqun-gateway start
SERVICE

Als Systemdienst registrieren

Startet
Bei Anmeldung und nach Abstürzen automatisch.
Stoppt
Nur bei service uninstall.
Übersteht Neustart
Ja.
Rückgängig
service uninstall (Kopplungen bleiben erhalten).
service
muqun-gateway service install
Eine systemd-User-Unit unter Linux, ein LaunchAgent unter macOS. Niemals root, niemals außerhalb deines Home-Verzeichnisses.
WIE OPENCODE GESTARTET WIRD
  1. Das Gateway prüft, ob bereits ein intakter OpenCode-Dienst läuft, indem es die Adresse in ~/.local/state/opencode/service.json ausliest.
  2. Gefunden? Es dockt direkt daran an, und deine eigene opencode serve-Sitzung bleibt unberührt.
  3. Andernfalls startet es opencode serve --service selbst und überwacht den Prozess. Startet OpenCode auf einem neuen Port neu, wird dies automatisch erkannt.
●
Kein OpenCode auf dem Rechner? Dann dockt nichts an; nur die Agent-Ansicht zeigt Offline, das Terminal bleibt völlig unbeeinträchtigt.
config.json
"opencode": { "autostart": false }
DAS VERWALTUNGSFENSTER
Wird mit muqun-gateway manage geöffnet. Es listet aktive Prozesse und berechtigte Geräte auf und bietet folgende Tastenkürzel:
p
Kopplungs-QR-Code erneut anzeigen, um ein weiteres Gerät hinzuzufügen.
x
Zugriffsberechtigung für ein Gerät widerrufen.
u
Im QR codierte Adresse bearbeiten (a führt eine automatische Neu-Erkennung durch).
s / t
Gateway starten oder stoppen, ohne den Manager zu verlassen.
m / h
tmux- oder Herdr-Backend hinzufügen (f wählt Standard, d entfernt eines).
e
Verschlüsselungsmodus für künftige Kopplungen ändern.
q
Manager schließen. Beendet deine Terminalsitzungen niemals.

Ältere Gateways bleiben kompatibel

Die App fragt das Gateway aktiv nach seinen Fähigkeiten, statt diese anhand der Versionsnummer zu erraten, und blendet nicht unterstützte Funktionen nahtlos aus. Ein älteres Gateway bleibt also ein voll funktionsfähiges Terminal. Lediglich die Agent-Kollaboration setzt Herdr 0.9.0 oder neuer in der jeweiligen Sitzung voraus (tmux unterstützt dies nicht).

Aktualisierung

Führe einfach denselben Installationsbefehl erneut aus. Er ersetzt die Binärdatei an Ort und Stelle, behält deine Server-Identität, Adresse, Konfiguration und alle Kopplungen bei. Falls du den Dienst installiert hattest, führe danach noch einmal service install aus.

Protokolle

DIAGNOSTICS
Im Direktmodus und unter macOS LaunchAgent schreibt das Gateway nach ~/.local/share/muqun-gateway/gateway.log. Unter Linux mit systemd fließen die Logs ins Journal. Für mehr Details setze vor dem Start MUQUN_LOG=debug (oder RUST_LOG=debug); Standard ist info.
linux · Dienstmodus
journalctl --user -u dev.osuki.muqun-gateway

muqun.dev/themes

Themes.

Themes passen das Aussehen der App und des Terminals synchron an. Jedes Theme-Pack enthält eine helle und eine dunkle Variante. 24 Packs werden mitgeliefert; viele weitere gibt es im Katalog.

24 mitgelieferte Packs

Unter Einstellungen → Darstellung → Theme, inklusive Catppuccin, Gruvbox, Kanagawa, Rosé Pine, Tokyo Night und Everforest.

Katalog durchstöbern

Online-Katalog auf muqun.dev durchsuchen. Der Download startet erst beim Antippen, die Paketgröße wird vorab transparent angezeigt.

Aufbau eines Themes

Eine .muqun-theme-Datei ist ein Zip mit einer theme.json und einem assets-Ordner für Grafiken. .muqun-theme.json ist die bildfreie Variante.

Anpassungsumfang

17 Schnittstellenfarben je Modus, Terminalfarben für Cursor, Links und alle 16 ANSI-Slots, Grafiken für 11 Oberflächen und 3 benutzerdefinierte Icons.

Dateigrößenlimits

Manifest bis 256 KiB, bis zu 32 Bilder mit je max. 8 MiB, maximal 25 MiB für das gesamte Paket.

Aus Datei installieren

Öffne eine .muqun-theme-Datei über Dateien, AirDrop oder das Teilen-Menü, oder nutze „Datei importieren“ in der Theme-Auswahl.

Per Weblink installieren

Theme-URL oder GitHub-Repository angeben. Vor dem Download zeigt eine Prüfkarte die Host-Domain der Bilddateien an.

Direkt aus dem Terminal installieren

Tippe auf einen .muqun-theme-Pfad in der Terminalausgabe, um eine sofortige Vorschau anzuzeigen.

Vorschau vor dem Anwenden

Das Theme wird geladen und temporär auf die gesamte App angewendet. Dein bisheriges Theme bleibt unverändert, bis du auf „Theme anwenden“ tippst.

Hintergrund-Deckkraft

Zwei Regler für eigene Themes: Deckkraft des UI-Hintergrunds und des Terminal-Hintergrunds für subtile Durchschein-Effekte.

Themes selbst erstellen

Themes werden als Dateien verfasst. Mit dem mitgelieferten Agent-Skill beschreibst du einfach das gewünschte Design und erhältst ein fertiges Paket.

Im Katalog veröffentlichen

Der Katalog wird auf GitHub per Pull Request gepflegt. Nach dem Merge erscheint dein Theme automatisch auf muqun.dev.

Themes löschen

Einfach in der Themenliste zur Seite wischen. Unter Einstellungen → Speicher können ungenutzte Themes mit einem Klick aufgeräumt werden.
Theme-Katalog durchstöbern

when it does not connect

Fehlerbehebung.

Fast alle Verbindungsprobleme haben eine von vier Ursachen: Das Gateway läuft nicht, die Adresse ist nicht erreichbar, die Kopplung fehlt, oder OpenCode ist offline.
SCHNELLPRÜFUNGEN

Einen Rechner koppeln

Gateway auf dem Rechner installieren (unterstützt tmux oder Herdr), Manager öffnen, QR in Muqun scannen und Bestätigungscode eingeben.

Verbindung prüfen

Prüfen, ob tmux oder Herdr 0.7.5+ und das aktuelle Gateway laufen. Sicherstellen, dass beide Geräte dieselbe private Adresse erreichen.

Gerät entfernen

Server auf dem Muqun-Startbildschirm löschen, um den Zugriff zu entziehen. Alternativ im Gateway-Manager auf dem Rechner widerrufen.

Benachrichtigungen erneuern

Mitteilungen in den Systemeinstellungen und in Muqun aktivieren. Gekoppelten Server erneut öffnen, um das Token zu aktualisieren.
DIAGNOSTIC SOLUTIONS

Kopplung schlägt fehl

„Could not reach the gateway“ bedeutet, dass die Adresse im QR-Code vom Handy aus nicht erreichbar ist. Prüfe muqun-gateway status und stelle sicher, dass beide Geräte im selben Wi-Fi oder Tailnet sind. Ein an 127.0.0.1 gebundenes Gateway ist von außen unerreichbar; passe dies mit u im Manager an.

Code abgelehnt oder abgelaufen

Der 8-stellige Code ist 5 Minuten gültig und verfällt nach 8 Fehlversuchen. Drücke p im Manager für einen neuen Code. Die Zeichen 0, 1, I, L, O kommen nicht vor.

Bedeutung des Statuspunkts

Ein ausgefüllter Punkt bedeutet eine bestätigte Rückmeldung (Grün: ONLINE, Grau: OFFLINE). Ein hohler Kreis mit NOT CONNECTED bedeutet, dass noch keine Prüfung stattfand — einfaches Antippen verbindet.

Aufforderung zur erneuten Kopplung

Das Gerätetoken auf dem Gateway existiert nicht mehr. Koppel den Server einfach erneut; deine übrigen Einstellungen auf dem Handy bleiben erhalten.

OpenCode wird nicht gefunden

Wenn die Agent-Ansicht offline meldet, starte opencode serve --service auf dem Rechner und tippe auf Erneut prüfen. Falls es bereits läuft, gib in config.json den absoluten Pfad unter opencode.binary an.

Modelle ausgegraut oder keine kostenlosen

„Auf dem Host einrichten“ bedeutet, dass der Provider in OpenCode noch nicht konfiguriert ist. Wenn keine kostenlosen Modelle erscheinen, deaktiviere den „Nur kostenlos“-Filter. Muqun verlangt keine eigenen Gebühren.

Agent möchte das Projekt verlassen

Beim Lesen oder Schreiben außerhalb des Projekts erscheint eine Sicherheitsabfrage mit Pfadangabe. Prüfe den Pfad vor dem Erlauben.

Changes-Button fehlt

Erscheint nur, wenn das Terminal in einem Git-Verzeichnis steht und das Gateway Diff-fähig ist. Installiere das neueste Gateway-Update.

Neueres Gateway erforderlich

Ältere Gateways behalten ihre Terminalfunktion. Für Agent-Kollaboration wird Herdr 0.9.0+ benötigt; die App weist auf das nötige Upgrade hin.

Rechner hinter einem Proxy

Dein Rechner kommuniziert mit den Modellanbietern. Falls ein Proxy für den Internetzugang nötig ist, konfiguriere diesen direkt in OpenCode auf dem Rechner.

github · issues

Noch Fragen?

Eröffne ein Issue auf GitHub. Jedes Feedback fließt direkt in die Weiterentwicklung ein.
USEFUL REPORT CHECKLIST
Gib die App-Version, die Gateway-Version und die genauen Schritte vor dem Problem an.
Issue auf GitHub eröffnen ↗
PRIVACY GUARANTEE

Datenschutz und sicheres Melden

Der Support benötigt niemals Zugangstokens, vollständige Terminalausgaben, Quellcode oder Kopplungs-QRs. Entferne sensible Daten vor dem Hochladen von Screenshots oder Logs.
Datenschutzerklärung lesen