porterminal v1.0.7

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

1. uvx ptn
2. Gib 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 URL bedeutet vollständigen Zugriff auf diesen Computer. Jeder (oder jeder KI-Agent), dem du sie gibst, erhält eine echte Shell auf deinem Rechner – ohne Passwort. Das ist ja der ganze Sinn der Sache, aber es ist gefährlich einfach, einem Agenten mehr zu geben, als du beabsichtigt hast. Behandle die URL wie ein Geheimnis, teile sie nur mit Menschen und Agenten, denen du vertraust, und lies Sicherheit, bevor du sie auf etwas Wichtiges richtest.

Warum

Ich brauche etwas, das den Fernzugriff auf einen Computer gefährlich einfach macht.

ngrok erfordert eine Registrierung und der kostenlose Tarif taugt nichts. Cloudflare Tunnel ist hervorragende Infrastruktur, liefert aber für sich allein genommen nur einen Tunnel, kein handygerechtes Terminal. Tailscale ist großartig, wenn man beide Enden besitzt, aber es bedeutet trotzdem, Geräte in ein privates Netzwerk aufzunehmen. Termius erfordert eine komplizierte Einrichtung: Portweiterleitung, Firewall-Regeln, Schlüsselverwaltung...

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

Dann machte es Klick: Derselbe Trick (ein Befehl, eine URL) ist der einfachste Weg, einem KI-Agenten auf jedem Computer ein echtes Terminal zu geben. Kein MCP-Server, den man schreiben müsste, 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 dieser Maschine. Und weil es ein Web-Terminal ist, kannst du dieselbe Sitzung in einem beliebigen Browser öffnen, um live zuzusehen, oder die Tastatur übernehmen und die Kontrolle ergreifen.

Funktionen

• Übergib einem Agenten einen Computer, volle Kontrolle, und schau zu - Gib einem KI-Agenten die URL, und er erhält über MCP oder einfaches REST ein echtes Terminal auf der Maschine. Öffne dieselbe Sitzung in einem beliebigen Browser, um live zuzusehen, und übernimm die Tastatur, wann immer du willst. Keine Schlüssel, kein Docker. Der Agent lernt das Vorgehen aus /llms.txt und /.well-known/mcp.json. Siehe Agentenzugriff.
• Ein Befehl, sofortiger Zugriff - uvx ptn und du (oder ein Agent) erhältst ein echtes Terminal auf dieser Maschine. Kein SSH, keine Portweiterleitung, keine Konfigurationsdateien. Cloudflare-Tunnel + QR-Code.
• Auf dem Handy wirklich nutzbar - Touch-optimiert mit Schwung-Scrolling, Pinch-to-Zoom, Wischgesten und Modifikatortasten (Strg, Alt).
• Vollwertige Terminal-Apps - vim, htop, less und tmux funktionieren dank korrekter Alt-Screen-Puffer-Behandlung einwandfrei.
• Persistente Multi-Tab-Sitzungen - Sitzungen überstehen Trennungen. 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önnen sich eine Sitzung teilen: zusehen 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 privat - Die geheime Tunnel-URL steht nie auf dem Bildschirm, daher ist es unbedenklich, den Bildschirm zu teilen oder einen Screenshot des QR-Codes zu machen. Drücke c, um Agenten-Anweisungen und URL zu kopieren, oder u, um nur die URL zu kopieren.

Installation

Einzeiler-Installation (uv + ptn):

Erfordert Python 3.12+ und cloudflared (wird bei Bedarf automatisch installiert).

Verwendung

ptn                    # Start in current directory
ptn ~/projects/myapp   # Start in specific folder

Während des Betriebs: Bei aktivem Tunnel wird die Verbindungs-URL aus Datenschutzgründen nicht auf dem Bildschirm angezeigt. Drücke c, um Agenten-Anweisungen 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 nativ typisierte Tools nutzen. Agenten, die keinen MCP-Server registrieren können, verwenden das REST-Fallback unter <url>/api/agent/run mit gewöhnlichen HTTP-Anfragen. Beide Wege erzeugen eine persistente Agenten-Shell, die als 🤖-Tab angezeigt wird und die du vom Handy aus beobachten und übernehmen kannst.

