ptn 0.1.1

Web-based terminal accessible from phone via Cloudflare Tunnel

Simple, quick and dirty web terminal accessible from your phone via Cloudflare Quick Tunnel. Vibe-coding-friendly interface with virtual keys, multi-tab sessions, etc.

Features

• Touch-optimized - Virtual keyboard, touch gestures
• Multi-tab sessions - Run multiple terminals simultaneously with persistent sessions
• Instant access - Cloudflare Quick Tunnel with QR code, no port forwarding needed
• Cross-platform - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish)

Quick Start

# Run without installing
uvx ptn


# Or install
uv tool install ptn
ptn

Scan the QR code with your phone to connect.

Usage

ptn [path] [options]

Examples:

# Start in current directory with tunnel
ptn

# Start in a specific project folder
ptn ~/projects/myapp

# Local network only (no Cloudflare tunnel)
ptn --no-tunnel

# Run in background (returns immediately)
ptn -b

# Show detailed startup logs
ptn -v

# Update to latest version
ptn -U

# Check for updates without installing
ptn --check-update

Options:

Option	Description
path	Starting directory for the shell (default: current)
--no-tunnel	Local network only, no Cloudflare tunnel
-b, --background	Run in background and return immediately
-v, --verbose	Show detailed startup logs
-U, --update	Update to the latest version
--check-update	Check if a newer version is available
-V, --version	Show version
-h, --help	Show help message

Configuration

Create config.yaml in your working directory to customize:

# Server settings
server:
  host: "127.0.0.1"
  port: 8000

# Terminal settings
terminal:
  cols: 120        # Default columns (40-500)
  rows: 30         # Default rows (10-200)
  default_shell: powershell  # Default shell ID

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

# Custom quick-action buttons
buttons:
  - label: "git"
    send: "git status\r"
  - label: "ls"
    send: "ls -la\r"
  - label: "clear"
    send: "clear\r"
  - label: "exit"
    send: "exit\r"

Minimal config example:

terminal:
  default_shell: bash

Security

Warning: The URL is the only authentication. Anyone with the link can access your terminal.

• Environment variables sanitized (API keys, tokens, secrets blocked)
• Rate limiting on input
• Sessions isolated per user via Cloudflare Access

Requirements

• Python 3.12+
• uv is prefered
• cloudflared (auto-installed if missing)

License

AGPL-3.0