porterminal v1.0.7 — Quick n' dirty web/mcp terminal tunneling your phone & pc

把一台电脑交给一个智能体，完全控制，并实时观看。
一条命令，一个 URL。（同时也是你自己手机上的一个顺滑终端。）

1. uvx ptn
2. 把 URL 交给 AI 智能体，或者自己扫描二维码
3. 在任意浏览器中观看它工作，随时接管

Porterminal 演示

[!WARNING] 那个完整 URL 就是这台电脑的完全访问权限。 它包含每次启动随机生成的访问码，任何拿到它的人（或任何 AI 智能体）都能在你的机器上获得一个真实的 shell。请把 URL 和二维码当作机密对待，只分享给你信任的人和智能体，并在把 Porterminal 指向任何重要内容之前阅读安全部分。

为什么

我需要一种危险地简单的方式来远程访问一台电脑。

ngrok 需要注册，而且免费套餐很糟糕。Cloudflare Tunnel 是出色的底层管道，但仅凭它只能给你一条隧道，而不是一个适合手机的终端。Tailscale 在你拥有两端时很棒，但它仍然意味着要把设备加入一个私有网络。Termius 需要复杂的设置：端口转发、防火墙规则、密钥管理……

所以我做了一个更简单的东西：运行一条命令，扫描二维码，开始输入。

然后我恍然大悟：同样的技巧（一条命令，一个 URL）是把一个真实终端交给 AI 智能体、让它控制任意电脑的最简单方式。无需编写 MCP 服务器，无需 SSH 密钥，无需 Docker，无需配置。运行 uvx ptn，交出 URL，智能体就能在那台机器上运行命令、读取屏幕并回答提示。而且因为它是一个 Web 终端，你可以在任意浏览器中打开同一个会话，实时观看它工作，或者抢过键盘接管。

功能

把一台电脑交给一个智能体，完全控制，并实时观看 - 把 URL 交给 AI 智能体，它就能通过 MCP 或普通 REST 在这台机器上获得一个真实终端。在任意浏览器中打开同一个会话，实时观看它工作，随时抢过键盘。无需密钥，无需 Docker。智能体可以从 <url>/llms.txt 和 <url>/.well-known/mcp.json 学习如何使用。参见智能体访问。
一条命令，即时访问 - uvx ptn，你（或一个智能体）就能在这台机器上获得一个真实终端。无需 SSH，无需端口转发，无需配置文件。Cloudflare 隧道 + 二维码。
在手机上真正可用 - 针对触控优化，支持惯性滚动、双指缩放、滑动手势和修饰键（Ctrl、Alt）。
完整的终端应用 - vim、htop、less、tmux 都能正常工作，具备正确的备用屏幕缓冲区处理。
持久的多标签会话 - 会话在断开连接后依然存在。关闭浏览器、切换网络、从另一台设备重新连接，你的 shell 和正在运行的进程仍然在那里。你和智能体可以共享一个会话：观看它工作，或者接管。
跨平台 - Windows（PowerShell、CMD、WSL）、Linux/macOS（Bash、Zsh、Fish、Nushell，以及通过 $SHELL 指定的任意 shell）。自动检测你的 shell。
默认难以猜测 - 每次启动都会添加一个独立的 128 位随机访问路径。裸隧道主机名和所有错误路径都返回 404。URL 在屏幕上被隐藏，但二维码包含完整凭据，所以请对两者保密。按 c 复制智能体指令和 URL，按 u 只复制 URL，或按 s 在屏幕上显示智能体提示（q 关闭它）。

安装

方式	安装	更新
uvx（无需安装）	`uvx ptn`	`uvx ptn@latest`
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`

一行安装（uv + ptn）：

操作系统	命令
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`

需要 Python 3.12+ 和 cloudflared（如果缺失会自动安装）。

用法

ptn                    # 在当前目录启动
ptn ~/projects/myapp   # 在指定文件夹启动

参数	描述
`-n, --no-tunnel`	仅本地网络（不使用 Cloudflare 隧道）
`--mcp-only`	仅 MCP shell 控制，不显示二维码、浏览器终端或 REST API
`-p, --password`	提示输入密码以保护此会话
`-sp, --save-password`	在配置中保存或清除密码
`-tp, --toggle-password`	设置密码要求（开/关/切换）
`-v, --verbose`	显示详细启动日志
`-i, --init`	创建 `.ptn/ptn.yaml`，将自动发现的项目脚本作为按钮
`-if, --init-from URL/PATH`	从 URL 或本地文件创建 `.ptn/ptn.yaml`
`-c, --compose`	默认启用撰写模式
`-k, --keep-qr`	首次连接后保持二维码可见
`-u, --check-update`	检查是否有更新版本可用
`-V, --version`	显示版本

