lyehe/porterminalTunneling terminale web/mcp veloce e sporco per telefono e 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 with decorative QR artwork." width="800">
</a>
</p>
<h1 align="center">Dai un computer qualsiasi al tuo agente</h1>
<p align="center">
Un comando. Un URL. Un terminale reale per il tuo agente, una vista live per te.
</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>
Esegui Porterminal su un computer Windows, macOS o Linux e fornisci il link
generato al tuo agente AI. Ottiene una shell reale con i file, gli strumenti e i progetti
presenti su quella macchina. Apri lo stesso link sul tuo telefono o in qualsiasi browser per osservare
l'agente al lavoro e digitare nel suo terminale.
## Inizia da qui
Sul computer che vuoi dare al tuo agente:
```bash
uvx ptn
```
1. **Fornisci il link all'agente.** Premi **`c`** nella finestra locale di Porterminal
per copiare l'URL e le istruzioni di connessione. Incollale nel tuo agente
con un'attività. L'agente necessita del supporto MCP remoto o di un modo per effettuare richieste HTTP.
2. **Apri la tua vista.** Scansiona il codice QR o apri l'URL completo in un browser.
Seleziona la **scheda 🤖** dell'agente per vedere il suo terminale.
3. **Lavorate insieme.** Osserva l'output, rispondi a un prompt interattivo, digita un
comando o chiudi la scheda per terminare quella shell.
4. **Accedi al tuo computer da qualsiasi telefono.** Usa il browser del tuo telefono per
il vibe coding, correzioni rapide, esecuzione di comandi e altro.
Per iniziare in un progetto specifico, usa `uvx ptn /path/to/project`.
Per le opzioni di installazione, vedi [installation](https://github.com/porterminal/porterminal/blob/master/docs/installation.md), oppure usa un installer qui sotto.
> **Il link è la chiave del computer.** L'URL completo e il codice QR concedono
> l'accesso alla shell. Condividili solo con persone e agenti di cui ti fidi.
> [Leggi il modello di sicurezza](#security).
## L'agente lavora. Tu resti nel loop.
| Il tuo agente | Tu |
|------------|-----|
| Esegue comandi nella shell reale del computer | Osservi lo stesso output in tempo reale in un browser |
| Legge le schermate del terminale e risponde ai prompt | Digiti nello stesso terminale quando necessario |
| Mantiene lo stato della shell tra le chiamate agli strumenti | Passi tra le schede dell'agente e quelle personali |
| Usa MCP o HTTP per connettersi | Usa il codice QR o l'URL da un telefono o desktop |
L'input del terminale è condiviso; coordina la digitazione con il tuo agente. Porterminal
supporta applicazioni terminali interattive, schede multiple e la riconnessione a sessioni
in esecuzione finché il server e la sessione restano attivi.
L'interfaccia per telefono include i tasti Ctrl/Alt/Shift, la selezione touch, lo scorrimento,
lo zoom con pinch, e un campo di composizione per modificare o dettare input più lunghi.
Vedi [terminal controls](https://github.com/porterminal/porterminal/blob/master/docs/frontend_features.md).
## Prova la demo
Assegna a un agente un piccolo progetto di fatturazione con un controllo che fallisce. Osservalo trovare il
bug, modificare il file e far passare i controlli. Poi rispondi al prompt dell'etichetta della ricevuta
dal tuo telefono e fai leggere il risultato all'agente.
La [demo guide](https://github.com/porterminal/porterminal/blob/master/docs/demo.md) include un progetto pronto da copiare, un'attività per l'agente,
e un piano di registrazione da 60 secondi. Dimostra comandi, modifiche ai file,
verifica e input umano in un'unica sessione condivisa.
## Connetti il tuo agente
Premendo **`c`** si copiano le istruzioni per i metodi di connessione disponibili.
Il server in esecuzione le fornisce anche su `<url>/llms.txt`.
Qui, **`<url>` è l'URL completo generato, incluso il suo codice di accesso**.
| Capacità dell'agente | Connessione |
|------------------|------------|
| MCP remoto | `<url>/mcp` — Streamable HTTP |
| Richieste HTTP | `<url>/api/agent/run` — REST |
| Automazione del browser | Apri `<url>/`; usa **Terminal screen** e **Terminal input** |
MCP espone quattro strumenti: `run_command`, `read_screen`, `send_keys` e
`send_signal`. REST restituisce un `session_id` che l'agente riutilizza per i comandi
e l'interazione successivi. Le shell dell'agente appaiono come schede 🤖 nel tuo browser.
Vedi [agent access](https://github.com/porterminal/porterminal/blob/master/docs/agent-access.md) per la configurazione del client, esempi di richieste,
durata delle sessioni e comandi di lunga durata.
## Installazione
Richiede **Python 3.12+**. Porterminal tenta di installare `cloudflared`
automaticamente quando manca.
| Metodo | Esegui o installa | Aggiorna |
|--------|----------------|--------|
| 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` |
**Installa uv e Porterminal insieme:**
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
```
## Utilizzo
Dopo l'installazione, esegui `ptn` o `ptn /path/to/project`.
| Opzione | Scopo |
|--------|---------|
| `--no-tunnel` | Esegue senza un tunnel Cloudflare |
| `--mcp-only` | Espone solo MCP; disabilita il codice QR, il terminale del browser e l'API REST |
| `--compose` | Avvia con il campo compose mobile abilitato |
| `--init` | Genera `.ptn/ptn.yaml` con i pulsanti rilevati dagli script del progetto |
| `--password` | Aggiunge una password all'accesso del terminale del browser |
| `--help` | Mostra tutte le opzioni |
| `--version` | Mostra la versione installata |
Durante l'esecuzione: **`c`** copia le istruzioni per l'agente, **`u`** copia solo
l'URL, e **`s`** mostra il testo di condivisione sullo schermo (**`q`** lo chiude).
**Ctrl+C** arresta Porterminal. In modalità solo MCP i tasti di condivisione usano l'URL MCP.
Shell personalizzate, pulsanti della barra degli strumenti e impostazioni di avvio si trovano in `ptn.yaml`.
Vedi [configuration](https://github.com/porterminal/porterminal/blob/master/docs/configuration.md).
## Sicurezza
Porterminal fornisce accesso a una shell reale con i permessi del tuo utente. La
directory iniziale è una comodità, non una sandbox né un limite all'accesso ai file.
Ogni avvio crea un nuovo percorso di accesso casuale a 128 bit. Il nome host del tunnel
nudo e i percorsi errati restituiscono 404, ma chiunque abbia l'URL completo può usare la shell.
Mantieni privati l'URL e il codice QR, arresta Porterminal al termine e riavvialo
per ruotare il codice di accesso se il link viene divulgato.
**La password opzionale protegge le connessioni del browser. MCP e REST usano
l'URL completo come credenziale e non richiedono quella password.**
Vedi [security](https://github.com/porterminal/porterminal/blob/master/docs/security.md) per il modello completo e il comportamento della password.
Segnala le vulnerabilità tramite [la security policy](https://github.com/porterminal/porterminal/blob/master/.github/SECURITY.md).
## Documentazione e sviluppo
- [Installation](https://github.com/porterminal/porterminal/blob/master/docs/installation.md)
- [Agent access: MCP, REST, and browser fallback](https://github.com/porterminal/porterminal/blob/master/docs/agent-access.md)
- [Demo setup and recording](https://github.com/porterminal/porterminal/blob/master/docs/demo.md)
- [Configuration](https://github.com/porterminal/porterminal/blob/master/docs/configuration.md)
- [Architecture](https://github.com/porterminal/porterminal/blob/master/docs/architecture.md)
- [Development and release process](https://github.com/porterminal/porterminal/blob/master/docs/development.md)
- [Changelog](https://github.com/porterminal/porterminal/blob/master/docs/CHANGELOG.md)
Segnalazioni di bug e richieste di funzionalità sono benvenute come
[issues](https://github.com/porterminal/porterminal/issues).
Le pull request esterne e i contributi di codice non sono accettati; vedi
[CONTRIBUTING.md](https://github.com/porterminal/porterminal/blob/master/CONTRIBUTING.md). Puoi fare un fork ed eseguire la tua copia.
## Licenza
[AGPL-3.0](https://github.com/porterminal/porterminal/blob/master/LICENSE)