A server running inside a box is only useful if someone can reach it. A teammate who wants to see the preview, a webhook that has to call back, an agent that built a page and needs to show it: all of them need an address, and "ssh in and port-forward" is not one.
kvbox gives a box two ways to be reached. A raw public port for anything that speaks TCP or UDP, and an HTTPS name under kvbox.app for anything that speaks HTTP. This post is about the second one, because it is the one you will reach for most.
Start something to look at
Any server will do. Create a box, then start one inside it. exec waits for its command to finish, so a server has to be detached from the session to let it return:
$ kvbox new lab1$ kvbox exec lab1 -- 'cd /srv; setsid -f python3 -m http.server 3000 > server.log 2>&1 < /dev/null'$ kvbox exec lab1 -- 'curl -s -o /dev/null -w "%{http_code}" localhost:3000'200
At this point the page works, but only from inside the box. It has a private address behind its host, and nothing outside knows about it.
Claim a name
One command gives the box an address:
$ kvbox claim lab1 mysite --port 3000✓ https://mysite.kvbox.app → box lab1 port 3000
That is the whole setup. The address serves over HTTPS with a valid certificate, there is nothing to open on a router, and no DNS to touch.
Names are global and first come, first served. If mysite is taken, the command says so and you pick another. A box holds one name, and removing the box frees it.
More servers, more names
A real lab is rarely one process. There is an API, a dev server, maybe a dashboard. Instead of juggling ports, hang as many names as you like under the one you claimed:
$ kvbox vm proxy add lab1 8080 --name api$ kvbox vm proxy add lab1 5173 --name vite
Now https://api.mysite.kvbox.app reaches port 8080 and https://vite.mysite.kvbox.app reaches port 5173, all inside the same box. Each one is its own origin, so a frontend on one name can call the API on another the way it would in production.
WebSockets pass through, which means a dev server's hot reload works from the public address. Edit a file in the box and the page open in your browser updates.
What happens to a request
A visitor never talks to your box directly. The request goes to an edge service that looks the name up, finds which host the box lives on, and streams the request to that host over its own HTTPS connection. The host forwards it to the box's port.
That path is what lets a box sit anywhere: on a server in a data centre, or on a machine at home behind a router. The address is the same either way.
Sleeping boxes wake up
You do not have to keep a box running to keep its address alive. Hibernate it, and a visit to its HTTPS name wakes it and then serves the page. The first request after a nap takes a few seconds, and the ones after are normal speed.
$ kvbox hibernate lab1$ curl -s -o /dev/null -w "%{http_code}\n" https://mysite.kvbox.app200
A few rules keep this from surprising you. A visit wakes a box at most once a minute. It never happens when your account is out of credit. And a box you stopped on purpose stays stopped: its address shows a "box is stopped" page until you run kvbox start.
For a demo, a preview link or a lab you share now and then, this means you pay for the box while it is awake and the link still works the rest of the time.
Raw ports are still there
HTTPS names carry HTTP only. For a database, an SSH-like service or a game server, publish the port directly:
$ kvbox vm proxy add lab1 5432✓ box lab1 port 5432 is reachable at 203.0.113.5:41822 (tcp)
The public port is picked at random and stays the box's until you remove it. A box can publish up to 16.
One warning
Anyone who has the address can connect. An HTTPS name is public, so put a login in front of anything private before you share the link.
Try it
$ kvbox new lab1$ kvbox claim lab1 mysite --port 3000$ kvbox vm proxy ls lab1
The ports guide in the docs covers the rest: set-port to point a name at another port, rm to drop one name, and release to give the whole address up.