运行期间： 隧道激活时，连接 URL 会出于隐私在屏幕上隐藏。按 c 复制智能体指令和 URL，包括 /mcp、/api/agent/run 和 /llms.txt；按 u 只复制 URL；按 s 将完整的智能体提示显示为可选文本（q 关闭它）；或扫描二维码连接。Ctrl+C 停止服务器。

智能体访问（MCP + REST）

若要在完全后台进行 shell 控制，请运行 ptn --mcp-only。本地终端 UI 保持打开：按 c 复制智能体提示和 MCP 地址，按 u 只复制 MCP 地址，或按 s 在屏幕上显示提示（q 关闭它）。这些按键在 --no-tunnel 下也有效。将你的 MCP 客户端连接到生成的 <url>/mcp 端点。此模式不显示二维码，并禁用 Web 终端、浏览器 WebSocket 和 REST API，因此无法通过浏览器观看或输入命令。MCP 发现和 /llms.txt 仍然可用。完整的 MCP URL 仍然授予对这台电脑的 shell 控制权。

同一个 URL 也适用于 AI 智能体。支持 MCP 的客户端可以使用 <url>/mcp（Streamable HTTP）来获得原生类型化工具。无法注册 MCP 服务器的智能体可以使用位于 <url>/api/agent/run 的 REST 回退，通过普通 HTTP 请求操作。任一路径都会创建一个持久化的智能体 shell，显示为一个 🤖 标签页，你可以从手机观看并接管。

把完整的生成 URL（包括其访问码）交给智能体。MCP 客户端可以从 <url>/.well-known/mcp.json（MCP server.json 描述符）自动发现服务器，还有一个人类/智能体可读的 <url>/llms.txt 说明用法。基础页面还包含面向浏览器驱动智能体的无障碍可见提示，同时人类 UI 保持紧凑。客户端配置示例：

{
  "mcpServers": {
    "porterminal": { "url": "https://<your-tunnel>.trycloudflare.com/<access-code>/mcp" }
  }
}

MCP 工具：run_command（干净输出 + 退出码）、read_screen、send_keys、send_signal（Ctrl-C / EOF）。

REST 回退：

curl -s -X POST https://<your-tunnel>.trycloudflare.com/<access-code>/api/agent/run \
  -H "content-type: application/json" \
  -d '{"command":"echo hello","timeout":30}'

响应包含一个 session_id；可将其与 <url>/api/agent/screen、 <url>/api/agent/keys、<url>/api/agent/signal 以及 DELETE <url>/api/agent/session 一起复用。

当你在手机上打开 Porterminal 时，右上角的复制按钮会复制同样的智能体就绪分享文本。仅浏览器智能体在基础页面上也有回退：一个 DOM 可读的 Terminal screen 镜像和一个清晰标注的 Terminal input。

安全： <url> 指完整的生成 URL，包括其随机访问码。裸隧道主机名不暴露任何内容，但任何（或任何智能体）拥有完整 URL 的人都会获得完整的、非提权的 shell 访问权限。参见 docs/agent-access.md。

手机手势

手势	操作
点击	聚焦终端，清除选择
长按	开始文本选择
双击	选择单词
左/右滑动	方向键（← →）
滚动	带物理效果的惯性滚动
双指捏合	缩放文本（10-24px）

修饰键（Ctrl、Alt、Shift）：点击一次为粘滞（一次按键），双击为锁定。

撰写模式（▤ 按钮）：切换一个文本输入框，你可以在其中输入或口述，使用完整的手机编辑功能（自动更正、建议、光标定位）编辑文本，然后发送到终端。适用于较长的命令或语音输入。

配置

运行 ptn --init 创建初始配置。它会从 package.json、pyproject.toml 或 Makefile 自动发现项目脚本，并将它们添加为按钮：

ptn -i
# Created: .ptn/ptn.yaml
# Discovered 3 project script(s): build, dev, test

或手动创建 ptn.yaml：

# Terminal settings
terminal:
  default_shell: nu              # Default shell ID
  shells:                        # Custom shell definitions
    - id: nu
      name: Nushell
      command: nu
      args: []

# Custom buttons (appear in toolbar)
# row: 1 = default row, 2+ = additional rows
buttons:
  - label: "claude"
    send:
      - "claude"
      - 100        # delay in ms
      - "\r"
  - label: "build"
    send: "npm run build\r"
    row: 2         # second button row

# 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 require password at startup
  password_hash: ""         # Saved password hash (use ptn -sp to set)
  max_auth_attempts: 5      # Max failed attempts before disconnect

配置按以下顺序搜索：$PORTERMINAL_CONFIG_PATH、./ptn.yaml、./.ptn/ptn.yaml、~/.ptn/ptn.yaml。

安全

每次启动都会创建一个新的 128 位随机路径，例如 https://<tunnel>.trycloudflare.com/<access-code>/。所有浏览器、WebSocket、 MCP、REST、健康检查和静态路由都要求该确切前缀；裸主机和错误路径返回 404。这使得对已发现的隧道主机名进行暴力破解变得不切实际。