Back to Details

ngrok-engine

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

The ngrok engine: endpoints and Traffic Policy

ngrok 引擎：endpoints 与 Traffic Policy

Two decisions sit behind almost every ngrok task:
  1. What kind of endpoint? Agent, cloud, or internal - and on what protocol.
  2. What should happen to the traffic? The Traffic Policy that runs at the edge.
This skill answers both at the level a job skill needs, and holds the detail in 
references/
. Where to apply the result is a separate question - see 
ngrok-surfaces
.
Make these decisions from the user's intent. Do not ask them to choose an endpoint type; they should not have to know the taxonomy.
几乎每项 ngrok 任务背后都有两个决策：
  1. 使用哪种 endpoint？ Agent、cloud 还是 internal，以及采用什么协议。
  2. 应该如何处理流量？ 在 edge 上运行的 Traffic Policy。
此 skill 从 job skill 所需的层面回答这两个问题，并将详细信息保存在 
references/
中。在哪里应用结果是一个独立问题——请参阅 
ngrok-surfaces
。
应根据用户的意图作出这些决策。不要让用户选择 endpoint 类型；他们不应该需要了解这套分类体系。

1. Endpoint type

1. Endpoint 类型

  • Agent endpoint - created by a running agent or SDK process, lives only as long as that process. Ephemeral, local, demos, tests.
  • Cloud endpoint - created via API, dashboard, or IaC, independent of any agent. Always-on, stable URL. Production front doors, and anything a third party connects to on its own schedule.
  • Internal endpoint - no public URL. Reachable only through a 
    forward-internal
    action. This is how a receiver stays off the public internet.
The composed shape most jobs land on:
cloud endpoint (public, runs the policy) -> forward-internal -> internal endpoint -> local service
Protocol is a separate axis from type. HTTP is the default; TCP (SSH, RDP, databases) changes several things - a public TCP endpoint needs a reserved address, internal TCP URLs need an explicit port, the policy phase becomes 
on_tcp_connect
, and the Kubernetes operator does not support TCP at all.
Full decision logic, bindings, and the TCP rules: 
references/endpoints.md
.
  • Agent endpoint——由正在运行的 agent 或 SDK 进程创建，仅在该进程存续期间存在。适用于临时、本地、演示和测试场景。
  • Cloud endpoint——通过 API、dashboard 或 IaC 创建，不依赖任何 agent。始终在线且 URL 稳定。适用于生产环境入口，以及任何由第三方按自己的时间安排发起连接的服务。
  • Internal endpoint——没有公开 URL，仅可通过 
    forward-internal
    action 访问。这样可以让接收端远离公共互联网。
大多数任务最终采用以下组合形态：
cloud endpoint（公开，运行 policy）-> forward-internal -> internal endpoint -> 本地服务
协议是与类型相互独立的维度。HTTP 是默认协议；TCP（SSH、RDP、数据库）会改变若干事项——公开 TCP endpoint 需要预留地址，internal TCP URL 需要显式指定端口，policy phase 会变为 
on_tcp_connect
，而 Kubernetes operator 完全不支持 TCP。
完整的决策逻辑、bindings 和 TCP 规则：
references/endpoints.md
。

2. Traffic Policy

2. Traffic Policy

Rules grouped by phase. Each rule has optional CEL 
expressions
and a list of 
actions
.
yaml
on_http_request:
  - expressions:
      - "req.url.path.startsWith('/admin')"
    actions:
      - type: deny
  • Phases: 
    on_http_request
    , 
    on_http_response
    , 
    on_tcp_connect
    , 
    on_event_stream_message
    .
  • Rules run in order, and a terminating action ends the chain. Every Cloud Endpoint policy must end with a terminating action; agent endpoints need not.
  • The policy body is identical on every surface. Only attachment differs.
Grammar, CEL variables, Secrets and Vaults, the seven most-used actions, and how actions chain: 
references/traffic-policy.md
.
规则按 phase 分组。每条规则都有可选的 CEL 
expressions
和一个 
actions
列表。
yaml
on_http_request:
  - expressions:
      - "req.url.path.startsWith('/admin')"
    actions:
      - type: deny
  • Phases：
    on_http_request
    、
    on_http_response
    、
    on_tcp_connect
    、
    on_event_stream_message
    。
  • 规则按顺序运行，终止性 action 会结束整个 chain。每个 Cloud Endpoint policy 都必须以终止性 action 结尾；agent endpoint 则无需如此。
  • **policy body 在所有 surface 上都完全相同。**区别仅在于附加方式。
语法、CEL 变量、Secrets 与 Vaults、最常用的七个 actions，以及 actions 如何串联：
references/traffic-policy.md
。

The action vocabulary

Action 词汇表

