Share a running app

Share a public link when someone else should try the app running on your Template box or devbox — for example, a teammate who wants to click through a feature before you open the pull request. They will open the link in their own browser, without installing boxes.dev or signing in to boxes.dev.

Create the link

Anyone with the link will be able to reach your app. Before sharing, check that the app uses its own authentication for private data or actions. Don't share an unauthenticated admin console or database browser.

1. Select the Template box or devbox where your app is running. If needed, ask its agent to start the HTTP server, or start it yourself in Terminal.
2. Open Ports in the desktop titlebar and find the app's port.
3. Hover over the port's row and choose Share publicly.
4. Read and accept the confirmation, then choose Copy link and send the link to your reviewer.

The confirmation explains that anyone with the public link can reach the app. Select the image to enlarge it.

If Share publicly isn't available, check that the app shows in Ports as a detected HTTP app — its row offers a web URL — and that its port is allowed by the project's rules under Configure port forwarding… in Ports (see changing forwarding rules). If the port isn't listed at all, check the server's output in Terminal (see resolving a missing port).

The HTTPS link points to that exact machine and port. Switching threads or closing the desktop app won't change its destination, and it doesn't depend on local port forwarding. Its address looks like user-preview-<token>.onboxes.dev. The address is hard to guess, but it can appear in browser history, referrer information, and request records; it isn't a substitute for your app's authentication.

Keep the app available

A public link works while its machine is awake and the app is running. Traffic through the link can keep an awake machine active. When visitor traffic and other activity stop, the machine can sleep on its own; leaving the server running doesn't prevent sleep, and the public link cannot wake the machine.

While the machine is asleep or the app is stopped, visitors will see an unavailable page, and Ports marks the link as paused while the machine sleeps. Stopping your app doesn't remove its public link. To restore access, wake the machine and restart the app if needed — the same link will work again. Allow up to one minute after the app returns for the link's availability to refresh, then have your visitor retry.

If boxes.dev recovered the machine after an unexpected stop, check the recovered app before sending anyone back to it. If recovery replaced the machine, the old public link was revoked, so share a new one.

Manage and stop sharing

Open Ports to copy, open, or stop sharing a link on the selected machine; links stay listed there even after their apps stop. To manage links across all of the project's machines, open Public links in the sidebar or choose All public links… from Ports. The sidebar section appears while the project has at least one active link, names the machine that owns each link, and can stop sharing any of them without switching machines.

Choose Stop sharing when the reviewer is finished. This will block new requests and close public WebSocket connections within 30 seconds. It can't take back what a visitor already has: an HTTP response already in progress may finish, and anything they downloaded or cached will remain with them. Your app will keep running, and any other way of reaching it will be unaffected. Sharing the port again later will create a new URL.

Share from a script or agent

An agent or shell script on the Template box or devbox can manage that machine's links with dvb-onbox, the command installed on the machine itself. The dvb CLI belongs on your laptop. Use the following commands to create a link, list active links, or stop sharing when you're finished:

# Create a link
dvb-onbox ports share --port 4000

# List active links
dvb-onbox ports list-public

# Stop sharing when you're finished
dvb-onbox ports stop-sharing --port 4000

Replace 4000 with your app's detected HTTP port. The same conditions apply as in Ports: the port must be allowed by the project's forwarding rules, and excluded, undetected, and non-HTTP ports are rejected. The commands act only on the machine where they run — there is no project or machine selector.

The share command prints the URL so a script can capture it, and repeating it will return the same active link. Add --json to any command for structured output. Links created by an agent will also appear in the desktop app, where you can stop sharing them yourself.

For a callback or API address that you can move between devboxes without changing the URL, use a Project URL.