ptn 0.4.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 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.

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 terminal use.
• Persistent multi-tab sessions - Sessions survive disconnects. Close the browser, switch networks, reconnect from another device—your shell and running processes are still there. Multiple devices can view the same session simultaneously.
• Cross-platform - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish, and any shell via $SHELL). 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

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
ptn --no-tunnel        # Local network only
ptn -b                 # Run in background
ptn -p                 # Enable password protection
ptn -dp                # Toggle default password requirement in config
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

Configuration

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)

# Security settings
security:
  require_password: true    # Always prompt for password at startup
  max_auth_attempts: 5      # Max failed attempts before disconnect

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

Security

Use password if your screen can be exposed to others:

ptn -p                 # Prompt for password this session
ptn -dp                # Enable password by default (toggle)

Password is per-session (never saved to disk). See docs/security.md for details.

Troubleshooting

Connection fails? Cloudflare tunnel sometimes blocks connections. Restart the server (Ctrl+C, then ptn) to get a fresh tunnel URL.

Contributing

Issues and PRs welcome.

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

License

AGPL-3.0