ngrok-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set up ngrok

设置 ngrok

Get the user authenticated and pointed at the right surface. Every ngrok action requires a credential: an authtoken (agent/SDK), an API key (IaC and the REST API), or an OAuth login to the ngrok MCP server. There is no unauthenticated mode; this is deliberate abuse prevention.

让用户完成身份验证，并指向正确的使用方式。每个 ngrok 操作都需要凭据：authtoken（Agent/SDK）、API key（IaC 和 REST API），或通过 OAuth 登录 ngrok MCP server。不存在免认证模式；这是有意设置的滥用预防措施。

1. Figure out the surface

1. 确定使用方式

Pick from what the user is doing, then defer the how-to to that surface skill:

ngrok-surfaces

carries the routing table and the per-surface mechanics - read it off the user's project rather than asking. In short: a terminal means the agent CLI, an ngrok dependency in a manifest means the SDK,

*.tf

or k8s manifests mean infrastructure-as-code, and a controlplane provisioning per-tenant resources means the REST API.

If it is not obvious, the terminal path is the safe default for one-off tasks.

根据用户的操作选择使用方式，然后将具体操作方法交给对应的 surface skill：

ngrok-surfaces

包含路由表和各使用方式的操作机制——应从用户项目中判断，而不要询问。简而言之：terminal 意味着 Agent CLI，manifest 中有 ngrok 依赖意味着 SDK，

*.tf

或 k8s manifest 意味着 IaC，而 control plane 中配置 per-tenant resources 意味着 REST API。

如果不明确，对于一次性任务，默认选择 terminal 路径是安全的。

2. Authenticate

2. 身份认证

CLI / SDK (authtoken):

Check for an existing token:
```
ngrok config check
```
, and check the
```
NGROK_AUTHTOKEN
```
env var.
If none is set, have the user set it themselves - do not ask them to paste the token to you. Give them the link and the exact command to run:
Grab your authtoken from https://dashboard.ngrok.com/get-started/your-authtoken, then run:
```
ngrok config add-authtoken <YOUR_TOKEN>
```
On a headless box, or where the token comes from a secret store,
```
export NGROK_AUTHTOKEN=<YOUR_TOKEN>
```
in their environment does the same job.
Tell them to say when it is done, then re-run
```
ngrok config check
```
to confirm and carry on with the original task. Run every other ngrok command yourself - the authtoken is the one step that stays with the user.

IaC and the REST API (API key): Terraform, the operator, and

api.ngrok.com

authenticate with an ngrok API key (the operator needs an API key and an authtoken), not the agent authtoken. Point the user to https://dashboard.ngrok.com/api-keys and have them set it as the provider/operator credential or

NGROK_API_KEY

. See

ngrok-surfaces

Before you ask for an API key, check whether the ngrok MCP server is connected. If it is, a one-off account resource such as a vault, a secret, or a cloud endpoint needs no API key.

ngrok-surfaces

says when to use which.

The two credentials are not interchangeable and have very different blast radii: an API key administers the account, an authtoken only starts agent sessions. If a call fails with an auth error, check which one is in play before rotating anything.

ngrok MCP server (OAuth): gives you, the agent, access to the user's account with the user's role permissions. It can read and change resources, so keep the client's approval prompts on. It is a third credential, separate from both of the above. CLI authtokens and API keys do not authenticate it. The server is at

https://mcp.ngrok.com/mcp

(streamable HTTP) and is available on all plans, including free. If the user asks to connect it, give them the commands for their client from the MCP server docs. Login is a browser step the user does themselves, like the authtoken.

If the server is already connected, use it to check instead of asking:

platform_whoami

names the account, the caller's role, and the plan.

platform_list_authtokens

and

platform_list_api_keys

show which credentials exist and who owns them. No tool returns a secret value.

CLI / SDK（authtoken）：

检查现有 token：运行
```
ngrok config check
```
，并检查
```
NGROK_AUTHTOKEN
```
环境变量。
如果尚未设置，让用户自行设置——不要让他们将 token 粘贴给你。 提供链接和需要运行的准确命令：
从 https://dashboard.ngrok.com/get-started/your-authtoken 获取你的 authtoken，然后运行：
```
ngrok config add-authtoken <YOUR_TOKEN>
```
在 headless 环境中，或者当 token 来自 secret store 时，在其环境中执行
```
export NGROK_AUTHTOKEN=<YOUR_TOKEN>
```
效果相同。
请用户完成后告知你，然后重新运行
```
ngrok config check
```
以确认配置，并继续执行原始任务。其他所有 ngrok 命令都由你运行——authtoken 这一步始终由用户自行完成。

