porterminal

Übergib einem Agenten einen Computer, volle Kontrolle, und schau zu.
Ein Befehl, eine URL. (Außerdem ein elegantes Terminal für dein eigenes Telefon.)

1. uvx ptn
2. Übergib die URL einem KI-Agenten oder scanne selbst den QR-Code
3. Schau zu, wie es in jedem Browser funktioniert, und übernimm jederzeit

[!WARNING] Diese vollständige URL bedeutet vollen Zugriff auf diesen Computer. Sie enthält einen zufälligen Zugangscode pro Start, und jeder (oder jeder KI-Agent), dem du sie gibst, erhält eine echte Shell auf deinem Rechner. Behandle die URL und den QR-Code wie ein Geheimnis, teile sie nur mit Personen und Agenten, denen du vertraust, und lies Sicherheit, bevor du Porterminal auf etwas Wichtiges richtest.

Warum

Ich brauche etwas, mit dem man gefährlich einfach aus der Ferne auf einen Computer zugreifen kann.

ngrok erfordert eine Registrierung und die kostenlose Stufe ist schlecht. Cloudflare Tunnel ist eine hervorragende Infrastruktur, aber für sich genommen liefert es nur einen Tunnel, kein handyfreundliches Terminal. Tailscale ist großartig, wenn man beide Enden besitzt, aber es bedeutet trotzdem, Geräte einem privaten Netzwerk beizutreten. Termius erfordert eine komplizierte Einrichtung: Portweiterleitung, Firewall-Regeln, Schlüsselverwaltung ...

Also habe ich etwas Einfacheres gebaut: einen Befehl ausführen, einen QR-Code scannen, loslegen.

Dann machte es Klick: Derselbe Trick (ein Befehl, eine URL) ist der einfachste Weg, einem KI-Agenten ein echtes Terminal auf jedem Computer zu geben. Kein MCP-Server zum Schreiben, keine SSH-Schlüssel, kein Docker, keine Konfiguration. Führe uvx ptn aus, übergib die URL, und der Agent führt Befehle aus, liest den Bildschirm und beantwortet Eingabeaufforderungen auf diesem Rechner. Und weil es ein Web-Terminal ist, kannst du dieselbe Sitzung in jedem Browser öffnen, um live zuzusehen, oder die Tastatur übernehmen.

Funktionen

• Übergib einem Agenten einen Computer, volle Kontrolle, und schau zu - Gib einem KI-Agenten die URL, und er erhält ein echtes Terminal auf dem Rechner über MCP oder einfaches REST. Öffne dieselbe Sitzung in jedem Browser, um live zuzusehen, und übernimm die Tastatur, wann immer du willst. Keine Schlüssel, kein Docker. Der Agent lernt, wie es geht, über <url>/llms.txt und <url>/.well-known/mcp.json. Siehe Agentenzugriff.
• Ein Befehl, sofortiger Zugriff - uvx ptn und du (oder ein Agent) erhältst ein echtes Terminal auf diesem Rechner. Kein SSH, keine Portweiterleitung, keine Konfigurationsdateien. Cloudflare-Tunnel + QR-Code.
• Wirklich auf Mobilgeräten nutzbar - Touch-optimiert mit Momentum-Scrolling, Pinch-to-Zoom, Wischgesten und Modifikatortasten (Ctrl, Alt).
• Vollständige Terminal-Apps - vim, htop, less, tmux funktionieren alle korrekt mit ordnungsgemäßer Alt-Screen-Pufferbehandlung.
• Persistente Multi-Tab-Sitzungen - Sitzungen überleben Verbindungsabbrüche. Schließe den Browser, wechsle das Netzwerk, verbinde dich von einem anderen Gerät neu, und deine Shell und laufenden Prozesse sind immer noch da. Du und ein Agent könnt euch eine Sitzung teilen: zusehen, wie sie arbeitet, oder übernehmen.
• Plattformübergreifend - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish, Nushell und jede Shell über $SHELL). Erkennt deine Shells automatisch.
• Standardmäßig schwer zu erraten - Jeder Start fügt einen unabhängigen 128-Bit-Zufallszugriffspfad hinzu. Der nackte Tunnel-Hostname und jeder falsche Pfad geben 404 zurück. Die URL ist auf dem Bildschirm verborgen, aber der QR-Code enthält die vollständige Anmeldeinformation. Halte also beides privat. Drücke c, um Agentenanweisungen und URL zu kopieren, oder u, um nur die URL zu kopieren.

Installation

