ngrok-surfaces

在用户使用的界面上应用 ngrok

Job skills 决定要构建什么——端点类型和策略，两者都在 ngrok-engine 中。此 skill 决定要在哪里应用，并将任务交给具体的实现方式。

配置本身不会因界面而改变。 策略正文、端点 URL、内部主机名都相同。只有封装方式不同。因此，用户切换界面时，切勿重新推导策略；只需重新封装。

选择界面

根据用户的项目判断，而不是询问：

信号	界面	参考
终端、端口、“只要给我一个 URL”	agent CLI / ngrok.yml	references/cli.md
存在 package.json、pyproject.toml、go.mod 或 Cargo.toml，且包含 ngrok 依赖；或者端点应随进程一起启动和终止	SDK	references/sdk.md
在运行时为每个租户／沙盒／设备创建资源的控制平面	REST API	references/api.md
*.tf 文件	Terraform	references/terraform.md
Chart.yaml、kustomization.yaml、k8s 清单	Kubernetes Operator	references/kubernetes-operator.md

如果这些信号都不明显，一次性任务默认使用 CLI 最稳妥。

真正区分这些方式的关键

不同界面的区别在于资源何时创建，以及由什么负责其生命周期：

• CLI 和 SDK 在运行时从工作负载内部创建资源。资源的生命周期与 Agent 或进程相同。
• Terraform 和 Operator 在部署时声明资源，适用于一组预先已知并提交到代码仓库中的端点。
• REST API 在运行时从工作负载外部创建资源，适用于一组事先未知的端点——每个沙盒、客户或设备一个，数量可达数千个。

Terraform 和 API 看似可以互换，实际并非如此。“我的账户有这三个端点”适合用 Terraform。“每个沙盒都要一个”适合用 API。后者请参阅 provision-sandbox-access。

单个设置通常会结合使用两种方式：API 或 Terraform 配置公有云端点，而 CLI 或 SDK 则从工作负载内部启动内部端点。两者通过约定的内部主机名会合。

不同界面的身份验证方式不同

• CLI 和 SDK 使用Agent authtoken（NGROK_AUTHTOKEN）。它只用于启动 Agent 会话。
• REST API、Terraform 和 Operator 使用API 密钥，用于管理账户。Operator 两者都需要。
• ngrok MCP 服务使用 OAuth，以用户身份和用户角色执行操作。它无需 API 密钥即可创建账户资源。请参阅下一节。

这些凭据不可互换，且各自的影响范围差异很大。如果调用因身份验证错误而失败，在轮换任何凭据之前，先确认当前使用的是哪种凭据。请参阅 ngrok-setup。

账户资源：MCP 服务或 API 密钥

有些任务会创建位于工作负载之外的账户资源：保留域名、保管库及其密钥、云端点。创建这些资源需要 ngrok MCP 服务或 API 密钥。使用第一个适用的选项：

1. 用户以代码形式管理 ngrok（*.tf 文件、Operator 清单）。在其中添加资源，以便设置保持可复现。仅使用 MCP 服务检查状态。
2. 已连接 ngrok MCP 服务（你可以调用其工具，例如 platform_whoami）。使用 MCP 服务创建资源，不要向用户索要 API 密钥。先调用 platform_whoami。它会显示用户的角色和套餐。如果用户的角色无权进行更改，或者套餐不包含该功能，服务会拒绝写入，因此请在尝试之前告知用户。
3. **未连接 MCP 服务。**使用用户设置的 API 密钥运行 ngrok api（参见 ngrok-setup），或使用控制面板。告知用户一次：使用 ngrok MCP 服务便无需在此处使用 API 密钥，然后继续操作。

资源	MCP 服务工具	使用 API 密钥的 CLI
保留域名	gw_reserve_domain	ngrok api reserved-domains create
保管库	gw_create_vault	ngrok api vaults create
密钥	gw_create_secret	ngrok api secrets create
云端点	gw_create_cloud_endpoint，然后使用 gw_update_cloud_endpoint 进行更改	ngrok api endpoints create

使用 MCP 服务时：

• gw_create_secret 从不接收密钥值。它会返回一个控制面板链接，用户可在其中输入密钥值，状态为 awaiting_user_action。用户提交表单后，密钥才会创建。使用相同参数以及结果中的 started_at 再次调用该工具。只有状态变为 complete 后，才能创建读取该密钥的策略。
• 创建云端点之前，先使用 endpoint_type 设为 cloud 的 gw_validate_traffic_policy 验证其策略。将策略保存在用户项目中的文件里，并告知用户你创建的资源 ID。这样用户就能在没有你的帮助时重新创建或移除设置。

以上顺序适用于你为用户执行的设置。在运行时创建资源的代码（例如 controlplane，参见 provision-sandbox-access）始终使用 API 密钥。

给 Agent 的说明

• 如果你有 shell，请亲自运行命令；返回结果，而不是操作说明。
• 如果已连接 ngrok MCP 服务，请在任何界面上应用设置前后使用它检查状态：使用 gw_list_endpoints 或带 URL 的 get_resource 确认端点已启用，并使用 gw_validate_traffic_policy 检查策略（参见 ngrok-engine）。
• 将策略单独保存在 policy.yaml 中，并引用该文件。这样用户之后添加第二个界面时，策略仍可移植；用户通常都会这么做。
• Kubernetes Operator 不支持 TCP 端点。如果用户需要在 k8s 上使用 TCP，请尽早说明，不要等到最后才发现。
• 不要凭记忆在不同界面之间移植配置——它们的结构差异足以导致故障，看起来像是网络问题。请阅读目标界面的参考文件。