一条命令。一个 URL。为你的智能体提供真实终端，为你提供实时视图。
在 Windows、macOS 或 Linux 计算机上运行 Porterminal，并将生成的链接交给你的 AI 智能体。它就能获得一个真实 shell，可访问该机器上的文件、工具和项目。在手机或任意浏览器中打开同一链接，即可观看智能体的工作过程，并在其终端中输入内容。
在你想交给智能体的那台计算机上：
uvx ptn
c
复制 URL 和连接说明。将它们连同任务一起粘贴到你的 agent 中。
agent 需要支持远程 MCP，或者具备发起 HTTP 请求的方式。要在特定项目中启动，请使用 uvx ptn /path/to/project。
有关安装选项，请参阅 installation，或使用下方的安装程序。
链接就是电脑的钥匙。 完整 URL 和二维码可授予 shell 访问权限。请仅与你信任的人和 agent 分享。 阅读安全模型。
| 你的 agent | 你 |
|---|---|
| 在电脑的真实 shell 中运行命令 | 在浏览器中实时观看相同的输出 |
| 读取终端屏幕并回答提示 | 在需要时向同一终端输入 |
| 在多次工具调用之间保持 shell 状态 | 在 agent 标签页和个人标签页之间切换 |
| 使用 MCP 或 HTTP 连接 | 从手机或桌面使用二维码或 URL |
终端输入是共享的；请与你的 agent 协调输入。Porterminal 支持交互式终端应用、多个标签页，以及在服务器和会话保持存活时重新连接到正在运行的 会话。
手机 UI 包含 Ctrl/Alt/Shift 键、触摸选择、滚动、 双指缩放，以及用于编辑或口述较长输入的撰写字段。 请参阅 terminal controls。
给 agent 一个带有失败检查的小型发票项目。观察它找到 bug、编辑文件，并让检查通过。然后从你的手机回答收据的标签 提示，并让 agent 读取结果。
demo guide 包含一个可直接复制的项目、一个 agent 任务， 以及一个 60 秒的录制计划。它在一个共享会话中演示了命令、文件更改、 验证和人工输入。
按 c 会复制可用连接方法的说明。
正在运行的服务器也会在 <url>/llms.txt 提供这些说明。
此处，<url> 是生成的完整 URL，包括其访问码。
| agent 能力 | 连接方式 |
|---|---|
| 远程 MCP | <url>/mcp — Streamable HTTP |
| HTTP 请求 | <url>/api/agent/run — REST |
| 浏览器自动化 | 打开 <url>/；使用 Terminal screen 和 Terminal input |
MCP 暴露四个工具：run_command、read_screen、send_keys 和
send_signal。REST 返回一个 session_id，agent 在后续
命令和交互中复用它。agent shell 在你的浏览器中显示为 🤖 标签页。
有关客户端设置、请求示例、 会话生命周期和长时间运行的命令，请参阅 agent access。
需要 Python 3.12+。当 cloudflared 缺失时，Porterminal 会尝试
自动安装它。
| 方式 | 运行或安装 | 更新 |
|---|---|---|
| uvx | uvx ptn | uvx --isolated 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 和 Porterminal：
Windows (PowerShell)：
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/porterminal/porterminal/master/install.ps1 | iex"
macOS / Linux：
curl -LsSf https://raw.githubusercontent.com/porterminal/porterminal/master/install.sh | sh
安装后，运行 ptn 或 ptn /path/to/project。
| 选项 | 用途 |
|---|---|
--no-tunnel | 不使用 Cloudflare 隧道运行 |
--mcp-only | 仅暴露 MCP；禁用二维码、浏览器终端和 REST API |
--compose | 启动时启用移动端 compose 字段 |
--init | 生成 .ptn/ptn.yaml，其中包含从项目脚本中发现的按钮 |
--password | 为浏览器终端访问添加密码 |
--help | 显示所有选项 |
--version | 显示已安装的版本 |
运行期间：c 复制 agent 指令，u 仅复制 URL，s 在屏幕上显示分享文本（q 关闭它）。
Ctrl+C 停止 Porterminal。在仅 MCP 模式下，分享键使用 MCP URL。
自定义 shell、工具栏按钮和启动设置位于 ptn.yaml 中。
参见配置。
Porterminal 提供以你的用户权限访问真实 shell 的能力。起始目录只是便利设置，并非沙箱，也不限制文件访问。
每次启动都会创建一个新的 128 位随机访问路径。裸隧道主机名和错误路径会返回 404，但任何拥有完整 URL 的人都可以使用该 shell。 请对 URL 和二维码保密，完成后停止 Porterminal，并在链接泄露时重启它以轮换访问码。
可选密码保护浏览器连接。MCP 和 REST 使用完整 URL 作为凭据，不需要该密码。
有关完整模型和密码行为，参见安全。 请通过安全策略报告漏洞。
欢迎通过 issues 提交 bug 报告和功能请求。 不接受外部 pull request 和代码贡献；参见 CONTRIBUTING.md。你可以 fork 并运行自己的副本。