url.md

Shareable URLs

Shareable URLs make an HTTP service running on a Devbox accessible through a devbox.so URL. Use them to access web applications, APIs, dashboards, and other HTTP endpoints from outside the Devbox.

Unlike port forwarding, a shareable URL does not require a local port or a running CLI process.

Expose a shareable URL

Expose an application running on port 3000 so you can open it in your browser:

1. Start a service

Start the HTTP server on your Devbox, for example a web project on port 3000. Run it as a service to keep it running and restart it if it fails.

2. Expose the service

CLI

devbox url expose my-devbox --port 3000 --name web

Omit the Devbox name to select it interactively. The CLI prints the URL to access the service:

 ╭───────────────────────────────────────────────────────╮
 │ Port Name URL                                         │
 │───────────────────────────────────────────────────────│
 │ 3000 web  https://dbxobe71pivgcufc-p3000.devbox.so/   │
 ╰───────────────────────────────────────────────────────╯

TS SDK

const devbox = await client.devboxes.get("my-devbox");

const port = await devbox.exposedPorts.create({ name: "web", number: 3000 });
console.log(port.url);

See exposedPorts.create().

Dashboard

Open the Devbox in the dashboard and press Expose port in the Exposed URLs section. Enter the Port and an optional Name, then press Expose port.

3. Access the service

Open the URL in your browser to access the service. Shareable URLs require authentication, so you will be prompted to log in with your Namespace account if you are not already logged in.

Manage shareable URLs

View exposed URLs

CLI

View every shareable URL exposed by the Devbox:

devbox url list my-devbox

Retrieve the shareable URL for a specific port:

devbox url get my-devbox --port 3000

Retrieve a shareable URL by its assigned name:

devbox url get my-devbox --name web

TS SDK

List every exposed URL, or look one up by id, name, or number:

const ports = await devbox.exposedPorts.list();
const web = await devbox.exposedPorts.get({ name: "web" });

console.log(web.url);

Dashboard

The Exposed URLs section of a running Devbox lists each URL by name, or by port when it has no name. Select one to open it.

Remove a shareable URL

When you no longer need a shareable URL, remove it by port or name. The server behind it keeps running.

CLI

Remove the shareable URL for a specific port:

devbox url unexpose my-devbox --port 3000

Remove the shareable URL for a specific name:

devbox url unexpose my-devbox --name web

TS SDK

await devbox.exposedPorts.delete({ number: 3000 });

Select the port by exactly one of id, name, or number.

Dashboard

In the Exposed URLs section, hover over a URL, press the × button, and confirm Remove exposed port.

Manage access

Shareable URLs use one access mode for all exposed ports on a Devbox:

private limits access to the Devbox owner.
workspace allows access to members of the workspace.

Set the access mode while exposing a port:

devbox url expose my-devbox --port 3000 --access workspace

To inspect or change the access mode later, use devbox url access:

Check access

devbox url access my-devbox

devbox.so access: workspace

Update access

devbox url access my-devbox --mode private

devbox.so access changed from workspace to private

For all available commands and options, see the devbox url CLI reference.

From within a Devbox

The devbox CLI is installed and authenticated inside a Devbox, which allows you to expose and manage shareable URLs from within the Devbox shell.

Tell your agent

An agent with the Namespace devboxes skill installed can expose a port and report the URL for you. Ask for the outcome rather than the command:

expose the port my web app runs on and give me its shareable URL

The skill uses devbox url expose, and asks before changing the access mode, since that setting applies to every URL on the Devbox.

Port forwarding

Forward ports from your Devbox to localhost. Keep the command running for as long as you need the ports:

devbox port-forward my-devbox --ports 3000,8080

Remap ports with local:remote syntax:

devbox port-forward my-devbox --ports 4000:3000

If your Devbox has configured port forwards in its blueprint, running devbox port-forward my-devbox without --ports forwards all of them automatically.

See devbox port-forward for every option.