Burrowee Docs

Appearance

Sessions ​

A session is a time-limited grant of access to one target. Minting a session produces a token; a browser request carrying that token (it rides in the session URL) is verified by the gateway and forwarded to the target. No token, no access — unless you've explicitly marked a domain public.

Sessions are owned by the gateway and stored locally; the cloud console mirrors them so you can see and manage them from anywhere. Each session has a target, an optional label (free text, up to 64 characters — "for Alex", "demo until Friday"), a creation time, and an expiry.

Sessions apply to web targets only — a raw target has no session surface (access control happens at the protocol you tunnel, like SSH's own auth). And on a web target whose domains are all marked public, the sessions controls are hidden: there is nothing a session would gate.

Two kinds of session ​

Full sessions are the normal kind: one URL that opens the target — every page of it — until the session expires or you revoke it. Mint one, send the link, done.

Page-share sessions are for sharing single pages of an app rather than the whole thing. Minting one returns a base token plus a share seed; the target application uses the seed to derive a separate token per page, so each link you hand out opens exactly one page. This needs a small amount of support inside the target app — the reveal dialog in either console links app developers to the integration guide.

Minting ​

Mint sessions from a target's detail view — in the local console or the cloud console — choosing a label and a TTL. The default TTL is 24 hours.

For a page-share session, the mint response is special: it shows the base token, the share seed, and an example URL, and the seed is shown to you at mint time with a copy-it-now warning. Treat the seed like a password — anyone holding it can derive valid page links. Both consoles can re-reveal it later from the session row: the local console reads it directly (loopback-only, on the gateway machine), and the cloud console's reveal is a live pull from your gateway through the relay — the cloud never stores the seed itself.

Every active full session has a Copy button. If its target has a domain attached (custom domain first, else the random one), Copy puts the complete viewer URL on your clipboard — https://<domain>/?<name>=<token>, ready to paste into a browser. Without a domain yet, it falls back to copying the bare session token.

TTL, extend, relabel, revoke ​

Every session expires on its own at the end of its TTL. Until then you can manage it from either console:

  • Extend / set expiration — pick a number of days (1 to 365); the expiry becomes that many days from now. The default in the dialog is 30.
  • Relabel — change the display label any time; the token is untouched.
  • Revoke — kill the session immediately (a two-step confirm in both consoles guards against a stray click). Links stop working at once, and a revoked session cannot be extended back to life: mint a new one instead.
  • Delete — remove the (expired or revoked) row from the list entirely, also behind a two-step confirm.

Sessions survive restarts — but not target deletion

Sessions are persisted in the gateway's store, so a gateway restart or machine reboot doesn't invalidate your links. Deleting the session's target does — see the warning in Targets.

Seeing who's connected ​

Open sessions show up live while they are open — the local console's live view lists each one with the relay carrier it rides, and the cloud console's gateway Live tab mirrors the same registry. Only genuinely open sessions count: an orphaned session that never closed cleanly doesn't linger as "live". Daily byte counters accrue while a session runs, not only when it closes.

Each session also carries a liveness lease that syncs through the relay. A lease that has never managed to sync shows as unproven rather than lapsed — "we haven't heard yet" is a different statement from "it stopped".

Instead of sending someone the raw session URL, you can send a gated share link. The Share action on a session row produces a https://…/share/<code> link; whoever opens it signs in to Burrowee first and is then taken to the session viewer. That gives you a named, sign-in-gated handoff — useful when "anyone holding the URL" is too loose — while revocation still works exactly the same: revoke the session and the share link dies with it.