Computer ports and URLs

This page lists the exact rules for published ports and the computer url. To publish a port, see Publish a computer on an HTTPS URL. For state names, see Computer lifecycle states.

Port mappings

Each mapping has three fields.

Field	Meaning	Constraint
`published`	Port on the platform side. Forms the URL.	`443` or `8000` to `20000`. Unique within the list.
`target`	Port the workload listens on inside the computer.	`1` to `65535`.
`protocol`	How the platform speaks to the workload.	`http1` (default) or `http2` (h2c).

A computer holds at most 16 mappings.
A mapping list replaces as a whole. Send the full list to change one mapping.

Shorthand syntax

The CLI accepts this syntax for nevia new -p and nevia set -p. Repeat -p or separate values with commas.

Input	Published	Target	Protocol	URL
`8080`	8080	8080	http1	`https://<host>:8080`
`443:8080`	443	8080	http1	`https://<host>`
`8080/h2`	8080	8080	http2	`https://<host>:8080`
`443:3000/h2`	443	3000	http2	`https://<host>`
`none`	n/a	n/a	n/a	Clears all mappings (`nevia set` only)

MCP takes the same fields as objects: {"published": 443, "target": 3000, "protocol": "http2"}. protocol is optional and defaults to http1.

Protocols

Protocol	Speaks to the workload	Use when
`http1`	HTTP/1.1	Default. Web servers and most APIs.
`http2`	HTTP/2 over plaintext (h2c)	The workload speaks only HTTP/2, such as gRPC.

TLS ends at the platform in both cases. Clients always connect to https://. The workload never serves TLS. The /h2 suffix and http2 set only the protocol to the workload.

URLs

Rule	Detail
Form	`https://<host>` for `443`. `https://<host>:<published>` for any other port.
Computer `url`	Set once, when the computer first becomes `ready`. It never changes.
Per-mapping `url`	Each mapping response includes its own `url`.
Before a hostname	The mapping `url` is `null` until the computer has a hostname.
Stability	Sleep and wake keep the `url`. Branch and checkpoint restore issue a new `url`.
Auth	The URL has no authentication. Anyone with the address can reach it.

url shows an address, not the current state. A sleeping computer keeps its url but does not answer on it.

Behaviour by state

State	Computer `url`	Ports
`creating`	Not yet set.	Do not answer.
`ready`	Set.	Answer when the workload listens on the target. Return `503` when nothing listens.
`sleeping`	Kept.	Do not answer. Changes are refused with `409 invalid_state`.

Behaviour by lifecycle action

Action	URL	Ports	Programs
Sleep	Kept.	Kept. Do not answer while asleep.	Paused in memory. Active exec sessions end.
Wake	Kept.	Kept. Answer again.	Resume. Exec sessions do not reconnect.
Branch	New `url` on a new computer.	Same mapping list.	Not copied. Ports return `503` until something listens.
Restore a checkpoint	New `url` on a new computer.	Same mapping list.	Not copied. Ports return `503` until something listens.
Update ports	Kept.	Replaced by the new list. Open connections are interrupted.	Keep running.

Port changes require the ready state. A sleeping computer refuses them until you wake it.

Responses

Condition	Response
Workload listens on the target	Forwarded to the workload.
Nothing listens on the target	`503`.
Computer sleeping	Port does not answer.
Port change while sleeping, transitioning or otherwise not `ready`	`409 invalid_state`.

Interfaces

Interface	Set ports at create	Change ports later	Notes
CLI	`nevia new -p <MAPPING>`	`nevia set <COMPUTER> -p <MAPPING>`	`-p` is repeatable or comma-separated. `none` clears. The CLI publishes nothing by default.
MCP	`create_computer` with `ports`	`update_computer` with `ports`	`[]` removes HTTPS. Omit `ports` to leave the list unchanged.
Console	Publishes `443` for new computers.	Toggle, target port and protocol.	Shows one endpoint: the `443` mapping. Mappings on other ports stay in place and do not appear.

Use nevia status <COMPUTER> to read the computer url. See nevia new and nevia set for all flags.

Computer ports and URLs

On this page