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

# Changelog

> New features and changes that you can see.

**November 16, 2026**

## Fewer slow starts after many starts

* After many creates, forks, or template starts of one size in a short time, more ready machines of that size wait for the next starts for one hour. Starts that come one after another wait less often for a new machine. See [When no host has room](https://vms.dev/docs/sandboxes/create-and-delete.md#when-no-host-has-room).
* A sandbox that waits for a new machine starts on the first machine of its size that is ready.

## Wide sheets for sandboxes and templates

* The sheet of a sandbox and the sheet of a template are wide. The top shows the name, the ID, and the actions. A column at the right shows the facts, such as the state, the base image, and the latest snapshot. On a small screen, the facts are below the tabs. See [See the details of a sandbox](https://vms.dev/docs/sandboxes/in-the-app.md#see-the-details-of-a-sandbox) and [See the details of a template](https://vms.dev/docs/sandboxes/templates-in-the-app.md#see-the-details-of-a-template).
* The saved files of a sandbox are in the **Snapshots** tab of its sheet. The separate snapshot page is gone, and an old link to it opens the tab. See [Browse the files of a snapshot](https://vms.dev/docs/sandboxes/in-the-app.md#browse-the-files-of-a-snapshot).
* The share codes of a template are in its **Share codes** tab. The menu of a code says **Revoke**. A new code that shows one time goes away when you revoke it. See [Share a template with another workspace](https://vms.dev/docs/sandboxes/templates-in-the-app.md#share-a-template-with-another-workspace).
* The URL holds the open sheet and its tab, so a reload keeps them.

## Tables update by themselves

* The **Sandboxes** and **Templates** tables, the sandbox and template sheets, the share codes, and the snapshot menu show each change at once, with no page reload. This includes changes from the API, the CLI, the SDK, and agents. See [Find a sandbox](https://vms.dev/docs/sandboxes/in-the-app.md#find-a-sandbox) and [Find a template](https://vms.dev/docs/sandboxes/templates-in-the-app.md#find-a-template).
* The sheet of a sandbox or a template that is deleted shows that it was deleted.
* **Payment methods**, **Invoices**, and **Charges** on the **Billing** page read Stripe again when you come back to the tab. See [What the Billing page shows](https://vms.dev/docs/workspace/billing.md#what-the-billing-page-shows).

## SSH on IPv4 networks

* `ssh.vms.dev` now works on networks with IPv4 only, as well as on IPv6. See [Connect with SSH](https://vms.dev/docs/sandboxes/ssh.md#before-you-start).
* `vms ssh` and `ssh()` of the SDK say `Could not connect to ssh.vms.dev. Check your network.` when your computer cannot find or reach `ssh.vms.dev`. See [ssh](https://vms.dev/docs/reference/cli.md#ssh).

## A CLI tutorial

* A new tutorial creates a sandbox, runs a command, copies a file, and connects with SSH from your terminal. See [Use a sandbox from your terminal](https://vms.dev/docs/cli-quickstart.md).

## Starts when no machine is ready

* A create, a fork with `count`, and a start from a template no longer answer `503 no_capacity` when a host has room but no ready machine is free. They answer `202`, and the sandbox is `running` a few seconds later. See [When no host has room](https://vms.dev/docs/sandboxes/create-and-delete.md#when-no-host-has-room).

## Hydration failures and pinned recoveries

* A download of saved files that stops for good now shows `hydration.phase: failed` with `hydration.errorCode: hydration_failed`, and sends `sandbox.degraded` with `data.reason: hydration_failed`. See [Hydration](https://vms.dev/docs/sandboxes/stop-and-resume.md#hydration).
* A download that starts again after a reboot or a stop of the download now works also after 1 hour.
* A recovery after a host failure keeps a pinned base image when a host with room has it. See [Keep the current base image](https://vms.dev/docs/sandboxes/stop-and-resume.md#keep-the-current-base-image).
* A sandbox in which you install or remove packages with `apt` keeps its base image: its next snapshot sets `pinImage` to `true`. See [Base image upgrades](https://vms.dev/docs/sandboxes/stop-and-resume.md#base-image-upgrades).

## Desktop keys and browser data

* A fork, a resume, and a sandbox from a template get new desktop pairing keys. The snapshots no longer save `/var/lib/vms-desktop`.
* The snapshots no longer save the cache folders of the desktop browser. The browser profile, with its cookies and sign-ins, is still saved, also in templates. See [A template is a full copy](https://vms.dev/docs/sandboxes/templates.md#a-template-is-a-full-copy).

## Desktop and template access

* A desktop link opens one time. A second open answers `401`. See [See the desktop of a sandbox](https://vms.dev/docs/sandboxes/desktop.md).
* The desktop cookie works for 1 hour, and each load of the desktop page checks your access again. If the member who made the link leaves the workspace, or you delete the API key that made it, the desktop page answers `403`.
* Saving a template now needs `snapshots:read` as well as `templates:write`, because a template copies the files of the sandbox. See [API key scopes](https://vms.dev/docs/reference/workspace-access.md#api-key-scopes).
* A template of a stopped sandbox with no saved files fails with `no_snapshot`. See [Templates](https://vms.dev/docs/sandboxes/templates.md).
* A deleted template keeps its files until each sandbox from it has a full snapshot of its own, so a sandbox that still downloads its files keeps working.
* Snapshot reads answer `429 rate_limited` with `retryAfterSeconds` when too many reads are open. See [Read the files of a snapshot](https://vms.dev/docs/sandboxes/snapshot-files.md).

## Base image upgrades

* A sandbox shows the version of its base image in `imageVersion`. The sandbox sheet in the app shows it as **Base image**. See [Base image upgrades](https://vms.dev/docs/sandboxes/stop-and-resume.md#base-image-upgrades).
* A resume after the hold starts the sandbox on the latest base image, with your saved files and your changes to the system folders. If the new image also changed a file that you changed, the sandbox keeps your version and logs the path.
* Send `"pinImage": true` in `PATCH /v1/sandboxes/{id}` to keep the current base image at each resume. See [Keep the current base image](https://vms.dev/docs/sandboxes/stop-and-resume.md#keep-the-current-base-image).

## Top up with your saved card, and change the plan from Overview

* **Top up** charges your default card at once, after a confirmation that names the card. Stripe Checkout opens only when the workspace has no saved card. If your bank asks you to confirm the payment, its page opens and sends you back. See [Top up the balance](https://vms.dev/docs/workspace/usage-and-balance.md#top-up-the-balance).
* If the bank declines the card, the dialog shows the error, and the balance does not change. See [Top up the balance](https://vms.dev/docs/workspace/usage-and-balance.md#top-up-the-balance).
* **Payment methods** shows each card one time, also when you entered the same card on more than one Stripe page. See [What the Billing page shows](https://vms.dev/docs/workspace/billing.md#what-the-billing-page-shows).
* The **Plan** card is gone. **Overview** shows the plan and its main limits. **Change plan** opens the list of plans in the Stripe billing portal, and **Overview** shows the new plan when you come back. See [Change the plan](https://vms.dev/docs/workspace/billing.md#change-the-plan).
* A workspace with no plan uses **Choose a plan** in **Overview** to start the trial or choose a plan. See [Choose a plan](https://vms.dev/docs/workspace/billing.md#choose-a-plan).

## Calls just after a start

* A command or a file call that you send as soon as a sandbox is `running` no longer fails with `503`. This failure was possible after a create, a fork, a start from a template, and a resume.
* A fork or a template of a sandbox that started a moment before no longer fails.

## Docker and services after a fast resume

* After a resume or a start from a template, Docker and your enabled services come back a few seconds after the sandbox is `running`. The new `docker` phase shows this step. See [Hydration](https://vms.dev/docs/sandboxes/stop-and-resume.md#hydration).
* The extended attributes and the folder modification times are back when `hydrated` is `true`. If the sandbox reboots before then, the download continues after the boot. See [Resume from the saved files](https://vms.dev/docs/sandboxes/stop-and-resume.md#resume-from-the-saved-files).

## Fast resume

* A resume after the hold and a start from a template are `running` before each file of the home folders is local. A file downloads when a program opens it, and the other files download in the background. See [Resume from the saved files](https://vms.dev/docs/sandboxes/stop-and-resume.md#resume-from-the-saved-files).
* A sandbox shows `hydrated`, `hydratedAt`, and `hydration` with the phase and the files done. See [Hydration](https://vms.dev/docs/sandboxes/stop-and-resume.md#hydration).
* The new `sandbox.hydrated` webhook goes out when each file is local. See [Webhook events](https://vms.dev/docs/reference/webhook-events.md).
* A resume first downloads the files that programs opened first after the last start. A start from a template first downloads the files that earlier sandboxes from the template opened first. See [Resume from the saved files](https://vms.dev/docs/sandboxes/stop-and-resume.md#resume-from-the-saved-files).

## Templates, forks, desktops, and snapshots in the app

* The new **Templates** page lists the templates of the workspace. Create a sandbox from a template, share it with a code, and rename or delete one or many templates. See [Use templates in the app](https://vms.dev/docs/sandboxes/templates-in-the-app.md).
* A sandbox on the **Sandboxes** page has the new actions **Fork**, **Save as template**, **Open desktop**, and **Browse snapshots**. See [Use sandboxes in the app](https://vms.dev/docs/sandboxes/in-the-app.md).
* **Browse snapshots** shows the saved files of each snapshot of a sandbox, also when it is stopped. Download a file, a folder, or all files. See [Browse the files of a snapshot](https://vms.dev/docs/sandboxes/in-the-app.md#browse-the-files-of-a-snapshot).
* The create sheet of an API key now shows the **Snapshots** and **Templates** scopes and the desktop scope to each role that can give them. See [API keys](https://vms.dev/docs/workspace/api-keys.md).

## Forks, templates, snapshots, and the desktop in the SDK and the CLI

* The CLI has new commands: `vms fork`, `vms template save`, `vms template ls`, `vms template rm`, `vms snapshot ls`, `vms snapshot get`, and `vms desktop`. `vms new --template` starts a sandbox from a template. See [CLI reference](https://vms.dev/docs/reference/cli.md#fork).
* `vms desktop` opens the desktop of a sandbox in your default browser. `vms desktop --mode browser` shows only its Chrome window. See [CLI reference](https://vms.dev/docs/reference/cli.md#desktop).
* `vms login` now gives the key the scopes `sandboxes:desktop`, `snapshots:read`, `templates:read`, and `templates:write` too, if your role permits them. Run `vms login` again to get a key with these scopes. See [Sign in](https://vms.dev/docs/reference/cli.md#with-your-browser).
* The TypeScript SDK has new helpers: `fork()`, `saveTemplate()`, `waitUntilTemplateReady()`, `latestSnapshot()`, `readSnapshotFile()`, and `desktop()`. It also has a method for each new API route. See [TypeScript SDK reference](https://vms.dev/docs/reference/typescript-sdk.md#helpers).
* These parts are in version 0.2.0 of `@vms.dev/sdk` and of `vms`.

## Read a snapshot without a sandbox

* List a folder of a snapshot with `GET /v1/snapshots/{id}/tree`. See [List a folder](https://vms.dev/docs/sandboxes/snapshot-files.md#list-a-folder).
* Download one file, or a folder as a tar, with `GET /v1/snapshots/{id}/files`. See [Download a file or a folder](https://vms.dev/docs/sandboxes/snapshot-files.md#download-a-file-or-a-folder).
* Download the whole snapshot as a tar with `GET /v1/snapshots/{id}/download`. See [Download the whole snapshot](https://vms.dev/docs/sandboxes/snapshot-files.md#download-the-whole-snapshot).
* These routes work for a stopped or deleted sandbox until its saved files are deleted. `GET /v1/sandboxes/{id}/snapshots` now also lists the snapshots of a deleted sandbox until then.
* New scope: `snapshots:read`. See [API key scopes](https://vms.dev/docs/reference/workspace-access.md#api-key-scopes).
* A file of an older snapshot can answer `409 snapshot_old_format`. Resume the sandbox to read it. See [Errors](https://vms.dev/docs/sandboxes/snapshot-files.md#errors).

## Desktop

* Each sandbox has a desktop. Send `POST /v1/sandboxes/{id}/desktop-sessions` to get a link that shows it in a browser tab, at 1080p and 60 frames each second. See [See the desktop of a sandbox](https://vms.dev/docs/sandboxes/desktop.md).
* A desktop link stops working 10 minutes after the create if nobody opens it.
* A new scope, `sandboxes:desktop`, opens the desktop. See [API key scopes](https://vms.dev/docs/reference/workspace-access.md#api-key-scopes).
* The desktop works behind a strict NAT or a company firewall through a relay on the host of the sandbox.
* Port 7912 of a sandbox cannot have a URL. See [Open a port of a sandbox on a public URL](https://vms.dev/docs/sandboxes/urls.md#create-a-url).
* Send `"mode": "browser"` to see only the Chrome window of the sandbox. An agent in the sandbox can control the same Chrome on `127.0.0.1:9222`. See [Show only Chrome](https://vms.dev/docs/sandboxes/desktop.md#show-only-chrome).
* The desktop stream carries the sound of the sandbox. See [Sound](https://vms.dev/docs/sandboxes/desktop.md#sound).

## Template share codes

* Share a template with another workspace: make a share code with `POST /v1/templates/{id}/share-codes`. The other workspace sends the code as `template` in `POST /v1/sandboxes`. It cannot see or download the template or its files. See [Share a template with another workspace](https://vms.dev/docs/sandboxes/templates.md#share-a-template-with-another-workspace).
* Revoke a code with `DELETE /v1/templates/{id}/share-codes/{codeId}`. Sandboxes that were created with the code continue to run. See [Revoke a share code](https://vms.dev/docs/sandboxes/templates.md#revoke-a-share-code).

## Templates

* Save a running or stopped sandbox as a template with `POST /v1/templates`. A save of a running sandbox takes a new snapshot first. See [Save a sandbox as a template](https://vms.dev/docs/sandboxes/templates.md).
* Create a sandbox from a template: send `template`, with the name or the ID, in `POST /v1/sandboxes`. See [Create a sandbox from a template](https://vms.dev/docs/sandboxes/templates.md#create-a-sandbox-from-a-template).
* A template is a full copy with no expiry date. It stays when its sandbox changes or is deleted.
* New scopes: `templates:read` and `templates:write`. See [API key scopes](https://vms.dev/docs/reference/workspace-access.md#api-key-scopes).
* Each plan includes as many templates as saved snapshots. Each extra template costs \$0.04 each day. `GET /v1/limits` shows `templates`. See [Plans](https://vms.dev/docs/reference/plans.md#plans).

## Fork a sandbox

* Send `fromSandbox` in `POST /v1/sandboxes` to fork a running or stopped sandbox. The fork gets the files and the environment variables of the source. See [Fork a sandbox](https://vms.dev/docs/sandboxes/fork.md).
* A fork of a running sandbox takes a new snapshot first. Send `"freshSnapshot": false` to start from the last snapshot. See [Fork a running sandbox](https://vms.dev/docs/sandboxes/fork.md#fork-a-running-sandbox).
* Send `count` to make up to 100 forks in one request. See [Make many forks](https://vms.dev/docs/sandboxes/fork.md#make-many-forks).
* Each sandbox has `forkedFrom`, the ID of the sandbox that it is a fork of.

## Templates for eve agents

* `eve build` saves the setup of an eve agent as a template, and each new session starts from it. A session does not run `prepare` again. See [Run setup commands](https://vms.dev/docs/sandboxes/eve.md#run-setup-commands).
* A build with no change uses the same template.
* The API key of the eve provider now needs `templates:read` and `templates:write`. Without them, `eve build` fails with `403`. See [Before you start](https://vms.dev/docs/sandboxes/eve.md#before-you-start).

## API keys, URLs, and SSH

* Each API key can send 1,200 requests in one minute, up from 120. The command and file routes count the requests too. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* A revoked key stops on the command and file routes within 10 seconds. See [Revoke an API key](https://vms.dev/docs/workspace/api-keys.md#revoke-an-api-key).
* `waitUntilRunning` of the SDK reads the sandbox one time each second, and waits longer after a `429`. See [waitUntilRunning](https://vms.dev/docs/reference/typescript-sdk.md#waituntilrunning).
* An API key without `sandboxes:write` gets `null` in the `token` of a sandbox URL. See [Open a port of a sandbox on a public URL](https://vms.dev/docs/sandboxes/urls.md).
* Each sandbox has `sshUser`, such as `agent-42-k3m7q2v9`. Use it as the user name for `ssh.vms.dev`, so that a sandbox with the same name in another workspace cannot block your login. See [Open a shell](https://vms.dev/docs/sandboxes/ssh.md#open-a-shell).
* The sandboxes of an API key count against the member caps of the person who created the key.

## Files, the eve provider, and the billing page

* A file that you write or upload to `/home/user`, with `writeFiles`, `PUT /v1/sandboxes/{id}/files`, a tar, or `vms cp`, belongs to `user`. See [Write a file](https://vms.dev/docs/sandboxes/files.md#write-a-file).
* The eve provider waits longer each time that a create or a resume gets `no_capacity` or `429`. See [eve provider reference](https://vms.dev/docs/reference/eve-provider.md).
* The tables of the billing page are shorter when they are empty.

## API changes

* A new scope, `webhooks:read`, lists and gets webhook endpoints. Before, these needed `webhooks:write`. See [API key scopes](https://vms.dev/docs/reference/workspace-access.md#api-key-scopes).
* Webhook endpoints, SSH keys, and sandbox URLs have bulk routes: `create-many`, `update-many`, and `delete-many` where they apply. See [Change or delete an endpoint](https://vms.dev/docs/sandboxes/webhooks.md#change-or-delete-an-endpoint).
* `GET /v1/sandboxes` takes `search` and `sort`. The sandboxes page searches and sorts each sandbox, not only the loaded rows. See [List sandboxes](https://vms.dev/docs/sandboxes/list-and-label.md#list-sandboxes).

## Environment and files at create

* Send `env` and `files` in `POST /v1/sandboxes`. The sandbox has them when it is `running`. See [Give environment variables and files](https://vms.dev/docs/sandboxes/create-and-delete.md#give-environment-variables-and-files).

## Billing rules

* The spending limit is hard: at 100%, the running sandboxes stop with their data kept. See [Set a spending limit](https://vms.dev/docs/workspace/usage-and-balance.md#set-a-spending-limit).
* **Member caps** on the billing page caps the sandboxes and the unit-hours of each member. See [Cap the use of each member](https://vms.dev/docs/workspace/usage-and-balance.md#cap-the-use-of-each-member).
* A sandbox with `health: degraded` is billed, because a program in the sandbox can block the guest agent. The new `health: unreachable` is for a problem on our side, and is not billed. See [Health and recovery](https://vms.dev/docs/reference/health-and-recovery.md#health).
* A stop that cannot reach the guest agent stays billed, and gives up after 1 hour, not 3 days. See [When the last snapshot fails](https://vms.dev/docs/sandboxes/stop-and-resume.md#when-the-last-snapshot-fails).
* Each stopped sandbox above the saved snapshots of the plan costs \$0.04 each day. See [Plans reference](https://vms.dev/docs/reference/plans.md).
* `GET /v1/usage` takes `label` filters and `groupByLabel`, to get the cost of each value of a label. See [Read the usage with the API](https://vms.dev/docs/workspace/usage-and-balance.md#read-the-usage-with-the-api).

## The vms CLI

* Use sandboxes from your terminal with `vms new`, `ls`, `ssh`, `exec`, `cp`, `stop`, `resume`, `rm`, and `url`. See [CLI reference](https://vms.dev/docs/reference/cli.md).
* Install the CLI with `brew install vms-dev-org/tap/vms`, or download it from [GitHub releases](https://github.com/vms-dev-org/cli/releases/latest). See [Install](https://vms.dev/docs/reference/cli.md#install).
* Sign in with `vms login` in your browser. The CLI saves an API key for one workspace, not your password. You can also use an API key in `VMS_API_KEY`. See [Sign in](https://vms.dev/docs/reference/cli.md#sign-in).
* `vms ssh` adds the host key of `ssh.vms.dev` to `~/.ssh/known_hosts`, so that `ssh` does not ask you to trust the host. See [ssh](https://vms.dev/docs/reference/cli.md#ssh).

## SDK and eve provider on npm

* Install the TypeScript SDK with `npm install @vms.dev/sdk` or `bun add @vms.dev/sdk`. It runs on Node.js 22 or later and on Bun. See [Install](https://vms.dev/docs/reference/typescript-sdk.md#install).
* Install the eve provider with `npm install @vms.dev/eve`. See [Give the agent a sandbox](https://vms.dev/docs/sandboxes/eve.md#give-the-agent-a-sandbox).

## eve sandbox provider

* `@vms.dev/eve` gives each session of an eve 1.0 agent its own sandbox. The `bash` and file tools of the agent run in it. See [Run eve agents in sandboxes](https://vms.dev/docs/sandboxes/eve.md).
* When the session waits for a message, the sandbox stops after 60 seconds. The next message starts the same sandbox with the same files. The end of the session deletes the sandbox. See [What happens in a session](https://vms.dev/docs/sandboxes/eve.md#what-happens-in-a-session).
* The files and commands of `prepare` run again in each new sandbox. See [Run setup commands](https://vms.dev/docs/sandboxes/eve.md#run-setup-commands) and the [eve provider reference](https://vms.dev/docs/reference/eve-provider.md).

## Host failures, crashes, and health

* When a host stops reporting for 30 seconds, its running sandboxes move to `error` with `errorReason` set to `host_lost`, and billing stops. See [When the host stops](https://vms.dev/docs/reference/health-and-recovery.md#when-the-host-stops).
* A sandbox whose latest snapshot is less than 2 minutes old starts again on another host with its saved files, with a `recover` operation. See [Automatic recovery](https://vms.dev/docs/reference/health-and-recovery.md#automatic-recovery).
* A kernel crash starts the sandbox again with its local disk within 15 seconds. `lastReboot.reason` is `crash`. See [When the kernel crashes](https://vms.dev/docs/reference/health-and-recovery.md#when-the-kernel-crashes).
* A sandbox whose guest agent does not answer for 60 seconds shows `health: degraded`, keeps running, and is not billed. You get the `sandbox.degraded` and `sandbox.recovered` events. See [Health](https://vms.dev/docs/reference/health-and-recovery.md#health).

## Resume from the saved files

* A resume more than 10 minutes after the stop now works. The sandbox starts on any host with room and gets back its saved files before it is `running`. Before, the API answered `409`. See [Resume from the saved files](https://vms.dev/docs/sandboxes/stop-and-resume.md#resume-from-the-saved-files).
* Send `size` with `"state": "running"` to resume a stopped sandbox with a different size. See [Change the size at resume](https://vms.dev/docs/sandboxes/stop-and-resume.md#change-the-size-at-resume).
* If the files do not come back, the sandbox is `error` with `errorReason` set to `restore_failed`, and its saved files do not change. You can resume a sandbox in the `error` state again.
* A resume when no host has room answers `503 no_capacity`, and the sandbox stays `stopped`.

## Saved files for 30 days

* A stopped sandbox keeps its saved files for 30 days. `GET /v1/sandboxes/{id}` shows the date in `dataExpiresAt`. After that date, a resume answers `409 snapshot_expired`. See [How long a stopped sandbox keeps its files](https://vms.dev/docs/sandboxes/stop-and-resume.md#how-long-a-stopped-sandbox-keeps-its-files).
* The saved files of a deleted sandbox are deleted within 24 hours. See [Delete a sandbox](https://vms.dev/docs/sandboxes/create-and-delete.md#delete-a-sandbox).
* After 50 snapshots, the next snapshot holds each saved file again, and the older snapshots are deleted within 24 hours. See [When saved files are deleted](https://vms.dev/docs/reference/saved-files.md#when-saved-files-are-deleted).

## Usage, balance, and top-ups

* Usage costs \$0.017 for each capacity-unit hour, by the second, only while a sandbox is `running` and not degraded. It takes the plan credit first, then the balance. See [Credit and balance](https://vms.dev/docs/reference/plans.md#credit-and-balance).
* Top up the balance from $5 to $100,000 in **Billing**. From \$100, a top-up gets a bonus of up to 27%. Top-ups also work during the trial. See [Top up the balance](https://vms.dev/docs/workspace/usage-and-balance.md#top-up-the-balance).
* Turn on automatic top-up from \$5, also in the trial. See [Turn on automatic top-up](https://vms.dev/docs/workspace/usage-and-balance.md#turn-on-automatic-top-up).
* Set a monthly spending limit, with emails at 50%, 80%, and 100%. See [Set a spending limit](https://vms.dev/docs/workspace/usage-and-balance.md#set-a-spending-limit).
* When the credit and the balance are empty, a paid plan keeps running for 48 hours, with a debt allowance. Then the sandboxes stop with their data kept. See [Grace and debt](https://vms.dev/docs/reference/plans.md#grace-and-debt).
* The trial stops new sandboxes after its 60 unit-hours. A top-up gives more time.
* See the cost of each sandbox and each label this month in **Billing**, and export the usage as a CSV file. See [See the cost of each sandbox](https://vms.dev/docs/workspace/usage-and-balance.md#see-the-cost-of-each-sandbox).
* Read the usage of each minute, the credit, and the balance with `GET /v1/usage` and the `billing:read` scope. Read the cost of one sandbox with `GET /v1/sandboxes/{id}/usage`, and the cost of each sandbox with `include=cost` on `GET /v1/sandboxes`. See [Read the usage with the API](https://vms.dev/docs/workspace/usage-and-balance.md#read-the-usage-with-the-api).

## TypeScript SDK

* `@vms.dev/sdk` has one typed method for each API route, also the command and file routes, with one base URL. See [Use a sandbox from TypeScript](https://vms.dev/docs/sdk-quickstart.md).
* Helpers wait until a sandbox runs, stream a command, write many files in one tar upload, and open SSH with your key. See [Helpers](https://vms.dev/docs/reference/typescript-sdk.md#helpers).
* An API error is a `VmsError` with its `status` and `code`. `readWebhook()` checks the signature of a webhook. See [Errors](https://vms.dev/docs/reference/typescript-sdk.md#errors).

## Auto-stop

* Each new sandbox stops on its own 1 hour after its start. `GET /v1/sandboxes/{id}` shows the time in `stopAt` and the run time in `stopAfterSeconds`. See [Stop a sandbox on its own](https://vms.dev/docs/sandboxes/auto-stop.md).
* Send `stopAfterSeconds` or `stopAt` at create, or change them with `PATCH /v1/sandboxes/{id}`. Send `null` to turn off the auto-stop. See [Extend the auto-stop](https://vms.dev/docs/sandboxes/auto-stop.md#extend-the-auto-stop).
* At `stopAt`, the sandbox stops with a normal stop operation. Each resume sets a new `stopAt`.
* In the trial, the default is also 1 hour. You can extend it up to 4 hours after the start. See [Limits of the trial](https://vms.dev/docs/sandboxes/auto-stop.md#limits-of-the-trial).

## Stop and resume

* Stop a sandbox with `PATCH /v1/sandboxes/{id}` and `"state": "stopped"`. The API answers `202` with the stop operation. The sandbox runs `~/.vms/pre-stop`, takes a last snapshot, and is then `stopped` and not billed. See [Stop and resume a sandbox](https://vms.dev/docs/sandboxes/stop-and-resume.md).
* Resume it within 10 minutes with `"state": "running"`. The sandbox runs again in less than 0.5 seconds, with each process. See [Resume a sandbox](https://vms.dev/docs/sandboxes/stop-and-resume.md#resume-a-sandbox).
* If the last snapshot fails 3 times, the stop is `failing`, the sandbox runs again without billing, and the stop tries again. See [When the last snapshot fails](https://vms.dev/docs/sandboxes/stop-and-resume.md#when-the-last-snapshot-fails).
* Stop or resume up to 500 sandboxes in one request with `POST /v1/sandboxes/update-many`. See [Stop or resume many sandboxes](https://vms.dev/docs/sandboxes/stop-and-resume.md#stop-or-resume-many-sandboxes).

## SSH

* Add your public SSH key to a sandbox with `POST /v1/sandboxes/{id}/ssh-keys`, then connect with `ssh <name>@ssh.vms.dev`. List and delete keys with the same resource. The endpoints need the `sandboxes:ssh` scope. See [Connect with SSH](https://vms.dev/docs/sandboxes/ssh.md).
* `scp`, `sftp`, port forwarding, and `ssh -J` work through `ssh.vms.dev`. See [Open a shell](https://vms.dev/docs/sandboxes/ssh.md#open-a-shell).
* `GET /v1/sandboxes/{id}` shows the SSH host key of the sandbox in `sshHostKey`. See [Check the host keys](https://vms.dev/docs/sandboxes/ssh.md#check-the-host-keys).

## Public URLs

* Give a port of a sandbox an HTTPS URL with `POST /v1/sandboxes/{id}/urls`, such as `https://web-app-3000-k3m7q2v9.vmsdev.run`. See [Open a port of a sandbox on a public URL](https://vms.dev/docs/sandboxes/urls.md).
* A URL needs its token: open it one time with `?_token=`, and the browser keeps a cookie. Send `public: true` to open the URL to everyone. See [Open the URL](https://vms.dev/docs/sandboxes/urls.md#open-the-url).
* WebSockets work through the URL, so dev servers with live reload work. See [Use WebSockets](https://vms.dev/docs/sandboxes/urls.md#use-websockets).
* When you rename a sandbox, its URLs move to the new name. `GET /v1/sandboxes/{id}` shows the URLs in `urls`.

## Billing page

* **Billing** shows one card for each part: **Overview**, **Plan**, **Billing info**, **Payment methods**, **Invoices**, and **Charges**. See [What the Billing page shows](https://vms.dev/docs/workspace/billing.md#what-the-billing-page-shows).
* **Plan** shows the four plans with their price, usage credit, and limits, and marks your plan. Choose a plan, start the trial, or change the plan from the card. See [Change the plan](https://vms.dev/docs/workspace/billing.md#change-the-plan).
* See the name, the email, the phone, and the address on your invoices, and the cards that you saved. Choose **Edit** to change them in the Stripe billing portal.
* Search, sort, and download your invoices as PDF files. See [Download an invoice](https://vms.dev/docs/workspace/billing.md#download-an-invoice).
* See each payment attempt, also the failed ones, and open its receipt. See [See the payments](https://vms.dev/docs/workspace/billing.md#see-the-payments).

## Sandbox network

* Each sandbox has its own public IPv6 address. `GET /v1/sandboxes/{id}` shows it in `ipv6` when the sandbox starts. See [Sandbox network](https://vms.dev/docs/reference/sandbox-network.md#addresses).
* A sandbox reaches IPv4 sites through the IPv4 address of its host.
* From the internet, port 22 and port 7911 of a sandbox are open. Each other port is closed. See [Traffic to the sandbox](https://vms.dev/docs/reference/sandbox-network.md#traffic-to-the-sandbox).
* Connections to port 25 and port 465, to other sandboxes, to the host, and to the provider metadata addresses fail. See [Traffic from the sandbox](https://vms.dev/docs/reference/sandbox-network.md#traffic-from-the-sandbox).
* Each sandbox has a limit of 100 new connections each second and 500 Mbit/s in each direction. See [Rate limits](https://vms.dev/docs/reference/sandbox-network.md#rate-limits).

## Checkout details

* Stripe Checkout shows the email of the person who starts it. Stripe saves the name and the address that you enter for your invoices.
* Checkout asks for an optional tax ID, such as a VAT number, for your invoices.

## Snapshots each minute

* A running sandbox saves its changed files each minute. A minute with no change uploads nothing and updates only `snapshotVerifiedAt` and `lastSnapshotLagSeconds`. See [Saved files](https://vms.dev/docs/reference/saved-files.md).
* List the snapshots of a sandbox with `GET /v1/sandboxes/{id}/snapshots`, and read one with `GET /v1/sandboxes/{id}/snapshots/{snapshotId}`. Both need the `sandboxes:read` scope. See [List the snapshots](https://vms.dev/docs/reference/saved-files.md#list-the-snapshots).
* Put a `.vmsignore` file in a folder to keep paths out of the snapshots. See [.vmsignore](https://vms.dev/docs/reference/saved-files.md#vmsignore).

## Webhooks

* Add up to 10 webhook endpoints with `/v1/webhooks`. Each endpoint gets a signed `POST` request when a sandbox is running, stopped, in error, deleted, or failed. See [Get webhooks when a sandbox changes state](https://vms.dev/docs/sandboxes/webhooks.md).
* Check each request with its HMAC-SHA256 signature in the `vms-signature` header.
* A failed request comes again, up to 8 attempts in about 11 hours. See [Webhook events](https://vms.dev/docs/reference/webhook-events.md).

## Sandbox lists, names, and labels

* List the sandboxes of the workspace with `GET /v1/sandboxes`. Filter by state, name, start of the name, and label, and read each page with a cursor. See [List, find, and label sandboxes](https://vms.dev/docs/sandboxes/list-and-label.md).
* Give a sandbox a `name` and `labels` at create, and change them with `PATCH /v1/sandboxes/{id}`. A name is unique in the workspace. A second sandbox with the name gets `409 sandbox_name_taken`. See [Give a sandbox a name and labels](https://vms.dev/docs/sandboxes/list-and-label.md#give-a-sandbox-a-name-and-labels).
* Find a sandbox by its name with `GET /v1/sandboxes?name=agent-42`. See [Find a sandbox by its name](https://vms.dev/docs/sandboxes/list-and-label.md#find-a-sandbox-by-its-name).
* Create or delete up to 500 sandboxes in one request with `POST /v1/sandboxes/create-many` and `POST /v1/sandboxes/delete-many`. See [Create or delete many sandboxes](https://vms.dev/docs/sandboxes/list-and-label.md#create-or-delete-many-sandboxes).

## Sandboxes

* Create a sandbox with `POST /v1/sandboxes`, read it with `GET /v1/sandboxes/{id}`, and delete it with `DELETE /v1/sandboxes/{id}`. See [Create, get, and delete a sandbox](https://vms.dev/docs/sandboxes/create-and-delete.md).
* Read the status of a create or a delete with `GET /v1/operations/{id}`.
* If no host has room, the create answers `503 no_capacity` at once, with `retryAfterSeconds`. Send `"failFast": true` to get an answer within 1.5 seconds.
* Send an `Idempotency-Key` header, so that a retry does not create a second sandbox.

## Plan limits

* A create checks the limits of the plan. With no plan and no trial, it answers `402 billing_required`. See [the limits of each plan](https://vms.dev/docs/reference/plans.md#limits).
* A size that the trial does not include answers `403 size_not_allowed`. Each paid plan includes each size, `xlarge` too.
* Too many sandboxes at a time or too many starts answer `429 start_limit`. For too many starts, the error has `retryAfterSeconds`. A start costs nothing.
* Read the limits and their use with `GET /v1/limits`.
* In the trial, each new sandbox gets a `stopAt` 4 hours after the create.

## Commands

* Run a command in a sandbox with `POST /v1/sandboxes/{id}/commands`, and read its output as a stream. A command has no time limit unless you send `timeoutSeconds`. See [Run commands in a sandbox](https://vms.dev/docs/sandboxes/run-commands.md).
* Send stdin, list commands, get a command, and kill a command with its signal. An out-of-memory kill shows `oomKilled: true`.
* Send `"detached": true` to keep a command running after you disconnect, and read its output again from a `seq`.
* A call to a sandbox that is not running answers `409 sandbox_not_running`, and a call during a stop answers `409 sandbox_stopping`.

## Files

* Read, write, and delete files and folders in a sandbox with `GET`, `PUT`, and `DELETE /v1/sandboxes/{id}/files?path=`. A write creates the missing folders. See [Read and write files in a sandbox](https://vms.dev/docs/sandboxes/files.md).
* Upload a tar or a gzip tar into a folder with `POST /v1/sandboxes/{id}/files/tar?path=`. See [Upload a tar](https://vms.dev/docs/sandboxes/files.md#upload-a-tar).
* These endpoints need the `sandboxes:files` scope.

## API key scopes

* New scopes: `sandboxes:read`, `sandboxes:write`, `sandboxes:exec`, `sandboxes:files`, `sandboxes:ssh`, `webhooks:write`, and `billing:read`. See [API key scopes](https://vms.dev/docs/reference/workspace-access.md#api-key-scopes).
* The **Create API key** sheet shows the **Sandboxes**, **Webhooks**, and **Billing** areas.

## Sandboxes page

* In the sidebar, choose **Sandboxes** to see the sandboxes of your workspace with their name, state, size, and last change. Search, filter by state, and sort the table. See [Find a sandbox](https://vms.dev/docs/sandboxes/in-the-app.md#find-a-sandbox).
* Choose a sandbox to see its state, size, IPv6 address, latest snapshot, SSH command, and URLs. See [See the details of a sandbox](https://vms.dev/docs/sandboxes/in-the-app.md#see-the-details-of-a-sandbox).
* Stop, resume, or delete one sandbox from its menu, or many sandboxes from **Actions**. See [Stop, resume, or delete many sandboxes](https://vms.dev/docs/sandboxes/in-the-app.md#stop-resume-or-delete-many-sandboxes).

**November 15, 2026**

## Plans and billing

* Choose the $20, $100, $500, or $2,000 plan, or start the 14-day trial, on the new **Billing** settings page. See [Choose a plan or start a trial](https://vms.dev/docs/workspace/billing.md).
* Change the plan, the card, or the billing email in the Stripe billing portal. See [Change the plan, the card, or the billing email](https://vms.dev/docs/workspace/billing.md#change-the-plan-the-card-or-the-billing-email).
* Members are free. Each member can see the plan. Only owners and admins can change it. See [workspace access](https://vms.dev/docs/reference/workspace-access.md#roles).
* See the limits of each plan and the trial in the [plans reference](https://vms.dev/docs/reference/plans.md), and the comparison with boat.dev in [How billing works](https://vms.dev/docs/explanation/billing.md).

## Website

* `https://vms.dev` shows a page about sandboxes when you are signed out. Choose **Sign in** to open your workspace. See [Sign in](https://vms.dev/docs/account/sign-in.md).
* Pages compare sandboxes with E2B, Daytona, Modal, Vercel Sandbox, and boat at `/compare`. Pages for use cases are at `/use-cases`, and definitions are at `/definitions`.
* AI agents can read a summary at `/llms.txt`.
* The browser tab, the home screen, and the bookmarks show the V icon.
* Choose **Copy the setup prompt** on `https://vms.dev`, and paste it into your agent. The agent reads the docs and signs itself up with auth.md. See [Agent skills](https://vms.dev/docs/agent-skills).
* The sign-in page has a new layout. A new email gets an account from the same link. See [Sign in](https://vms.dev/docs/account/sign-in.md).
* Each public page has its own image for link previews.
* Each public page has one main heading. Search engines and AI agents that do not run JavaScript can read the full page.
* The public pages have a URL for each language, such as `https://vms.dev/fr`. Choose a language at the bottom of the page.
* The app uses the theme of your system until you choose one. See [Profile](https://vms.dev/docs/account/profile.md).
* The language codes are reserved workspace URLs, such as `fr` and `de`. See the [URL rules](https://vms.dev/docs/reference/workspace-settings.md#workspace-url).
* More workspace URLs are reserved, such as `compare`, `docs`, and `use-cases`. See the [URL rules](https://vms.dev/docs/reference/workspace-settings.md#workspace-url).
* `ingest` is a reserved workspace URL. See the [URL rules](https://vms.dev/docs/reference/workspace-settings.md#workspace-url).
* If a page cannot load, it shows **Could not load the page**, a reference, and **Try again**.

## Docs

* The docs sidebar links to `llms.txt` and `llms-full.txt` for AI agents. See [Agent skills](https://vms.dev/docs/agent-skills).
* To get help, choose **Email us** in the docs sidebar, or send an email to `support@vms.dev`.

## Workspaces and accounts

* Sign in with an email link. See [Sign in](https://vms.dev/docs/account/sign-in.md).
* Create a workspace with your first name, your last name, and the company website. Change its name, website, URL, and default language, or delete it. See [workspace settings](https://vms.dev/docs/workspace/settings.md).
* Invite members by name and email, and give them a role. The members table shows the name of each invited person. See [Members](https://vms.dev/docs/workspace/members.md).
* Change your name, avatar, language, time zone, and theme. See [Profile](https://vms.dev/docs/account/profile.md).

## API keys and the REST API

* Create API keys with scopes for a workspace. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* The API is at `https://vms.dev/api`, and the MCP server is at `https://vms.dev/api/mcp`. See the [API introduction](https://vms.dev/docs/api-reference/introduction.md#base-url).
* Read the workspace with `GET /v1/workspace`. See [your first API request](https://vms.dev/docs/api-reference/first-request.md).
* List the changes of the workspace with `GET /v1/workspace-changes`. See [pagination](https://vms.dev/docs/api-reference/introduction.md#pagination).
* Get the OpenAPI document at `GET /v1/openapi.json`.
* The API examples show TypeScript first, and cURL in the next tab. See [your first API request](https://vms.dev/docs/api-reference/first-request.md).

## Agent registration (auth.md)

* An AI agent can register for you, then call the MCP server with its own token. All three auth.md methods are on: an ID-JAG from a trusted provider, your email, or anonymous. See [Register an agent with auth.md](https://vms.dev/docs/api-reference/agent-registration.md).
* Enter the 6-digit code from an agent to connect it, and disconnect it on your profile. See [Connect an AI agent with a code](https://vms.dev/docs/account/connect-agent.md).
* Give your agent the agent sign-up skill at `/auth.md`. See [Agent skills](https://vms.dev/docs/agent-skills).

## MCP

* Connect Claude, Cursor, Visual Studio Code, or another MCP client with OAuth sign-in. See [Connect an MCP client](https://vms.dev/docs/install-mcp.md).
* Use the tools `list_organizations`, `get_workspace`, and `list_workspace_changes`. See the [MCP reference](https://vms.dev/docs/reference/workspace-mcp.md).


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