Guides

Reach a server on a screen

Give a dev server, an app's API or a coding agent's server on a screen its own HTTPS URL, behind a token or a secret link.

A screen makes no connections inbound: nothing on the internet can reach it directly. A port gives one service listening inside the screen its own HTTPS URL, such as a dev server, your app's API, or a coding agent's server like T3 Code's. HTTP and WebSocket requests to that URL reach the service on the screen's port.

Open a port

Start the service on the screen first, for example with exec and "timeout_s": 0 so it keeps running. It can listen on 127.0.0.1; nothing has to listen for the outside. Then:

TerminalCode
curl -X PUT https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/ports/3000 \ -H "Authorization: Bearer $KUBI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"access": "token"}'
JSONCode
{"port": 3000, "access": "token", "url": "https://3000-k7q2m9x4w8p3t6z1b5n0c2v7ra.trykubi.dev", "token": "kpt_...", "screen_id": "scr_7f2kq9w3x8m4b6tzp1ac", "created_at": "2026-11-22T10:43:44.909Z"}

With the SDK:

TypeScriptCode
const screen = client.screen("scr_7f2kq9w3x8m4b6tzp1ac"); const { url, token } = await screen.ports.open(3000); const res = await fetch(`${url}/health`, { headers: { "Kubi-Port-Token": token! } });

Opening a port needs a key with the network permission (Keys and permissions). Agent apps signed in over MCP can't open ports.

AccessWho gets inUse it for
token (default)Requests with Kubi-Port-Token: <token>Scripts, your backend, an SDK
linkAnyone holding the URLBrowsers and apps that can't add a header
  • With token, a request without the token, or with a wrong one, gets 401. The token is removed before the request reaches your service, and your own Authorization header passes through, so the service can keep its own login.
  • With link, the secret is the random part of the URL. Treat the URL like a password, and keep the service's own login on: T3 Code still asks for its pairing code.
  • GET .../ports/3000 shows the URL and the token again. To change a port's access, close it and open it again; it gets a new URL.

What the service sees

  • The request's own Host (the trykubi.dev name), so apps that build links or sign-in URLs from it work. A dev server that only accepts localhost must allow that name: for Vite, server.allowedHosts: [".trykubi.dev"].
  • X-Forwarded-Proto: https, X-Forwarded-Host and X-Forwarded-For with the caller's address.
  • A connection from 127.0.0.1, which is where every request through a port comes from inside the screen. Don't treat that as a local, trusted caller.

Example: T3 Code

Run T3 Code's server on the screen and pair the T3 Code app on your laptop or phone with it:

TerminalCode
# on the screen, through exec with "timeout_s": 0 t3 serve --host 127.0.0.1 --port 3773 --no-browser

Open port 3773 with "access": "link", mint a pairing code on the screen with t3 pair, and in the app choose Add environment, then Remote link, with the port's URL as the host and the code. The app then runs threads, terminals and projects on the screen.

Stop, start and close

  • A port belongs to its screen, not to the key that opened it. It stays open across stop and start with the same URL and token, and closes when the screen is deleted.
  • The service doesn't come back by itself after a start: start it again, or install it as a service on the screen.
  • DELETE .../ports/3000 closes the port and ends every connection through it within a few seconds.
  • GET .../ports lists the screen's open ports.

Errors

These come from Kubi, in the error shape. Every other answer is your service's own.

StatusCodeMeans
401UNAUTHENTICATEDNo token, or a wrong one
403ORGANIZATION_SUSPENDEDThe organization is suspended
404NOT_FOUNDNo such port, or it was closed
409SCREEN_NOT_RUNNINGThe screen is stopped; start it
429RATE_LIMITEDOver a port limit below; see Retry-After
502PORT_NOT_LISTENINGNothing listens on that port in the screen
503SCREEN_UNAVAILABLEThe screen can't be reached right now; retry

A fourth port on a screen is refused with 402 QUOTA_EXCEEDED.

Limits

WhatLimit
Open ports3 per screen, included in the price
Requests300 a second per screen, bursts up to 2,000
WebSockets open at once32 per screen
Idle connection5 minutes for HTTP, 1 hour for a WebSocket
Request headers16 KiB

Ports carry HTTP and WebSocket only, not raw TCP: SSH, databases and other TCP protocols don't go through them.

Ports are for your own use and your agents', not for serving the public: don't run a public website, shop or API on one. Anyone who has a link URL reaches the service behind it.