Guides

Ports

Publish a port and a server running inside a box gets its own HTTPS URL. Leave it public for demos and webhooks, or make it private so only people holding the link get in.

Publish a port

moil port publish dev 3000 --name 'Web app'   # prints the URL; anyone can open it
moil port publish dev 3000 --private           # prints a link with a token
moil port publish dev 3000 --private --rotate  # a new link; the old one stops working
moil port publish dev 3000 --public            # open to anyone again
moil port ls dev
moil port unpublish dev 3000

The URL looks like https://3000-b7k2q9.box.moil.dev: the port, then the box’s ID. TLS is handled for you, and WebSockets work. A public URL is not a secret — anyone who has it reaches the whole service until you unpublish it.

From inside the box

An agent working in the box can publish its own ports with moil-port, which is already installed:

moil-port publish 3000
moil-port serve ./report --port 8080   # serve a folder with an index.html

Private ports

A private port only answers requests that carry its token. Share the printed link: a browser that opens it gets a cookie and is redirected to the plain URL, so every later request — WebSockets included — gets through. Scripts send the token as a header instead:

curl -H "Authorization: Bearer $PORT_TOKEN" https://3000-b7k2q9.box.moil.dev/health
  • Everyone else gets 401, and their requests never wake the box.
  • The link is shown once; Moil only keeps a hash of the token. --rotate prints a new one and drops the old link’s connections.
  • --public removes the token and opens the port to anyone.

Paused boxes and URLs

A request to a box that paused itself for being idle wakes it: the request waits while the box resumes, then goes through. That lets a webhook or a phone reach a box without starting it first. A box you paused or stopped stays offline and its URLs answer 503 until you resume or start it — after a stop, start your server again too.

Just for you: port forwarding

For a database, a debugger or anything else you don’t want on the internet, forward the port to your own machine instead. Nothing is published, and the tunnel lasts until Ctrl-C.

moil port forward dev 5432          # localhost:5432 → the box's 5432
moil port forward dev 8080:3000     # localhost:8080 → the box's 3000

Good to know

  • Up to 16 published ports per box. The dashboard’s Ports tab shows them and which are private.
  • Response headers can be up to 24 KiB; larger ones get a 502 from the edge instead of your app’s response.
  • Traffic into a box is free. Responses count toward your plan’s monthly egress.