Skip to content
Back to search

tunnel-client

SkillOfficial: OpenAIGitHub

Customer-run client for Secure MCP Tunnel: connect private or localhost MCP servers to ChatGPT, Codex, the Responses API, and AgentKit without exposing them to the public internet.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/openai/tunnel-client with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/openai/tunnel-client'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openai--tunnel-client/badge.svg)](/listings/openai--tunnel-client)

HTML

<a href="/listings/openai--tunnel-client"><img src="/api/listings/openai--tunnel-client/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

On macOS, Homebrew is the supported installation path. Directly downloaded release ZIPs are not currently notarized and can be blocked by Gatekeeper. If a manually downloaded archive is blocked, do not use `xattr`, `spctl`, or **Open Anyway** to bypass the check; install from the official OpenAI tap instead:

brew install openai/tools/tunnel-client

Verify the installed version, then start with the guided setup:

tunnel-client --version
tunnel-client help quickstart

The Formula installs the matching `tunnel-client`, bundled `cloudflared`, and companion manifest together, while exposing only the `tunnel-client` command. For Docker, Kubernetes, or VM deployments, see [`docs/deployment/overview.md`](docs/deployment/overview.md).

To generate the shareable guide output locally:

make end-user-guide-screenshots
make end-user-guide-html
make end-user-guide-slides

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 962 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Secure MCP Tunnel client
  2. `tunnel-client` is the customer-run agent behind Secure MCP Tunnel. It connects
  3. a private or localhost MCP (Model Context Protocol) server to ChatGPT, Codex,
  4. the Responses API, and AgentKit through an OpenAI-hosted MCP tunnel endpoint,
  5. while keeping the MCP server off the public internet.
  6. This CLI and its [Go SDK](#embed-as-a-go-sdk) run beside your private MCP server.
  7. Applications call the OpenAI-hosted `/v1/mcp/{tunnel_id}` endpoint through their
  8. MCP transport; the runtime receives those requests and delivers responses.
  9. The poll/response endpoints are the runtime's queue protocol for client
  10. implementers. See the [architecture](docs/architecture.md) for the request flow
  11. and the [protocol](docs/protocol.md) when building a compatible runtime.
  12. Use it when:
  13. - You have an MCP server on a laptop, VM, Kubernetes cluster, or private
  14. network and need an OpenAI-hosted product to reach it.
  15. - Security will not approve a new inbound firewall rule or public endpoint for
  16. the MCP server.
  17. - You want an operator-visible daemon with `/healthz`, `/readyz`, `/metrics`,
  18. and `/ui` before a connector or API call depends on it.
  19. If you searched for "secure MCP tunnel", "MCP tunnel ChatGPT", "connect local
  20. MCP server to ChatGPT", "connect local MCP server to Codex", "localhost to
  21. ChatGPT", or "Codex local MCP", start with `tunnel-client help quickstart`,
  22. then read the onboarding guide below.
  23. ## Start Here
  24. - **Selecting a regional control-plane endpoint?** Use
  25. `--control-plane.residency`, `CONTROL_PLANE_RESIDENCY`, or YAML
  26. `control_plane.residency`. See the [endpoint catalog and mTLS settings](docs/configuration.md#residency-endpoint-selection).
  27. Endpoint selection is independent of regional Tunnel service availability.
  28. - **Need the shortest working path from localhost or a private MCP server to
  29. ChatGPT or Codex?** Start with [`docs/onboarding.md`](docs/onboarding.md).
  30. - **Need the customer-shareable network and trust-boundary story?** Read
  31. [`docs/architecture.md`](docs/architecture.md).
  32. - **Need roles, groups, tunnel IDs, or API keys?** Read
  33. [`docs/permissions.md`](docs/permissions.md).
  34. - **Need Docker, Kubernetes, or VM deployment guidance?** Read
  35. [`docs/deployment/overview.md`](docs/deployment/overview.md).
  36. - **Need to debug readiness, connector discovery, or OAuth?** Read
  37. [`docs/troubleshooting.md`](docs/troubleshooting.md).
  38. - **Building a compatible client in another language?** Read
  39. [`docs/protocol.md`](docs/protocol.md) and use
  40. [`docs/openapi.json`](docs/openapi.json). Optional client features use the
  41. common [`X-Tunnel-Client-Capabilities` header](docs/protocol.md#tunnel-client-capabilities).
  42. - **Upgrading for server-directed polling placement?** Read the
  43. [routing correction and activation notes](docs/routing-correction.md).
  44. Supporting clients work with existing services immediately; corrections are
  45. enabled separately after client release. No configuration change is needed.
  46. - **Using MCP timing or distributed tracing?** Read the
  47. [timing release and rollback guidance](docs/configuration.md#response-timing-compatibility).
  48. Trace forwarding is disabled by default; opt in with
  49. `--mcp.forward-trace-context` to carry W3C trace context in MCP `params._meta`
  50. over stdio and Streamable HTTP.
  51. Opt-in [local span export](docs/configuration.md#local-tracing) uses
  52. `--tracing.enabled --tracing.file=/private/new-trace.jsonl`. Complete traces
  53. require compatible service queue handoff and caller parent propagation first.
  54. - **Forwarding the original HTTP request ID?** MCP HTTP forwarding is enabled
  55. by default. Use `--forward-request-id=mcp,harpoon` to include Harpoon REST
  56. requests, `--forward-request-id=mcp,oauth` to include eligible queued OAuth
  57. discovery requests, or `--forward-request-id=none` to disable
  58. automatic forwarding.
  59. The same setting is available as `FORWARD_REQUEST_ID` or top-level YAML
  60. `forward_request_id`; see [request ID forwarding](docs/configuration.md#request-id-forwarding).
  61. - **Using a namespaced tunnel ID?** Preserve the full ID returned by the service.
  62. The client accepts legacy IDs and aliases with a four-character namespace;
  63. see [tunnel identifiers](docs/protocol.md#scope).
  64. - **Embedding an MCP server directly in a Go process?** Use the Go SDK with
  65. the MCP SDK's in-memory transport; see
  66. [`examples/go-sdk-inmemory`](examples/go-sdk-inmemory).
  67. ## Try the embedded demo
  68. With a runtime API key and tunnel ID, run the built-in `server_info`, `echo`,
  69. and `uppercase` tools without a separate MCP server:
  70. ```bash
  71. export CONTROL_PLANE_API_KEY="sk-..."
  72. export CONTROL_PLANE_TUNNEL_ID="tunnel_0123456789abcdef0123456789abcdef"
  73. tunnel-client run --embedded-stateless-mcp-stub --health.listen-addr 127.0.0.1:0
  74. ```
  75. `--embedded-stateless-mcp-stub` uses stateless MCP handling even when a client
  76. sends `initialize` and `notifications/initialized`. It issues no MCP session
  77. ID, and these demo tools do not require MCP session affinity between processes.
  78. OAuth and application state have separate requirements.
  79. `--embedded-mcp-stub` keeps its existing compatibility behavior: legacy
  80. initialization and session requests use stateful handling; self-contained
  81. modern discovery and tool requests use stateless handling. Choose one embedded
  82. mode per run. Both share the embedded listen-address, Unix-socket, server-name, and
  83. server-version options; see [embedded demo configuration](docs/configuration.md#embedded-demo-mcp-modes)
  84. for defaults and target conflicts.
  85. ## Embed as a Go SDK
  86. The module can run in the same process as a Go MCP server. The MCP server does
  87. not need to bind a port or use stdio: give the server side of an in-memory MCP
  88. transport pair to your server and the client side to `tunnelclient.New`.
  89. ~~~bash
  90. go get github.com/openai/tunnel-client
  91. ~~~
  92. ~~~go
  93. import (
  94. "context"
  95. "github.com/modelcontextprotocol/go-sdk/mcp"
  96. tunnelclient "github.com/openai/tunnel-client"
  97. )
  98. ctx := context.Background()
  99. server := mcp.NewServer(&mcp.Implementation{Name: "my-server", Version: "1.0.0"}, nil)
  100. serverTransport, tunnelTransport := mcp.NewInMemoryTransports()
  101. go server.Run(ctx, serverTransport)
  102. client, err := tunnelclient.New(tunnelclient.Config{
  103. TunnelID: "tunnel_0123456789abcdef0123456789abcdef",
  104. APIKey: apiKey,
  105. }, tunnelTransport)
  106. if err != nil {
  107. return err
  108. }
  109. return client.Run(ctx)
  110. ~~~
  111. The runnable [Go SDK example](examples/go-sdk-inmemory) registers an `echo`
  112. tool and connects it to the OpenAI Tunnel control plane.
  113. If your gateway serves tunnel runtime requests under a custom path, set
  114. `--control-plane.tunnel-base-path=/custom/tunnels` or set `Config.TunnelBasePath`
  115. in the Go SDK. The default is `/v1/tunnels`. To send an extra header on runtime
  116. requests, pass `--control-plane.extra-headers "X-Example-Header: example"` or
  117. set `Config.ControlPlaneExtraHeaders` in the SDK.
  118. [Configuration reference](docs/configuration.md#other-control-plane-settings)
  119. ## Documentation Map
  120. - **Public Secure MCP Tunnel guide**:
  121. [`developers.openai.com/api/docs/guides/secure-mcp-tunnels`](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
  122. - **Shareable end-user guide**: [`docs/end-user-guide.md`](docs/end-user-guide.md)
  123. - **Start here**: [`docs/onboarding.md`](docs/onboarding.md)
  124. - **Permissions, roles, and groups**: [`docs/permissions.md`](docs/permissions.md)
  125. - **Architecture diagrams**: [`docs/architecture.md`](docs/architecture.md)
  126. - **Connector behavior**: [`docs/connectors.md`](docs/connectors.md)
  127. - **Wire protocol for client implementers**: [`docs/protocol.md`](docs/protocol.md)
  128. - **OpenAPI contract**: [`docs/openapi.json`](docs/openapi.json)
  129. - **Enterprise customer handoff**:
  130. [`docs/enterprise-customer-onboarding.md`](docs/enterprise-customer-onboarding.md)
  131. - **Configuration reference**: [`docs/configuration.md`](docs/configuration.md)
  132. - **Deployment guides**: [`docs/deployment/overview.md`](docs/deployment/overview.md)
  133. - **Bundled Cloudflare companion**:
  134. [`docs/deployment/cloudflared.md`](docs/deployment/cloudflared.md)
  135. - **Troubleshooting**: [`docs/troubleshooting.md`](docs/troubleshooting.md), including
  136. [DNS diagnostic logs for Android / Termux](docs/troubleshooting.md#dns-failures-and-android--termux).
  137. - **Development & testing**: [`docs/development.md`](docs/development.md)
  138. - **In-memory Go SDK example**:
  139. [`examples/go-sdk-inmemory`](examples/go-sdk-inmemory)
  140. - **Roadmap / design notes**: [`docs/roadmap.md`](docs/roadmap.md)
  141. ## Install with Homebrew
  142. On macOS, Homebrew is the supported installation path. Directly downloaded
  143. release ZIPs are not currently notarized and can be blocked by Gatekeeper. If
  144. a manually downloaded archive is blocked, do not use `xattr`, `spctl`, or
  145. **Open Anyway** to bypass the check; install from the official OpenAI tap
  146. instead:
  147. ```bash
  148. brew install openai/tools/tunnel-client
  149. ```
  150. Verify the installed version, then start with the guided setup:
  151. ```bash
  152. tunnel-client --version
  153. tunnel-client help quickstart
  154. ```
  155. The Formula installs the matching `tunnel-client`, bundled `cloudflared`,
  156. and companion manifest together, while exposing only the `tunnel-client`
  157. command. It also installs Bash, Zsh, and Fish completions for that version.
  158. If your shell does not load them automatically, follow
  159. [Homebrew's shell completion setup](https://docs.brew.sh/Shell-Completion).
  160. For Docker, Kubernetes, or VM deployments, see
  161. [`docs/deployment/overview.md`](docs/deployment/overview.md).
  162. To generate the shareable guide output locally:
  163. ```bash
  164. make end-user-guide-screenshots
  165. make end-user-guide-html
  166. make end-user-guide-slides
  167. ```
  168. ### Start at macOS login
  169. The Homebrew Formula supports `brew services`. It supervises
  170. `tunnel-client run` using the profile at
  171. `$(brew --prefix)/etc/tunnel-client.yaml`, starts at login, and restarts the
  172. runtime after it exits. Installation and upgrades do not create or replace
  173. that profile.
  174. First, select the profile you already configured. If it belongs to a managed
  175. alias, find its `profile_path` with `tunnel-client runtimes status <alias> --json`,
  176. then run `tunnel-client runtimes stop <alias>` before starting the service.
  177. Copy the profile to the service location, preserving your custom settings:
  178. ```bash
  179. service_profile="$(brew --prefix)/etc/tunnel-client.yaml"
  180. if [ -e "$service_profile" ]; then
  181. cp -p "$service_profile" "$service_profile.backup.$(date +%Y%m%d%H%M%S)"
  182. fi
  183. install -m 600 /absolute/path/to/existing-profile.yaml "$service_profile"
  184. ```
  185. Use absolute paths in this profile, including paths to MCP executables,
  186. working directories, and secret files. The service includes Homebrew's `bin`
  187. and `sbin` on `PATH`, but does not load your interactive shell configuration.
  188. Replace shell-only `env:` references with persistent references such as this
  189. existing profile field:
  190. ```yaml
  191. control_plane:
  192. api_key: file:/Users/YOU/.config/tunnel-client/runtime.key
  193. ```
  194. Store the runtime API key in that file with permissions `0600`; keep its
  195. directory private too. The service definition contains the profile path,
  196. not the key. Validate the profile, then start the service as your logged-in
  197. user, without `sudo`:
  198. ```bash
  199. tunnel-client doctor --profile-file "$(brew --prefix)/etc/tunnel-client.yaml"
  200. brew services start openai/tools/tunnel-client
  201. brew services info openai/tools/tunnel-client
  202. tunnel-client health --url http://127.0.0.1:8080 --json
  203. ```
  204. The health command above uses the default listener. If your profile configures
  205. a different health address or a `health.url_file`, use that address or
  206. `health --url-file /absolute/path/to/health-url` instead. An active service
  207. alone does not mean the tunnel is ready. Inspect
  208. `$(brew --prefix)/var/log/tunnel-client.log` and any `log.file` destination in
  209. your profile if startup fails.
  210. Use Homebrew to manage this runtime:
  211. ```bash
  212. # Reload the profile/key or pick up the installed version after a brew upgrade.
  213. brew services restart openai/tools/tunnel-client
  214. # Stop the runtime and disable automatic login startup.
  215. brew services stop openai/tools/tunnel-client
  216. ```
  217. The service uses Homebrew's stable `opt` path across upgrades. The CLI's
  218. `runtimes status` and `runtimes stop` commands manage its own detached
  219. processes; they do not discover or control the Homebrew service. Do not run
  220. `runtimes connect` for the same tunnel while the service is active: that
  221. command writes a generated profile and starts a separate runtime. Stop the
  222. service before switching back to CLI management. Keep only one runtime active
  223. for the tunnel during the switch, especially for stdio or stateful MCP servers.
  224. The per-user macOS service runs during your login session, not before login
  225. or after logout. Sleep suspends the Mac's work; wake allows the runtime's
  226. network retries to resume. Homebrew's launchd service restarts an exited
  227. process, but does not restart one merely because readiness fails. Start a
  228. local HTTP MCP server through its own supervisor. For a server that starts
  229. later, set `mcp.startup_wait_timeout` (for example, `2m`) in the profile to
  230. allow startup connection retries. If that window expires, restart the service
  231. after the MCP server is available; the process can remain alive with its
  232. startup probe failed. After a server restart, check readiness and logs;
  233. existing MCP sessions may need to be initialized again. For a stdio target,
  234. the runtime owns the MCP child. Do not assume interrupted tool calls are
  235. replayed. See [Supervising startup](docs/health.md#supervising-startup) for
  236. interpreting process liveness, OAuth discovery, readiness, and polling state.
  237. ## For Codex / Copilot
  238. If you want the shortest supported path from a local or localhost MCP server to
  239. ChatGPT or Codex, start with `tunnel-client help quickstart`. For Codex plugin
  240. lifecycle work, use the native `tunnel-client runtimes ...` and
  241. `tunnel-client admin-profiles ...` command trees surfaced by
  242. `tunnel-client help plugin`.
  243. Supervision choice:
  244. - Use `tunnel-client run ...` for a foreground daemon attached to the current
  245. terminal or supervised by the OS; see [macOS login startup](#start-at-macos-login).
  246. - For a long-lived local runtime managed by Codex, prefer
  247. `tunnel-client runtimes connect ...`. Do not use `nohup` or `disown` as the
  248. tunnel-client supervision path.
  249. - After `runtimes connect`, check `tunnel-client runtimes status <alias>`
  250. before reporting success. Only report success when status shows the managed
  251. runtime running with health reported. Use `--json` when Codex needs the
  252. explicit `process_running`, `healthy`, and `ready` fields.
  253. Use these exact setup pages during first use:
  254. - Tunnels management and supported tunnel-client download:
  255. `https://platform.openai.com/settings/organization/tunnels`
  256. - Organization roles: `https://platform.openai.com/settings/organization/people/roles`
  257. - Organization groups: `https://platform.openai.com/settings/organization/people/groups`
  258. - Runtime API keys: `https://platform.openai.com/settings/organization/api-keys`
  259. - Admin API keys: `https://platform.openai.com/settings/organization/admin-keys`
  260. - ChatGPT connector settings: `https://chatgpt.com/#settings/Connectors`
  261. Which value comes from where:
  262. - `CONTROL_PLANE_TUNNEL_ID`: create or inspect it in Tunnels management, or via
  263. `tunnel-client admin tunnels create|list|get ...` with `OPENAI_ADMIN_KEY`.
  264. - `CONTROL_PLANE_API_KEY`: create it in Runtime API keys; this is the key used
  265. by `tunnel-client doctor` and `tunnel-client run`.
  266. - For [AWS workload identity](docs/configuration.md#aws-workload-identity), set
  267. `CONTROL_PLANE_AWS_IDENTITY_PROVIDER_ID` and `CONTROL_PLANE_AWS_SERVICE_ACCOUNT_ID`.
  268. - `OPENAI_ADMIN_KEY`: only for `tunnel-client admin tunnels
  269. list|create|update|delete`. Do not use the admin key for the long-lived
  270. daemon.
  271. Required tunnel permissions:
  272. - Runtime users and the principal that creates `CONTROL_PLANE_API_KEY` need
  273. Tunnels **Read** + **Use**.
  274. - Tunnel managers need Tunnels **Read** + **Manage**, plus **Use** if they also
  275. run the daemon or attach ChatGPT connectors.
  276. - Admin-key creators need the Platform admin-key permission in addition to any
  277. tunnel permissions they need.
  278. See [`docs/permissions.md`](docs/permissions.md) for the group/role workflow
  279. and screenshots.
  280. Binary-first flow:
  281. ```bash
  282. tunnel-client help quickstart
  283. tunnel-client profiles samples list
  284. tunnel-client profiles samples show sample_mcp_enterprise_proxy
  285. tunnel-client init --sample sample_mcp_stdio_local --profile local-stdio --tunnel-id tunnel_0123456789abcdef0123456789abcdef --mcp-command "python /path/to/server.py"
  286. tunnel-client doctor --profile local-stdio --explain
  287. tunnel-client run --profile local-stdio
  288. tunnel-client run --profile-file ./profiles/local-stdio.yaml
  289. ```
  290. **Stdio deployment limit:** run only one active `tunnel-client` instance per
  291. tunnel ID when using `--mcp.command` / `MCP_COMMAND`. Multiple active instances
  292. sharing that tunnel ID are **not supported**, including overlap during a
  293. restart. Each instance launches a separate MCP child, and initialization and
  294. later requests can reach different children. Stop the old instance before
  295. starting its replacement, or use distinct tunnel IDs for independent instances.
  296. See [stdio deployment limits](docs/configuration.md#stdio-deployment-limits).
  297. By default, `tunnel-client` restarts a supervised stdio child after an
  298. unexpected exit, stdout EOF, or stdin write failure. Calls in progress may
  299. fail, and legacy callers must initialize the replacement child before retrying.
  300. If your deployment uses an external process supervisor to restart the whole
  301. client, set `--mcp.stdio-failure-policy=exit`,
  302. `MCP_STDIO_FAILURE_POLICY=exit`, or YAML `mcp.stdio_failure_policy: exit`.
  303. That setting restores nonzero client exit on these failures; intentional
  304. shutdown still exits successfully. Remove the new flag or YAML key before
  305. downgrading to a version that does not recognize it.
  306. Stdio initialization is checked automatically. Legacy calls require a successful
  307. `initialize` exchange followed by `notifications/initialized`; premature calls
  308. return `mcp_initialization_required` immediately. Self-contained MCP requests
  309. using protocol version `2026-07-28` or later pass through without a handshake.
  310. The caller owns initialization, including after child replacement. See
  311. [configuration](docs/configuration.md#mcp-server) for lifecycle behavior.
  312. If you need the tunnel id or runtime/admin keys first, open the matching URL
  313. above before running `init`. If your rollout has self-serve tunnel access,
  314. create the tunnel yourself in Tunnels management or with
  315. `tunnel-client admin tunnels create`, then export the returned id as
  316. `CONTROL_PLANE_TUNNEL_ID` and a separate runtime key as
  317. `CONTROL_PLANE_API_KEY`. Create or verify the connector from the ChatGPT
  318. settings URL above only while `tunnel-client run ...` is healthy, and keep the
  319. daemon running for connector discovery and every MCP call from ChatGPT.
  320. The Platform Tunnels page download button is sourced from tunnel-service's
  321. gated tunnel metadata response. When a new public tunnel-client release becomes
  322. the supported download, update tunnel-service's hard-coded public artifact URL
  323. alongside the release handoff.
  324. Validate a source checkout with native Go tooling:
  325. ```bash
  326. go build ./...
  327. go test ./...
  328. ```
  329. Independent tests, subtests, and fuzz seed cases use `t.Parallel()`. Give each
  330. case its own mutable fixtures, and use `t.Cleanup` for resources shared by
  331. parallel children. Keep dependent state transitions in one test. Keep tests
  332. that mutate process-wide globals, environment variables, signals, or stdio
  333. serial.
  334. Check concurrent execution with the race detector and shuffled test order:
  335. ```bash
  336. go test -race -shuffle=on -count=3 ./...
  337. ```
  338. The E2E and mock-server packages default to two concurrent tests to bound
  339. resource use. An explicit `-parallel=N` overrides that default.
  340. ## SBOMs
  341. The public repository includes deterministic six-platform dependency baselines
  342. for the
  343. [full client](https://github.com/openai/tunnel-client/blob/master/compliance/tunnel-client.spdx.json),
  344. [runtime](https://github.com/openai/tunnel-client/blob/master/compliance/tunnel-client-runtime.spdx.json),
  345. and
  346. [runtime with Cloudflared](https://github.com/openai/tunnel-client/blob/master/compliance/tunnel-client-runtime-cloudflared.spdx.json).
  347. They inventory synthetic payloads built from declared offline source and vendor
  348. snapshots, including pinned Cloudflared module versions, purls, and CPEs. Do
  349. not hand-edit them; maintainers refresh them through the hermetic SBOM
  350. generation check when dependency inputs or a Cloudflared pin changes. The
  351. baselines are useful for dependency review and drift detection, but they do not
  352. claim that a public release ZIP contains the same bytes.
  353. From a checkout of this public repository, verify that the mirrored baseline
  354. files match their mirrored manifest before importing them into a dependency
  355. scanner:
  356. ```bash
  357. ./scripts/verify_sbom_baselines.sh
  358. ```
  359. That command proves the checkout's three baseline documents match
  360. `compliance/sbom-baseline-manifest.json` and parse as SPDX 2.3. It does not
  361. prove that any release archive contains those bytes.
  362. ### Validate a downloaded release
  363. Releases produced by the current release workflow publish a matching SPDX 2.3
  364. sidecar for each ZIP, embed the same sidecar in the ZIP, cover both files in
  365. `SHA256SUMS.txt`, and publish the workflow's signed Sigstore provenance bundle.
  366. They also publish:
  367. - `tunnel-client-vX.Y.Z-vulnerability-report.json`, generated by a
  368. checksum-pinned Grype binary from exactly 18 release-specific SPDX sidecars:
  369. three flavors across six platforms, each bound to its matching ZIP and
  370. license-report SHA256, with the exact vulnerability-database SHA256 recorded;
  371. - `tunnel-client-vX.Y.Z.openvex.json` only when the scan has findings, with
  372. every automated statement set to `under_investigation` rather than claiming
  373. that a finding is fixed, exploitable, or not affected; and
  374. - `tunnel-client-vX.Y.Z-enterprise-evidence.json`, which inventories the
  375. release evidence bytes, scanner/database identity, scan scope, and
  376. provenance boundary.
  377. The vulnerability report explicitly records OCI images as `not_scanned`:
  378. the release contract has multi-architecture OCI index digests, not exact
  379. per-platform OCI manifest scan inputs. Every pre-bundle release artifact is
  380. covered by `SHA256SUMS.txt`, `PUBLIC_URLS.txt`, and the signed provenance
  381. bundle. The bundle is intentionally excluded from its own checksum and
  382. signature subject set.
  383. Older releases without `.spdx.json` sidecars cannot be archive/SBOM-validated
  384. this way; releases without a `*-provenance.sigstore.json` bundle cannot be
  385. provenance-validated this way. Use the release sidecar, not a checked-in
  386. baseline, to validate downloaded bytes.
  387. From a checkout of this public repository at the matching release tag, replace
  388. the example tag and choose one of `client`, `runtime`, or
  389. `runtime-cloudflared`. The commands require Bash, Python 3, `curl`, and the
  390. GitHub CLI:
  391. ```bash
  392. release=vX.Y.Z
  393. platform=linux-amd64
  394. flavor=runtime
  395. prefix=tunnel-client-runtime
  396. stem="${prefix}-${release}-${platform}"
  397. base="https://github.com/openai/tunnel-client/releases/download/${release}"
  398. bundle="tunnel-client-${release}-provenance.sigstore.json"
  399. source_digest="$(git rev-parse HEAD)"
  400. curl -fLO "${base}/${stem}.zip"
  401. curl -fLO "${base}/${stem}.spdx.json"
  402. curl -fLO "${base}/${stem}-licenses.txt"
  403. curl -fLO "${base}/SHA256SUMS.txt"
  404. curl -fLO "${base}/${bundle}"
  405. gh attestation verify "${stem}.zip" \
  406. --bundle "${bundle}" \
  407. --repo openai/tunnel-client \
  408. --signer-workflow openai/tunnel-client/.github/workflows/release.yml \
  409. --source-ref "refs/tags/${release}" \
  410. --source-digest "${source_digest}" \
  411. --signer-digest "${source_digest}" \
  412. --predicate-type https://slsa.dev/provenance/v1 \
  413. --deny-self-hosted-runners
  414. gh attestation verify "${stem}.spdx.json" \
  415. --bundle "${bundle}" \
  416. --repo openai/tunnel-client \
  417. --signer-workflow openai/tunnel-client/.github/workflows/release.yml \
  418. --source-ref "refs/tags/${release}" \
  419. --source-digest "${source_digest}" \
  420. --signer-digest "${source_digest}" \
  421. --predicate-type https://slsa.dev/provenance/v1 \
  422. --deny-self-hosted-runners
  423. gh attestation verify "${stem}-licenses.txt" \
  424. --bundle "${bundle}" \
  425. --repo openai/tunnel-client \
  426. --signer-workflow openai/tunnel-client/.github/workflows/release.yml \
  427. --source-ref "refs/tags/${release}" \
  428. --source-digest "${source_digest}" \
  429. --signer-digest "${source_digest}" \
  430. --predicate-type https://slsa.dev/provenance/v1 \
  431. --deny-self-hosted-runners
  432. gh attestation verify SHA256SUMS.txt \
  433. --bundle "${bundle}" \
  434. --repo openai/tunnel-client \
  435. --signer-workflow openai/tunnel-client/.github/workflows/release.yml \
  436. --source-ref "refs/tags/${release}" \
  437. --source-digest "${source_digest}" \
  438. --signer-digest "${source_digest}" \
  439. --predicate-type https://slsa.dev/provenance/v1 \
  440. --deny-self-hosted-runners
  441. ./scripts/verify_release_archive.sh \
  442. --flavor "${flavor}" \
  443. --archive "${stem}.zip" \
  444. --sbom "${stem}.spdx.json" \
  445. --checksums SHA256SUMS.txt
  446. ```
  447. To verify the complete release evidence set, download every asset into a clean
  448. directory and run both fail-closed contract verifiers:
  449. ```bash
  450. mkdir release-evidence
  451. gh release download "${release}" \
  452. --repo openai/tunnel-client \
  453. --dir release-evidence
  454. ./scripts/verify_release_provenance.sh \
  455. --bundle "release-evidence/${bundle}" \
  456. --artifact-dir release-evidence \
  457. --release "${release}" \
  458. --source-digest "${source_digest}"
  459. ./scripts/verify_release_evidence.sh \
  460. --artifact-dir release-evidence \
  461. --release "${release}" \
  462. --source-digest "${source_digest}"
  463. ```
  464. Use `prefix=tunnel-client` with `flavor=client`, or
  465. `prefix=tunnel-client-runtime-cloudflared` with
  466. `flavor=runtime-cloudflared`. The bundle is the release workflow's signed
  467. Sigstore evidence and supports verification without GitHub attestation lookup.
  468. It is emitted after `SHA256SUMS.txt` is attested, so it is intentionally not
  469. listed in that checksum file; `gh attestation verify` checks the bundle's
  470. signature, transparency-log material, signer workflow, source ref, source
  471. digest, and subject digest. The archive verifier then fails closed when the
  472. published checksums do not match, the ZIP is too large or has unsafe,
  473. duplicate, or non-regular members, its embedded sidecar differs from the
  474. downloaded sidecar, or the SPDX SHA256 inventory does not match the extracted
  475. payload. After it passes, import the matching `.spdx.json` file into the
  476. dependency scanner of your choice. Runtime releases also publish a matching
  477. `*-scan-manifest.json` that binds scanner scope, source archives, license
  478. evidence, and the release sidecars.
  479. For a fully disconnected verification environment, capture a trusted root from
  480. an independently trusted online environment before disconnecting:
  481. ```sh
  482. gh attestation trusted-root > trusted_root.jsonl
  483. ```
  484. Transfer that file with the release evidence and add
  485. `--custom-trusted-root trusted_root.jsonl` to each `gh attestation verify`
  486. command above. The release bundle removes the GitHub attestation API
  487. dependency; the trusted-root file removes the remaining online trust-root
  488. lookup.
  489. Build the CLI binary from a source checkout. The Make target stamps the
  490. checkout Git SHA into the version sent in `User-Agent` and
  491. `X-Tunnel-Client-Version`:
  492. ```bash
  493. make admin-ui
  494. make tunnel-client
  495. ./bin/tunnel-client help quickstart
  496. ```
  497. If you invoke Go directly, stamp the same metadata explicitly:
  498. ```bash
  499. module_path="$(go list -m -f '{{.Path}}')"
  500. git_sha="$(git rev-parse HEAD)"
  501. mkdir -p bin
  502. go build \
  503. -ldflags "-X ${module_path}/pkg/version.GitSHA=${git_sha}" \
  504. -o bin/tunnel-client \
  505. ./cmd/client
  506. ```
  507. ## Narrow runtime artifacts
  508. `tunnel-client-runtime` and `tunnel-client-runtime-cloudflared` are the
  509. runtime-only customer surfaces. They intentionally expose only `run` plus
  510. flag-based `--help` and `--version`; use the full `tunnel-client` binary for
  511. onboarding, admin, Codex, and profile-management commands. The Cloudflare
  512. flavor adds only the approved `cloudflared.*` settings and supervises a pinned
  513. `cloudflared` companion.
  514. Build either binary from a source checkout with its Make target (the shorter
  515. aliases are equivalent):
  516. ```bash
  517. make tunnel-client-runtime # alias: make runtime
  518. make tunnel-client-runtime-cloudflared # alias: make runtime-cloudflared
  519. ```
  520. The targets write platform-specific binaries under `bin/<goos>_<goarch>/` and
  521. stable paths at `bin/tunnel-client-runtime` and
  522. `bin/tunnel-client-runtime-cloudflared` (`.exe` on Windows). Inspect the exact
  523. runtime flags with `./bin/tunnel-client-runtime run --help` or
  524. `./bin/tunnel-client-runtime-cloudflared run --help`.
  525. Run the narrow runtime against an HTTP MCP server:
  526. ```bash
  527. export CONTROL_PLANE_API_KEY='...'
  528. export CONTROL_PLANE_TUNNEL_ID='tunnel_0123456789abcdef0123456789abcdef'
  529. export MCP_SERVER_URL='https://mcp.example.com/mcp'
  530. ./bin/tunnel-client-runtime run
  531. ```
  532. For managed Cloudflare provisioning, use the Cloudflare flavor. Release
  533. archives place the pinned `cloudflared` executable beside the runtime; for a
  534. source-only build, point to an existing companion explicitly:
  535. ```bash
  536. ./bin/tunnel-client-runtime-cloudflared run \
  537. --cloudflared.managed \
  538. --cloudflared.path /path/to/cloudflared
  539. ```
  540. To build the corresponding Linux images, use `make build-image-runtime` and
  541. `make build-image-runtime-cloudflared`; the Cloudflare image includes its pinned
  542. companion and both images use `run` as their entrypoint.
  543. Contributors can run the compatibility suite with `make test-runtime`. Its
  544. host-binary checks compare the full client and runtime flavors with the same
  545. profile bytes, environment, flags, local control-plane/MCP/OAuth/proxy/TLS
  546. fixtures, and shutdown signal. The same target also packages native
  547. release-shaped ZIPs and checks that they verify, extract, identify the expected
  548. flavor, and expose `run --help`; that ZIP smoke is not a second fake-service
  549. parity run.
  550. After building the runtime images, `make runtime-container-compatibility`
  551. runs a deployment smoke for their default and overridden entrypoints with
  552. read-only profile/Secret mounts and hardened container settings. It uses
  553. intentionally unreachable local endpoints to check startup surfaces and
  554. SIGTERM, not to compare image behavior with the full client or assert
  555. `/readyz` readiness. An optional local Kubernetes deployment smoke is
  556. available with `TUNNEL_CLIENT_RUNTIME_K8S_COMPAT=1 make
  557. runtime-k8s-compatibility`; it requires Docker plus `kind` or `k3d`, checks
  558. the runtime Pods' mounted profile/Secret and `/healthz` surface, and does not
  559. contact external services.
  560. Public releases use plain semantic-version tags such as `v0.0.10`. Source
  561. archives from release tags carry the release version in
  562. `pkg/version/VERSION`. A plain `go build` from a downloaded release `.tar.gz`
  563. therefore reports the tag semantic version through `tunnel-client --version`,
  564. `User-Agent`, and the explicit control-plane version headers. Source-checkout
  565. builds made with the Make target or explicit linker flag above append the Git
  566. SHA to that semantic version.
  567. Supported release archives also bundle pinned `cloudflared` `2026.10.2` beside
  568. the CLI for Linux `amd64`/`arm64`, macOS `amd64`/`arm64`, and Windows
  569. `amd64`/`arm64`.
  570. Official release images are published at `ghcr.io/openai/tunnel-client` for
  571. Linux `amd64` and `arm64`; they bundle the matching companion. Pin an exact
  572. `vX.Y.Z` tag or digest for production. Stable releases also update the
  573. `X.Y` and `latest` aliases; prereleases do not. For a logical tunnel created
  574. with managed Cloudflare provisioning, let the authenticated client fetch the
  575. runtime token and start the companion without distributing a static token:
  576. ```bash
  577. tunnel-client run \
  578. --cloudflared.managed \
  579. --control-plane.tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  580. --mcp.server-url https://mcp.example.com/mcp
  581. ```
  582. For a pre-provisioned Cloudflare tunnel, a static token remains available as an
  583. explicit override and is never put in argv:
  584. ```bash
  585. export CLOUDFLARED_TOKEN='...'
  586. tunnel-client run \
  587. --cloudflared.token env:CLOUDFLARED_TOKEN \
  588. --control-plane.tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  589. --mcp.server-url https://mcp.example.com/mcp
  590. ```
  591. See [`docs/deployment/cloudflared.md`](docs/deployment/cloudflared.md) for
  592. platform coverage, readiness/failure behavior, Go module provenance, and
  593. security-update ownership.
  594. If an operator intentionally runs `cloudflared` without `tunnel-client`, print
  595. a token-free production config and keep the token in a separate secret file:
  596. ```bash
  597. tunnel-client cloudflared config \
  598. --token-file /run/secrets/cloudflared/token \
  599. > /etc/cloudflared/config.yml
  600. TUNNEL_MANAGEMENT_DIAGNOSTICS=false \
  601. cloudflared tunnel --config /etc/cloudflared/config.yml run
  602. ```
  603. Fastest Codex terminal path:
  604. ```bash
  605. tunnel-client codex assistant "Summarize what tunnel-client is doing in this checkout."
  606. tunnel-client codex status
  607. tunnel-client codex plugin install
  608. tunnel-client runtimes list
  609. tunnel-client help plugin
  610. tunnel-client codex plugin uninstall
  611. ```
  612. Choose the raw binary when you want the smallest possible setup surface.
  613. Choose `tunnel-client codex assistant` when you want the fastest Codex-native
  614. terminal path. Choose the plugin when you want a Codex-local entrypoint over
  615. the native `runtimes` / `admin-profiles` command trees.
  616. Starter prompts for Codex:
  617. - `Figure out what tunnel-client is for from the binary help, then get me to /ui with the shortest local path.`
  618. - `I only have the source checkout. Figure out how to build tunnel-client, then get me to /ui with the shortest local path.`
  619. - `Use tunnel-client to create or reuse a profile, run doctor --explain, and then start the foreground daemon attached to this terminal.`
  620. - `Run tunnel-client codex assistant and summarize what this checkout is for in one sentence.`
  621. - `Install the Codex plugin from the tunnel-client binary, connect the provided tunnel id, and tell me whether the runtime is launched, healthy, or ready.`
  622. - `For a long-lived local runtime, use tunnel-client runtimes connect to attach the provided tunnel id, then run tunnel-client runtimes status <alias> before reporting whether the runtime is launched, healthy, or ready.`
  623. ### Complete ChatGPT setup with Codex
  624. Copy this prompt into Codex on a computer with browser access and a terminal on
  625. or connected to a host that can reach your private MCP server:
  626. ```text
  627. Help me set up and verify a private Secure MCP Tunnel from my internal MCP server to ChatGPT end to end. Use browser/computer access and a terminal, following https://developers.openai.com/api/docs/guides/secure-mcp-tunnels and https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md; check current UI and CLI help as you go.
  628. First identify the intended Platform organization and ChatGPT workspace, MCP server HTTP URL or stdio command, and client host. Inspect existing tunnel, key, and ChatGPT custom MCP plugin; reuse suitable resources. Confirm tunnel organization/workspace association and permissions: tunnel creators need Tunnels Read + Manage; the restricted runtime key and plugin operator need Tunnels Read + Use. Keep literal secrets out of chat, command arguments, logs, screenshots, and config files; have me enter them locally through a secure input or environment reference.
  629. Install the supported tunnel-client; run `tunnel-client help quickstart`, configure the server, run `tunnel-client doctor --profile <name> --explain`, start the client, and verify readiness and active polling. Keep it running for discovery and calls. In ChatGPT Plugins, add or finish a private custom MCP server with Connection: Tunnel, select the same tunnel, configure required authentication, install it, and make a safe representative tool call.
  630. Report observed evidence for each checkpoint and the exact error and next action for any blocker. Call setup complete only after the ChatGPT tool call succeeds.
  631. ```
  632. The ChatGPT custom MCP plugin in this prompt is separate from the local Codex
  633. plugin installed by `tunnel-client codex plugin install`.
  634. ## What it does
  635. - The client **long-polls** the OpenAI tunnel control plane over HTTPS:
  636. - `GET /v1/tunnels/{tunnel_id}/poll`
  637. - `POST /v1/tunnels/{tunnel_id}/response`
  638. - Older tunnel-client releases may still use the singular `/v1/tunnel/...`
  639. aliases. Tunnel-service keeps those aliases during migration; removing them,
  640. if ever desired, is a separate later cleanup after telemetry shows no
  641. remaining legacy clients.
  642. - Control-plane requests include `User-Agent: oai-tunnel-client/<version>` for
  643. compatibility, plus explicit `X-Tunnel-Client-Name` and
  644. `X-Tunnel-Client-Version` headers for service-side logs and metrics. Each
  645. process also generates a new opaque `client_instance_id`, sends it as
  646. `X-Tunnel-Client-Instance-Id`, and includes it in structured logs and the
  647. local admin UI for request correlation.
  648. - Control-plane HTTPS requests can present a separate client certificate/key
  649. pair using `--control-plane.client-cert` and `--control-plane.client-key`
  650. (or `CONTROL_PLANE_CLIENT_CERT` / `CONTROL_PLANE_CLIENT_KEY`). When those are
  651. configured with the default `https://api.openai.com` host, the client
  652. automatically uses `https://mtls.api.openai.com` for control-plane calls.
  653. - On startup, it fetches tunnel metadata for operator visibility:
  654. - `GET /v1/tunnels/{tunnel_id}`
  655. - The `tunnel-client process started` log confirms process startup. Check
  656. `/readyz` for readiness and `/health/control-plane` for observed polling.
  657. Optional all-404 OAuth metadata discovery logs at INFO and reports
  658. `not_advertised` in `/health/oauth`, including HTML or JSON 404 bodies.
  659. See [startup supervision](docs/health.md#supervising-startup).
  660. - It forwards received JSON-RPC requests to your configured MCP server over
  661. Streamable HTTP, stdio, or in-memory transport, and relays explicit
  662. Streamable HTTP session termination requests when the control plane receives
  663. `DELETE /v1/mcp/{tunnel_id}`.
  664. - It routes commands by channel: `main` targets the configured MCP binding,
  665. additional configured channels can target their own MCP bindings, and
  666. `harpoon` is routable only when Harpoon has registered targets.
  667. - By default, it fetches OAuth Protected Resource Metadata from the MCP server on startup
  668. and registers discovered Harpoon targets. Timeouts, HTTP `429`/`5xx`, and
  669. malformed successful metadata responses retry with bounded exponential
  670. backoff until discovery succeeds or the process stops. Permanent errors
  671. remain visible through readiness; discovery validation and trusted-origin
  672. restrictions still apply. For an MCP server using a static credential,
  673. set `MCP_OAUTH_DISCOVERY=disabled` to skip startup and later OAuth discovery.
  674. [MCP configuration](docs/configuration.md#mcp-server)
  675. - Before polling for Harpoon work, the runtime waits for startup discovery and
  676. target registration to complete. Failed startup catalogs do not consume
  677. commands, and readiness remains non-ready until registration succeeds.
  678. Plain MCP servers without OAuth and explicitly scoped pollers
  679. that exclude Harpoon remain supported. Transient HTTP `429`/`5xx` MCP startup
  680. initialization errors also retry without replaying tunneled commands.
  681. - After configured and startup OAuth-discovered Harpoon targets settle, it
  682. emits one privacy-safe `harpoon startup catalog digest` INFO log. Compare
  683. replicas only when they use the same tunnel ID and control-plane runtime API
  684. key; the startup-only digest is a comparison aid, not convergence
  685. enforcement.
  686. - For sidecar deployments whose local MCP listener may bind after
  687. `tunnel-client` starts, the optional `MCP_STARTUP_WAIT_TIMEOUT` gate delays
  688. the first control-plane poll and OAuth discovery until the main MCP listener
  689. is reachable.
  690. - For OAuth auth-server handling, `authorization_servers[0]` from PRMD is the
  691. only source of truth and metadata fetch target.
  692. - OAuth discovery trusts the configured MCP origin by default. Before upgrading
  693. deployments with separate metadata or authorization hosts, explicitly list
  694. those origins with `--mcp.oauth-trusted-origin`, `MCP_OAUTH_TRUSTED_ORIGINS`, or
  695. `mcp.oauth_trusted_origins`. See the [configuration reference](docs/configuration.md#mcp-server)
  696. for trust boundaries and staged upgrade guidance. Full-client profile editing
  697. also requires a [supported editor command](docs/profile-editor.md).
  698. - Forwarding OAuth requests to a separate HTTPS origin requires an independent
  699. opt-in: `--harpoon.oauth-forward-origin`, `HARPOON_OAUTH_FORWARD_ORIGINS`, or
  700. `harpoon.oauth_forward_origins`. Discovery trust alone remains insufficient.
  701. Approved discovered endpoints retain their OAuth roles and groups; other
  702. origins remain subject to the existing registration policy. See
  703. [OAuth forwarding origins](docs/configuration.md#oauth-forwarding-origins)
  704. for exact-origin matching and deployment guidance.
  705. - Metadata is accepted even when `issuer` differs from
  706. `authorization_servers[0]` (external IdP issuer URLs are supported), with
  707. mismatch diagnostics preserved in logs/state.
  708. - It exposes an **admin/health server** (`/healthz`, `/readyz`, `/metrics`) and
  709. a lightweight **admin UI** (`/ui`) for operational status.
  710. - The admin UI supports a generic reverse-proxy path prefix. Prefix-stripping
  711. proxies need no base-path setting; prefix-preserving proxies use
  712. `--admin-ui.base-path`. An explicit `--admin-ui.public-origin` can allow the
  713. browser's origin for guarded actions through a reverse proxy. See
  714. [reverse proxy paths](docs/configuration.md#reverse-proxy-paths) for mount
  715. URLs, security boundaries, and configuration examples.
  716. - Local `GET /health?details=true`, `GET /health/mcp`, and `GET /health/oauth`
  717. expose bounded observations of legacy initialize and modern `server/discover`
  718. MCP discovery, OAuth startup probes, polling, response delivery, queues, and
  719. active work. Plain `/health` stays compact unless `--health.show-details=true`
  720. is set (default false). See the [health reference](docs/health.md) for examples,
  721. Unix sockets, and the difference between readiness and observed discovery.
  722. - The admin UI Overview reports the process-scoped `client_instance_id`,
  723. channel availability, and reasons when channels are disabled.
  724. - The admin UI Logs tab can switch the live runtime log level between `debug`,
  725. `info`, and `warn` without restarting the process.
  726. - The admin UI log export returns a redacted support bundle with recent logs
  727. plus a point-in-time Prometheus snapshot from `/metrics` and a redacted
  728. runtime YAML snapshot containing argv, relevant environment, actual YAML
  729. config, and effective config.
  730. - It embeds the **Harpoon MCP server** to provide a labeled, allowlisted
  731. outbound HTTP client for internal tooling.
  732. ### Harpoon target templates
  733. Opt-in Harpoon templates let callers provide bounded identifiers for an
  734. operator-configured GET, POST, or PUT operation, such as `/cases/{case_id}` or
  735. `/profiles?session-id={session_id}`. The client fixes the destination, method,
  736. query names, and authentication headers, validates each identifier, and never
  737. follows redirects. POST/PUT require an explicit body policy for content types,
  738. byte limits, required or optional bodies, and validation. GET remains bodyless;
  739. DELETE is unsupported. Existing exact-URL targets continue to work.
  740. Templates use HTTPS by default. An operator can set `allow_loopback_http: true`
  741. on one template to call a literal loopback IP with a fixed port over HTTP.
  742. Those calls bypass configured HTTP proxies so local API credentials stay on
  743. the local connection. The setting does not enable other plaintext targets.
  744. Templates use YAML `config_version: 2` and `template.version: 1`, and execute
  745. through the shared `call_target` MCP tool without a caller-supplied method.
  746. Exact targets keep their required method argument. `list_targets` publishes
  747. each template's complete invocation schema, public parameter descriptions, and
  748. validated examples when available. Writes require the advertised `operation`
  749. constant and never automatically replay after an ambiguous failure. Upgrade all
  750. eligible clients before enabling writes or adding parameter metadata. See the
  751. [target template guide](docs/harpoon-target-templates.md) for complete
  752. configuration, discovery and invocation examples, authorization requirements,
  753. limits, and upgrade behavior.
  754. ## Admin UI build notes
  755. The admin UI assets under `pkg/adminui/assets` are generated from the TypeScript/Svelte
  756. source in `adminui/`. To rebuild them locally:
  757. ```bash
  758. ./scripts/build_admin_ui.sh ./adminui ./pkg/adminui/assets
  759. # or
  760. make admin-ui
  761. ```
  762. ## CLI
  763. - `tunnel-client` shows help and available subcommands.
  764. - `tunnel-client help <topic>` shows embedded task-oriented help for
  765. `quickstart`, `samples`, `doctor`, `oauth`, and `plugin`.
  766. - `tunnel-client codex assistant [prompt...]` starts a terminal assistant
  767. session through the supervised `codex app-server`, using prompt args for
  768. one-shot mode and TTY stdin for REPL mode. It defaults to `medium`
  769. reasoning effort, and the REPL supports `/model` to inspect or change model
  770. and reasoning without restarting.
  771. - `tunnel-client codex status|install|upgrade|uninstall` inspects local Codex
  772. CLI/app-server availability and prints the official install/upgrade/remove
  773. commands.
  774. - `tunnel-client codex plugin install|uninstall|export` installs, removes, or
  775. exports the embedded Tunnel MCP plugin bundle.
  776. - `tunnel-client dev mcp-stub` runs an embedded demo MCP + OAuth metadata server
  777. for one-binary end-to-end validation.
  778. - `tunnel-client dev proxy` runs a local control plane plus tunnel-client for
  779. integration tests. TCP ingress is the default and prints `mcp_url`; pass
  780. `--listen-unix-socket PATH` for external MCP ingress over a Unix socket. Its
  781. `--backend auto|go|rust` flag defaults to `auto`, and
  782. `--engine-queue-backend inmem` is the supported queue setting. Ordinary public
  783. builds use the Go in-memory backend; `rust` requires a binary with the
  784. optional linked Rust adapter. Rust Redis support has been removed. The
  785. deprecated `--engine-redis-url` flag, nonempty `TUNNEL_ENGINE_REDIS_URL`, or an
  786. explicit Redis backend selection returns a removal error before startup.
  787. Remove retired settings and use `inmem` only for local, ephemeral work, or
  788. keep the prior version for Redis-backed setups.
  789. - `tunnel-client init` writes a validated first-use profile.
  790. - `tunnel-client doctor` validates config and explains what is missing before
  791. startup.
  792. - `tunnel-client profiles samples list|show` exposes built-in sample profiles.
  793. - `sample_mcp_enterprise_proxy` is the built-in starter for outbound proxies
  794. and private PKI, with env-backed proxy and CA bundle references.
  795. - The first control-plane poll attempt requests the shorter of
  796. `--control-plane.initial-poll-timeout` (default `30s`) and the configured
  797. wait, while retaining its normal client deadline. Both wait settings default
  798. to `30s`. A lower initial-poll timeout can shorten the first requested wait.
  799. Subsequent polls use `--control-plane.poll-timeout` /
  800. `CONTROL_PLANE_POLL_TIMEOUT`, including after an initial failure.
  801. If an HTTP-proxied poll loses its connection
  802. before response headers with an EOF-style error while neither deadline has
  803. fired, tunnel-client automatically learns a shorter
  804. process-local timeout for future polls. The learned timeout only decreases,
  805. never below 5 seconds, while the configured poll timeout remains its ceiling.
  806. Subsequent direct and Unix-socket polls keep the configured timeout.
  807. - `tunnel-client admin-profiles list|set|delete` manages saved admin-key
  808. profiles for native runtime workflows.
  809. - `tunnel-client runtimes create|connect|list|status|stop|rm` manages native
  810. alias state and local runtime supervision.
  811. - `tunnel-client run` starts the foreground/manual client poller attached to
  812. the current terminal.
  813. - `tunnel-client cloudflared version` prints the bundled companion pin,
  814. upstream release, and security-patch owner without starting a process.
  815. - `tunnel-client cloudflared config --token-file <path>` prints a token-free
  816. production `cloudflared` config for operators who run `cloudflared` directly.
  817. - `tunnel-client admin tunnels get <id>` is the read-only metadata lookup used
  818. on the runtime-user path; broader `admin tunnels` CRUD still requires an
  819. admin key. When you need admin CRUD scope, inspect the returned
  820. `organization_ids` / `workspace_ids` from `tunnel-client admin --json tunnels get <id>`
  821. and reuse those live values instead of guessing ids.
  822. ## License
  823. This project is licensed under the [Apache License 2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.