Skip to main content
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.

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.
  • 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.
The answer is 201 with the URL:
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:
  • 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.

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.
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, 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.