HTTP access

Mint preview URLs for HTTP services running inside a sandbox.

To reach an HTTP server running inside a sandbox (a dev server, a Jupyter kernel, an agent webhook), mint a preview URL for the port. The platform routes the public URL through its gateway into the sandbox.

List listening ports

Not sure which port your service bound to? List the ports the sandbox is currently listening on, each with the process that owns it:

tektona sandbox ports <sandbox-id>

The sandbox must be running. Pass --json for machine-readable output. Use this to find the port, then mint a preview URL for it.

Mint a preview URL

tektona sandbox preview <sandbox-id> <port>

For a sandbox created with --public and no TTL, the CLI returns the durable canonical URL. Otherwise it issues a bearer-token URL that expires. When no TTL is provided for a token URL, the server default is 12 hours.

Time-bounded preview

tektona sandbox preview <sandbox-id> 3000 --ttl 1h

--ttl accepts Go-style durations: 15m, 1h, 1h30m, 24h. The minimum is 1 minute and the maximum is 24 hours. Token URLs expire when the TTL runs out, so the URL stops working without a separate revoke.

Open in a browser

tektona sandbox preview <sandbox-id> 3000 --open

Or -b for short. The CLI also copies the URL to your clipboard by default, so pass --copy=false to skip.

Revoke a preview URL early

tektona sandbox revoke-preview <sandbox-id> <token>

Alias: tektona sandbox rp. Revocation is idempotent. Calling it on an already-expired or revoked token still succeeds.

HTTP/2 and gRPC

Preview URLs speak HTTP/2 and HTTP/1.1 to clients. Your server in the sandbox gets HTTP/1.1, except for gRPC requests. You configure nothing.

gRPC requests reach your server over HTTP/2 without TLS (h2c), which is the default for gRPC servers without TLS. Unary calls and client, server and bidirectional streams work. A stream stays open while the client and the server keep it open.

The client connects with TLS on port 443 to the host of the preview URL. Set the authority to the host without the port:

grpcurl -authority <preview-host> <preview-host>:443 list

<preview-host> is the preview URL without https://. Many gRPC clients send the port in the authority by default (<preview-host>:443). A preview URL does not accept that authority, and the call fails with Unimplemented. In a Go client, use grpc.WithAuthority("<preview-host>").

Public sandboxes

Make a sandbox publicly reachable on canonical preview URLs from the start:

tektona sandbox create tektona/desktop --egress-network-policy tektona/open --public

Subsequent preview calls without --ttl return canonical URLs that stay valid for the lifetime of the sandbox.

Flags

FlagDefaultPurpose
--ttl(none)URL lifetime (15m, 1h, 24h, min 1m, max 24h)
--copytrueCopy the URL to the clipboard (TTY only)
-b, --openfalseOpen the URL in a browser

On this page