lyehe/porterminal: Quick n’ dirty web terminal tunneling your phone & pc

1. uvx ptn
2. Scan the QR
3. Access your terminal from your phone

I wanted to vibe code from bed.

ngrok requires registration and the free tier sucks. Cloudflare Quick Tunnel works great but is hard to use directly on the phone. Termius requires complicated setup: port forwarding, firewall rules, key management… Tried Claude Code web, but it can’t access my local hardware and environment. Also tried Happy, but it’s too bulky and updates lag behind.

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

• One command, instant access – No SSH, no port forwarding, no config files. Cloudflare tunnel + QR code.
• Actually usable on mobile – Essential buttons and gestures for everyday terminal use.
• Multi-tab shared sessions – Run builds in one tab, tail logs in another. Sessions and tabs persist across reconnects.
• Cross-platform – Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish). Auto-detects your shells.

One-line install (uv + ptn):

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

ptn                    # Start in current directory
ptn ~/projects/myapp   # Start in specific folder
ptn --no-tunnel        # Local network only
ptn -b                 # Run in background
ptn -v                 # Verbose startup logs
ptn --init             # Create .ptn/ptn.yaml config
ptn -V                 # Show version
ptn -U                 # Update to latest version
ptn --check-update     # Check if update available

Run ptn --init to create a starter config, or create ptn.yaml manually:

# Custom buttons (appear in toolbar)
buttons:
  - label: "claude"
    send:
      - "claude"
      - 100        # delay in ms
      - "\r"
  - label: "tmux"
    send: "tmux\r"

# Update checker settings
update:
  notify_on_startup: true   # Show update notification
  check_interval: 86400     # Seconds between checks (default: 24h)

Config is searched in order: $PORTERMINAL_CONFIG_PATH, ./ptn.yaml, ./.ptn/ptn.yaml, ~/.ptn/ptn.yaml.

Warning: The URL is the only authentication. Anyone with the link has full terminal access.

• Don’t share the URL
• Stop the server when not in use (Ctrl+C)
• Use --no-tunnel for local network only
• Environment variables are sanitized (API keys, tokens stripped)

Issues and PRs welcome.

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

AGPL-3.0