Einzeilige Installation (uv + ptn):

Erfordert Python 3.12+ und cloudflared (wird automatisch installiert, falls fehlend).

Verwendung

ptn                    # Im aktuellen Verzeichnis starten
ptn ~/projects/myapp   # In einem bestimmten Ordner starten

Während der Ausführung: Bei aktivem Tunnel ist die Verbindungs-URL aus Datenschutzgründen auf dem Bildschirm verborgen. Drücke c, um Agentenanweisungen und URL zu kopieren, einschließlich /mcp, /api/agent/run und /llms.txt; drücke u, um nur die URL zu kopieren; oder scanne den QR-Code, um dich zu verbinden. Ctrl+C stoppt den Server.

Agentenzugriff (MCP + REST)

Dieselbe URL funktioniert auch für KI-Agenten. MCP-fähige Clients können <url>/mcp (Streamable HTTP) für native typisierte Tools verwenden. Agenten, die keinen MCP-Server registrieren können, können den REST-Fallback unter <url>/api/agent/run mit gewöhnlichen HTTP-Anfragen verwenden. Beide Pfade erstellen eine persistente Agenten-Shell, die als 🤖-Tab angezeigt wird und die du von deinem Telefon aus beobachten und übernehmen kannst.

Übergib dem Agenten die vollständige generierte URL, einschließlich ihres Zugangscodes. MCP-Clients können den Server automatisch über <url>/.well-known/mcp.json (den MCP-server.json-Deskriptor) entdecken, und es gibt eine für Menschen/Agenten lesbare <url>/llms.txt mit Nutzungshinweisen. Die Basisseite enthält außerdem für Barrierefreiheit sichtbare Hinweise für browsersteuernde Agenten, während die menschliche Benutzeroberfläche kompakt bleibt. Beispiel-Client-Konfiguration:

{
  "mcpServers": {
    "porterminal": { "url": "https://<your-tunnel>.trycloudflare.com/<access-code>/mcp" }
  }
}

MCP-Tools: run_command (saubere Ausgabe + Exit-Code), read_screen, send_keys, send_signal (Ctrl-C / EOF).

REST-Fallback:

curl -s -X POST https://<your-tunnel>.trycloudflare.com/<access-code>/api/agent/run \
  -H "content-type: application/json" \
  -d '{"command":"echo hello","timeout":30}'

Die Antwort enthält eine session_id; verwende sie erneut mit <url>/api/agent/screen, <url>/api/agent/keys, <url>/api/agent/signal und DELETE <url>/api/agent/session.

Wenn du Porterminal auf deinem Telefon öffnest, kopiert die Kopier-Schaltfläche oben rechts denselben agentenbereiten Freigabetext. Nur-Browser-Agenten erhalten außerdem einen Fallback auf der Basisseite: einen DOM-lesbaren Terminalbildschirm-Spiegel und ein klar beschriftetes Terminal-Eingabefeld.

Sicherheit: <url> bedeutet die vollständige generierte URL, einschließlich ihres zufälligen Zugangscodes. Der nackte Tunnel-Hostname legt nichts offen, aber jeder (oder jeder Agent) mit der vollständigen URL erhält vollen, nicht erhöhten Shell-Zugriff. Siehe docs/agent-access.md.

Mobile Gesten

Modifikatortasten (Ctrl, Alt, Shift): Einmal tippen für klebrig (ein Tastendruck), doppeltippen zum Sperren.

Komponiermodus (▤-Schaltfläche): Schaltet ein Texteingabefeld um, in dem du tippen oder diktieren kannst, deinen Text mit vollständigen mobilen Bearbeitungsfunktionen bearbeiten (Autokorrektur, Vorschläge, Cursorpositionierung) und dann an das Terminal senden kannst. Nützlich für längere Befehle oder Spracheingabe.

Konfiguration

Führe ptn --init aus, um eine Startkonfiguration zu erstellen. Sie erkennt Projekt-Skripte automatisch aus package.json, pyproject.toml oder Makefile und fügt sie als Schaltflächen hinzu:

ptn -i
# Erstellt: .ptn/ptn.yaml
# 3 Projekt-Skript(e) erkannt: build, dev, test

Oder erstelle ptn.yaml manuell:

# Terminal-Einstellungen
terminal:
  default_shell: nu              # Standard-Shell-ID
  shells:                        # Benutzerdefinierte Shell-Definitionen
    - id: nu
      name: Nushell
      command: nu
      args: []

