porterminal v1.2.0

Confiez un ordinateur à un agent, avec un contrôle total, et regardez-le travailler.
Une commande, une URL. (Aussi un terminal élégant pour votre propre téléphone.)

1. uvx ptn
2. Confiez l'URL à un agent IA, ou scannez le QR vous-même
3. Regardez-le travailler dans n'importe quel navigateur, et reprenez la main à tout moment

[!WARNING] Cette URL complète donne un accès total à cet ordinateur. Elle contient un code d'accès aléatoire propre à chaque lancement, et quiconque (ou n'importe quel agent IA) à qui vous la confiez obtient un véritable shell sur votre machine. Traitez l'URL et le QR code comme un secret, ne les partagez qu'avec des personnes et des agents de confiance, et lisez la section Sécurité avant de pointer Porterminal vers quoi que ce soit d'important.

Pourquoi

J'avais besoin de quelque chose de dangereusement simple pour accéder à distance à un ordinateur.

ngrok exige une inscription et son offre gratuite est médiocre. Cloudflare Tunnel est une excellente plomberie, mais à lui seul il ne fournit qu'un tunnel, pas un terminal adapté au téléphone. Tailscale est parfait quand vous possédez les deux extrémités, mais cela implique quand même de joindre les appareils à un réseau privé. Termius exige une configuration compliquée : redirection de ports, règles de pare-feu, gestion des clés...

J'ai donc construit quelque chose de plus simple : lancez une commande, scannez un QR, commencez à taper.

Puis j'ai compris : le même tour de passe-passe (une commande, une URL) est la façon la plus simple de donner à un agent IA un véritable terminal sur n'importe quel ordinateur. Pas de serveur MCP à écrire, pas de clés SSH, pas de Docker, pas de configuration. Lancez uvx ptn, transmettez l'URL, et l'agent exécute des commandes, lit l'écran et répond aux invites sur cette machine. Et comme c'est un terminal web, vous pouvez ouvrir la même session dans n'importe quel navigateur pour le regarder travailler en direct, ou prendre le clavier et reprendre la main.

Fonctionnalités

• Confiez un ordinateur à un agent, avec un contrôle total, et regardez-le travailler - Donnez l'URL à un agent IA et il obtient un véritable terminal sur la machine via MCP ou REST simple. Ouvrez la même session dans n'importe quel navigateur pour le regarder travailler en direct, et prenez le clavier quand vous le souhaitez. Pas de clés, pas de Docker. L'agent apprend comment faire à partir de <url>/llms.txt et <url>/.well-known/mcp.json. Voir Accès agent.
• Une commande, accès instantané - uvx ptn et vous (ou un agent) obtenez un véritable terminal sur cette machine. Pas de SSH, pas de redirection de ports, pas de fichiers de configuration. Tunnel Cloudflare + QR code.
• Vraiment utilisable sur mobile - Optimisé pour le tactile avec défilement inertiel, zoom par pincement, gestes de balayage et touches modificatrices (Ctrl, Alt).
• Applications terminal complètes - vim, htop, less, tmux fonctionnent tous correctement avec une gestion adéquate du tampon d'écran alternatif.
• Sessions multi-onglets persistantes - Les sessions survivent aux déconnexions. Fermez le navigateur, changez de réseau, reconnectez-vous depuis un autre appareil, et votre shell et vos processus en cours sont toujours là. Vous et un agent pouvez partager une session : regardez-le travailler, ou reprenez la main.
• Multiplateforme - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish, Nushell, et n'importe quel shell via $SHELL). Détecte automatiquement vos shells.
• Difficile à deviner par défaut - Chaque lancement ajoute un chemin d'accès aléatoire indépendant de 128 bits. Le nom d'hôte du tunnel nu et tout chemin erroné renvoient 404. L'URL est masquée à l'écran, mais le QR contient l'identifiant complet, alors gardez les deux privés. Appuyez sur c pour copier les instructions de l'agent et l'URL, ou sur u pour copier uniquement l'URL.

Installation

Installation en une ligne (uv + ptn) :

Nécessite Python 3.12+ et cloudflared (installé automatiquement si absent).

Utilisation

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

Pendant l'exécution : avec un tunnel actif, l'URL de connexion est masquée à l'écran pour des raisons de confidentialité. Appuyez sur c pour copier les instructions de l'agent et l'URL, y compris /mcp, /api/agent/run et /llms.txt ; appuyez sur u pour copier uniquement l'URL ; ou scannez le QR pour vous connecter. Ctrl+C arrête le serveur.

Accès agent (MCP + REST)

Pour un contrôle du shell entièrement en arrière-plan, lancez ptn --mcp-only. L'interface du terminal local reste ouverte : appuyez sur c pour copier l'invite de l'agent et l'adresse MCP, ou sur u pour copier uniquement l'adresse MCP. Ces touches fonctionnent aussi avec --no-tunnel. Connectez votre client MCP au point de terminaison généré <url>/mcp. Ce mode n'affiche aucun QR code et désactive le terminal web, les WebSockets du navigateur et l'API REST, de sorte que les commandes ne peuvent pas être observées ni saisies via le navigateur. La découverte MCP et /llms.txt restent disponibles. L'URL MCP complète accorde toujours le contrôle du shell de l'ordinateur.

