ngrok-surfaces
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseApplying ngrok on the user's surface
在用户的 surface 上应用 ngrok
Job skills decide what to build - the endpoint type and the policy, both in . This skill decides where to apply it and hands off to the mechanics.
ngrok-engineThe configuration itself does not change across surfaces. The same policy body, the same endpoint URL, the same internal hostname. Only the wrapper differs. So never re-derive a policy because the user switched surfaces; re-wrap it.
Job skill 决定 构建什么——endpoint 类型和 policy,二者都在 中。本 skill 决定 在哪里应用,然后交给具体机制处理。
ngrok-engine配置本身不会因 surface 而异。 policy body、endpoint URL 和内部 hostname 都相同,只有包装形式不同。因此,当用户切换 surface 时,绝不要重新推导 policy;只需重新封装。
Pick the surface
选择 surface
Read it off the user's project rather than asking:
| Signal | Surface | Reference |
|---|---|---|
| A terminal, a port, "just give me a URL" | agent CLI / | |
| SDK | |
| A controlplane creating resources per tenant/sandbox/device at runtime | REST API | |
| Terraform | |
| Kubernetes Operator | |
If none of these is obvious, the CLI is the safe default for a one-off task.
从用户项目中读取线索,而不是询问:
| 信号 | Surface | 参考文件 |
|---|---|---|
| 终端、端口、"just give me a URL" | agent CLI / | |
| SDK | |
| controlplane 在运行时为每个 tenant/sandbox/device 创建资源 | REST API | |
| Terraform | |
| Kubernetes Operator | |
如果这些线索都不明显,对于一次性任务,CLI 是安全的默认选择。
The axis that actually separates them
真正区分它们的维度
Surfaces differ by when the resource is created and what owns its lifetime:
- CLI and SDK create it at run time, from inside the workload. It lives as long as the agent or process does.
- Terraform and the Operator declare it at deploy time, for a set of endpoints known in advance and checked into a repo.
- The REST API creates it at run time from outside the workload, for a set that is not known in advance - one per sandbox, customer, or device, with thousands of them.
Terraform and the API look interchangeable and are not. "My account has these three endpoints" is Terraform. "Every sandbox gets one" is the API. See for the latter.
provision-sandbox-accessA single setup often uses two: the API or Terraform provisions the public cloud endpoint, and the CLI or SDK brings up the internal endpoint from inside the workload. They rendezvous on an agreed internal hostname.
surface 的差异在于 资源何时创建以及谁负责其生命周期:
- CLI 和 SDK 在运行时从 workload 内部创建资源。其生命周期与 agent 或 process 相同。
- Terraform 和 Operator 在部署时声明资源,用于一组预先已知且已提交到 repo 的 endpoint。
- REST API 在运行时从 workload 外部创建资源,用于一组预先未知的资源——每个 sandbox、customer 或 device 一个,数量可达数千。
Terraform 和 API 看起来可以互换,但事实并非如此。"我的账户有这三个 endpoint"属于 Terraform。"每个 sandbox 都有一个"属于 API。后者参见 。
provision-sandbox-access单个设置通常会同时使用两者:API 或 Terraform 配置公共 cloud endpoint,CLI 或 SDK 在 workload 内部启动内部 endpoint。二者通过约定的内部 hostname 对接。
Auth differs by surface
各 surface 的认证方式不同
- CLI and SDK use an agent authtoken (). It starts agent sessions and nothing else.
NGROK_AUTHTOKEN - REST API, Terraform, and the Operator use an API key. It administers the account. The Operator needs both.
- The ngrok MCP server uses OAuth and acts as the user, with the user's role. It can create account resources without an API key. See the next section.
These are not interchangeable and have very different blast radii. If a call fails with an auth error, check which credential is in play before rotating anything. See .
ngrok-setup- CLI 和 SDK 使用 agent authtoken()。它仅用于启动 agent session,不用于其他用途。
NGROK_AUTHTOKEN - REST API、Terraform 和 Operator 使用 API key。它用于管理账户。Operator 两者都需要。
- ngrok MCP server 使用 OAuth,并以用户身份和用户角色执行操作。它无需 API key 即可创建账户资源。参见下一节。
这些凭据不可互换,影响范围也大不相同。如果调用因 auth 错误而失败,先检查当前使用的是哪种凭据,再轮换任何凭据。参见 。
ngrok-setupAccount resources: the MCP server or an API key
账户资源:MCP server 或 API key
Some jobs create account resources that live outside the workload: a reserved domain, a vault and its secrets, a cloud endpoint. You need the ngrok MCP server or an API key to create them. Use the first option that applies:
- The user manages ngrok as code (files, Operator manifests). Add the resource there, so the setup stays reproducible. Use the MCP server only to check state.
*.tf - The ngrok MCP server is connected (you can call its tools, such as ). Create the resource with the MCP server, and do not ask the user for an API key. Call
platform_whoamifirst. It names the user's role and plan. The server refuses a write when the role cannot make the change or the plan does not include the feature, so tell the user that before you try.platform_whoami - The MCP server is not connected. Use with an API key that the user sets (see
ngrok api), or the dashboard. Tell the user once that the ngrok MCP server removes the need for an API key here, then continue.ngrok-setup
| Resource | MCP server tool | CLI with an API key |
|---|---|---|
| Reserved domain | | |
| Vault | | |
| Secret | | |
| Cloud endpoint | | |
When you use the MCP server:
- never takes the value. It returns a dashboard link where the user types the value, with status
gw_create_secret. The secret does not exist until the user saves the form. Call the tool again with the same arguments and theawaiting_user_actionfrom the result. Create a policy that reads the secret only after the status isstarted_at.complete - Before you create a cloud endpoint, run its policy through with
gw_validate_traffic_policyset toendpoint_type. Keep the policy in a file in the user's project, and give the user the IDs of what you created. Then the user can recreate or remove the setup without you.cloud
This order is for setup that you do for the user. Code that creates resources at run time, such as a controlplane (see ), always uses an API key.
provision-sandbox-access有些 job 会创建位于 workload 之外的账户级资源:reserved domain、vault 及其 secrets、cloud endpoint。需要 ngrok MCP server 或 API key 才能创建这些资源。优先选择以下第一个适用方案:
- 用户以代码方式管理 ngrok(文件、Operator manifests)。将资源添加在那里,使设置保持可复现。仅使用 MCP server 检查状态。
*.tf - ngrok MCP server 已连接(可以调用其工具,例如 )。使用 MCP server 创建资源,不要向用户索要 API key。首先调用
platform_whoami。它会返回用户的角色和套餐。如果角色无权进行更改或套餐不包含该功能,server 会拒绝写入,因此尝试之前先告知用户。platform_whoami - MCP server 未连接。 使用 并由用户设置 API key(参见
ngrok api),或使用 dashboard。告知用户一次:ngrok MCP server 在这里无需 API key,然后继续。ngrok-setup
| 资源 | MCP server 工具 | 使用 API key 的 CLI |
|---|---|---|
| Reserved domain | | |
| Vault | | |
| Secret | | |
| Cloud endpoint | | |
使用 MCP server 时:
- 从不接收 secret 的值。它返回一个 dashboard 链接,供用户在其中输入值,状态为
gw_create_secret。在用户保存表单之前,secret 并不存在。使用相同参数以及结果中的awaiting_user_action再次调用该工具。仅当状态为started_at后,才创建读取该 secret 的 policy。complete - 创建 cloud endpoint 前,先通过 验证其 policy,并将
gw_validate_traffic_policy设为endpoint_type。将 policy 保存在用户项目中的文件里,并向用户提供所创建资源的 ID。这样用户无需你协助即可重新创建或移除该设置。cloud
此顺序适用于你代用户执行的设置。像 controlplane(参见 )这样在运行时创建资源的代码,始终使用 API key。
provision-sandbox-accessNotes for agents
给 Agent 的注意事项
- Run the commands yourself when you have a shell; hand back the result, not instructions.
- If the ngrok MCP server is connected, use it to check state before and after you apply on any surface: or
gw_list_endpointswith the URL to confirm the endpoint is live, andget_resourceto check a policy (seegw_validate_traffic_policy).ngrok-engine - Keep the policy in its own and reference it. That is what makes it portable when the user adds a second surface later, which they usually do.
policy.yaml - TCP endpoints are not supported by the Kubernetes Operator. If the user needs TCP on k8s, surface that early rather than discovering it late.
- Do not port config between surfaces from memory - the shapes differ enough to fail in ways that look like network problems. Read the target surface's reference file.
- 有 shell 时,亲自运行命令;返回结果,而不是操作说明。
- 如果 ngrok MCP server 已连接,在任何 surface 上应用前后都用它检查状态:使用 ,或使用
gw_list_endpoints并传入 URL,以确认 endpoint 已上线;使用get_resource检查 policy(参见gw_validate_traffic_policy)。ngrok-engine - 将 policy 单独保存在 中并引用它。这样当用户以后添加第二个 surface 时(通常都会如此),配置仍可移植。
policy.yaml - Kubernetes Operator 不支持 TCP endpoints。如果用户需要在 k8s 上使用 TCP,应尽早明确指出这一限制,而不是等到后期才发现。
- 不要凭记忆在不同 surface 之间移植配置——它们的结构差异很大,可能以看似网络问题的方式失败。请阅读目标 surface 的参考文件。