IaC 和 REST API（API key）： Terraform、operator 和

api.ngrok.com

使用 ngrok API key 进行身份验证（operator 需要 API key 和 authtoken），而不是 Agent authtoken。请用户访问 https://dashboard.ngrok.com/api-keys，并将其设置为 provider/operator 凭据或

NGROK_API_KEY

。参见

ngrok-surfaces

。

在要求用户提供 API key 之前，检查 ngrok MCP server 是否已连接。如果已连接，对于 vault、secret 或 cloud endpoint 等一次性 account resource，无需 API key。

ngrok-surfaces

会说明何时使用哪种凭据。

这两类凭据不可互换，权限影响范围也大不相同：API key 可以管理账户，而 authtoken 只能启动 Agent session。如果调用因身份验证错误而失败，请先确认使用的是哪一种凭据，再决定是否轮换。

ngrok MCP server（OAuth）： 让你这个 Agent 能够以用户的角色权限访问用户账户。它可以读取和更改资源，因此应保留客户端的审批提示。这是独立于上述两种凭据的第三类凭据。CLI authtoken 和 API key 均不能用于认证该 server。Server 地址为

https://mcp.ngrok.com/mcp

（streamable HTTP），所有套餐均可使用，包括免费套餐。如果用户要求连接它，请根据 MCP server 文档提供适用于其客户端的命令。与 authtoken 一样，登录需要由用户自行在浏览器中完成。

如果 server 已经连接，应使用它进行检查，而不是询问用户：

platform_whoami

会返回账户、调用者角色和套餐信息；

platform_list_authtokens

和

platform_list_api_keys

会显示存在哪些凭据以及由谁持有。任何工具都不会返回 secret 的值。

3. Make sure the tool is present

3. 确保工具已就绪

CLI: if
```
ngrok
```
is not installed, install it (
```
brew install ngrok
```
, or the platform package). Confirm with
```
ngrok --help
```
.
SDK: ensure the ngrok package for the language is a project dependency; see
```
ngrok-surfaces
```
.
IaC: ensure the provider/operator is configured; see
```
ngrok-surfaces
```
.
REST API: no tool to install - confirm the key works with a read call before writing provisioning code.

CLI：如果尚未安装 ngrok，请进行安装（
```
brew install ngrok
```
或使用对应平台的软件包）。通过
```
ngrok --help
```
确认安装成功。
SDK：确保相应语言的 ngrok package 已是项目 dependency；参见
```
ngrok-surfaces
```
。
IaC：确保 provider/operator 已配置；参见
```
ngrok-surfaces
```
。
REST API：无需安装工具——在编写 provisioning code 前，通过 read 调用确认 API key 可用。

4. Hand back

4. 返回原始任务

Once authenticated and the surface is ready, return to whatever the user actually asked for (expose a service, receive webhooks, etc.).

完成身份验证并准备好相应的使用方式后，返回用户最初实际要求的事项（暴露服务、接收 webhook 等）。

Notes for agents

给 Agent 的注意事项

Never ask the user to paste an authtoken, API key, or any other secret into the chat, and never accept one offered that way - tell them to set it themselves and continue once they confirm. A secret in a transcript has left their control: it is logged, and it is in your context for the rest of the session.
This is a single one-time action per machine. Frame it that way, not as a wall.
If a secret does end up in the conversation, do not repeat, echo, or print it. Acknowledge that it is set and move on, and suggest rotating it. The same goes for any token minted by
```
POST /credentials
```
.
If a later ngrok command fails with an auth error, come back here rather than retrying blindly.

绝不要要求用户将 authtoken、API key 或其他 secret 粘贴到聊天中，也不要接受用户以这种方式提供的 secret——应让用户自行设置，并在他们确认后继续。出现在对话记录中的 secret 已脱离用户控制：它会被记录，而且会在整个 session 期间保留在你的上下文中。
这台机器只需执行一次。应将其描述为一次性操作，而不是一道障碍。
如果 secret 最终出现在对话中，不要重复、回显或打印它。确认它已设置并继续执行，同时建议轮换。通过
```
POST /credentials
```
创建的任何 token 也应遵循同样的原则。
如果后续 ngrok 命令因身份验证错误而失败，请回到此流程处理，而不是盲目重试。