ptn 0.1.7

Web-based terminal accessible from phone via Cloudflare Tunnel

Access your terminal from your phone. No setup. Just scan.

uvx ptn

Scan the QR code. Start typing. That's it.

---

Why I Built This

I wanted to continue vibe coding after bed. I tried ngrok, but it requires registration. I tried Cloudflare Tunnel, but it doesn't provide a usable terminal UI. I tried Termius, but it comes with apps, accounts, and too much setup. I just wanted something simpler: open a browser, get a terminal, start typing.

So I built Porterminal. A mobile-first web terminal with secure tunneling, no registration, no installation on your phone, and a touch-friendly UI optimized for vibe coding with whatever AI app you want.

Features

• One command, instant access - No SSH, no port forwarding, no config files. Cloudflare tunnel + QR code.
• Actually usable on mobile - Virtual modifier keys (Ctrl, Alt, Tab, arrows), swipe gestures, copy/paste that works.
• Multi-tab 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.

Installation

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 (no Cloudflare)
ptn -b                 # Run in background

All options

Option	Description
path	Starting directory (default: current)
--no-tunnel	Local network only
-b, --background	Run in background
-v, --verbose	Detailed logs
-U, --update	Update to latest
--check-update	Check for updates
-V, --version	Show version

Configuration

Create config.yaml in your working directory (optional):

terminal:
  default_shell: bash
  cols: 120
  rows: 30

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

Full config options

server:
  host: "127.0.0.1"
  port: 8000

terminal:
  cols: 120
  rows: 30
  default_shell: powershell

  # Custom shells (auto-detected if not specified)
  shells:
    - id: powershell
      name: PowerShell
      command: powershell.exe
      args: ["-NoLogo"]
    - id: wsl
      name: WSL
      command: wsl.exe

buttons:
  - label: "git"
    send: "git status\r"
  - label: "ls"
    send: "ls -la\r"

Security

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

Best practices:

• Don't share the URL
• Stop the server when not in use (Ctrl+C)
• Use --no-tunnel for local network only

Built-in protections:

• Environment variables sanitized (API keys, tokens stripped)
• Rate limiting on input
• Cloudflare Access integration for teams

Contributing

Issues and PRs welcome. This project uses uv for development:

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

License

AGPL-3.0