From a03f1cd84246d9a400aa5ad5fbe76bce6dd544b5 Mon Sep 17 00:00:00 2001 From: jona62 Date: Sun, 4 Oct 2026 00:20:49 -0400 Subject: [PATCH 1/2] docs(tunnels): stage unavailable tunnel guide and API contracts --- api-reference/overview.mdx | 4 + api-reference/tunnels/create.mdx | 18 + api-reference/tunnels/get.mdx | 16 + api-reference/tunnels/list.mdx | 16 + api-reference/tunnels/stop.mdx | 16 + api-reference/tunnels/update-policy.mdx | 18 + cli-reference/cli.mdx | 8 + docs.json | 11 + guides/local-tunnels.mdx | 205 +++++++++++ openapi/tunnels-api.json | 464 ++++++++++++++++++++++++ scripts/api-navigation-base.json | 10 + scripts/build-navigation.py | 4 +- 12 files changed, 788 insertions(+), 2 deletions(-) create mode 100644 api-reference/tunnels/create.mdx create mode 100644 api-reference/tunnels/get.mdx create mode 100644 api-reference/tunnels/list.mdx create mode 100644 api-reference/tunnels/stop.mdx create mode 100644 api-reference/tunnels/update-policy.mdx create mode 100644 guides/local-tunnels.mdx create mode 100644 openapi/tunnels-api.json diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx index 663ed45..cdf9659 100644 --- a/api-reference/overview.mdx +++ b/api-reference/overview.mdx @@ -10,6 +10,7 @@ Start with the [API quickstart](/build/quickstart) to make an authenticated requ - [Workspaces](/api-reference/workspaces/list): lifecycle and resources. - [Apps](/api-reference/apps/list): installed applications and runtime controls. - [App releases](/api-reference/app-releases/list): prepare and activate v0.13 deployments. +- [Planned local tunnels](/api-reference/tunnels/list): prepared contracts for a service that is currently disabled; the signed CLI 0.13.0 release is not yet published. - [Snapshots](/api-reference/snapshots/list): stopped-workspace root-disk checkpoints. - [API keys](/api-reference/api-keys/list): account credentials. @@ -18,3 +19,6 @@ Start with the [API quickstart](/build/quickstart) to make an authenticated requ The account API uses the public HTTPS endpoint and an authorized credential. The [managed AI proxy](/guides/managed-proxy) is a VM-local interface with different authentication and protocol semantics. First-party console and policy endpoints are grouped separately from the application deployment lifecycle. This is a v0.13 documentation preview. App-release functionality requires the matching server capability. Reading a generated schema does not establish that a feature is enabled for your account. See [API conventions](/build/api-conventions) for polling, pagination, and failure handling. + +The tunnel API pages are reference-only while production tunnels remain disabled +pending browser-domain isolation. They do not offer a live request playground. diff --git a/api-reference/tunnels/create.mdx b/api-reference/tunnels/create.mdx new file mode 100644 index 0000000..29bfa2b --- /dev/null +++ b/api-reference/tunnels/create.mdx @@ -0,0 +1,18 @@ +--- +title: "Create a local tunnel" +openapi: "/openapi/tunnels-api.json POST /api/v1/tunnels" +playground: "none" +--- + + +Tunnels are not available to customers yet. The production service is disabled +pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +yet published. This page documents the prepared API contract; it does not enable +the service. See [local tunnels](/guides/local-tunnels) for planned use and risks. + + +Requires an enabled tunnel capability and an account eligible to use tunnels. A new tunnel is private and points to one fixed literal loopback target. Its assigned website URL uses HTTPS; the local server can use HTTP or verified HTTPS. + +Creation returns the tunnel record and separate connector and lease credentials. Keep both credentials secret and out of logs. Creating the record does not connect your laptop or deploy an application. The foreground [tunnel command](/guides/local-tunnels#start-privately-when-available) creates a record and runs its connector together, managing the lease for you. + +See [local tunnels](/guides/local-tunnels) for access modes, local HTTPS setup, and operating limits. diff --git a/api-reference/tunnels/get.mdx b/api-reference/tunnels/get.mdx new file mode 100644 index 0000000..9a1768d --- /dev/null +++ b/api-reference/tunnels/get.mdx @@ -0,0 +1,16 @@ +--- +title: "Inspect a local tunnel" +openapi: "/openapi/tunnels-api.json GET /api/v1/tunnels/{id}" +playground: "none" +--- + + +Tunnels are not available to customers yet. The production service is disabled +pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +yet published. This page documents the prepared API contract; it does not enable +the service. See [local tunnels](/guides/local-tunnels) for planned use and risks. + + +Returns an owned tunnel and its current invitation email list. Read the returned policy epoch, connection generation, and target fingerprint before [changing access](/api-reference/tunnels/update-policy). + +The connector target stays fixed for the lifetime of this tunnel. To serve a different local target, start a new tunnel through the [CLI](/guides/local-tunnels#start-privately-when-available). diff --git a/api-reference/tunnels/list.mdx b/api-reference/tunnels/list.mdx new file mode 100644 index 0000000..19cdcfd --- /dev/null +++ b/api-reference/tunnels/list.mdx @@ -0,0 +1,16 @@ +--- +title: "List local tunnels" +openapi: "/openapi/tunnels-api.json GET /api/v1/tunnels" +playground: "none" +--- + + +Tunnels are not available to customers yet. The production service is disabled +pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +yet published. This page documents the prepared API contract; it does not enable +the service. See [local tunnels](/guides/local-tunnels) for planned use and risks. + + +Lists the current account's tunnel records, including their hostname, target, access policy, and connection state. A record does not establish that a connector is running or that its website is reachable. + +See [local tunnels](/guides/local-tunnels) to start a connector and share its website. diff --git a/api-reference/tunnels/stop.mdx b/api-reference/tunnels/stop.mdx new file mode 100644 index 0000000..638c005 --- /dev/null +++ b/api-reference/tunnels/stop.mdx @@ -0,0 +1,16 @@ +--- +title: "Stop a local tunnel" +openapi: "/openapi/tunnels-api.json DELETE /api/v1/tunnels/{id}" +playground: "none" +--- + + +Tunnels are not available to customers yet. The production service is disabled +pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +yet published. This page documents the prepared API contract; it does not enable +the service. See [local tunnels](/guides/local-tunnels) for planned use and risks. + + +Stops the owned tunnel, revokes its connector and lease credentials, and invalidates its viewer sessions. The relay closes active traffic after observing the stopped state. + +A stopped connection generation cannot be resumed. Start a new tunnel through the [CLI](/guides/local-tunnels#start-privately-when-available) when you want to serve the website again. diff --git a/api-reference/tunnels/update-policy.mdx b/api-reference/tunnels/update-policy.mdx new file mode 100644 index 0000000..27d714c --- /dev/null +++ b/api-reference/tunnels/update-policy.mdx @@ -0,0 +1,18 @@ +--- +title: "Update tunnel access" +openapi: "/openapi/tunnels-api.json PATCH /api/v1/tunnels/{id}/policy" +playground: "none" +--- + + +Tunnels are not available to customers yet. The production service is disabled +pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +yet published. This page documents the prepared API contract; it does not enable +the service. See [local tunnels](/guides/local-tunnels) for planned use and risks. + + +Choose `private` for the owner, `privileged` for the owner and invited verified email identities, or `public` for visitors without Rigbox sign-in. An admitted visitor receives the access your local application provides, including its write and administrative features. + +Submit the current policy epoch and connection generation from [inspect](/api-reference/tunnels/get). Public access also requires an affirmative acknowledgment of that exact target fingerprint, policy epoch, and generation. If the tunnel changes, reload and review its target before submitting another update. + +The invitation list replaces the previous list and is valid only with privileged access. A policy change invalidates existing viewer sessions and closes streams admitted under the previous policy. See [local tunnels](/guides/local-tunnels) for sharing behavior. diff --git a/cli-reference/cli.mdx b/cli-reference/cli.mdx index aa72fb1..b287fd9 100644 --- a/cli-reference/cli.mdx +++ b/cli-reference/cli.mdx @@ -47,6 +47,14 @@ Choose a command below, then follow its subcommand links. Each page includes its [Configuration and output](/cli-reference/configuration) explains scripting options. [Local versus workspace CLI](/cli-reference/execution-modes) explains which command surface to use. +## Planned local tunnels + +[`rig tunnel`](/guides/local-tunnels) is prepared for the planned signed CLI +0.13.0 release, which is not yet published. The production tunnel service is +disabled pending browser-domain isolation. Its guide documents future commands +and risks; these commands require both that matching CLI and an enabled service. +The generated command reference above retains its existing source version. + ## Source and coverage The command tree comes from the CLI's Clap definitions at v0.13.0-rc.5 (revision `824aefd`), including both local and workspace modes. Inside a workspace, some commands parse but refuse with a one-line message saying where they work; their pages say so. Hidden internal commands and Clap's automatically generated `help` routing aliases are excluded; every documented command supports `--help`. diff --git a/docs.json b/docs.json index def567c..fdec634 100644 --- a/docs.json +++ b/docs.json @@ -77,6 +77,7 @@ "configure/health", "guides/visibility", "guides/expose-and-route", + "guides/local-tunnels", "guides/custom-domains", { "group": "rig.yaml", @@ -325,6 +326,16 @@ "api-reference/app-releases/activate", "api-reference/app-releases/logs" ] + }, + { + "group": "Local tunnels", + "pages": [ + "api-reference/tunnels/list", + "api-reference/tunnels/create", + "api-reference/tunnels/get", + "api-reference/tunnels/update-policy", + "api-reference/tunnels/stop" + ] } ] }, diff --git a/guides/local-tunnels.mdx b/guides/local-tunnels.mdx new file mode 100644 index 0000000..12f166b --- /dev/null +++ b/guides/local-tunnels.mdx @@ -0,0 +1,205 @@ +--- +title: "Local tunnels" +description: "Planned local website tunnels, access controls, and exposure risks." +--- + + +Tunnels are not available to customers yet. The production service is disabled +pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +yet published. The commands below describe prepared behavior and require both +that matching CLI and an enabled tunnel service. Reading these instructions does +not enable tunnels or expose your laptop. + + +The planned tunnel keeps your service running on your laptop. Its foreground CLI +connects outbound to Rigbox and gives one fixed loopback port a fresh HTTPS URL. +Public HTTPS and verified outbound WSS are required from the first release. +Keep the foreground command running while you use it. + + +Anyone admitted to the tunnel can invoke everything the local app exposes. +That can include files, debug consoles, commands, and access to other services +through an app vulnerability. Rigbox does not sandbox the app or your laptop. +Review the service before sharing it, even when the tunnel is private. + + +## Start privately when available + +Start your HTTP service on `127.0.0.1:3000`, then run: + +```bash +rig login +rig tunnel --port 3000 +``` + +Review the first-use target and capability warning. The command prints its URL +after the local service and an authenticated connector channel are ready. Open +that URL and sign in using the owner's Rigbox browser account. A CLI API key does +not mint a browser viewer session; browser access uses a fresh authenticated +Rigbox login. Private and privileged tunnel traffic uses browser access only. +Keep Rigbox account API keys on the control API; never send them to a tunnel URL. +Public native HTTP callers can use credentials issued by their local application, +with the explicit client header described below. + +A private or privileged link opened from another website first shows a Rigbox +Continue page. That page does not contact the local app. Click Continue to enter +through the bound browser flow; sign in if needed. Every browser completes a +cookie-boundary check before the local app or its assets load. Deliberate Public +links complete that check automatically when the browser supplies the required +evidence. Ambiguous navigation may require Continue. + +Browser access requires supported cookie isolation and Fetch Metadata headers. +If those checks fail, the local app receives no request. Use a supported current +browser and reopen the URL. Concurrent entry tabs can invalidate an earlier +tab's binding and require it to restart the entry flow. + +An older account may sign in successfully but receive `recovery_required` when +using tunnel controls. Complete the console's verified account recovery and old +credential revocation first; retry after the displayed recovery delay. A signed +email claim or API key does not bypass that ownership check. + +Creation always starts private. Each new local session receives a new hostname +on a separate content domain with sibling cookie isolation. The destination +remains literal `127.0.0.1` and the selected port; the connector has no remote destination, +arbitrary TCP, shell, file-serving, or background daemon mode. + +## Choose who can reach it + +```bash +rig tunnel ls +rig tunnel status --tunnel TUNNEL_ID +rig tunnel share --tunnel TUNNEL_ID --emails colleague@example.com +rig tunnel share --tunnel TUNNEL_ID --private +``` + +Private access admits only the owner. Privileged access admits the owner and +invites verified Rigbox email addresses. A viewer accepts the +invitation with a verified email, and the permission is then bound to that +immutable Rigbox user ID. Invitation acceptance does not prove that the person +will continue owning the mailbox. Viewers can use the whole application; this is +not a read-only permission or permission to manage the tunnel. + +Public access admits anyone on the internet, including anonymous native HTTP +callers, and requires a separate confirmation +for the current target and session: + +```bash +rig tunnel share --tunnel TUNNEL_ID --public +``` + +The CLI binds public acknowledgment to the current target fingerprint, +connection generation, and policy version. If those change before the update, +the request fails and you must review the new status. It does not retry public +sharing automatically. You can also select the initial policy before connecting: + +```bash +rig tunnel --port 3000 --visibility privileged --allow-email colleague@example.com +rig tunnel --port 3000 --visibility public +``` + +## Stop and restart + +Press Ctrl-C in the foreground command, or stop from another terminal: + +```bash +rig tunnel stop --tunnel TUNNEL_ID +``` + +Stop revokes the session and connector. Changing access closes flows admitted +under the old policy. The connector renews short authority leases and closes its +local connections if renewal fails or expires. The 15-second bound runs from a +gateway-observed change and valid lease issuance; it does not promise instant +detection of an external identity-provider change. + +A session has an eight-hour maximum lifetime. A service disappearing terminates +the connector and requires an explicit new session. A fixed port does not identify +a process: an undetected replacement on the same port can still be reached. +Close the tunnel before restarting or replacing the local service. Expired +leases and sessions that never started within 60 seconds are cleaned up when you +create another tunnel; a live session requires explicit stop. + +## Identity deletion + +The prepared Clerk identity-deletion handler revokes tunnel browser +access created through the deleted identity after Rigbox verifies and commits +the signed deletion event. Older browser grants whose sign-in identity is unknown +are revoked for the affected Rigbox account and Clerk issuer. + +Your Rigbox account, native credentials and other linked identities remain +intact. Another undeleted, verified Clerk identity can keep that account eligible +for tunnels. If the owner loses its only eligible identity, new tunnel access +and lease renewals are refused, including anonymous Public access. Existing +short-lived authority keeps its expiry and polling bounds. + +Provider delivery can be delayed or missed, so provider deletion alone does not +promise immediate revocation. This prepared contract does not establish real +provider delivery or customer availability. + +## HTTPS and local certificates + +Public HTTPS and verified outbound WSS are required. The final hop may use HTTP +on literal loopback. For a local HTTPS service, keep certificate validation on: + +```bash +rig tunnel --port 3443 --https --tls-server-name localhost --ca-cert local-ca.pem +``` + +The CA file stays on your laptop. The connector verifies the certificate name +while dialing the fixed loopback IP; it does not resolve that name to a different +destination. There is no certificate-verification bypass flag. If a development +server rejects the tunnel's Host header, allow the exact printed hostname in its +configuration rather than disabling host checks globally. + +## Compatibility and limits + +Requests carrying `Origin` must name the exact HTTPS tunnel origin. Cross-origin +browser API calls and embedding are rejected even in Public mode; setting CORS +headers on the local app does not bypass the tunnel boundary. Public native HTTP +requires exactly one explicit intent header and no Origin or Fetch Metadata headers: + +```bash +curl -H 'X-Rigbox-Tunnel-Client: native' "$TUNNEL_URL/healthz" +``` + +This header is removed before forwarding. It does not authenticate the caller; +Public mode still permits anonymous access. Webhook providers that cannot set +the header are unsupported. Application WebSockets require the exact tunnel +origin and a completed browser boundary check; native WebSockets are unsupported. +Service workers, PWAs, and Web Workers are unsupported. + +The connector permits 16 concurrent flows with shared bandwidth of approximately +10 Mbps per direction. Uploads are limited to 32 MiB and responses to 128 MiB. +Ordinary HTTP has a 120-second total deadline and a 10-second idle deadline. +An explicit `text/event-stream` response uses a 60-second idle deadline. WebSocket +messages are limited to 256 KiB and compression is disabled. Exceeding a limit +closes the stream; split large transfers and ensure event streams send heartbeats. + +## Automation and output + +Without an interactive terminal, accept exposure explicitly. Public mode needs +both acknowledgments: + +```bash +rig tunnel --port 3000 --acknowledge-exposure --output json +rig tunnel --port 3000 --visibility public --acknowledge-exposure --acknowledge-public +``` + +Plain JSON streams readiness and terminal events as NDJSON. YAML, text, table, +and queried output follow the CLI's document buffering rules and finish when the +foreground command exits. Connector grants, traffic bodies, request URLs, query +strings, cookies, and CA file contents are excluded from tunnel telemetry, even +when HTTP body tracing is enabled. Rigbox terminates public TLS, so its gateway +can process the plaintext HTTP traffic; this is not end-to-end encryption. + +## A small example + +The [planned local-tunnel example](https://github.com/rigbox-dev/rigbox-examples/tree/eacc8f269a567ead9c66106585d7802dd376d466/local-tunnel) +serves fixed in-memory routes with Python and never provides directory browsing +or arbitrary file serving. It can run locally +without exposing a folder; sharing it still requires the enabled tunnel service +and matching CLI. + +Python's general-purpose `http.server` serves files and follows symlinks. Its +directory option is not a filesystem sandbox. Pointing it at a home directory or +repository may expose credentials and private files to admitted visitors. See +the [Python documentation](https://docs.python.org/3/library/http.server.html). diff --git a/openapi/tunnels-api.json b/openapi/tunnels-api.json new file mode 100644 index 0000000..ae22d31 --- /dev/null +++ b/openapi/tunnels-api.json @@ -0,0 +1,464 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Rigbox Public API", + "description": "Gateway-owned public API for Rigbox. The gateway composes its local lifecycle API with service-owned exported specs.", + "contact": { + "name": "Rigbox", + "url": "https://rigbox.dev" + }, + "license": { + "name": "" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://api.rigbox.dev", + "description": "Production gateway" + } + ], + "paths": { + "/api/v1/tunnels": { + "get": { + "tags": [ + "Tunnels" + ], + "operationId": "list", + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TunnelList" + } + } + } + } + }, + "security": [ + { + "bearer": [] + } + ] + }, + "post": { + "tags": [ + "Tunnels" + ], + "operationId": "create", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateTunnelRequest" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateTunnelResponse" + } + } + } + }, + "429": { + "description": "" + }, + "503": { + "description": "" + } + }, + "security": [ + { + "bearer": [] + } + ] + } + }, + "/api/v1/tunnels/{id}": { + "get": { + "tags": [ + "Tunnels" + ], + "operationId": "get", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TunnelDetails" + } + } + } + }, + "404": { + "description": "" + } + }, + "security": [ + { + "bearer": [] + } + ] + }, + "delete": { + "tags": [ + "Tunnels" + ], + "operationId": "stop", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "" + }, + "404": { + "description": "" + } + }, + "security": [ + { + "bearer": [] + } + ] + } + }, + "/api/v1/tunnels/{id}/policy": { + "patch": { + "tags": [ + "Tunnels" + ], + "operationId": "policy", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateTunnelPolicyRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TunnelDetails" + } + } + } + }, + "409": { + "description": "" + } + }, + "security": [ + { + "bearer": [] + } + ] + } + } + }, + "tags": [ + { + "name": "Tunnels" + } + ], + "components": { + "schemas": { + "CreateTunnelRequest": { + "type": "object", + "required": [ + "target" + ], + "properties": { + "target": { + "$ref": "#/components/schemas/TunnelTarget" + } + }, + "additionalProperties": false + }, + "CreateTunnelResponse": { + "type": "object", + "required": [ + "tunnel", + "connector_token", + "lease_token", + "connect_url", + "lease_url", + "lease_ttl_seconds", + "max_slots" + ], + "properties": { + "connect_url": { + "type": "string" + }, + "connector_token": { + "type": "string" + }, + "lease_token": { + "type": "string" + }, + "lease_ttl_seconds": { + "type": "integer", + "format": "int64", + "minimum": 0 + }, + "lease_url": { + "type": "string" + }, + "max_slots": { + "type": "integer", + "format": "int32", + "minimum": 0 + }, + "tunnel": { + "$ref": "#/components/schemas/Tunnel" + } + } + }, + "PublicAcknowledgment": { + "type": "object", + "required": [ + "target_fingerprint", + "connection_generation", + "policy_epoch", + "acknowledged" + ], + "properties": { + "acknowledged": { + "type": "boolean" + }, + "connection_generation": { + "type": "integer", + "format": "int64" + }, + "policy_epoch": { + "type": "integer", + "format": "int64" + }, + "target_fingerprint": { + "type": "string" + } + }, + "additionalProperties": false + }, + "Tunnel": { + "type": "object", + "required": [ + "id", + "user_id", + "hostname", + "target", + "target_fingerprint", + "visibility", + "status", + "policy_epoch", + "connection_generation", + "expires_at", + "created_at", + "updated_at" + ], + "properties": { + "connection_generation": { + "type": "integer", + "format": "int64" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "expires_at": { + "type": "string", + "format": "date-time" + }, + "hostname": { + "type": "string" + }, + "id": { + "type": "string" + }, + "lease_expires_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "policy_epoch": { + "type": "integer", + "format": "int64" + }, + "status": { + "type": "string" + }, + "target": { + "$ref": "#/components/schemas/TunnelTarget" + }, + "target_fingerprint": { + "type": "string" + }, + "updated_at": { + "type": "string", + "format": "date-time" + }, + "user_id": { + "type": "string" + }, + "visibility": { + "type": "string" + } + } + }, + "TunnelDetails": { + "type": "object", + "required": [ + "tunnel", + "allowed_emails" + ], + "properties": { + "allowed_emails": { + "type": "array", + "items": { + "type": "string" + } + }, + "tunnel": { + "$ref": "#/components/schemas/Tunnel" + } + } + }, + "TunnelList": { + "type": "object", + "required": [ + "items" + ], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Tunnel" + } + } + } + }, + "TunnelTarget": { + "type": "object", + "required": [ + "local_ip", + "port", + "scheme" + ], + "properties": { + "http_host": { + "type": [ + "string", + "null" + ] + }, + "local_ip": { + "type": "string" + }, + "port": { + "type": "integer", + "format": "int32" + }, + "scheme": { + "type": "string" + }, + "tls_server_name": { + "type": [ + "string", + "null" + ] + } + }, + "additionalProperties": false + }, + "UpdateTunnelPolicyRequest": { + "type": "object", + "required": [ + "expected_policy_epoch", + "expected_connection_generation", + "visibility" + ], + "properties": { + "allowed_emails": { + "type": "array", + "items": { + "type": "string" + } + }, + "expected_connection_generation": { + "type": "integer", + "format": "int64" + }, + "expected_policy_epoch": { + "type": "integer", + "format": "int64" + }, + "public_acknowledgment": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/PublicAcknowledgment" + } + ] + }, + "visibility": { + "type": "string" + } + }, + "additionalProperties": false + } + }, + "securitySchemes": { + "bearer": { + "type": "http", + "scheme": "bearer" + } + } + } +} diff --git a/scripts/api-navigation-base.json b/scripts/api-navigation-base.json index 41a2e0e..ab11b96 100644 --- a/scripts/api-navigation-base.json +++ b/scripts/api-navigation-base.json @@ -44,6 +44,16 @@ "api-reference/apps/verify-domain" ] }, + { + "group": "Local tunnels", + "pages": [ + "api-reference/tunnels/list", + "api-reference/tunnels/create", + "api-reference/tunnels/get", + "api-reference/tunnels/update-policy", + "api-reference/tunnels/stop" + ] + }, { "group": "App Logs", "pages": [ diff --git a/scripts/build-navigation.py b/scripts/build-navigation.py index 78450be..e637f7c 100644 --- a/scripts/build-navigation.py +++ b/scripts/build-navigation.py @@ -27,7 +27,7 @@ def area(label,pages): group('Workspace images',[group('Reproducible builds',['deploy/build-cache','deploy/reimage','guides/releases-and-rollback'],'deploy/reproducible-builds'),'guides/bluegreen'])]), area('Configure applications',[ group('Configuration',['configure/overview','configure/environment','configure/secrets','configure/parameters','configure/commands','configure/health']), - group('Networking',['guides/visibility','guides/expose-and-route','guides/custom-domains']), + group('Networking',['guides/visibility','guides/expose-and-route','guides/local-tunnels','guides/custom-domains']), group('Manifest reference',[group('rig.yaml',['reference/rig-yaml/application','reference/rig-yaml/workspace','reference/rig-yaml/source','reference/rig-yaml/configuration','reference/rig-yaml/deployment'],'reference/rig-yaml')])]), area('Workspaces and storage',[ group('Workspaces',['workspaces/overview','guides/workspaces','concepts/limits',group('SSH',['workspaces/ssh-keys','workspaces/file-transfer'],'guides/ssh-access'),'guides/images-and-templates']), @@ -48,7 +48,7 @@ def area(label,pages): group('Integrate',['build/overview','build/quickstart','build/workspace-lifecycle','build/deploy-monitor','guides/build-hosting-platform','build/api-conventions']), group('Platform',['concepts/architecture','concepts/security']), group('First-party integrations',['sandbox-api-surface','clawd-api-surface','clawd-runtime-services'])])] -api_groups=[group('Start',['api-reference/overview']),group('Access',[api['API Keys'],api['Access Control']]),group('Workspaces',[api['Workspaces'],api['Workspace Services'],api['SSH Keys']]),group('Applications and releases',[api['Apps'],api['App Logs'],group('App releases',[f'api-reference/app-releases/{x}' for x in ['list','create','get','activate','logs']])]),group('Storage',[api['Snapshots']]),group('AI and tools',[api['AI'],api['Managed Proxy'],api['Tools']]),group('Registry',[api['App Catalog'],api['Templates'],api['Setup Scripts'],api['Service Specs']]),group('Account and platform',[api['User Settings'],api['Roadmap'],api['System']])] +api_groups=[group('Start',['api-reference/overview']),group('Access',[api['API Keys'],api['Access Control']]),group('Workspaces',[api['Workspaces'],api['Workspace Services'],api['SSH Keys']]),group('Applications and releases',[api['Apps'],api['App Logs'],group('App releases',[f'api-reference/app-releases/{x}' for x in ['list','create','get','activate','logs']]),api['Local tunnels']]),group('Storage',[api['Snapshots']]),group('AI and tools',[api['AI'],api['Managed Proxy'],api['Tools']]),group('Registry',[api['App Catalog'],api['Templates'],api['Setup Scripts'],api['Service Specs']]),group('Account and platform',[api['User Settings'],api['Roadmap'],api['System']])] extra=Path('scripts/deployment-api-navigation.json') if extra.exists(): for name,pages in json.loads(extra.read_text())['groups'].items(): From 85316eb04a8a373d8ee0b72a17d147e0dd029fe4 Mon Sep 17 00:00:00 2001 From: jona62 Date: Sun, 4 Oct 2026 00:52:24 -0400 Subject: [PATCH 2/2] docs(tunnels): target pending signed CLI 0.13.1 release --- api-reference/overview.mdx | 2 +- api-reference/tunnels/create.mdx | 2 +- api-reference/tunnels/get.mdx | 2 +- api-reference/tunnels/list.mdx | 2 +- api-reference/tunnels/stop.mdx | 2 +- api-reference/tunnels/update-policy.mdx | 2 +- cli-reference/cli.mdx | 2 +- guides/local-tunnels.mdx | 4 ++-- 8 files changed, 9 insertions(+), 9 deletions(-) diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx index cdf9659..28b62c3 100644 --- a/api-reference/overview.mdx +++ b/api-reference/overview.mdx @@ -10,7 +10,7 @@ Start with the [API quickstart](/build/quickstart) to make an authenticated requ - [Workspaces](/api-reference/workspaces/list): lifecycle and resources. - [Apps](/api-reference/apps/list): installed applications and runtime controls. - [App releases](/api-reference/app-releases/list): prepare and activate v0.13 deployments. -- [Planned local tunnels](/api-reference/tunnels/list): prepared contracts for a service that is currently disabled; the signed CLI 0.13.0 release is not yet published. +- [Planned local tunnels](/api-reference/tunnels/list): prepared contracts for a service that is currently disabled; the signed CLI 0.13.1 release is not yet published. - [Snapshots](/api-reference/snapshots/list): stopped-workspace root-disk checkpoints. - [API keys](/api-reference/api-keys/list): account credentials. diff --git a/api-reference/tunnels/create.mdx b/api-reference/tunnels/create.mdx index 29bfa2b..5a8d46f 100644 --- a/api-reference/tunnels/create.mdx +++ b/api-reference/tunnels/create.mdx @@ -6,7 +6,7 @@ playground: "none" Tunnels are not available to customers yet. The production service is disabled -pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +pending browser-domain isolation, and the planned signed CLI 0.13.1 release is not yet published. This page documents the prepared API contract; it does not enable the service. See [local tunnels](/guides/local-tunnels) for planned use and risks. diff --git a/api-reference/tunnels/get.mdx b/api-reference/tunnels/get.mdx index 9a1768d..c613634 100644 --- a/api-reference/tunnels/get.mdx +++ b/api-reference/tunnels/get.mdx @@ -6,7 +6,7 @@ playground: "none" Tunnels are not available to customers yet. The production service is disabled -pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +pending browser-domain isolation, and the planned signed CLI 0.13.1 release is not yet published. This page documents the prepared API contract; it does not enable the service. See [local tunnels](/guides/local-tunnels) for planned use and risks. diff --git a/api-reference/tunnels/list.mdx b/api-reference/tunnels/list.mdx index 19cdcfd..c92988c 100644 --- a/api-reference/tunnels/list.mdx +++ b/api-reference/tunnels/list.mdx @@ -6,7 +6,7 @@ playground: "none" Tunnels are not available to customers yet. The production service is disabled -pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +pending browser-domain isolation, and the planned signed CLI 0.13.1 release is not yet published. This page documents the prepared API contract; it does not enable the service. See [local tunnels](/guides/local-tunnels) for planned use and risks. diff --git a/api-reference/tunnels/stop.mdx b/api-reference/tunnels/stop.mdx index 638c005..8b03fca 100644 --- a/api-reference/tunnels/stop.mdx +++ b/api-reference/tunnels/stop.mdx @@ -6,7 +6,7 @@ playground: "none" Tunnels are not available to customers yet. The production service is disabled -pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +pending browser-domain isolation, and the planned signed CLI 0.13.1 release is not yet published. This page documents the prepared API contract; it does not enable the service. See [local tunnels](/guides/local-tunnels) for planned use and risks. diff --git a/api-reference/tunnels/update-policy.mdx b/api-reference/tunnels/update-policy.mdx index 27d714c..27cb518 100644 --- a/api-reference/tunnels/update-policy.mdx +++ b/api-reference/tunnels/update-policy.mdx @@ -6,7 +6,7 @@ playground: "none" Tunnels are not available to customers yet. The production service is disabled -pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +pending browser-domain isolation, and the planned signed CLI 0.13.1 release is not yet published. This page documents the prepared API contract; it does not enable the service. See [local tunnels](/guides/local-tunnels) for planned use and risks. diff --git a/cli-reference/cli.mdx b/cli-reference/cli.mdx index b287fd9..74dcbfe 100644 --- a/cli-reference/cli.mdx +++ b/cli-reference/cli.mdx @@ -50,7 +50,7 @@ Choose a command below, then follow its subcommand links. Each page includes its ## Planned local tunnels [`rig tunnel`](/guides/local-tunnels) is prepared for the planned signed CLI -0.13.0 release, which is not yet published. The production tunnel service is +0.13.1 release, which is not yet published. The production tunnel service is disabled pending browser-domain isolation. Its guide documents future commands and risks; these commands require both that matching CLI and an enabled service. The generated command reference above retains its existing source version. diff --git a/guides/local-tunnels.mdx b/guides/local-tunnels.mdx index 12f166b..1a12136 100644 --- a/guides/local-tunnels.mdx +++ b/guides/local-tunnels.mdx @@ -5,7 +5,7 @@ description: "Planned local website tunnels, access controls, and exposure risks Tunnels are not available to customers yet. The production service is disabled -pending browser-domain isolation, and the planned signed CLI 0.13.0 release is not +pending browser-domain isolation, and the planned signed CLI 0.13.1 release is not yet published. The commands below describe prepared behavior and require both that matching CLI and an enabled tunnel service. Reading these instructions does not enable tunnels or expose your laptop. @@ -193,7 +193,7 @@ can process the plaintext HTTP traffic; this is not end-to-end encryption. ## A small example -The [planned local-tunnel example](https://github.com/rigbox-dev/rigbox-examples/tree/eacc8f269a567ead9c66106585d7802dd376d466/local-tunnel) +The [planned local-tunnel example](https://github.com/rigbox-dev/rigbox-examples/tree/073522d4f0cca5e6426cd2afa1a002e3fe37ae2e/local-tunnel) serves fixed in-memory routes with Python and never provides directory browsing or arbitrary file serving. It can run locally without exposing a folder; sharing it still requires the enabled tunnel service