porterminal v1.2.0

Consegna un computer a un agente, pieno controllo, e guardalo lavorare.
Un comando, un URL. (Anche un terminale elegante per il tuo telefono.)

1. uvx ptn
2. Consegna l'URL a un agente AI, oppure scansiona tu stesso il QR
3. Guardalo lavorare in qualsiasi browser, e prendi il controllo in qualsiasi momento

[!WARNING] Quell'URL completo è accesso completo a questo computer. Contiene un codice di accesso casuale per ogni avvio, e chiunque (o qualsiasi agente AI) a cui lo consegni ottiene una shell reale sulla tua macchina. Tratta l'URL e il codice QR come un segreto, condividili solo con persone e agenti di cui ti fidi, e leggi Sicurezza prima di puntare Porterminal verso qualcosa di importante.

Perché

Ho bisogno di qualcosa di pericolosamente semplice per accedere da remoto a un computer.

ngrok richiede la registrazione e il piano gratuito fa schifo. Cloudflare Tunnel è un'ottima infrastruttura, ma da sola fornisce solo un tunnel, non un terminale adatto al telefono. Tailscale è ottimo quando possiedi entrambe le estremità, ma significa comunque aggiungere dispositivi a una rete privata. Termius richiede una configurazione complicata: port forwarding, regole del firewall, gestione delle chiavi...

Così ho costruito qualcosa di più semplice: esegui un comando, scansiona un QR, inizia a digitare.

Poi ho capito: lo stesso trucco (un comando, un URL) è il modo più semplice per dare a un agente AI un terminale reale su qualsiasi computer. Nessun server MCP da scrivere, nessuna chiave SSH, nessun Docker, nessuna configurazione. Esegui uvx ptn, consegna l'URL, e l'agente esegue comandi, legge lo schermo e risponde ai prompt su quella macchina. E poiché è un terminale web, puoi aprire la stessa sessione in qualsiasi browser per guardarlo lavorare dal vivo, oppure prendere la tastiera e subentrare.

Funzionalità

• Consegna un computer a un agente, pieno controllo, e guardalo lavorare - Dai a un agente AI l'URL e ottiene un terminale reale sulla macchina tramite MCP o semplice REST. Apri la stessa sessione in qualsiasi browser per guardarlo lavorare dal vivo, e prendi la tastiera quando vuoi. Nessuna chiave, nessun Docker. L'agente impara come fare da <url>/llms.txt e <url>/.well-known/mcp.json. Vedi Accesso agente.
• Un comando, accesso istantaneo - uvx ptn e tu (o un agente) ottenete un terminale reale su questa macchina. Niente SSH, niente port forwarding, niente file di configurazione. Tunnel Cloudflare + codice QR.
• Davvero utilizzabile su mobile - Ottimizzato per il tocco con scorrimento con inerzia, pinch-to-zoom, gesture di swipe e tasti modificatori (Ctrl, Alt).
• Applicazioni terminale complete - vim, htop, less, tmux funzionano tutti correttamente con una corretta gestione del buffer alt-screen.
• Sessioni multi-tab persistenti - Le sessioni sopravvivono alle disconnessioni. Chiudi il browser, cambia rete, riconnettiti da un altro dispositivo, e la tua shell e i processi in esecuzione sono ancora lì. Tu e un agente potete condividere una sessione: guardalo lavorare, oppure subentra.
• Multipiattaforma - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish, Nushell, e qualsiasi shell tramite $SHELL). Rileva automaticamente le tue shell.
• Difficile da indovinare per impostazione predefinita - Ogni avvio aggiunge un percorso di accesso casuale indipendente a 128 bit. Il semplice hostname del tunnel e ogni percorso errato restituiscono 404. L'URL è nascosto sullo schermo, ma il QR contiene la credenziale completa, quindi mantieni entrambi privati. Premi c per copiare le istruzioni per l'agente e l'URL, oppure u per copiare solo l'URL.

Installazione

Installazione in una riga (uv + ptn):

Richiede Python 3.12+ e cloudflared (installato automaticamente se mancante).

Utilizzo

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

Durante l'esecuzione: con un tunnel attivo, l'URL di connessione è nascosto sullo schermo per privacy. Premi c per copiare le istruzioni per l'agente e l'URL, inclusi /mcp, /api/agent/run e /llms.txt; premi u per copiare solo l'URL; oppure scansiona il QR per connetterti. Ctrl+C arresta il server.

Accesso agente (MCP + REST)

Per il controllo della shell interamente dietro le quinte, esegui ptn --mcp-only. L'interfaccia del terminale locale rimane aperta: premi c per copiare il prompt dell'agente e l'indirizzo MCP, oppure u per copiare solo l'indirizzo MCP. Questi tasti funzionano anche con --no-tunnel. Connetti il tuo client MCP all'endpoint generato <url>/mcp. Questa modalità non mostra alcun codice QR e disabilita il terminale web, i WebSocket del browser e l'API REST, quindi i comandi non possono essere osservati o inseriti tramite il browser. Il rilevamento MCP e /llms.txt rimangono disponibili. L'URL MCP completo concede comunque il controllo della shell del computer.