Übergib dem Agenten die Tunnel-URL. 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 und Agenten lesbare <url>/llms.txt mit Nutzungshinweisen. Die Basis-Seite enthält außerdem für assistive Technologien sichtbare Hinweise für browsersteuernde Agenten, während die Oberfläche für Menschen kompakt bleibt. Beispiel-Client-Konfiguration:

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

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

REST-Fallback:

curl -s -X POST https://<your-tunnel>.trycloudflare.com/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 /api/agent/screen, /api/agent/keys, /api/agent/signal und DELETE /api/agent/session.

Wenn du Porterminal auf deinem Handy öffnest, kopiert der Kopieren-Button oben rechts denselben agentenfertigen Freigabetext. Auch reine Browser-Agenten erhalten ein Fallback auf der Basis-Seite: einen DOM-lesbaren Terminalbildschirm-Spiegel und ein klar beschriftetes Terminal-Eingabefeld.

Sicherheit: Wie beim menschlichen Terminal ist der einzige Schutz die geheime Tunnel-URL: Jeder (oder jeder Agent), der sie besitzt, erhält vollständigen, nicht privilegierten Shell-Zugriff. Wenn du echte Authentifizierung benötigst, verwende ein anderes Tool. Siehe docs/agent-access.md.

Mobile Gesten

Modifikatortasten (Strg, Alt, Umschalt): Einmal tippen für Sticky (ein Tastendruck), doppelt tippen zum Sperren.

Compose-Modus (▤-Taste): Schaltet ein Texteingabefeld um, in das du tippen oder diktieren kannst, deinen Text mit den vollständigen mobilen Bearbeitungsfunktionen (Autokorrektur, Vorschläge, Cursorpositionierung) bearbeiten 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
# Created: .ptn/ptn.yaml
# Discovered 3 project script(s): build, dev, test

Oder erstelle ptn.yaml manuell:

# Terminal settings
terminal:
  default_shell: nu              # Default shell ID
  shells:                        # Custom shell definitions
    - id: nu
      name: Nushell
      command: nu
      args: []

# Custom buttons (appear in toolbar)
# row: 1 = default row, 2+ = additional rows
buttons:
  - label: "claude"
    send:
      - "claude"
      - 100        # delay in ms
      - "\r"
  - label: "build"
    send: "npm run build\r"
    row: 2         # second button row

# Update checker settings
update:
  notify_on_startup: true   # Show update notification
  check_interval: 86400     # Seconds between checks (default: 24h)

# Security settings
security:
  require_password: true    # Always require password at startup
  password_hash: ""         # Saved password hash (use ptn -sp to set)
  max_auth_attempts: 5      # Max failed attempts before disconnect

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

Sicherheit

Standardmäßig gibt es kein Passwort. Das Einzige, was jemanden aufhält, ist, dass die zufällige Tunnel-URL nicht erraten werden kann. Jeder (oder jeder KI-Agent), der sie erhält, hat eine vollständige Shell auf deiner Maschine. Mach nichts zugänglich, was du nicht auch einem Fremden geben würdest, und lege für alles Sensible ein Passwort fest:

Über die Oberfläche: Öffne die Einstellungen (Zahnrad-Symbol) und verwende den Bereich Sicherheit, um ein Passwort festzulegen/zu ändern und die Passwortpflicht umzuschalten. Änderungen erfordern einen Neustart des Servers.

Über die CLI:

# One-time password (prompt each session)
ptn -p

# Save password to config (no prompt needed)
ptn -sp
# Password: ****
# Confirm password: ****

# Clear saved password (enter empty password)
ptn -sp
# Password: [press Enter]

# Set or toggle password requirement
ptn -tp on       # Enable
ptn -tp off      # Disable
ptn -tp toggle   # Toggle current state

Details findest du in docs/security.md.

Fehlerbehebung

Die Verbindung schlägt fehl? Der Cloudflare-Tunnel blockiert manchmal Verbindungen. Starte den Server neu (Ctrl+C, dann ptn), um eine neue Tunnel-URL zu erhalten.

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

Mitwirken

Dieses Projekt nimmt aus Sicherheitsgründen keine externen Beiträge an (Pull Requests oder Codeänderungen; siehe CONTRIBUTING.md). Du kannst das Repository gerne forken und unter AGPL-3.0 eine eigene Kopie betreiben.

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