# 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:

```bash
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"}'
```

```json
{"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:

```ts
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](/concepts/permissions)). Agent apps signed in over MCP can't open ports.

## Token or link

| Access | Who gets in | Use it for |
|---|---|---|
| `token` (default) | Requests with `Kubi-Port-Token: <token>` | Scripts, your backend, an SDK |
| `link` | Anyone holding the URL | Browsers 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:

```bash
# 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](/errors). Every other answer is your service's own.

| Status | Code | Means |
|---|---|---|
| 401 | `UNAUTHENTICATED` | No token, or a wrong one |
| 403 | `ORGANIZATION_SUSPENDED` | The organization is suspended |
| 404 | `NOT_FOUND` | No such port, or it was closed |
| 409 | `SCREEN_NOT_RUNNING` | The screen is stopped; start it |
| 429 | `RATE_LIMITED` | Over a port limit below; see `Retry-After` |
| 502 | `PORT_NOT_LISTENING` | Nothing listens on that port in the screen |
| 503 | `SCREEN_UNAVAILABLE` | The screen can't be reached right now; retry |

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

## Limits

| What | Limit |
|---|---|
| Open ports | 3 per screen, included in the price |
| Requests | 300 a second per screen, bursts up to 2,000 |
| WebSockets open at once | 32 per screen |
| Idle connection | 5 minutes for HTTP, 1 hour for a WebSocket |
| Request headers | 16 KiB |

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

:::caution
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.
:::
