porterminal v1.2.0

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

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

[!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。

安装

一行安装（uv + ptn）：

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

用法

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

运行期间： 隧道激活时，连接 URL 会出于隐私在屏幕上隐藏。按 c 复制智能体说明和 URL，包括 /mcp、/api/agent/run 和 /llms.txt；按 u 仅复制 URL；或扫描二维码连接。Ctrl+C 停止服务器。

智能体访问（MCP + REST）

若要在完全后台进行 shell 控制，请运行 ptn --mcp-only。 本地终端 UI 保持打开：按 c 复制智能体提示和 MCP 地址，或按 u 仅复制 MCP 地址。这些按键在 --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。

移动端手势

修饰键（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。这使得对已发现的隧道 主机名进行暴力破解变得不切实际。

完整的生成 URL 仍然是一个持有者凭据：任何获得它的人 都拥有 shell 访问权限。如果它泄露了，请重启 Porterminal 以轮换访问码。 可选的密码为浏览器 WebSocket 添加了身份验证，但 MCP 和 REST 继续信任完整 URL，以便智能体可以使用单链接工作流。

浏览器会在限定于该完整启动 URL 的明文存储中记住成功的密码。 为同一来源上较新的启动保存密码会淘汰较旧的 Porterminal 密码条目； 清除或拒绝记住的密码会移除所有条目，而不会触及浏览器其他存储。因此， 同一来源上的并发启动可能会再次提示，而已经 通过身份验证的连接保持连接。

从 UI： 打开设置（齿轮图标），使用安全部分设置/更改密码并切换密码要求。更改需要重启服务器。

从 CLI：

# One-time password (prompt each session)
ptn -p

# Save password to config (no prompt needed)
ptn -sp
# Password: ****
# Confirm password: ****

# Clear saved password (enter empty password)
ptn -sp
# Password: [press Enter]

# Set or toggle password requirement
ptn -tp          # Toggle on/off

详情参见 docs/security.md。

故障排除

连接失败？ 使用完整的生成 URL，包括其访问码。Cloudflare 隧道问题也可以通过重启服务器（Ctrl+C，然后 ptn）来解决，以获得新的隧道和访问路径。

uvx ptn 仍然运行较旧版本？ 现有的 uv tool 安装 可能优先。运行 uv tool upgrade ptn，或使用 uvx --isolated ptn@latest 绕过已安装的工具。

未检测到 shell？ 设置你的 $SHELL 环境变量，或在 ptn.yaml 中配置 shell。

贡献

本项目不接受外部贡献（拉取请求或代码 更改），出于安全原因（参见 CONTRIBUTING.md）。欢迎你 在 AGPL-3.0 下 fork 并运行自己的副本。

从源码运行：

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

许可证

AGPL-3.0