ptn 0.2.0

Web-based terminal accessible from phone via Cloudflare Tunnel

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

---

Why

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 works after complicated setup: port forwarding, firewall rules, key management... I just wanted something simpler: run a command, scan a QR, start typing.

Features

• 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 terminals use for vibe coding and mroe.
• Multi-tab shared sessions - Run builds in one tab, tail logs in another. Sessions persist across reconnects.
• Cross-platform - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish). Auto-detects your shells.

Install

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

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

Usage

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 logs

Configuration

Create ptn.yaml in your working directory, .ptn/ptn.yaml, or ~/.ptn/ptn.yaml (optional):

terminal:
  default_shell: bash
  cols: 120
  rows: 30

buttons:
  - label: "git"
    send: "git status\r"
  - label: "build"
    send: "npm run build\r"

Security

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)

Contributing

Issues and PRs welcome.

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

License

AGPL-3.0