Lo stesso URL funziona anche per gli agenti AI. I client compatibili con MCP possono usare <url>/mcp (Streamable HTTP) per strumenti tipizzati nativi. Gli agenti che non possono registrare un server MCP possono usare il fallback REST su <url>/api/agent/run con normali richieste HTTP. Entrambi i percorsi creano una shell agente persistente, mostrata come scheda 🤖 che puoi osservare e di cui puoi prendere il controllo dal tuo telefono.

Consegna all'agente l'URL completo generato, incluso il suo codice di accesso. I client MCP possono rilevare automaticamente il server da <url>/.well-known/mcp.json (il descrittore MCP server.json), e c'è un <url>/llms.txt leggibile da umani/agenti con le istruzioni d'uso. La pagina base include anche suggerimenti visibili per l'accessibilità per gli agenti che guidano il browser, mentre l'interfaccia umana rimane compatta. Esempio di configurazione del client:

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

Strumenti MCP: run_command (output pulito + codice di uscita), read_screen, send_keys, send_signal (Ctrl-C / EOF).

Fallback REST:

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}'

La risposta include un session_id; riutilizzalo con <url>/api/agent/screen, <url>/api/agent/keys, <url>/api/agent/signal, e DELETE <url>/api/agent/session.

Quando apri Porterminal sul tuo telefono, il pulsante di copia in alto a destra copia lo stesso testo di condivisione pronto per l'agente. Gli agenti solo-browser ottengono anche un fallback sulla pagina base: uno specchio Terminal screen leggibile dal DOM e un Terminal input chiaramente etichettato.

Sicurezza: <url> indica l'URL completo generato, incluso il suo codice di accesso casuale. Il semplice hostname del tunnel non espone nulla, ma chiunque (o qualsiasi agente) con l'URL completo ottiene accesso completo alla shell, non elevato. Vedi docs/agent-access.md.

Gesti Mobile

Tasti modificatori (Ctrl, Alt, Shift): tocca una volta per sticky (una pressione), doppio tocco per il blocco.

Modalità compose (pulsante ▤): attiva/disattiva un campo di input di testo dove puoi digitare o dettare, modificare il tuo testo con tutte le funzionalità di editing mobile (correzione automatica, suggerimenti, posizionamento del cursore), poi inviarlo al terminale. Utile per comandi più lunghi o input vocale.

Configurazione

Esegui ptn --init per creare una configurazione iniziale. Rileva automaticamente gli script di progetto da package.json, pyproject.toml o Makefile e li aggiunge come pulsanti:

ptn -i
# Created: .ptn/ptn.yaml
# Discovered 3 project script(s): build, dev, test

Oppure crea ptn.yaml manualmente:

# 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

La configurazione viene cercata in ordine: $PORTERMINAL_CONFIG_PATH, ./ptn.yaml, ./.ptn/ptn.yaml, ~/.ptn/ptn.yaml.

Sicurezza

Ogni avvio crea un nuovo percorso casuale a 128 bit come https://<tunnel>.trycloudflare.com/<access-code>/. Tutte le rotte browser, WebSocket, MCP, REST, health e statiche richiedono quel prefisso esatto; l'host semplice e i percorsi errati restituiscono 404. Questo rende impraticabile il brute-forcing di un hostname di tunnel scoperto.

L'URL completo generato è comunque una credenziale bearer: chiunque lo ottenga ha accesso alla shell. Riavvia Porterminal per ruotare il codice se trapela. La password opzionale aggiunge autenticazione ai WebSocket del browser, ma MCP e REST continuano a fidarsi dell'URL completo così gli agenti possono usare il flusso di lavoro a link singolo.

Un browser ricorda una password inserita con successo in un archivio in chiaro limitato a quell' URL di avvio completo. Salvare una password per un avvio più recente sulla stessa origine ritira le voci di password Porterminal più vecchie; cancellare o rifiutare una password memorizzata le rimuove tutte senza toccare altro archivio del browser. Di conseguenza, avvii concorrenti sulla stessa origine potrebbero richiedere nuovamente la password, mentre una connessione già autenticata rimane connessa.

Dall'interfaccia: Apri Impostazioni (icona ingranaggio) e usa la sezione Sicurezza per impostare/cambiare la password e attivare/disattivare il requisito della password. Le modifiche richiedono il riavvio del server.

Da 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          # Toggle on/off

Vedi docs/security.md per i dettagli.

Risoluzione dei problemi

La connessione fallisce? Usa l'URL completo generato, incluso il suo codice di accesso. I problemi del tunnel Cloudflare possono anche essere risolti riavviando il server (Ctrl+C, poi ptn) per un nuovo tunnel e percorso di accesso.

uvx ptn esegue ancora una versione più vecchia? Un'installazione uv tool esistente può avere la precedenza. Esegui uv tool upgrade ptn, oppure bypassa gli strumenti installati con uvx --isolated ptn@latest.

Shell non rilevata? Imposta la tua variabile d'ambiente $SHELL o configura le shell in ptn.yaml.

Contribuire

Questo progetto non accetta contributi esterni (pull request o modifiche al codice) per motivi di sicurezza (vedi CONTRIBUTING.md). Sei il benvenuto a fare un fork ed eseguire la tua copia sotto AGPL-3.0.

Esegui dal sorgente:

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

Licenza

AGPL-3.0