All 26 actions, so you know what exists without fetching anything:
<!-- BEGIN generated: action-names -->
  • connection modification: 
    deny
    , 
    forward-internal
    , 
    http-request
    , 
    log
    , 
    restrict-ips
    , 
    set-vars
    , 
    terminate-tls
  • request modification: 
    add-headers
    , 
    circuit-breaker
    , 
    log
    , 
    owasp-crs-request
    , 
    rate-limit
    , 
    redirect
    , 
    remove-headers
    , 
    request-body-find-replace
    , 
    set-vars
    , 
    url-rewrite
  • response modification: 
    add-headers
    , 
    compress-response
    , 
    custom-response
    , 
    log
    , 
    owasp-crs-response
    , 
    remove-headers
    , 
    response-body-find-replace
    , 
    set-vars
    , 
    sse-find-replace
  • security: 
    basic-auth
    , 
    jwt-validation
    , 
    oauth
    , 
    openid-connect
    , 
    owasp-crs-request
    , 
    owasp-crs-response
    , 
    restrict-ips
    , 
    terminate-tls
    , 
    verify-webhook
  • traffic control: 
    circuit-breaker
    , 
    close-connection
    , 
    deny
    , 
    forward-internal
    , 
    http-request
    , 
    owasp-crs-request
    , 
    owasp-crs-response
    , 
    rate-limit
<!-- END generated: action-names -->
Never guess an action's config. Look it up in two steps:
  1. references/action-catalog.md
    - the index. One row per action: phases, whether it ends the chain, what it does.
  2. references/actions/<action>.md
    - that action's config fields, result variables, and an example.
Read only the action file you need; the whole directory is ~12k tokens and one action is a few hundred.
完整列出全部 26 个 actions，无需获取其他内容即可知道有哪些可用项：
<!-- BEGIN generated: action-names -->
  • 连接修改：
    deny
    、
    forward-internal
    、
    http-request
    、
    log
    、
    restrict-ips
    、
    set-vars
    、
    terminate-tls
  • 请求修改：
    add-headers
    、
    circuit-breaker
    、
    log
    、
    owasp-crs-request
    、
    rate-limit
    、
    redirect
    、
    remove-headers
    、
    request-body-find-replace
    、
    set-vars
    、
    url-rewrite
  • 响应修改：
    add-headers
    、
    compress-response
    、
    custom-response
    、
    log
    、
    owasp-crs-response
    、
    remove-headers
    、
    response-body-find-replace
    、
    set-vars
    、
    sse-find-replace
  • 安全：
    basic-auth
    、
    jwt-validation
    、
    oauth
    、
    openid-connect
    、
    owasp-crs-request
    、
    owasp-crs-response
    、
    restrict-ips
    、
    terminate-tls
    、
    verify-webhook
  • 流量控制：
    circuit-breaker
    、
    close-connection
    、
    deny
    、
    forward-internal
    、
    http-request
    、
    owasp-crs-request
    、
    owasp-crs-response
    、
    rate-limit
<!-- END generated: action-names -->
**绝不要猜测 action 的 config。**请通过以下两步进行查询：
  1. references/action-catalog.md
    ——索引。每个 action 占一行，列出适用 phases、是否会结束 chain 以及具体作用。
  2. references/actions/<action>.md
    ——该 action 的 config 字段、结果变量和示例。
只读取所需的 action 文件；整个目录约为 12k tokens，而单个 action 只有几百 tokens。

Notes for agents

Agent 注意事项

  • The seven actions written out in 
    references/traffic-policy.md
    are the ones existing job skills happen to use. They are not the interesting half - reach for the catalog whenever the task needs anything else.
  • Many actions enforce on their own (
    rate-limit
    returns its own 429, 
    verify-webhook
    fails closed). Check the action's entry before adding a 
    deny
    that duplicates it.
  • Keep the policy in its own 
    policy.yaml
    so it survives the user adding a second surface later.
  • If the ngrok MCP server is connected, run every policy you write or edit through 
    gw_validate_traffic_policy
    before you show or apply it. It runs the same checks as a save, including plan entitlements, and reports each problem with its line and column. Pass 
    endpoint_type
    , 
    scheme
    , and 
    binding
    when the policy is for a cloud, TCP, or internal endpoint.
  • references/traffic-policy.md
    中明确写出的七个 actions，是现有 job skills 恰好会使用的那些。但值得关注的功能远不止这些——任务需要其他 action 时，应查阅 catalog。
  • 许多 actions 会自行执行强制策略（
    rate-limit
    会自行返回 429，
    verify-webhook
    会采用 fail-closed 行为）。在添加可能与其重复的 
    deny
    之前，先查看该 action 的条目。
  • 将 policy 保存在独立的 
    policy.yaml
    中，以便用户之后添加第二个 surface 时仍可继续使用。
  • 如果已连接 ngrok MCP server，请在展示或应用之前，将编写或编辑的每个 policy 都通过 
    gw_validate_traffic_policy
    运行校验。它执行的检查与保存时相同，包括 plan entitlements，并会报告每个问题所在行和列。如果 policy 用于 cloud、TCP 或 internal endpoint，请传入 
    endpoint_type
    、
    scheme
    和 
    binding
    。