> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Open a port of a sandbox on a public URL

> Give a port of a sandbox an HTTPS URL, open it with its token or to everyone, and use WebSockets through it.

Give a port of a sandbox an HTTPS URL, such as `https://web-app-3000-k3m7q2v9.vmsdev.run`. Use it to show a web app that runs in the sandbox. A URL needs its token, unless you make it public.

Write the code that shows a dev server of a sandbox on a URL.

Use POST /v1/sandboxes/{id}/urls with port 3000 in the JSON body to get an HTTPS URL for port 3000 of a sandbox.
Open the url of the answer with ?\_token=TOKEN, where TOKEN is the token of the answer.
Send public true in the JSON body to open the URL to everyone.
Make the dev server listen on all addresses, not only on localhost.
Do not ask me to share my API key.

## Before you start

* You need an API key with the `sandboxes:write` scope to create, change, and delete a URL, and `sandboxes:read` to list them. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* A server must listen on the port in the sandbox. Make it listen on all addresses, such as `0.0.0.0` or `::`, not only on `localhost`. For example, run `npm run dev -- --host` for Vite.

## Create a URL

Send `POST /v1/sandboxes/{id}/urls` with the port. A sandbox has up to 20 URLs, one for each port. You cannot use port 22, port 7911, or port 7912.

```typescript TypeScript theme={null}
const response = await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/urls`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VMS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ port: 3000 }),
  },
);

const url = await response.json();
```

```bash cURL theme={null}
curl -X POST "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/urls" \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 3000}'
```

The answer is `201` with the URL:

```json theme={null}
{
  "id": "url_06d8k3m7q2v9x4b1n5c0e8f2jb",
  "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "port": 3000,
  "url": "https://web-app-3000-k3m7q2v9.vmsdev.run",
  "public": false,
  "token": "vmsu_Gq3n0Yb1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t",
  "createdAt": "2026-11-16T03:30:00.000Z",
  "updatedAt": "2026-11-16T03:30:00.000Z"
}
```

The URL has the name of the sandbox, the port, and a code of your workspace. A sandbox with no name, or with a name that is too long, has its ID in the URL. `GET /v1/sandboxes/{id}` also shows the URLs in `urls`.

A second URL for the same port answers `409`. To create, change, or delete many URLs of a sandbox in one request, send `POST /v1/sandboxes/{id}/urls/create-many`, `update-many`, or `delete-many`.

An API key without `sandboxes:write` gets `null` in `token`. It sees the URL, but it cannot open a URL that needs the token.

## Open the URL

Open the URL with `?_token=` and the token:

```text theme={null}
https://web-app-3000-k3m7q2v9.vmsdev.run/?_token=vmsu_Gq3n0Yb1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t
```

* A browser gets a cookie for the URL and goes to the same page without the token. The cookie works for 7 days.
* A program can send `?_token=` in each request. The server in the sandbox does not get the `_token` parameter or the cookie.
* A request without a correct token answers `401`.

The server in the sandbox gets the host name of the URL in `Host` and in `X-Forwarded-Host`. If it accepts only some host names, add `.vmsdev.run`. For example, set `server.allowedHosts` to `[".vmsdev.run"]` in the Vite config.

| Problem | Answer |
| - | - |
| No URL has this host name | `404` |
| The sandbox is not running | `409` with `sandbox_not_running`, `sandbox_starting`, or `sandbox_stopping` |
| Nothing listens on the port | `502` with `bad_gateway` |

## Use WebSockets

WebSocket connections work through the URL, with the same token rules. A dev server with live reload works without a change. A program that opens a WebSocket can add `?_token=` to the WebSocket URL.

## Make a URL public

Send `PATCH /v1/sandboxes/{id}/urls/{urlId}` with `public: true`. Then the URL works without the token. Send `public: false` to add the token gate again. The token does not change.

```typescript TypeScript theme={null}
await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/urls/${urlId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.VMS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ public: true }),
  },
);
```

```bash cURL theme={null}
curl -X PATCH "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/urls/url_06d8k3m7q2v9x4b1n5c0e8f2jb" \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public": true}'
```

To create a public URL at once, send `{"port": 3000, "public": true}` in the create request.

## Rename the sandbox

The URL has the name of the sandbox. When you [rename the sandbox](https://vms.dev/docs/sandboxes/list-and-label.md#change-the-name-or-the-labels), its URLs move to the new name at once, and the old URLs answer `404`. A browser needs the token one time more on the new URL.

## List and delete URLs

* `GET /v1/sandboxes/{id}/urls` lists the URLs of the sandbox, by port.
* `GET /v1/sandboxes/{id}/urls/{urlId}` gets one URL.
* `DELETE /v1/sandboxes/{id}/urls/{urlId}` deletes a URL. The server in the sandbox does not change.

```typescript TypeScript theme={null}
await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/urls/${urlId}`,
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${process.env.VMS_API_KEY}` },
  },
);
```

```bash cURL theme={null}
curl -X DELETE "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/urls/url_06d8k3m7q2v9x4b1n5c0e8f2jb" \
  -H "Authorization: Bearer $VMS_API_KEY"
```

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.