lyehe/porterminalSchnelles und unkompliziertes Web/MCP-Terminal-Tunneling für Handy & PC
<p align="center">
<a href="https://github.com/porterminal/porterminal">
<img src="https://raw.githubusercontent.com/porterminal/porterminal/master/assets/header.png?v=9" alt="PTN — Portable Terminal mit dekorativer QR-Grafik." width="800">
</a>
</p>
<h1 align="center">Gib deinem Agenten einen beliebigen Computer</h1>
<p align="center">
Ein Befehl. Eine URL. Ein echtes Terminal für deinen Agenten, eine Live-Ansicht für dich.
</p>
<p align="center">
<a href="https://pypi.org/project/ptn/"><img src="https://img.shields.io/pypi/v/ptn?style=flat-square&logo=pypi&logoColor=white&label=PyPI" alt="PyPI"></a>
<a href="https://pypi.org/project/ptn/"><img src="https://img.shields.io/pypi/pyversions/ptn?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/porterminal/porterminal/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/porterminal/porterminal/ci.yml?branch=master&style=flat-square&logo=github&label=CI" alt="CI"></a>
<a href="https://github.com/porterminal/porterminal/blob/master/LICENSE"><img src="https://img.shields.io/github/license/porterminal/porterminal?style=flat-square" alt="License"></a>
</p>
Führe Porterminal auf einem Windows-, macOS- oder Linux-Computer aus und gib den
generierten Link an deinen KI-Agenten weiter. Er erhält eine echte Shell mit den Dateien, Werkzeugen und Projekten
auf diesem Rechner. Öffne denselben Link auf deinem Smartphone oder in einem beliebigen Browser, um dem Agenten bei der Arbeit zuzusehen und in sein Terminal zu tippen.
## Hier starten
Auf dem Computer, den du deinem Agenten geben möchtest:
```bash
uvx ptn
```
1. **Gib dem Agenten den Link.** Drücke **`c`** im lokalen Porterminal-Fenster,
um die URL und die Verbindungsanweisungen zu kopieren. Füge sie zusammen mit
einer Aufgabe in deinen Agenten ein. Der Agent benötigt Remote-MCP-Unterstützung
oder eine Möglichkeit, HTTP-Anfragen zu stellen.
2. **Öffne deine Ansicht.** Scanne den QR-Code oder öffne die vollständige URL in
einem Browser. Wähle den **🤖-Tab** des Agenten, um sein Terminal zu sehen.
3. **Arbeitet zusammen.** Beobachte die Ausgabe, beantworte eine interaktive
Eingabeaufforderung, tippe einen Befehl ein oder schließe den Tab, um diese
Shell zu beenden.
4. **Greife von jedem Telefon aus auf deinen Computer zu.** Nutze den Browser
deines Telefons für Vibe Coding, schnelle Korrekturen, das Ausführen von
Befehlen und mehr.
Um in einem bestimmten Projekt zu starten, verwende `uvx ptn /path/to/project`.
Installationsoptionen findest du unter [installation](https://github.com/porterminal/porterminal/blob/master/docs/installation.md), oder verwende einen Installer unten.
> **Der Link ist der Schlüssel zum Computer.** Die vollständige URL und der
> QR-Code gewähren Shell-Zugriff. Teile sie nur mit Personen und Agenten, denen
> du vertraust. [Lies das Sicherheitsmodell](#security).
## Der Agent arbeitet. Du bleibst im Bilde.
| Dein Agent | Du |
|------------|-----|
| Führt Befehle in der echten Shell des Computers aus | Siehst dieselbe Ausgabe live im Browser |
| Liest Terminal-Bildschirme und beantwortet Eingabeaufforderungen | Tippst bei Bedarf in dasselbe Terminal |
| Behält den Shell-Zustand über Tool-Aufrufe hinweg bei | Wechselst zwischen Agenten- und persönlichen Tabs |
| Nutzt MCP oder HTTP zur Verbindung | Nutzt den QR-Code oder die URL von einem Telefon oder Desktop |
Die Terminal-Eingabe wird geteilt; koordiniere das Tippen mit deinem Agenten.
Porterminal unterstützt interaktive Terminal-Apps, mehrere Tabs und das
Wiederverbinden mit laufenden Sitzungen, solange der Server und die Sitzung
aktiv bleiben.
Die Telefon-Oberfläche umfasst Ctrl/Alt/Shift-Tasten, Touch-Auswahl, Scrollen,
Pinch-to-Zoom und ein Eingabefeld zum Bearbeiten oder Diktieren längerer Eingaben.
Siehe [terminal controls](https://github.com/porterminal/porterminal/blob/master/docs/frontend_features.md).
## Probiere die Demo aus
Gib einem Agenten ein kleines Rechnungsprojekt mit einer fehlschlagenden Prüfung.
Beobachte, wie er den Fehler findet, die Datei bearbeitet und die Prüfungen grün
macht. Beantworte dann die Beschriftungs-Eingabeaufforderung der Quittung von
deinem Telefon aus und lass den Agenten das Ergebnis lesen.
Der [Demo-Leitfaden](https://github.com/porterminal/porterminal/blob/master/docs/demo.md) enthält ein sofort kopierbares Projekt, eine Agenten-Aufgabe
und einen 60-Sekunden-Aufnahmeplan. Er demonstriert Befehle, Dateiänderungen,
Verifizierung und menschliche Eingaben in einer gemeinsamen Sitzung.
## Verbinde deinen Agenten
Durch Drücken von **`c`** werden Anweisungen für die verfügbaren
Verbindungsmethoden kopiert. Der laufende Server stellt sie auch unter
`<url>/llms.txt` bereit.
Hierbei ist **`<url>` die vollständige generierte URL, einschließlich ihres Zugriffscodes**.
| Agenten-Fähigkeit | Verbindung |
|------------------|------------|
| Remote-MCP | `<url>/mcp` — Streamable HTTP |
| HTTP-Anfragen | `<url>/api/agent/run` — REST |
| Browser-Automatisierung | Öffne `<url>/`; verwende **Terminal screen** und **Terminal input** |
MCP stellt vier Tools bereit: `run_command`, `read_screen`, `send_keys` und
`send_signal`. REST gibt eine `session_id` zurück, die der Agent für nachfolgende
Befehle und Interaktionen wiederverwendet. Agenten-Shells erscheinen als 🤖-Tabs in deinem Browser.
Siehe [agent access](https://github.com/porterminal/porterminal/blob/master/docs/agent-access.md) für die Client-Einrichtung, Anfragebeispiele,
Sitzungslebensdauern und lang laufende Befehle.
## Installation
Erfordert **Python 3.12+**. Porterminal versucht, `cloudflared` automatisch zu
installieren, wenn es fehlt.
| Methode | Ausführen oder installieren | Aktualisieren |
|--------|----------------|--------|
| uvx | `uvx ptn` | `uvx --isolated ptn@latest` |
| uv tool | `uv tool install ptn` | `uv tool upgrade ptn` |
| pipx | `pipx install ptn` | `pipx upgrade ptn` |
| pip | `pip install ptn` | `pip install -U ptn` |
**uv und Porterminal zusammen installieren:**
Windows (PowerShell):
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/porterminal/porterminal/master/install.ps1 | iex"
```
macOS / Linux:
```bash
curl -LsSf https://raw.githubusercontent.com/porterminal/porterminal/master/install.sh | sh
```
## Verwendung
Nach der Installation `ptn` oder `ptn /path/to/project` ausführen.
| Option | Zweck |
|--------|---------|
| `--no-tunnel` | Ohne Cloudflare-Tunnel ausführen |
| `--mcp-only` | Nur MCP bereitstellen; deaktiviert den QR-Code, das Browser-Terminal und die REST-API |
| `--compose` | Mit aktiviertem mobilem Compose-Feld starten |
| `--init` | `.ptn/ptn.yaml` mit aus Projektskripten ermittelten Buttons generieren |
| `--password` | Ein Passwort für den Zugriff auf das Browser-Terminal hinzufügen |
| `--help` | Alle Optionen anzeigen |
| `--version` | Die installierte Version anzeigen |
Während der Ausführung: **`c`** kopiert die Agent-Anweisungen, **`u`** kopiert nur die
URL, und **`s`** zeigt den Freigabetext auf dem Bildschirm an (**`q`** schließt ihn).
**Strg+C** beendet Porterminal. Im MCP-Only-Modus verwenden die Freigabetasten die MCP-URL.
Benutzerdefinierte Shells, Toolbar-Buttons und Starteinstellungen befinden sich in `ptn.yaml`.
Siehe [Konfiguration](https://github.com/porterminal/porterminal/blob/master/docs/configuration.md).
## Sicherheit
Porterminal gewährt Zugriff auf eine echte Shell mit den Berechtigungen deines Benutzers. Das
Startverzeichnis ist eine Annehmlichkeit, keine Sandbox und keine Einschränkung des Dateizugriffs.
Jeder Start erzeugt einen neuen zufälligen 128-Bit-Zugriffspfad. Der reine Tunnel-Hostname
und falsche Pfade liefern 404, aber jeder mit der vollständigen URL kann die Shell nutzen.
Halte die URL und den QR-Code geheim, stoppe Porterminal nach der Verwendung und starte
es neu, um den Zugriffscode zu rotieren, falls der Link preisgegeben wurde.
**Das optionale Passwort schützt Browser-Verbindungen. MCP und REST verwenden die
vollständige URL als Anmeldedaten und erfordern dieses Passwort nicht.**
Siehe [Sicherheit](https://github.com/porterminal/porterminal/blob/master/docs/security.md) für das vollständige Modell und das Passwortverhalten.
Melde Schwachstellen über [die Sicherheitsrichtlinie](https://github.com/porterminal/porterminal/blob/master/.github/SECURITY.md).
## Dokumentation und Entwicklung
- [Installation](https://github.com/porterminal/porterminal/blob/master/docs/installation.md)
- [Agent-Zugriff: MCP, REST und Browser-Fallback](https://github.com/porterminal/porterminal/blob/master/docs/agent-access.md)
- [Demo-Einrichtung und -Aufzeichnung](https://github.com/porterminal/porterminal/blob/master/docs/demo.md)
- [Konfiguration](https://github.com/porterminal/porterminal/blob/master/docs/configuration.md)
- [Architektur](https://github.com/porterminal/porterminal/blob/master/docs/architecture.md)
- [Entwicklungs- und Release-Prozess](https://github.com/porterminal/porterminal/blob/master/docs/development.md)
- [Changelog](https://github.com/porterminal/porterminal/blob/master/docs/CHANGELOG.md)
Fehlerberichte und Funktionswünsche sind willkommen als
[Issues](https://github.com/porterminal/porterminal/issues).
Externe Pull Requests und Code-Beiträge werden nicht angenommen; siehe
[CONTRIBUTING.md](https://github.com/porterminal/porterminal/blob/master/CONTRIBUTING.md). Du kannst das Projekt forken und eine eigene Kopie betreiben.
## Lizenz
[AGPL-3.0](https://github.com/porterminal/porterminal/blob/master/LICENSE)