# Benutzerdefinierte Schaltflächen (erscheinen in der Symbolleiste)
# row: 1 = Standardzeile, 2+ = zusätzliche Zeilen
buttons:
  - label: "claude"
    send:
      - "claude"
      - 100        # Verzögerung in ms
      - "\r"
  - label: "build"
    send: "npm run build\r"
    row: 2         # Zweite Schaltflächenzeile

# Update-Checker-Einstellungen
update:
  notify_on_startup: true   # Update-Benachrichtigung anzeigen
  check_interval: 86400     # Sekunden zwischen Prüfungen (Standard: 24h)

# Sicherheitseinstellungen
security:
  require_password: true    # Beim Start immer Passwort verlangen
  password_hash: ""         # Gespeicherter Passwort-Hash (mit ptn -sp festlegen)
  max_auth_attempts: 5      # Maximale Fehlversuche vor Trennung

Die Konfiguration wird in dieser Reihenfolge gesucht: $PORTERMINAL_CONFIG_PATH, ./ptn.yaml, ./.ptn/ptn.yaml, ~/.ptn/ptn.yaml.

Sicherheit

Jeder Start erstellt einen neuen 128-Bit-Zufallspfad wie https://<tunnel>.trycloudflare.com/<access-code>/. Alle Browser-, WebSocket-, MCP-, REST-, Health- und statischen Routen erfordern dieses genaue Präfix; der nackte Host und falsche Pfade geben 404 zurück. Das macht Brute-Force-Angriffe auf einen entdeckten Tunnel-Hostnamen unpraktikabel.

Die vollständige generierte URL ist dennoch eine Inhaber-Anmeldeinformation: Jeder, der sie erhält, hat Shell-Zugriff. Starte Porterminal neu, um den Code zu rotieren, falls er durchsickert. Das optionale Passwort fügt Browser-WebSockets eine Authentifizierung hinzu, aber MCP und REST vertrauen weiterhin der vollständigen URL, damit Agenten den Ein-Link-Workflow nutzen können.

Ein Browser speichert ein erfolgreiches Passwort im Klartextspeicher, der auf diese vollständige Start-URL beschränkt ist. Das Speichern eines Passworts für einen neueren Start auf derselben Origin entfernt ältere Porterminal-Passworteinträge; das Löschen oder Ablehnen eines gespeicherten Passworts entfernt sie alle, ohne anderen Browser-Speicher zu berühren. Folglich können gleichzeitige Starts auf derselben Origin erneut zur Eingabe auffordern, während eine bereits authentifizierte Verbindung verbunden bleibt.

Über die Benutzeroberfläche: Öffne die Einstellungen (Zahnrad-Symbol) und verwende den Sicherheitsbereich, um das Passwort festzulegen/zu ändern und die Passwortanforderung umzuschalten. Änderungen erfordern einen Server-Neustart.

Über die CLI:

# Einmaliges Passwort (Abfrage bei jeder Sitzung)
ptn -p

# Passwort in der Konfiguration speichern (keine Abfrage nötig)
ptn -sp
# Passwort: ****
# Passwort bestätigen: ****

# Gespeichertes Passwort löschen (leeres Passwort eingeben)
ptn -sp
# Passwort: [Enter drücken]

# Passwortanforderung festlegen oder umschalten
ptn -tp          # Ein/Aus umschalten

Details findest du in docs/security.md.

Fehlerbehebung

Verbindung schlägt fehl? Verwende die vollständige generierte URL, einschließlich ihres Zugangscodes. Probleme mit dem Cloudflare-Tunnel können auch durch einen Neustart des Servers (Ctrl+C, dann ptn) für einen frischen Tunnel und Zugangspfad behoben werden.

uvx ptn führt immer noch eine ältere Version aus? Eine vorhandene uv tool-Installation kann Vorrang haben. Führe uv tool upgrade ptn aus oder umgehe installierte Tools mit uvx --isolated ptn@latest.

Shell nicht erkannt? Setze deine $SHELL-Umgebungsvariable oder konfiguriere Shells in ptn.yaml.

Mitwirken

Dieses Projekt akzeptiert keine externen Beiträge (Pull-Requests oder Code- Änderungen) aus Sicherheitsgründen (siehe CONTRIBUTING.md). Du kannst gerne forken und deine eigene Kopie unter AGPL-3.0 ausführen.

Aus dem Quellcode ausführen:

git clone https://github.com/lyehe/porterminal
cd porterminal
uv sync --frozen
uv run --frozen ptn

Lizenz

AGPL-3.0