[Sandboxes] Document the new tunnels API#30876
Open
aron-cf wants to merge 3 commits into
Open
Conversation
aron-cf
requested review from
a team,
ghostwriternr and
whoiskatrin
as code owners
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
Contributor
ghostwriternr
approved these changes
May 18, 2026
|
|
||
| ## Requirements | ||
|
|
||
| - **RPC transport.** Calling `sandbox.tunnels` on a route-based transport throws `"RPC transport required"`. See [Transport configuration](/sandbox/configuration/transport/). |
Member
There was a problem hiding this comment.
nit: route-based is probably an implementation detail so:
Suggested change
| - **RPC transport.** Calling `sandbox.tunnels` on a route-based transport throws `"RPC transport required"`. See [Transport configuration](/sandbox/configuration/transport/). | |
| - **RPC transport.** Calling `sandbox.tunnels` on HTTP/Websocket transports will throw `"RPC transport required"`. See [Transport configuration](/sandbox/configuration/transport/). |
|
|
||
| ### `tunnels.get()` | ||
|
|
||
| Return a tunnel record for `port`. Idempotent: repeated calls for the same port return the same record. On a cache miss, the SDK spawns a fresh `cloudflared` process inside the container and persists the record in Durable Object storage. |
Member
There was a problem hiding this comment.
Suggested change
| Return a tunnel record for `port`. Idempotent: repeated calls for the same port return the same record. On a cache miss, the SDK spawns a fresh `cloudflared` process inside the container and persists the record in Durable Object storage. | |
| Return a tunnel record for `port`. The SDK spawns a fresh `cloudflared` process inside the container if not already running. The method is idempotent so repeated calls for the same port return the same record. |
|
|
||
| **Parameters**: | ||
|
|
||
| - `port` — Port number inside the sandbox to expose (1024-65535, excluding reserved ports). The service must already be listening on `0.0.0.0:<port>` inside the container. |
Member
There was a problem hiding this comment.
Suggested change
| - `port` — Port number inside the sandbox to expose (1024-65535, excluding reserved ports). The service must already be listening on `0.0.0.0:<port>` inside the container. | |
| - `port` — Port number inside the sandbox to expose (1024-65535, excluding reserved ports). The service to tunnel to must already be listening on `0.0.0.0:<port>` inside the container. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This adds a new Tunnels page to the Sandbox documents that covers the new
sandbox.tunnelsinterface recently added to the SDK. This gives an API reference as well as updating existing locations that referenceexposePort()to point to the new API.Currently Cloudflare Tunnels have limited use and need to exist next to
exposePort()while we work on the remaining functionality. I've tried to capture this in the Preview URLs document.Documentation checklist