porterminal

Hand a computer to an agent, full control, and watch it.
One command, one URL. (Also a slick terminal for your own phone.)

1. uvx ptn
2. Hand the URL to an AI agent, or scan the QR yourself
3. Watch it work in any browser, and take over anytime

[!WARNING] That complete URL is full access to this computer. It contains a random per-launch access code, and anyone (or any AI agent) you hand it to gets a real shell on your machine. Treat the URL and QR code like a secret, only share them with people and agents you trust, and read Security before you point Porterminal at anything important.

Why

I need something dangerously easy to remote access a computer.

ngrok requires registration and the free tier sucks. Cloudflare Tunnel is excellent plumbing, but by itself it only gives you a tunnel, not a phone-friendly terminal. Tailscale is great when you own both ends, but it still means joining devices to a private network. Termius requires complicated setup: port forwarding, firewall rules, key management...

So I built something simpler: run a command, scan a QR, start typing.

Then it clicked: the same trick (one command, one URL) is the easiest way to give an AI agent a real terminal on any computer. No MCP server to write, no SSH keys, no Docker, no config. Run uvx ptn, hand over the URL, and the agent runs commands, reads the screen, and answers prompts on that machine. And because it's a web terminal, you can open the same session in any browser to watch it work live, or grab the keyboard and take over.

Features

• Hand a computer to an agent, full control, and watch it - Give an AI agent the URL and it gets a real terminal on the machine via MCP or plain REST. Open the same session in any browser to watch it work live, and grab the keyboard whenever you want. No keys, no Docker. The agent learns how from <url>/llms.txt and <url>/.well-known/mcp.json. See Agent access.
• One command, instant access - uvx ptn and you (or an agent) get a real terminal on this machine. No SSH, no port forwarding, no config files. Cloudflare tunnel + QR code.
• Actually usable on mobile - Touch-optimized with momentum scrolling, pinch-to-zoom, swipe gestures, and modifier keys (Ctrl, Alt).
• Full terminal apps - vim, htop, less, tmux all work correctly with proper alt-screen buffer handling.
• Persistent multi-tab sessions - Sessions survive disconnects. Close the browser, switch networks, reconnect from another device, and your shell and running processes are still there. You and an agent can share one session: watch it work, or take over.
• Cross-platform - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish, Nushell, and any shell via $SHELL). Auto-detects your shells.
• Hard to guess by default - Every launch adds an independent 128-bit random access path. The bare tunnel hostname and every wrong path return 404. The URL is hidden on screen, but the QR contains the complete credential, so keep both private. Press c to copy agent instructions and URL, u to copy the URL only, or s to show the agent prompt on screen (q closes it).

Install

Method	Install	Update
uvx (no install)	uvx ptn	uvx 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

One-line install (uv + ptn):

OS	Command
Windows	powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/lyehe/porterminal/master/install.ps1 | iex"
macOS/Linux	curl -LsSf https://raw.githubusercontent.com/lyehe/porterminal/master/install.sh | sh

Requires Python 3.12+ and cloudflared (auto-installed if missing).

Usage

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

Flag	Description
-n, --no-tunnel	Local network only (no Cloudflare tunnel)
--mcp-only	MCP shell control without a QR code, browser terminal, or REST API
-p, --password	Prompt for password to protect this session
-sp, --save-password	Save or clear password in config
-tp, --toggle-password	Set password requirement (on/off/toggle)
-v, --verbose	Show detailed startup logs
-i, --init	Create .ptn/ptn.yaml with auto-discovered project scripts as buttons
-if, --init-from URL/PATH	Create .ptn/ptn.yaml from a URL or local file
-c, --compose	Enable compose mode by default
-k, --keep-qr	Keep the QR code visible after the first connection
-u, --check-update	Check if a newer version is available
-V, --version	Show version

While running: with a tunnel active, the connection URL is hidden on screen for privacy. Press c to copy agent instructions and URL, including /mcp, /api/agent/run, and /llms.txt; press u to copy the URL only; press s to show the full agent prompt as selectable text (q closes it); or scan the QR to connect. Ctrl+C stops the server.

Agent access (MCP + REST)

For shell control entirely behind the scenes, run ptn --mcp-only. The local terminal UI stays open: press c to copy the agent prompt and MCP address, u to copy just the MCP address, or s to show the prompt on screen (q closes it). These keys also work with --no-tunnel. Connect your MCP client to the generated <url>/mcp endpoint. This mode shows no QR code and disables the web terminal, browser WebSockets, and REST API, so commands cannot be watched or entered through the browser. MCP discovery and /llms.txt remain available. The complete MCP URL still grants shell control of the computer.

The same URL also works for AI agents. MCP-capable clients can use <url>/mcp (Streamable HTTP) for native typed tools. Agents that cannot register an MCP server can use the REST fallback at <url>/api/agent/run with ordinary HTTP requests. Either path creates a persistent agent shell, shown as a 🤖 tab you can watch and take over from your phone.