Skip to main content
Publish a port and the CLI prints its URL, https://<port>-<machine id without m_>.<domain>/.
Inside the machine, an agent does the same with instabox-port. Where it is missing, instabox port setup dev installs it.
In the dashboard, a machine’s Ports tab publishes and unpublishes ports and marks private ones. A machine has up to 16 published ports.
The URL is not a secret. A public port (the default) lets anyone reach the whole service until you unpublish it.

​
Share a private port

A private port answers only requests that carry its token. Everyone else gets 401, and those requests never wake the machine.
  • Browsers: share the printed link, which is the URL with ?_token=ibp_…. Opening it redirects to the plain URL and sets a cookie (__Host-instabox_port_auth). Every later request from that browser gets through, WebSockets included.
  • Scripts: send Authorization: Bearer ibp_….
You see the link once, because the server keeps only a hash. --private --rotate-token prints a new link and ends the old link’s connections. Renaming a private port keeps it private, and --public drops the token.

​
Visits wake a paused machine

A visit wakes a machine that paused itself after idle minutes. The request waits for the machine to resume, so a phone app or webhook can reach the URL without starting the machine first. instabox wake <machine> does the same without a request. A machine that you paused or stopped stays offline until you resume or start it, at the same URL. After a stop, start your server again.

​
Reach a port only from your computer

To reach a port without any URL, forward it over SSH: instabox port-forward dev 8080:3000. This works for any TCP service, such as a database or a debugger. See SSH.
A response’s header, meaning the status line and all fields, may be up to 24 KiB. A larger one, such as one with many or very large cookies, gets the platform’s 502 page (“The sandbox service disconnected or is unavailable.”) instead of the app’s response.
Where the server enables it, instabox port publish dev 5432 --tcp prints 5432-<id>.<tcp domain>:443 for raw TCP, such as Postgres or Redis. Connect with TLS and that name as SNI:
psql and libpq 14 and later send SNI. PG17 and later may add sslnegotiation=direct. For older clients, use stunnel or instabox port-forward.
  • The service in the machine sees plain TCP and must use its own password.
  • A raw TCP port is always public: --private does not apply to it.
  • It is in preview, for admins only, until the server opens it to everyone. Then it is for paid plans only, with a per-workspace limit.
  • A connection counts as activity only while bytes flow. An idle pooled connection does not keep the machine awake, so keep pool idle timeouts under minutes or send keepalives.

Preview URLs

Share a running app from an agent’s machine.

Auto-pause and max-run

When a machine pauses itself and what wakes it.