Preview your app

Your app runs on a devbox in the cloud, but you can test it in your laptop's browser. The boxes.dev desktop app forwards the devbox's ports to your laptop, so an address such as http://localhost:3000 can reach your app on the devbox.

Open a running app

1. In the desktop app, select a thread on the devbox you want to test, or select the Template box to test an app running there.
2. Ask the agent to start your app. You can also open Terminal from the titlebar and run your project's development command yourself.
3. Open Ports in the titlebar, then click your app's web URL. It will open in your laptop's browser.

By default, boxes.dev forwards each detected port to the same port on your laptop, so an app listening on the devbox's port 3000 appears at http://localhost:3000. Use the address shown in Ports: it will differ when the project's forwarding rules map the port elsewhere, or when a busy laptop port needed a temporary substitute.

Forwarding also follows your selection, so when you select a thread on a different devbox, the same address will reach that devbox instead. To keep several devboxes reachable at once, use Local URLs below.

The local addresses in Ports work only on your laptop. To let someone else try your app, create a public app link. To inspect a page together with your agent, use the shared Browser on the devbox.

Ports lists the detected server and the local address you can open. Select the image to enlarge it.

Resolve a missing or busy port

If your app is missing from Ports, check that you selected the machine where it's running. If that machine is sleeping, wake it from the machine status control in the titlebar and wait for Ports to refresh. If the app's port still doesn't appear, check the server's output in Terminal. When the Ports menu is empty, its header says why: no ports detected yet, still waiting for the machine, or reconnecting.

If Ports reports that a local port is in use by another program on your laptop, choose Use next available when offered. boxes.dev will pin the devbox's port to a free local port and show the new URL in the menu. The pin lasts for the rest of the current desktop app session, including across sleep and wake, and clears when you quit the app; choose Unpin to return to the saved mapping sooner.

Keep a devbox's local URL available

To keep a devbox reachable when you select another machine, select it, open Ports, and turn on Local URLs. boxes.dev will generate a hostname for that devbox and give each of its web apps an address in the form http://<name>.localhost:<port>. From then on, open the generated address shown in Ports: it replaces the plain localhost forward for each included HTTP app. The generated address will keep pointing to this devbox after you select another thread, so you can compare apps on different devboxes in separate browser tabs.

Local URLs include each detected HTTP app on ports 1024–65535, unless your forwarding rules exclude the port. The addresses use plain HTTP and need no local certificate or administrator approval.

You can turn the setting on before starting your app. Each app will get its address when it starts, at the same hostname with its own port number, and while the devbox is awake, stopping an app will release its address. The hostname and the setting survive desktop app restarts.

The addresses stay allocated while the devbox sleeps, but requests won't wake it by default. Turn on Wake on request if you want them to; requests can then wake the devbox repeatedly and consume box-hours.

Turn off Local URLs to release the devbox's stable addresses and return its ports to ordinary forwarding. If another process on your laptop owns one of the required ports, boxes.dev will report the conflict rather than move the stable URL to a different port.

Change forwarding rules

In Ports → Configure port forwarding…, you can change the default, allow or exclude ports and ranges, or map a devbox port to a different laptop port. The same rules apply to every machine in the project: its devboxes, and the Template box when the project has one.

Rules apply from top to bottom; the first match wins. Expand Effective policy to inspect the result before applying your changes. If you close the editor first, your unapplied changes will stay on this laptop until you apply or discard them.

Turn off Forwarding in the Ports menu to release all local ports used by the desktop app. Your configuration will remain saved, and the titlebar will show Ports off. Turn it back on to resume forwarding.

Connect other tools and services

For a database or another non-web service, click its row in Ports to copy the local address, then paste it into your database tool or other client on your laptop. Process names and service labels in the menu, such as Postgres or Redis, can help you find the right row. TLS, databases, SSH, and other non-HTTP services use ordinary TCP forwarding.

For HTTP and WebSocket apps, use the address displayed in Ports: localhost, a loopback IP such as 127.0.0.1, or a generated .localhost address. A custom hostname that you've pointed at 127.0.0.1 in your hosts file will be rejected, even though it resolves to the same local port.