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 follows your selection by default, so when you select a thread on a different devbox, the same address will reach that devbox instead. Keep localhost on one devbox to continue watching its app while you work elsewhere, or use Local URLs to keep several devboxes reachable at once. Both options are 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.

Keep localhost on one devbox

1. Select a thread on the devbox running your app, or select the Template box if the app runs there.
2. Open Ports, then choose the computer icon beside the Port forwarding switch. Its tooltip says Pin localhost to this devbox or Pin localhost to this Template box.
3. Continue working in other threads. Your app's localhost addresses will stay on the box you chose, including when you start writing a new-thread prompt.

The computer icon turns amber when enabled. The same amber icon marks the box in the sidebar. Your choice includes all its ports allowed by the project's forwarding rules, including ports detected later, and is saved for your account on this computer across desktop app restarts. To release localhost without opening the box, choose Unpin localhost from that devbox's right-click menu or the Template box's actions menu. This action appears only on the box keeping localhost.

When you select another devbox, its Ports menu will show an amber localhost is on {name} pill. Choose the name to return to the box using localhost, or choose X to let localhost follow selection again. You can also release it with the enabled computer icon, or move localhost by choosing the computer icon on another devbox. On a new-thread draft, Ports remains available for the box using localhost.

Keeping localhost does not keep the box awake or freeze its branch. To keep the box awake while you test, choose Keep awake in the titlebar status menu (see Sleep, wake, and recover). If the box sleeps, select it and wake it as usual. If it is deleted or becomes unavailable, release localhost or choose another box; it won't silently switch to the devbox you are viewing. Terminal, Git, and the other tools still follow your selection.

Signing in to an MCP on the Template box temporarily uses only its sign-in callback port. Your app's other ports stay on the box you chose.

Resolve a missing or busy port

If your app is missing from Ports, check that you selected the box where it's running. If that box is sleeping, wake it from the 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 box, or reconnecting. If the menu says localhost is on another box, choose the pill's X to resume forwarding for your current selection.

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.

Ports below 1024, such as 80 and 443, show privileged port until you add a rule for them. On macOS, to use the same local port, add a rule for that single port, such as 443, as described in Change forwarding rules. Linux normally reserves these ports for root on localhost, so that rule won't work there.

On either system, you can choose Use next available to forward the port 8000 ports higher, such as 8080 for 80 or 8443 for 443. To keep that mapping after you quit the app, add a rule that maps the port to a higher local port.

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 unless you also keep localhost on this devbox, in which case both addresses will work. 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 you view the awake devbox, stopping an app will release its address. Existing addresses stay allocated while you work elsewhere and refresh when you return. If you also keep localhost on that devbox, newly detected apps will continue getting Local URLs while you work elsewhere. 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. Ordinary forwarding will follow your localhost selection or saved owner. 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 the Port forwarding switch at the top of the Ports menu to stop ordinary localhost forwarding for that project. Your rules and choice of localhost owner will remain saved. Turn it back on to resume forwarding. Local URLs has its own switch and remains available independently.

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.