La même URL fonctionne aussi pour les agents IA. Les clients compatibles MCP peuvent utiliser <url>/mcp (Streamable HTTP) pour des outils typés natifs. Les agents qui ne peuvent pas enregistrer de serveur MCP peuvent utiliser le repli REST à <url>/api/agent/run avec de simples requêtes HTTP. L'un ou l'autre chemin crée un shell d'agent persistant, affiché comme un onglet 🤖 que vous pouvez surveiller et reprendre depuis votre téléphone.

Transmettez à l'agent l'URL complète générée, y compris son code d'accès. Les clients MCP peuvent auto-découvrir le serveur à partir de <url>/.well-known/mcp.json (le descripteur MCP server.json), et il existe un <url>/llms.txt lisible par un humain ou un agent avec les instructions d'utilisation. La page de base inclut également des indices visibles pour l'accessibilité destinés aux agents pilotant le navigateur, tandis que l'interface humaine reste compacte. Exemple de configuration client :

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

Outils MCP : run_command (sortie propre + code de sortie), read_screen, send_keys, send_signal (Ctrl-C / EOF).

Repli 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 réponse inclut un session_id ; réutilisez-le avec <url>/api/agent/screen, <url>/api/agent/keys, <url>/api/agent/signal, et DELETE <url>/api/agent/session.

Lorsque vous ouvrez Porterminal sur votre téléphone, le bouton de copie en haut à droite copie le même texte de partage prêt pour l'agent. Les agents uniquement navigateur disposent aussi d'un repli sur la page de base : un miroir Terminal screen lisible dans le DOM et une Terminal input clairement étiquetée.

Sécurité : <url> désigne l'URL complète générée, y compris son code d'accès aléatoire. Le nom d'hôte du tunnel nu n'expose rien, mais quiconque (ou n'importe quel agent) disposant de l'URL complète obtient un accès shell complet et non élevé. Voir docs/agent-access.md.

Gestes mobiles

Touches modificatrices (Ctrl, Alt, Shift) : appuyez une fois pour un mode collant (une frappe), double appui pour verrouiller.

Mode composition (bouton ▤) : basculez un champ de saisie de texte où vous pouvez taper ou dicter, modifier votre texte avec toutes les fonctionnalités d'édition mobile (correction automatique, suggestions, positionnement du curseur), puis l'envoyer au terminal. Utile pour les commandes longues ou la saisie vocale.

Configuration

Lancez ptn --init pour créer une configuration de départ. Il auto-découvre les scripts de projet à partir de package.json, pyproject.toml ou Makefile et les ajoute comme boutons :

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

Ou créez ptn.yaml manuellement :

# 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 configuration est recherchée dans l'ordre : $PORTERMINAL_CONFIG_PATH, ./ptn.yaml, ./.ptn/ptn.yaml, ~/.ptn/ptn.yaml.

Sécurité

Chaque lancement crée un nouveau chemin aléatoire de 128 bits tel que https://<tunnel>.trycloudflare.com/<access-code>/. Toutes les routes navigateur, WebSocket, MCP, REST, health et statiques exigent ce préfixe exact ; l'hôte nu et les chemins erronés renvoient 404. Cela rend le brute-force d'un nom d'hôte de tunnel découvert peu pratique.

L'URL complète générée reste néanmoins un identifiant porteur : quiconque l'obtient a un accès shell. Redémarrez Porterminal pour renouveler le code s'il fuit. Le mot de passe optionnel ajoute une authentification aux WebSockets du navigateur, mais MCP et REST continuent de faire confiance à l'URL complète afin que les agents puissent utiliser le flux de travail à lien unique.

Un navigateur mémorise un mot de passe réussi dans un stockage en clair limité à cette URL de lancement complète. Enregistrer un mot de passe pour un lancement plus récent sur la même origine retire les anciennes entrées de mot de passe Porterminal ; effacer ou rejeter un mot de passe mémorisé les supprime toutes sans toucher aux autres stockages du navigateur. Par conséquent, des lancements simultanés sur la même origine peuvent redemander le mot de passe, tandis qu'une connexion déjà authentifiée reste connectée.

Depuis l'interface : Ouvrez Paramètres (icône engrenage) et utilisez la section Sécurité pour définir/modifier le mot de passe et basculer l'exigence de mot de passe. Les modifications nécessitent un redémarrage du serveur.

Depuis la 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

Voir docs/security.md pour plus de détails.

Dépannage

La connexion échoue ? Utilisez l'URL complète générée, y compris son code d'accès. Les problèmes de tunnel Cloudflare peuvent aussi être résolus en redémarrant le serveur (Ctrl+C, puis ptn) pour obtenir un nouveau tunnel et un nouveau chemin d'accès.

uvx ptn exécute encore une version plus ancienne ? Une installation uv tool existante peut avoir la priorité. Lancez uv tool upgrade ptn, ou contournez les outils installés avec uvx --isolated ptn@latest.

Shell non détecté ? Définissez votre variable d'environnement $SHELL ou configurez les shells dans ptn.yaml.

Contribution

Ce projet n'accepte pas de contributions externes (pull requests ou modifications de code) pour des raisons de sécurité (voir CONTRIBUTING.md). Vous êtes invité à forker et exécuter votre propre copie sous AGPL-3.0.

Exécution depuis les sources :

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

Licence

AGPL-3.0