From 85fb18292f86c11ca499e31f2879badbd8f815dd Mon Sep 17 00:00:00 2001 From: jona62 Date: Sun, 4 Oct 2026 17:19:56 -0400 Subject: [PATCH] docs(tunnels): explain session reuse and history deletion --- api-reference/tunnels/delete-record.mdx | 20 ++++++++++++++ api-reference/tunnels/get.mdx | 2 ++ api-reference/tunnels/list.mdx | 2 ++ api-reference/tunnels/stop.mdx | 2 ++ docs.json | 3 ++- guides/local-tunnels.mdx | 29 +++++++++++++++----- openapi/tunnels-api.json | 35 +++++++++++++++++++++++++ scripts/api-navigation-base.json | 3 ++- 8 files changed, 88 insertions(+), 8 deletions(-) create mode 100644 api-reference/tunnels/delete-record.mdx diff --git a/api-reference/tunnels/delete-record.mdx b/api-reference/tunnels/delete-record.mdx new file mode 100644 index 0000000..563d01e --- /dev/null +++ b/api-reference/tunnels/delete-record.mdx @@ -0,0 +1,20 @@ +--- +title: "Delete tunnel history" +openapi: "/openapi/tunnels-api.json DELETE /api/v1/tunnels/{id}/record" +playground: "none" +--- + +Removes an inactive tunnel record owned by the current account and returns `204` +with no response body. This also removes its invitations, browser viewer grants, +and pending login transactions. Deletion cannot be undone. + +A live tunnel or valid pending start returns `409` with error code +`TUNNEL_RECORD_ACTIVE` and the message "Stop this tunnel before deleting its +history". [Stop the tunnel](/api-reference/tunnels/stop) first, then delete the +record. Stopped, expired, and already timed-out records can be removed. + +Deleted and other accounts' records return `404`. Deleted records no longer +appear in [List local tunnels](/api-reference/tunnels/list) or +[Inspect a local tunnel](/api-reference/tunnels/get). + +The existing `DELETE /api/v1/tunnels/{id}` remains Stop and keeps history. diff --git a/api-reference/tunnels/get.mdx b/api-reference/tunnels/get.mdx index 34e2561..e64ca60 100644 --- a/api-reference/tunnels/get.mdx +++ b/api-reference/tunnels/get.mdx @@ -14,3 +14,5 @@ before sharing an app. 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). + +After the owner [deletes this record](/api-reference/tunnels/delete-record), inspection returns `404`. diff --git a/api-reference/tunnels/list.mdx b/api-reference/tunnels/list.mdx index 5d8d1dd..f9fd744 100644 --- a/api-reference/tunnels/list.mdx +++ b/api-reference/tunnels/list.mdx @@ -13,4 +13,6 @@ before sharing an app. 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. +Stopped and expired records remain listed until the owner [deletes their history](/api-reference/tunnels/delete-record). + 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 index 58fdacb..488835d 100644 --- a/api-reference/tunnels/stop.mdx +++ b/api-reference/tunnels/stop.mdx @@ -13,4 +13,6 @@ before sharing an app. 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. +Stop keeps the tunnel record in your history. Use [Delete tunnel history](/api-reference/tunnels/delete-record) to remove an inactive record. + A stopped connection generation cannot be resumed. Start a new tunnel through the [CLI](/guides/local-tunnels#start-privately) when you want to serve the website again. diff --git a/docs.json b/docs.json index fdec634..9ceb7a1 100644 --- a/docs.json +++ b/docs.json @@ -334,7 +334,8 @@ "api-reference/tunnels/create", "api-reference/tunnels/get", "api-reference/tunnels/update-policy", - "api-reference/tunnels/stop" + "api-reference/tunnels/stop", + "api-reference/tunnels/delete-record" ] } ] diff --git a/guides/local-tunnels.mdx b/guides/local-tunnels.mdx index 4e269e8..f8efe06 100644 --- a/guides/local-tunnels.mdx +++ b/guides/local-tunnels.mdx @@ -34,9 +34,12 @@ 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. +that URL using the owner's Rigbox browser account. An existing active browser +session can be reused; sign in if your session has ended. Rigbox verifies the +current browser token and provider session before granting access, and you +choose Continue to app. Opening a tunnel does not itself require a new password +or MFA check. A CLI API key does not mint a browser viewer session. +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. @@ -126,7 +129,8 @@ Press Ctrl-C in the foreground command, or stop from another terminal: rig tunnel stop --tunnel TUNNEL_ID ``` -Stop revokes the session and connector. Changing access closes flows admitted +Stop revokes the session and connector and keeps the record in your history. +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 @@ -136,8 +140,21 @@ 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. +leases and sessions that never started within 60 seconds cannot be revived. +Starting another tunnel marks the previous stale record expired; it remains +in your history until you delete it. + +### Delete history + +In the Console's Tunnels page, choose Delete history for a stopped or expired +session and confirm its removal. This removes the record from your history and +cannot be undone. Stop an active tunnel first; deletion does not stop it for you. + +The API provides the same cleanup through +[`DELETE /api/v1/tunnels/{id}/record`](/api-reference/tunnels/delete-record). +The existing `DELETE /api/v1/tunnels/{id}` remains Stop. A live tunnel or valid +pending start returns `409 TUNNEL_RECORD_ACTIVE` when you try to delete its +history. ## Identity deletion diff --git a/openapi/tunnels-api.json b/openapi/tunnels-api.json index ae22d31..cb2cd76 100644 --- a/openapi/tunnels-api.json +++ b/openapi/tunnels-api.json @@ -197,6 +197,41 @@ } ] } + }, + "/api/v1/tunnels/{id}/record": { + "delete": { + "tags": [ + "Tunnels" + ], + "description": "Delete inactive tunnel history. Stop an active tunnel first.", + "operationId": "delete_record", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "" + }, + "404": { + "description": "" + }, + "409": { + "description": "" + } + }, + "security": [ + { + "bearer": [] + } + ] + } } }, "tags": [ diff --git a/scripts/api-navigation-base.json b/scripts/api-navigation-base.json index ab11b96..6475341 100644 --- a/scripts/api-navigation-base.json +++ b/scripts/api-navigation-base.json @@ -51,7 +51,8 @@ "api-reference/tunnels/create", "api-reference/tunnels/get", "api-reference/tunnels/update-policy", - "api-reference/tunnels/stop" + "api-reference/tunnels/stop", + "api-reference/tunnels/delete-record" ] }, {