# Connect an AI agent with a code Source: https://vms.dev/docs/account/connect-agent Enter the 6-digit code that an AI agent gives you, so that it can act as you. See and disconnect your agents. An AI agent can register itself and then ask you to confirm. It gives you a link and a 6-digit code. When you enter the code, the agent can act as you through the [MCP server](/docs/reference/workspace-mcp). Help me connect an agent. Explain what the agent can do if I connect it. Remind me to enter the code only on the page that opens after sign-in. Tell me how to disconnect the agent later. ## Before you start * Get the link and the 6-digit code from the agent. * If the agent asked for your email, sign in with that email. Only that account can enter the code. * The code works for 10 minutes. The page accepts 5 wrong codes. ## Enter the code **1. Open the link and sign in** Open the link from the agent. If you are not signed in, sign in or create an account. **2. Check the access and enter the code** Read what the agent can do as you. Type the 6-digit code from the agent, then choose **Connect agent**. ![The page An agent asks to act as you, with the signed-in email, the list of what the agent can do, the Code from the agent field, and the Connect agent button.](https://mintcdn.com/vms-c6f4e5ac/ik-PVuE4l6A-0My2/images/account/connect-agent/00-claim-page-light.png?fit=max\&auto=format\&n=ik-PVuE4l6A-0My2\&q=85\&s=8a4f208e7d8cb7010f39f6aac1790a61) The page shows **Agent connected**. Go back to the agent. It continues without more steps. If an agent provider already knows your email, the page title names the provider, for example **agents.example.com asks to link its agent to your account**. After you connect it once, agents from that provider connect without a code. ## See and disconnect your agents **1. Open Profile** Open the user menu at the bottom left of the sidebar. Choose **Account settings**. Find the **Connected agents** card. ![The Connected agents card with one agent connected with a code, the date it connected, and the Disconnect button.](https://mintcdn.com/vms-c6f4e5ac/ik-PVuE4l6A-0My2/images/account/connect-agent/01-connected-agents-light.png?fit=max\&auto=format\&n=ik-PVuE4l6A-0My2\&q=85\&s=a64b6a74d00b34bf8ddabb425bf6b953) **2. Disconnect the agent** Choose **Disconnect** next to the agent. In **Disconnect the agent?**, choose **Disconnect**. The agent stops at once. If it came from an agent provider, the link to that provider is also removed. To connect it again, the agent must ask you for a new code. ## Troubleshooting > [accordion] The code is not correct. > > Check the code that the agent shows, and type it again. After 5 wrong codes, ask the agent for a new code. > [accordion] This code expired. > > The code works for 10 minutes. Ask the agent for a new code. The agent gets a new code for the same registration for up to 24 hours. > [accordion] Sign in with a different account > > The agent asked for a different email. Choose **Switch account**, then sign in with the email that you gave to the agent. > [accordion] This link is not valid > > The link is wrong, or the registration was disconnected. Ask the agent for a new link. Read the [changelog.](/docs/changelog) # Change your profile Source: https://vms.dev/docs/account/profile Change your name, avatar, language, time zone, and theme, and see your connected agents. Use **Profile** to change your name, avatar, language, time zone, or theme. These changes do not change the settings of other members. Get help to set up my profile. Help me set up my profile from Account settings. Explain the Name, Avatar, Language, Time zone, and Theme cards. Tell me which settings apply only to this device. ## Before you start Sign in to your account. Each role can change its own profile. ## Change your profile **1. Open Profile** Open the user menu at the bottom left of the sidebar. Choose **Account settings**. ![The Profile page with the Name, Avatar, Language, Time zone, Theme, and Connected agents cards.](https://mintcdn.com/vms-c6f4e5ac/ik-PVuE4l6A-0My2/images/account/profile/00-profile-page-light.png?fit=max\&auto=format\&n=ik-PVuE4l6A-0My2\&q=85\&s=e284836442079a1ad435919785c95425) **2. Save the new value** Change a value, then choose **Save** in that card. **Avatar** and **Theme** save when you change them. | Setting | What it does | Rules | | - | - | - | | Name | Sets the first name and the last name that your team sees. | Up to 64 characters for each name. The first name is necessary. | | Avatar | Sets the image that shows next to your name. | PNG, JPEG, or WebP. 2 MB or less. | | Language | Sets the language of the app and your emails. | Applies on all your devices. **Workspace default** uses the [default language](/docs/workspace/settings) of the workspace. | | Time zone | Sets the time zone of the dates in the app. | Applies only on this device. **Automatic** uses the time zone of the device. | | Theme | Sets the colors of the app: light, dark, or the same as your system. The default is the same as your system. | Applies only on this device. | | Connected agents | Lists the AI agents that act as you. **Disconnect** stops one. | See [Connect an AI agent with a code](/docs/account/connect-agent). | ## Troubleshooting > [accordion] Use an image of 2 MB or less. > > The image is too large. Make the image smaller, then upload it again. > [accordion] Use a PNG, JPEG, or WebP image. > > Other image types do not work. Save the image as PNG, JPEG, or WebP, then upload it again. > [accordion] The theme or the time zone is different on a different device > > The theme and the time zone apply only on the device where you set them. Set them again on each device. Read the [changelog.](/docs/changelog) # Sign in and sign out Source: https://vms.dev/docs/account/sign-in Sign in with a link that you get by email, and sign out from the user menu. You sign in with a link that you get by email. You do not need a password. If your email has no account, the link makes one. Help me sign in. Explain how to sign in with an email link. Tell me what to do if the link does not work. Do not ask me to share the link. ## Sign in Go to `https://vms.dev` and choose **Sign in**, or go to `https://vms.dev/sign-in`. If you are signed in, `https://vms.dev` opens your workspace. **1. Ask for a sign-in link** Type your **Work email**, then choose **Email me a sign-in link**. ![The Sign in to VMS form with the Work email field and the Email me a sign-in link button.](https://mintcdn.com/vms-c6f4e5ac/jQnI_Fj6Glye5aBP/images/account/sign-in/00-sign-in-light.png?fit=max\&auto=format\&n=jQnI_Fj6Glye5aBP\&q=85\&s=3427715fa2cad66090aea44fb504a323) **2. Open the link** Open the email and choose the link. The link works for 15 minutes and one time only. If you have a workspace, it opens. If you have no workspace, **Create a workspace** opens. If you came from an invitation, the invitation opens. ## Sign out Open the user menu at the bottom left of the sidebar, then choose **Sign out**. ## Troubleshooting > [accordion] This sign-in link expired. Send a new one. > > The link works for 15 minutes. Ask for a new link. > [accordion] This sign-in link is not valid. Send a new one. > > Each link works one time. Ask for a new link, and use the newest email. Read the [changelog.](/docs/changelog) # Agent skills Source: https://vms.dev/docs/agent-skills Instructions that an AI agent reads to sign up and use your workspaces. An agent skill is a Markdown file with steps for an AI agent. Give the URL of a skill to your agent. The agent reads the file and does the steps. Find the right skill for my agent. Ask what I want my agent to do. Give me the URL of the skill that does it. Tell me what I must do while the agent works. ## Available skills | Skill | URL | What the agent does | | - | - | - | | [Agent sign-up](/docs/api-reference/agent-registration) | `https://vms.dev/auth.md` | Registers for you, gets a token, and calls the [MCP server](/docs/reference/workspace-mcp). | ## Give a skill to your agent Paste the URL of the skill into the chat with your agent, and ask the agent to follow it. For agent sign-up, the agent shows you a link and a 6-digit code. Open the link, sign in, and enter the code. See [Connect an AI agent with a code](/docs/account/connect-agent). ## Related pages * [Connect an MCP client](/docs/install-mcp) for a client that can open sign-in in your browser. * [How programs and agents get access](/docs/explanation/agent-access) for the differences between API keys, MCP sign-in, and agent sign-up. Read the [changelog.](/docs/changelog) # Register an agent with auth.md Source: https://vms.dev/docs/api-reference/agent-registration Let an AI agent register for a user, get a token, and call the MCP server, with no copied API key. An agent can register for a user with the [auth.md protocol](https://github.com/workos/auth.md). Then it gets OAuth tokens for the MCP server. Most agents read the instructions at `https://vms.dev/auth.md` and do these steps without help. Register this agent with VMS. Read `https://vms.dev/auth.md` and follow it. Use service_auth with my email if you cannot mint an ID-JAG. Show me the link and the code, and wait until I confirm. Then call list_organizations. ## Before you start * For the `identity_assertion` method, the issuer of your agent provider must be on the trust list. See `agent_auth.identity_assertion.trusted_issuers` in the Authorization Server metadata. If your provider is not on it, use `service_auth` or `anonymous`. ## Register and get a token **1. Discover the endpoints** Get `https://vms.dev/api/auth/.well-known/oauth-authorization-server`. Read the `token_endpoint` and the `agent_auth` block. **2. Register** Send one of the three bodies to `/api/auth/agent/identity`: ```typescript TypeScript theme={null} const response = await fetch("https://vms.dev/api/auth/agent/identity", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "service_auth", login_hint: "ada@example.com" }), }); ``` ```bash cURL theme={null} curl -X POST https://vms.dev/api/auth/agent/identity \ -H "Content-Type: application/json" \ -d '{ "type": "service_auth", "login_hint": "ada@example.com" }' ``` Use `identity_assertion` with an ID-JAG from a trusted provider, or `anonymous` if you know nothing about the user. See [Registration methods](/docs/reference/agent-registration#registration-methods). **3. Let the user confirm** If the response has a `claim` block, show the user the `verification_uri` and the `user_code`. The user signs in and enters the code. See [Connect an AI agent with a code](/docs/account/connect-agent). Poll the token endpoint every 5 seconds: ```typescript TypeScript theme={null} const response = await fetch("https://vms.dev/api/auth/oauth2/token", { method: "POST", body: new URLSearchParams({ grant_type: "urn:workos:agent-auth:grant-type:claim", claim_token: "clm_...", }), }); ``` ```bash cURL theme={null} curl -X POST https://vms.dev/api/auth/oauth2/token \ -d grant_type=urn:workos:agent-auth:grant-type:claim \ -d claim_token=clm_... ``` After the user confirms, the response has an `access_token` and an `identity_assertion`. **4. Get a new access token** When the access token expires after 15 minutes, exchange the identity assertion: ```typescript TypeScript theme={null} const response = await fetch("https://vms.dev/api/auth/oauth2/token", { method: "POST", body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion: "", resource: "https://vms.dev/api/mcp", }), }); ``` ```bash cURL theme={null} curl -X POST https://vms.dev/api/auth/oauth2/token \ -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \ -d assertion= \ -d resource=https://vms.dev/api/mcp ``` ## Check the result Send the access token as `Authorization: Bearer ` to `https://vms.dev/api/mcp` and call `list_organizations`. The result has the workspaces of the user. See the [MCP tools](/docs/reference/workspace-mcp#tools). For each endpoint, limit, and error, see the [agent registration reference](/docs/reference/agent-registration). Read the [changelog.](/docs/changelog) # Get the usage Source: https://vms.dev/docs/api-reference/billing/get-the-usage /api-reference/openapi.json get /v1/usage Returns the capacity-unit seconds and the cost of each minute, hour, or day in a window, and the credit and the balance of the workspace. Only running time that is not degraded costs money. Needs the `billing:read` scope. # Get a command Source: https://vms.dev/docs/api-reference/commands/get-a-command /api-reference/openapi.json get /v1/sandboxes/{id}/commands/{commandId} Returns one command with its status and its exit result. Needs the `sandboxes:exec` scope. # Kill a command Source: https://vms.dev/docs/api-reference/commands/kill-a-command /api-reference/openapi.json delete /v1/sandboxes/{id}/commands/{commandId} Sends a signal to each process of the command. The default signal is SIGKILL. The answer comes when the command exits, or after 5 seconds. Needs the `sandboxes:exec` scope. # List commands Source: https://vms.dev/docs/api-reference/commands/list-commands /api-reference/openapi.json get /v1/sandboxes/{id}/commands Returns the commands of the sandbox, the newest first. A sandbox keeps its 25 newest exited commands and each running command until it restarts. Needs the `sandboxes:exec` scope. # Run a command Source: https://vms.dev/docs/api-reference/commands/run-a-command /api-reference/openapi.json post /v1/sandboxes/{id}/commands Runs a command in a running sandbox and streams its output as NDJSON until the command exits. A command has no time limit unless you send `timeoutSeconds`. If you disconnect, the command gets SIGKILL. Send `detached: true` to get the command at once and keep it running after you disconnect. Needs the `sandboxes:exec` scope. # Send stdin to a command Source: https://vms.dev/docs/api-reference/commands/send-stdin-to-a-command /api-reference/openapi.json post /v1/sandboxes/{id}/commands/{commandId}/stdin Writes data to the stdin of a running command. The command must start with `stdin: true`. Send `eof: true` to close stdin. Needs the `sandboxes:exec` scope. # Stream the output of a command Source: https://vms.dev/docs/api-reference/commands/stream-the-output-of-a-command /api-reference/openapi.json get /v1/sandboxes/{id}/commands/{commandId}/events Streams the events of a command as NDJSON, also after the command exited. Send `after` to get only the events with a higher `seq`. The stream ends at the `exit` event. A sandbox keeps the newest 4 MiB of events of each command. Needs the `sandboxes:exec` scope. # Delete a file or a folder Source: https://vms.dev/docs/api-reference/files/delete-a-file-or-a-folder /api-reference/openapi.json delete /v1/sandboxes/{id}/files Deletes a file, or a folder and all of its content. You cannot delete the root folder. Needs the `sandboxes:files` scope. # Read a file Source: https://vms.dev/docs/api-reference/files/read-a-file /api-reference/openapi.json get /v1/sandboxes/{id}/files Returns the content of a file in a running sandbox. Needs the `sandboxes:files` scope. # Upload a tar Source: https://vms.dev/docs/api-reference/files/upload-a-tar /api-reference/openapi.json post /v1/sandboxes/{id}/files/tar Extracts a tar or a gzip tar into a folder. Creates the folder if it does not exist, and replaces the files that the tar contains. Send the content type `application/x-tar` or `application/gzip`. The body can be up to 128 MiB. A larger body gets `413`. Needs the `sandboxes:files` scope. # Write a file Source: https://vms.dev/docs/api-reference/files/write-a-file /api-reference/openapi.json put /v1/sandboxes/{id}/files Creates or replaces a file with the request body. Creates the missing folders of the path. The body can be up to 128 MiB. A larger body gets `413`. Needs the `sandboxes:files` scope. # Make your first API request Source: https://vms.dev/docs/api-reference/first-request Create an API key and read your workspace with the REST API. In this tutorial, you create an API key and read the name of your workspace. Guide my first API request. Guide me to create an API key with the workspace:read scope. Give me the TypeScript code for GET /v1/workspace. Do not ask me to share the key. ## Before you start * You need the **Owner** or **Admin** role in the workspace. * You need Bun, Deno, or Node.js 22.18 or later to run the TypeScript code. You can also use `curl` in a terminal. **1. Create the key** In the rail, choose **Settings**, then **API keys**. Choose **Create API key**. Type a **Name**, choose **Read** for **Workspace**, then choose **Create key**. Copy the key. ![The Create API key sheet with the Name field, the Expiration select set to 90 days, and the Workspace, Sandboxes, and Snapshots scopes.](https://mintcdn.com/vms-c6f4e5ac/kvsBm-leIVQYZQAw/images/workspace/api-keys/01-create-api-key-light.png?fit=max\&auto=format\&n=kvsBm-leIVQYZQAw\&q=85\&s=524e2fdb6dad87d3c48f1574614ca536) **2. Send the request** Save the code in `first-request.ts`. Replace `` with the key. Then run `bun first-request.ts`. ```typescript TypeScript theme={null} const response = await fetch("https://vms.dev/api/v1/workspace", { headers: { Authorization: "Bearer " }, }); console.log(response.status, await response.json()); ``` ```bash cURL theme={null} curl https://vms.dev/api/v1/workspace \ -H "Authorization: Bearer " ``` ## Check the result The API returns status 200 and the workspace: ```json theme={null} { "id": "RRe4VqZEvVmRRJ6c4cWO2JMDA2EWO0BA", "name": "Acme Inc", "slug": "acme", "website": "acme.com", "language": "en", "createdAt": "2026-11-15T22:26:13.708Z" } ``` If the API returns an error, see the [error codes](/docs/api-reference/introduction#errors). Read the [changelog.](/docs/changelog) # API introduction Source: https://vms.dev/docs/api-reference/introduction Authentication, scopes, errors, and limits of the REST API. The REST API gives a program access to one workspace. Each request uses an [API key](/docs/workspace/api-keys) of that workspace. Plan an API integration. Ask what my program must read or change. Tell me the endpoints and the scopes that it needs. Do not ask me to share an API key. ## Base URL ```text theme={null} https://vms.dev/api ``` Each path in this reference is relative to the base URL. For example, `GET /v1/workspace` is `https://vms.dev/api/v1/workspace`. ## Authentication Send the key in the `Authorization` header: ```bash theme={null} Authorization: Bearer ``` The API also accepts the key in the `x-api-key` header. The key sets the workspace of the request, so a request has no workspace parameter. ## Scopes Each endpoint needs one scope. See [API key scopes](/docs/reference/workspace-access#api-key-scopes). ## Pagination A list endpoint, such as `GET /v1/workspace-changes`, returns one page: ```json theme={null} { "data": [], "nextCursor": "eyJjcmVhdGVkQXQiOi..." } ``` Send `limit` (1 to 100, default 50) to set the page size. To get the next page, send the `nextCursor` of the last page as `cursor`. The last page has `"nextCursor": null`. ## Record IDs Each record ID starts with a prefix that tells its type, such as `wsc_` for a workspace change, `sbx_` for a sandbox, and `op_` for an operation. ## Errors An error response has a code, a message, and the ID of the request: ```json theme={null} { "error": { "code": "unauthenticated", "message": "The API key is not correct, or somebody revoked it.", "requestId": "19283a6c-8864-483f-8dab-320eec5015e1" } } ``` | Status | Code | Cause | | - | - | - | | 400 | `invalid` | The request is not valid. | | 401 | `unauthenticated` | The key is missing, not correct, revoked, or expired. | | 403 | `forbidden` | The key does not have the scope of the endpoint. | | 404 | `not_found` | The resource does not exist. | | 409 | `conflict` | The request conflicts with the current data, such as an `Idempotency-Key` that you sent with a different request. | | 429 | `rate_limited` | The key sent more than 1,200 requests in one minute. | | 500 | `internal_error` | An error occurred on the server. Try again later. | | 503 | `no_capacity` | No host has room for the size of the sandbox. Wait `retryAfterSeconds`, then try again. | A sandbox error can have two more fields: * `retryAfterSeconds`: the time to wait before you try again. The `Retry-After` header has the same value. * `sandboxId`: the sandbox that the error is about. Each response has the `x-request-id` header. Give this ID when you ask for help. The API also serves this reference as an OpenAPI 3.1 document at `https://vms.dev/api/v1/openapi.json`. Read the [changelog.](/docs/changelog) # Get the limits Source: https://vms.dev/docs/api-reference/limits/get-the-limits /api-reference/openapi.json get /v1/limits Returns the limits of the workspace plan and the current use of each limit. A create above a limit answers `402 billing_required`, `403 size_not_allowed`, or `429 start_limit`. Needs the `sandboxes:read` scope. # Add an SSH key to a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/add-an-ssh-key-to-a-sandbox /api-reference/openapi.json post /v1/sandboxes/{id}/ssh-keys Adds a public key to the sandbox. Then `ssh @ssh.vms.dev` with this key opens a shell in the sandbox as `user`, and so does SSH to the IPv6 address of the sandbox. A running sandbox gets the key in a few seconds. A sandbox can have 20 keys. Needs the `sandboxes:ssh` scope. # Add many SSH keys to a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/add-many-ssh-keys-to-a-sandbox /api-reference/openapi.json post /v1/sandboxes/{id}/ssh-keys/create-many Adds up to 500 public keys to the sandbox in one request. The API returns a result for each item, in the sequence of the items: the ID of the new key, or an error message. A sandbox can have 20 keys. Needs the `sandboxes:ssh` scope. # Create a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/create-a-sandbox /api-reference/openapi.json post /v1/sandboxes Creates a sandbox of the size that you send. Send `template` to start the sandbox with the files of a template: its ID, its name, or a share code from another workspace. The sandbox takes a warm slot, or waits a few seconds for a new slot when a host has room, and moves through `creating` and `starting` to `running`. Read the sandbox or its operation to see when it is `running`. If no host has room, the API answers `503` with the code `no_capacity` at once. Send `fromSandbox` to fork a running or stopped sandbox: the fork gets the files and the environment variables of the source, and its own name, hostname, SSH host keys, IPv6 address, and agent key. It does not get the auto-stop time or the URLs of the source. Send `count` to make more than one fork. Needs the `sandboxes:write` scope. # Create a URL for a port Source: https://vms.dev/docs/api-reference/sandboxes/create-a-url-for-a-port /api-reference/openapi.json post /v1/sandboxes/{id}/urls Gives a port of the sandbox an HTTPS URL, such as `https://agent-42-3000-k3m7q2v9.vmsdev.run`. The URL needs its token, unless you send `public: true`. A sandbox has up to 20 URLs. Needs the `sandboxes:write` scope. # Create many sandboxes Source: https://vms.dev/docs/api-reference/sandboxes/create-many-sandboxes /api-reference/openapi.json post /v1/sandboxes/create-many Creates up to 500 sandboxes in one request. Give each item the fields of a create. The API creates the items one after the other. It returns a result for each item, in the sequence of the items: the ID of the new sandbox, or the error message. Needs the `sandboxes:write` scope. # Create many URLs of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/create-many-urls-of-a-sandbox /api-reference/openapi.json post /v1/sandboxes/{id}/urls/create-many Gives up to 500 ports of the sandbox a URL in one request. The API returns a result for each item, in the sequence of the items: the ID of the new URL, or an error message. A sandbox can have 20 URLs. Needs the `sandboxes:write` scope. # Delete a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/delete-a-sandbox /api-reference/openapi.json delete /v1/sandboxes/{id} Moves the sandbox to `deleting`, then to `deleted`, and removes its data. A second delete while the sandbox is `deleting` returns the same sandbox. Needs the `sandboxes:write` scope. # Delete a URL of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/delete-a-url-of-a-sandbox /api-reference/openapi.json delete /v1/sandboxes/{id}/urls/{urlId} Deletes the URL. The port in the sandbox does not change. Needs the `sandboxes:write` scope. # Delete an SSH key Source: https://vms.dev/docs/api-reference/sandboxes/delete-an-ssh-key /api-reference/openapi.json delete /v1/sandboxes/{id}/ssh-keys/{keyId} Removes the key from the sandbox. New connections with the key fail. Needs the `sandboxes:ssh` scope. # Delete many sandboxes Source: https://vms.dev/docs/api-reference/sandboxes/delete-many-sandboxes /api-reference/openapi.json post /v1/sandboxes/delete-many Deletes up to 500 sandboxes in one request. Each sandbox moves to `deleting`, then to `deleted`. The API returns a result for each ID, in the sequence of the IDs: the ID, and an error message if the delete failed. Needs the `sandboxes:write` scope. # Delete many SSH keys of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/delete-many-ssh-keys-of-a-sandbox /api-reference/openapi.json post /v1/sandboxes/{id}/ssh-keys/delete-many Deletes up to 500 keys of the sandbox in one request. The API returns a result for each ID, in the sequence of the IDs. Needs the `sandboxes:ssh` scope. # Delete many URLs of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/delete-many-urls-of-a-sandbox /api-reference/openapi.json post /v1/sandboxes/{id}/urls/delete-many Deletes up to 500 URLs of the sandbox in one request. The API returns a result for each ID, in the sequence of the IDs. Needs the `sandboxes:write` scope. # Get a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/get-a-sandbox /api-reference/openapi.json get /v1/sandboxes/{id} Returns one sandbox with its latest operation. After a delete, the first request returns the sandbox with the state `deleted`, and each later request answers `404`. Needs the `sandboxes:read` scope. # Get a snapshot Source: https://vms.dev/docs/api-reference/sandboxes/get-a-snapshot /api-reference/openapi.json get /v1/sandboxes/{id}/snapshots/{snapshotId} Returns one saved snapshot of a sandbox. Needs the `sandboxes:read` scope. # Get a URL of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/get-a-url-of-a-sandbox /api-reference/openapi.json get /v1/sandboxes/{id}/urls/{urlId} Returns one URL of a sandbox. Needs the `sandboxes:read` scope. # Get an operation Source: https://vms.dev/docs/api-reference/sandboxes/get-an-operation /api-reference/openapi.json get /v1/operations/{id} Returns one operation on a sandbox, such as a create or a delete, with its status. Needs the `sandboxes:read` scope. # Get the usage of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/get-the-usage-of-a-sandbox /api-reference/openapi.json get /v1/sandboxes/{id}/usage Returns the capacity-unit seconds and the cost of one sandbox in a window. The default window is the current month (UTC). Needs the `sandboxes:read` scope. # List sandboxes Source: https://vms.dev/docs/api-reference/sandboxes/list-sandboxes /api-reference/openapi.json get /v1/sandboxes Lists the sandboxes of the workspace, newest first. A deleted sandbox is not in the list. Filter by state, name, start of the name, and label. To find a sandbox by its name, send `name`. To get the next page, send the nextCursor of the last page with the same filters and order. Needs the `sandboxes:read` scope. # List the snapshots of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/list-the-snapshots-of-a-sandbox /api-reference/openapi.json get /v1/sandboxes/{id}/snapshots Lists the saved snapshots of a sandbox, newest first. A running sandbox saves its changed files each minute. A minute with no change adds no snapshot. Needs the `sandboxes:read` scope. # List the SSH keys of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/list-the-ssh-keys-of-a-sandbox /api-reference/openapi.json get /v1/sandboxes/{id}/ssh-keys Lists the public keys that can connect to the sandbox with SSH, oldest first. Needs the `sandboxes:ssh` scope. # List the URLs of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/list-the-urls-of-a-sandbox /api-reference/openapi.json get /v1/sandboxes/{id}/urls Lists the HTTPS URLs of the ports of a sandbox, by port. Needs the `sandboxes:read` scope. # Open the desktop of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/open-the-desktop-of-a-sandbox /api-reference/openapi.json post /v1/sandboxes/{id}/desktop-sessions Gives a URL that shows the desktop of a running sandbox in a browser, at 1080p and 60 frames each second. The URL contains a token. It stops working 10 minutes after the create if nobody opens it. A browser that opens it keeps the desktop for 12 hours, while the sandbox runs. Needs the `sandboxes:desktop` scope. # Update a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/update-a-sandbox /api-reference/openapi.json patch /v1/sandboxes/{id} Changes the name, the labels, or the state of a sandbox. The request changes only the fields that you send. The labels that you send replace all labels of the sandbox. Send `name: null` to remove the name. Send `state: stopped` to stop a running sandbox. The sandbox moves to `stopping`: the API runs `~/.vms/pre-stop` (at most 60 seconds), takes a last snapshot, and pauses the sandbox. Then the sandbox is `stopped`, and billing stops. For 10 minutes, the host keeps the memory of the sandbox. A stop while a stop is pending returns the pending operation. If the last snapshot fails 3 times, the operation is `failing`, the sandbox runs again and is not billed, and the stop tries again each 5 minutes. After 3 days, the stop uses the last good snapshot and sends an email to the owners and admins. Send `state: running` within 10 minutes of a stop to resume the sandbox with its memory and its processes. A resume is a start, so the start limits of the plan apply. A resume while a stop is `failing` cancels the stop. With `state`, the API answers `202` with the operation of the stop or the resume. Needs the `sandboxes:write` scope. # Update a URL of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/update-a-url-of-a-sandbox /api-reference/openapi.json patch /v1/sandboxes/{id}/urls/{urlId} Opens the URL to everyone with `public: true`, or adds the token gate again with `public: false`. The token does not change. Needs the `sandboxes:write` scope. # Update many sandboxes Source: https://vms.dev/docs/api-reference/sandboxes/update-many-sandboxes /api-reference/openapi.json post /v1/sandboxes/update-many Changes up to 500 sandboxes in one request. Give each item the `id` of a sandbox and the fields of an update, such as `state: stopped` to stop it. The API changes the items one after the other. It returns a result for each item, in the sequence of the items: the ID, and an error message if the change failed. Needs the `sandboxes:write` scope. # Update many URLs of a sandbox Source: https://vms.dev/docs/api-reference/sandboxes/update-many-urls-of-a-sandbox /api-reference/openapi.json post /v1/sandboxes/{id}/urls/update-many Changes up to 500 URLs of the sandbox in one request. Each item has the `id` of a URL and the fields of an update. The API returns a result for each item, in the sequence of the items. Needs the `sandboxes:write` scope. # Download a file or a folder of a snapshot Source: https://vms.dev/docs/api-reference/snapshots/download-a-file-or-a-folder-of-a-snapshot /api-reference/openapi.json get /v1/snapshots/{id}/files Returns the content of a file. For a folder, returns a tar of the folder and of each saved file and folder in it. A snapshot holds the saved files: the files and folders that are different from the base image. It works with no running sandbox, also after the sandbox is deleted, until its saved files are deleted. Needs the `snapshots:read` scope. # Download a snapshot Source: https://vms.dev/docs/api-reference/snapshots/download-a-snapshot /api-reference/openapi.json get /v1/snapshots/{id}/download Streams a tar of each saved file and folder of a snapshot. The names in the tar have no leading /. A snapshot holds the saved files: the files and folders that are different from the base image. It works with no running sandbox, also after the sandbox is deleted, until its saved files are deleted. Needs the `snapshots:read` scope. # List a folder of a snapshot Source: https://vms.dev/docs/api-reference/snapshots/list-a-folder-of-a-snapshot /api-reference/openapi.json get /v1/snapshots/{id}/tree Returns the saved files and folders in one folder of a snapshot. A snapshot holds the saved files: the files and folders that are different from the base image. It works with no running sandbox, also after the sandbox is deleted, until its saved files are deleted. Needs the `snapshots:read` scope. # Create a share code Source: https://vms.dev/docs/api-reference/templates/create-a-share-code /api-reference/openapi.json post /v1/templates/{id}/share-codes Makes a code that lets another workspace create sandboxes from the template. The other workspace sends the code as `template` when it creates a sandbox. It cannot see, list, or download the template or its files. The response shows the code one time. A template can have 20 share codes. Needs the `templates:write` scope. # Create a template Source: https://vms.dev/docs/api-reference/templates/create-a-template /api-reference/openapi.json post /v1/templates Saves the files of a running or stopped sandbox as a template. The template has the status `saving`, then `ready` or `failed`. For a running sandbox, the template takes a new snapshot first, so that it has the latest writes. The template is a full copy: it does not change when the sandbox changes or is deleted, and it has no expiry date. Needs the `templates:write` and the `snapshots:read` scopes, because a template copies the files of the sandbox. # Create many templates Source: https://vms.dev/docs/api-reference/templates/create-many-templates /api-reference/openapi.json post /v1/templates/create-many Saves up to 500 templates in one request. The API returns a result for each item, in the sequence of the items. Needs the `templates:write` and the `snapshots:read` scopes, because a template copies the files of the sandbox. # Delete a template Source: https://vms.dev/docs/api-reference/templates/delete-a-template /api-reference/openapi.json delete /v1/templates/{id} Deletes the template. Its saved files go after each sandbox from the template has its own full snapshot. Sandboxes from the template do not change. Needs the `templates:write` scope. # Delete many templates Source: https://vms.dev/docs/api-reference/templates/delete-many-templates /api-reference/openapi.json post /v1/templates/delete-many Deletes up to 500 templates in one request. The API returns a result for each ID, in the sequence of the IDs. Needs the `templates:write` scope. # Get a template Source: https://vms.dev/docs/api-reference/templates/get-a-template /api-reference/openapi.json get /v1/templates/{id} Returns one template. Needs the `templates:read` or the `templates:write` scope. # List templates Source: https://vms.dev/docs/api-reference/templates/list-templates /api-reference/openapi.json get /v1/templates Returns the templates of the workspace, newest first. Needs the `templates:read` or the `templates:write` scope. # List the share codes of a template Source: https://vms.dev/docs/api-reference/templates/list-the-share-codes-of-a-template /api-reference/openapi.json get /v1/templates/{id}/share-codes Returns the share codes of the template, oldest first. The list shows the last 4 characters of each code, not the code. Needs the `templates:read` or the `templates:write` scope. # Revoke a share code Source: https://vms.dev/docs/api-reference/templates/revoke-a-share-code /api-reference/openapi.json delete /v1/templates/{id}/share-codes/{codeId} Revokes the share code. A create with the code then fails. Sandboxes that were created with the code continue to run. Needs the `templates:write` scope. # Revoke many share codes Source: https://vms.dev/docs/api-reference/templates/revoke-many-share-codes /api-reference/openapi.json post /v1/templates/{id}/share-codes/delete-many Revokes up to 500 share codes of the template in one request. The API returns a result for each ID, in the sequence of the IDs. Needs the `templates:write` scope. # Update a template Source: https://vms.dev/docs/api-reference/templates/update-a-template /api-reference/openapi.json patch /v1/templates/{id} Renames the template. Needs the `templates:write` scope. # Update many templates Source: https://vms.dev/docs/api-reference/templates/update-many-templates /api-reference/openapi.json post /v1/templates/update-many Renames up to 500 templates in one request. Each item has the `id` of a template and the fields of an update. The API returns a result for each item, in the sequence of the items. Needs the `templates:write` scope. # Create a webhook endpoint Source: https://vms.dev/docs/api-reference/webhooks/create-a-webhook-endpoint /api-reference/openapi.json post /v1/webhooks Adds an endpoint that gets a signed POST request for each event. The response has the signing secret. You see the secret only one time. A workspace can have 10 endpoints. Needs the `webhooks:write` scope. # Delete a webhook endpoint Source: https://vms.dev/docs/api-reference/webhooks/delete-a-webhook-endpoint /api-reference/openapi.json delete /v1/webhooks/{id} Deletes the endpoint. Events that wait for a retry do not go to it. Needs the `webhooks:write` scope. # Delete many webhook endpoints Source: https://vms.dev/docs/api-reference/webhooks/delete-many-webhook-endpoints /api-reference/openapi.json post /v1/webhooks/delete-many Deletes up to 500 endpoints in one request. The API returns a result for each ID, in the sequence of the IDs. Needs the `webhooks:write` scope. # Get a webhook endpoint Source: https://vms.dev/docs/api-reference/webhooks/get-a-webhook-endpoint /api-reference/openapi.json get /v1/webhooks/{id} Returns one webhook endpoint, without its secret. Needs the `webhooks:read` or the `webhooks:write` scope. # List webhook endpoints Source: https://vms.dev/docs/api-reference/webhooks/list-webhook-endpoints /api-reference/openapi.json get /v1/webhooks Returns the webhook endpoints of the workspace, oldest first. Needs the `webhooks:read` or the `webhooks:write` scope. # Sandbox event Source: https://vms.dev/docs/api-reference/webhooks/sandbox-event /api-reference/openapi.json webhook sandbox-event Each enabled endpoint that has the event type gets this request. Answer with a 2xx status within 10 seconds. If you do not, the request comes again, up to 8 attempts in total. # Update a webhook endpoint Source: https://vms.dev/docs/api-reference/webhooks/update-a-webhook-endpoint /api-reference/openapi.json patch /v1/webhooks/{id} Changes only the fields that you send. Set `enabled` to false to stop the events. Needs the `webhooks:write` scope. # Update many webhook endpoints Source: https://vms.dev/docs/api-reference/webhooks/update-many-webhook-endpoints /api-reference/openapi.json post /v1/webhooks/update-many Changes up to 500 endpoints in one request. Each item has the `id` of an endpoint and the fields of an update. The API returns a result for each item, in the sequence of the items. Needs the `webhooks:write` scope. # Get the workspace Source: https://vms.dev/docs/api-reference/workspace/get-the-workspace /api-reference/openapi.json get /v1/workspace Returns the workspace of the API key. Needs the `workspace:read` scope. # List workspace changes Source: https://vms.dev/docs/api-reference/workspace/list-workspace-changes /api-reference/openapi.json get /v1/workspace-changes Lists the changes of the workspace, newest first: the workspace was created, renamed, or got a new website, and members joined, changed role, or left. To get the next page, send the nextCursor of the last page. Needs the `workspace:read` scope. # Changelog Source: https://vms.dev/docs/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](/docs/sandboxes/create-and-delete#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](/docs/sandboxes/in-the-app#see-the-details-of-a-sandbox) and [See the details of a template](/docs/sandboxes/templates-in-the-app#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](/docs/sandboxes/in-the-app#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](/docs/sandboxes/templates-in-the-app#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](/docs/sandboxes/in-the-app#find-a-sandbox) and [Find a template](/docs/sandboxes/templates-in-the-app#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](/docs/workspace/billing#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](/docs/sandboxes/ssh#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](/docs/reference/cli#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](/docs/cli-quickstart). ## 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](/docs/sandboxes/create-and-delete#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](/docs/sandboxes/stop-and-resume#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](/docs/sandboxes/stop-and-resume#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](/docs/sandboxes/stop-and-resume#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](/docs/sandboxes/templates#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](/docs/sandboxes/desktop). * 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](/docs/reference/workspace-access#api-key-scopes). * A template of a stopped sandbox with no saved files fails with `no_snapshot`. See [Templates](/docs/sandboxes/templates). * 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](/docs/sandboxes/snapshot-files). ## 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](/docs/sandboxes/stop-and-resume#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](/docs/sandboxes/stop-and-resume#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](/docs/workspace/usage-and-balance#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](/docs/workspace/usage-and-balance#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](/docs/workspace/billing#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](/docs/workspace/billing#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](/docs/workspace/billing#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](/docs/sandboxes/stop-and-resume#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](/docs/sandboxes/stop-and-resume#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](/docs/sandboxes/stop-and-resume#resume-from-the-saved-files). * A sandbox shows `hydrated`, `hydratedAt`, and `hydration` with the phase and the files done. See [Hydration](/docs/sandboxes/stop-and-resume#hydration). * The new `sandbox.hydrated` webhook goes out when each file is local. See [Webhook events](/docs/reference/webhook-events). * 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](/docs/sandboxes/stop-and-resume#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](/docs/sandboxes/templates-in-the-app). * 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](/docs/sandboxes/in-the-app). * **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](/docs/sandboxes/in-the-app#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](/docs/workspace/api-keys). ## 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](/docs/reference/cli#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](/docs/reference/cli#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](/docs/reference/cli#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](/docs/reference/typescript-sdk#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](/docs/sandboxes/snapshot-files#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](/docs/sandboxes/snapshot-files#download-a-file-or-a-folder). * Download the whole snapshot as a tar with `GET /v1/snapshots/{id}/download`. See [Download the whole snapshot](/docs/sandboxes/snapshot-files#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](/docs/reference/workspace-access#api-key-scopes). * A file of an older snapshot can answer `409 snapshot_old_format`. Resume the sandbox to read it. See [Errors](/docs/sandboxes/snapshot-files#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](/docs/sandboxes/desktop). * 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](/docs/reference/workspace-access#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](/docs/sandboxes/urls#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](/docs/sandboxes/desktop#show-only-chrome). * The desktop stream carries the sound of the sandbox. See [Sound](/docs/sandboxes/desktop#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](/docs/sandboxes/templates#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](/docs/sandboxes/templates#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](/docs/sandboxes/templates). * 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](/docs/sandboxes/templates#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](/docs/reference/workspace-access#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](/docs/reference/plans#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](/docs/sandboxes/fork). * 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](/docs/sandboxes/fork#fork-a-running-sandbox). * Send `count` to make up to 100 forks in one request. See [Make many forks](/docs/sandboxes/fork#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](/docs/sandboxes/eve#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](/docs/sandboxes/eve#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](/docs/workspace/api-keys). * A revoked key stops on the command and file routes within 10 seconds. See [Revoke an API key](/docs/workspace/api-keys#revoke-an-api-key). * `waitUntilRunning` of the SDK reads the sandbox one time each second, and waits longer after a `429`. See [waitUntilRunning](/docs/reference/typescript-sdk#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](/docs/sandboxes/urls). * 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](/docs/sandboxes/ssh#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](/docs/sandboxes/files#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](/docs/reference/eve-provider). * 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](/docs/reference/workspace-access#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](/docs/sandboxes/webhooks#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](/docs/sandboxes/list-and-label#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](/docs/sandboxes/create-and-delete#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](/docs/workspace/usage-and-balance#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](/docs/workspace/usage-and-balance#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](/docs/reference/health-and-recovery#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](/docs/sandboxes/stop-and-resume#when-the-last-snapshot-fails). * Each stopped sandbox above the saved snapshots of the plan costs \$0.04 each day. See [Plans reference](/docs/reference/plans). * `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](/docs/workspace/usage-and-balance#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](/docs/reference/cli). * 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](/docs/reference/cli#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](/docs/reference/cli#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](/docs/reference/cli#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](/docs/reference/typescript-sdk#install). * Install the eve provider with `npm install @vms.dev/eve`. See [Give the agent a sandbox](/docs/sandboxes/eve#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](/docs/sandboxes/eve). * 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](/docs/sandboxes/eve#what-happens-in-a-session). * The files and commands of `prepare` run again in each new sandbox. See [Run setup commands](/docs/sandboxes/eve#run-setup-commands) and the [eve provider reference](/docs/reference/eve-provider). ## 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](/docs/reference/health-and-recovery#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](/docs/reference/health-and-recovery#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](/docs/reference/health-and-recovery#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](/docs/reference/health-and-recovery#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](/docs/sandboxes/stop-and-resume#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](/docs/sandboxes/stop-and-resume#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](/docs/sandboxes/stop-and-resume#how-long-a-stopped-sandbox-keeps-its-files). * The saved files of a deleted sandbox are deleted within 24 hours. See [Delete a sandbox](/docs/sandboxes/create-and-delete#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](/docs/reference/saved-files#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](/docs/reference/plans#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](/docs/workspace/usage-and-balance#top-up-the-balance). * Turn on automatic top-up from \$5, also in the trial. See [Turn on automatic top-up](/docs/workspace/usage-and-balance#turn-on-automatic-top-up). * Set a monthly spending limit, with emails at 50%, 80%, and 100%. See [Set a spending limit](/docs/workspace/usage-and-balance#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](/docs/reference/plans#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](/docs/workspace/usage-and-balance#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](/docs/workspace/usage-and-balance#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](/docs/sdk-quickstart). * Helpers wait until a sandbox runs, stream a command, write many files in one tar upload, and open SSH with your key. See [Helpers](/docs/reference/typescript-sdk#helpers). * An API error is a `VmsError` with its `status` and `code`. `readWebhook()` checks the signature of a webhook. See [Errors](/docs/reference/typescript-sdk#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](/docs/sandboxes/auto-stop). * 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](/docs/sandboxes/auto-stop#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](/docs/sandboxes/auto-stop#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](/docs/sandboxes/stop-and-resume). * 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](/docs/sandboxes/stop-and-resume#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](/docs/sandboxes/stop-and-resume#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](/docs/sandboxes/stop-and-resume#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 @ssh.vms.dev`. List and delete keys with the same resource. The endpoints need the `sandboxes:ssh` scope. See [Connect with SSH](/docs/sandboxes/ssh). * `scp`, `sftp`, port forwarding, and `ssh -J` work through `ssh.vms.dev`. See [Open a shell](/docs/sandboxes/ssh#open-a-shell). * `GET /v1/sandboxes/{id}` shows the SSH host key of the sandbox in `sshHostKey`. See [Check the host keys](/docs/sandboxes/ssh#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](/docs/sandboxes/urls). * 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](/docs/sandboxes/urls#open-the-url). * WebSockets work through the URL, so dev servers with live reload work. See [Use WebSockets](/docs/sandboxes/urls#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](/docs/workspace/billing#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](/docs/workspace/billing#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](/docs/workspace/billing#download-an-invoice). * See each payment attempt, also the failed ones, and open its receipt. See [See the payments](/docs/workspace/billing#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](/docs/reference/sandbox-network#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](/docs/reference/sandbox-network#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](/docs/reference/sandbox-network#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](/docs/reference/sandbox-network#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](/docs/reference/saved-files). * 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](/docs/reference/saved-files#list-the-snapshots). * Put a `.vmsignore` file in a folder to keep paths out of the snapshots. See [.vmsignore](/docs/reference/saved-files#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](/docs/sandboxes/webhooks). * 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](/docs/reference/webhook-events). ## 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](/docs/sandboxes/list-and-label). * 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](/docs/sandboxes/list-and-label#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](/docs/sandboxes/list-and-label#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](/docs/sandboxes/list-and-label#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](/docs/sandboxes/create-and-delete). * 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](/docs/reference/plans#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](/docs/sandboxes/run-commands). * 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](/docs/sandboxes/files). * Upload a tar or a gzip tar into a folder with `POST /v1/sandboxes/{id}/files/tar?path=`. See [Upload a tar](/docs/sandboxes/files#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](/docs/reference/workspace-access#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](/docs/sandboxes/in-the-app#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](/docs/sandboxes/in-the-app#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](/docs/sandboxes/in-the-app#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](/docs/workspace/billing). * Change the plan, the card, or the billing email in the Stripe billing portal. See [Change the plan, the card, or the billing email](/docs/workspace/billing#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](/docs/reference/workspace-access#roles). * See the limits of each plan and the trial in the [plans reference](/docs/reference/plans), and the comparison with boat.dev in [How billing works](/docs/explanation/billing). ## Website * `https://vms.dev` shows a page about sandboxes when you are signed out. Choose **Sign in** to open your workspace. See [Sign in](/docs/account/sign-in). * 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](/docs/agent-skills). * The sign-in page has a new layout. A new email gets an account from the same link. See [Sign in](/docs/account/sign-in). * 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](/docs/account/profile). * The language codes are reserved workspace URLs, such as `fr` and `de`. See the [URL rules](/docs/reference/workspace-settings#workspace-url). * More workspace URLs are reserved, such as `compare`, `docs`, and `use-cases`. See the [URL rules](/docs/reference/workspace-settings#workspace-url). * `ingest` is a reserved workspace URL. See the [URL rules](/docs/reference/workspace-settings#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](/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](/docs/account/sign-in). * 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](/docs/workspace/settings). * Invite members by name and email, and give them a role. The members table shows the name of each invited person. See [Members](/docs/workspace/members). * Change your name, avatar, language, time zone, and theme. See [Profile](/docs/account/profile). ## API keys and the REST API * Create API keys with scopes for a workspace. See [API keys](/docs/workspace/api-keys). * The API is at `https://vms.dev/api`, and the MCP server is at `https://vms.dev/api/mcp`. See the [API introduction](/docs/api-reference/introduction#base-url). * Read the workspace with `GET /v1/workspace`. See [your first API request](/docs/api-reference/first-request). * List the changes of the workspace with `GET /v1/workspace-changes`. See [pagination](/docs/api-reference/introduction#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](/docs/api-reference/first-request). ## 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](/docs/api-reference/agent-registration). * 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](/docs/account/connect-agent). * Give your agent the agent sign-up skill at `/auth.md`. See [Agent skills](/docs/agent-skills). ## MCP * Connect Claude, Cursor, Visual Studio Code, or another MCP client with OAuth sign-in. See [Connect an MCP client](/docs/install-mcp). * Use the tools `list_organizations`, `get_workspace`, and `list_workspace_changes`. See the [MCP reference](/docs/reference/workspace-mcp). # Use a sandbox from your terminal Source: https://vms.dev/docs/cli-quickstart Install the vms command line tool, sign in with your browser, create a sandbox, run a command, copy a file, connect with SSH, and delete the sandbox. In this tutorial, you use the `vms` command line tool to create a sandbox, run a command in it, copy a file, open SSH, and delete the sandbox. Use a sandbox from the terminal with the vms CLI. Use the vms CLI. Check that I am signed in with vms ls. Create a small sandbox with vms new, run a command in it with vms exec, copy a file into it with vms cp, and delete it with vms rm at the end. Do not ask me to share my API key. ## Before you start * Your workspace needs a plan or a trial. See [Choose a plan or start a trial](/docs/workspace/billing). * You need the **Owner** or **Admin** role in the workspace to sign in with your browser. A member can sign in with an API key. See [Sign in](/docs/reference/cli#sign-in). * You need Homebrew on macOS or Linux. To install without Homebrew, see [Install](/docs/reference/cli#install). **1. Install the CLI** ```bash theme={null} brew install vms-dev-org/tap/vms vms --version ``` **2. Sign in** ```bash theme={null} vms login ``` The CLI shows a code and opens a page in your browser. Check that the page shows the same code, and choose **Approve**. The CLI saves an API key for your workspace. **3. Create a sandbox** ```bash theme={null} vms new agent-42 ``` The CLI waits until the sandbox is `running`, and writes its ID. **4. Run a command** ```bash theme={null} vms exec agent-42 -- uname -a vms exec agent-42 'echo hello > /home/user/hello.txt && cat /home/user/hello.txt' ``` The CLI streams the output, and exits with the exit code of the command. **5. Copy a file** ```bash theme={null} echo "notes" > notes.txt vms cp notes.txt agent-42:/home/user/ vms cp agent-42:/home/user/hello.txt ./hello.txt ``` **6. Open a shell** ```bash theme={null} vms ssh agent-42 ``` The CLI adds your public key to the sandbox and the host key of `ssh.vms.dev` to `~/.ssh/known_hosts`. Type `exit` to close the shell. **7. Delete the sandbox** ```bash theme={null} vms rm agent-42 ``` This deletes the sandbox and its files. You cannot undo this. ## Check the result Run `vms ls`. The list does not show `agent-42`. ## Next steps * See each command and its options in the [CLI reference](/docs/reference/cli). * Stop a sandbox and resume it later with its files. See [Stop and resume a sandbox](/docs/sandboxes/stop-and-resume). * Make many copies of one sandbox with `vms fork`. See [Fork a sandbox](/docs/sandboxes/fork). * Use a sandbox from code. See [Use a sandbox from TypeScript](/docs/sdk-quickstart). Read the [changelog.](/docs/changelog) # How programs and agents get access Source: https://vms.dev/docs/explanation/agent-access API keys, MCP sign-in, and agent registration: what each gives access to, and why. There are three ways for software to get access. Each one answers a different question: who gives the access, and to what. Explain which access method fits my program. Ask what my program or agent must do, and whether a person is present. Recommend one access method from this page and explain why. ## API keys belong to a workspace An owner or an admin makes an [API key](/docs/workspace/api-keys) for one workspace. The key acts for the workspace, not for a person. It is for a script or a CI job that runs without a person. Its scopes limit it to the REST API. ## MCP sign-in acts as a person An [MCP client](/docs/install-mcp), such as Claude or Cursor, opens sign-in in the browser. The person signs in and allows the access on a consent screen. The client then acts as that person, in each workspace that the person is a member of, and only with the person's role. This needs the person at the browser when the client connects, and a client that supports OAuth. ## Agent registration starts from the agent With [agent registration](/docs/api-reference/agent-registration), the agent starts. It can arrive with no account and no key. It gets the same kind of token as an MCP client, so the same tools, roles, and limits apply. The person still decides. The agent shows a code, and the person enters it after sign-in. The code goes from the agent to the person, and not in the other direction. Then a person who did not sign in cannot connect an agent to an account, and an agent that saw a code cannot use it. When the agent gives an email, only that account can enter the code. An agent provider that already knows the person can skip the code. It signs an ID-JAG that says "this agent acts for this verified email". The service accepts it only from providers on its trust list. If the email already has an account, the person confirms the link one time. ## Each credential can stop | Credential | It stops when | | - | - | | API key | An owner or an admin revokes it, or it expires | | MCP sign-in | The access token expires after 15 minutes, and the person removes the client | | Agent registration | The person chooses **Disconnect**, the provider sends a revocation event, or the 7-day assertion expires | An unclaimed anonymous agent stops after 24 hours. It has no workspaces before a claim, so it can read no data. Read the [changelog.](/docs/changelog) # How billing works Source: https://vms.dev/docs/explanation/billing How the plan, the trial, and the usage credit of a workspace work, and how the terms compare with boat.dev. A workspace pays for one plan each month. The plan sets the limits of the workspace, and its fee comes back as credit for sandbox time. Explain the billing of my workspace. Explain how the plan, the trial, and the usage credit work. Use the plans reference for the exact values. ## The workspace pays, not each person The workspace is the Stripe customer. One invoice each month pays for the plan. Members are free, and the price does not change when the team grows. Owners and admins choose the plan and open the Stripe billing portal. Each member can see the plan, the invoices, and the charges. ## The fee comes back as credit Each month, the plan fee comes back as usage credit. Sandbox time uses the credit by the second, at the price of the size. Unused credit carries over for one month. The plan also sets the limits: how many sandboxes run at a time, and how many start each minute and each day. A start costs nothing. Each plan allows each size, `xlarge` included. ## Usage takes the credit, then the balance Each running second of a sandbox costs the price of its size. A sandbox that starts, stops, or fails costs nothing, and so does a sandbox that is unreachable because of a problem on our side. The usage of each minute comes out of the credit first, then out of the prepaid balance. Top-ups add to the balance, and from \$100 they get a bonus of up to 27%. Automatic top-up adds money when the funds go below a limit, so that the sandboxes do not stop. A monthly spending limit stops the running sandboxes and new starts, so that a runaway agent cannot spend more than you planned. When the credit and the balance are empty, a workspace with a paid plan keeps running for 48 hours, with a small debt allowance. A card problem does not stop your work at once. See [grace and debt](/docs/reference/plans#grace-and-debt). ## The trial needs a card The trial lasts 14 days. It gives 60 unit-hours, 3 sandboxes at a time, and sizes up to `large`. The card stops one person from starting many trials. Each workspace and each owner gets one trial. At the end of the trial, the \$20 plan starts. To stop before that, cancel in the billing portal. ## Comparison with boat.dev These terms come from boat.dev in November 2026. | Term | VMS | boat.dev | | - | - | - | | `small` each hour | \$0.017 | \$0.018 | | `xlarge` each hour | \$0.136 | \$0.200 | | Billing starts | When the sandbox is `running` | When a machine is assigned | | Plan fee | Comes back as credit, carries over one month | Comes back as time, does not carry over | | Sandboxes at a time on the \$20 plan | 150 | 100 | | Starts each minute on the \$20 plan | 40, at no cost | 12, extra starts cost money | | `xlarge` | On each plan | Needs the \$100 plan | | Team members | Free | Each seat pays the plan price | | Trial | 14 days, 60 unit-hours, 3 sandboxes | 7 days, 25 hours, 2 sandboxes | | Top-ups | From $5, bonus from $100, up to 27% | From $15, bonus from $200, up to 25% | | Automatic top-up | From \$5, also in the trial | From \$15, not in the trial | | Empty balance | 48 hours of grace, debt to 50% of the plan or \$100 | 24 hours of grace, debt to 25% of the plan or \$50 | | Saved snapshots on the \$20 plan | 20 | 10 | | Templates on the \$20 plan | 20, with no expiry date | Counted as saved snapshots | | Each extra snapshot or template each day | \$0.04 | \$0.056 | | Stopped data | 30 days | 14 days | See the [plans reference](/docs/reference/plans) for each value. Read the [changelog.](/docs/changelog) # Workspaces, members, and API keys Source: https://vms.dev/docs/explanation/workspaces How a workspace holds its members, their roles, and its API keys. A workspace holds the data of one team. Each person and each program gets access to a workspace in a different way. Explain workspace access. Explain how people and programs get access to a workspace. Use the workspace access reference for exact permissions. ## People are members A person signs in to their own account. The account can be a member of more than one workspace. The workspace menu in the rail changes between them. Each membership has one role: owner, admin, or member. The role sets what the person can do in that workspace only. A person can be an owner in one workspace and a member in a different workspace. A person becomes a member when they create a workspace or when they accept an invitation. An invitation is for one email address, so that only that person can accept it. ## Programs use API keys An API key belongs to the workspace, not to the person who created it. If that person leaves the workspace, the key continues to work. A key does not get the permissions of a role. It gets only the scopes that you give it, and you can give only the scopes that your role has. This keeps each key to the smallest access that its program needs. Only a hash of the key is stored. Nobody can read the key after you copy it. To change the scopes of a key, create a new key, then revoke the old key. ## Settings for each person and for the workspace Some settings belong to the workspace, such as its name and its default language. Owners and admins change them. Other settings belong to the person, such as their name, their avatar, and their language. A personal language replaces the default language of the workspace for that person. See [workspace access](/docs/reference/workspace-access) for the exact permissions. Read the [changelog.](/docs/changelog) # How-to guides Source: https://vms.dev/docs/guides Find the guide for a workspace or account task. Each guide solves one task. Use the [reference](/docs/reference/navigation) for exact facts. Find a guide for my task. Ask what I want to do. Link me to the one guide that does that task. ## Sandboxes > [card] [Create, get, and delete a sandbox](/docs/sandboxes/create-and-delete) > > Create a sandbox with the API, wait until it runs, and delete it. > [card] [Run eve agents in sandboxes](/docs/sandboxes/eve) > > Give each session of an eve agent its own sandbox. ## Workspace > [card] [Change the workspace settings](/docs/workspace/settings) > > Change the name, the URL, or the default language. Delete the workspace. > [card] [Add and remove members](/docs/workspace/members) > > Invite people, change roles, and remove members. > [card] [Create and revoke API keys](/docs/workspace/api-keys) > > Give a program access to the workspace. > [card] [Choose a plan, and see invoices and payments](/docs/workspace/billing) > > Pay for the workspace, download invoices, and change the plan or the card. ## Integrations > [card] [Connect an MCP client](/docs/install-mcp) > > Let an AI assistant read your workspaces. > [card] [Register an agent with auth.md](/docs/api-reference/agent-registration) > > Let an agent register for a user and get a token. ## Your account > [card] [Sign in and sign out](/docs/account/sign-in) > > Sign in with an email link. > [card] [Change your profile](/docs/account/profile) > > Change your name, avatar, language, time zone, and theme. > [card] [Connect an AI agent with a code](/docs/account/connect-agent) > > Enter the code from an agent, and disconnect it later. Read the [changelog.](/docs/changelog) # Introduction Source: https://vms.dev/docs/index Set up a workspace, connect an AI agent, complete a task, or find a reference. Use these docs to learn a task, complete your work, or understand a concept. Find the right guide. Ask what I want to do and whether I have a workspace. Choose a tutorial for a first task, or a how-to guide for a specific task. Link to reference details or an explanation only when I need them. ![The Acme Inc workspace with the left rail, the VMS sidebar, and the empty Overview page.](https://mintcdn.com/vms-c6f4e5ac/ik-PVuE4l6A-0My2/images/get-started/introduction/00-app-light.png?fit=max\&auto=format\&n=ik-PVuE4l6A-0My2\&q=85\&s=0258737b020df228c93deb7b650247ea) ## Parts of the app The [navigation reference](/docs/reference/navigation) lists each area and menu. ## Get started > [card] [Set up your first workspace](/docs/quickstart) > > Follow a tutorial from sign-in to your first invitation. > [card] [Connect an MCP client](/docs/install-mcp) > > Let an AI assistant read your workspaces. > [card] [Give your agent a skill](/docs/agent-skills) > > Let an AI agent sign up for you with one URL. > [card] [Complete a task](/docs/guides) > > Find a how-to guide for your work. > [card] [Make your first API request](/docs/api-reference/first-request) > > Create an API key and read your workspace. > [card] [Understand workspaces](/docs/explanation/workspaces) > > Learn how workspaces, members, roles, and API keys relate. Read the [changelog.](/docs/changelog) # Connect an MCP client Source: https://vms.dev/docs/install-mcp Connect Claude, Cursor, Visual Studio Code, or another MCP client to your workspaces, and use its tools. Connect an MCP client so that an AI assistant can read your workspaces with your account. Connect this client to the VMS MCP server. Add the VMS MCP server to this client and help me sign in. Call list_organizations and ask which workspace to use. Call get_workspace for that workspace and summarize it. Do not change anything. ## Before you start * You need an account and membership in the workspace that you want to use. * Your client must support remote MCP with OAuth. See [other clients](/docs/reference/workspace-mcp#other-clients). * The MCP server URL is `https://vms.dev/api/mcp`. The client opens sign-in in your browser. You approve its access there. Do not paste a password or an API key into the client. An agent that cannot open a browser can [register with auth.md](/docs/api-reference/agent-registration) instead. ## Connect a client > [tab] Claude > > **1. Add the connector** > > In Claude, open **Settings**, then **Connectors**, and choose **Add custom connector**. > > **2. Enter the server** > > Name it `VMS` and enter the MCP endpoint as the URL. Leave the OAuth fields empty. > > **3. Sign in and allow access** > > Choose **Connect**. In the browser, sign in, read the access that the client asks for, and choose **Allow**. > > ![The consent screen where claude.ai asks for access to your account, with the list of what it can do as you and the Deny and Allow buttons.](https://mintcdn.com/vms-c6f4e5ac/ik-PVuE4l6A-0My2/images/get-started/mcp/01-allow-access-light.png?fit=max\&auto=format\&n=ik-PVuE4l6A-0My2\&q=85\&s=7334c7550f124c314c960833564a4aa0) > [tab] Claude Code > > Add the server: > > ```bash theme={null} > claude mcp add --transport http vms https://vms.dev/api/mcp > ``` > > Then run `/mcp`, choose `vms`, and sign in in the browser. > [tab] Cursor > > Add the server to `.cursor/mcp.json` in your project: > > ```json theme={null} > { > "mcpServers": { > "vms": { "url": "https://vms.dev/api/mcp" } > } > } > ``` > > Cursor asks you to sign in the first time. > [tab] Visual Studio Code > > Add the server to `.vscode/mcp.json` in your project: > > ```json theme={null} > { > "servers": { > "vms": { "type": "http", "url": "https://vms.dev/api/mcp" } > } > } > ``` > > Start the server from the file. Visual Studio Code asks you to sign in the first time. ## Check the connection 1. Ask the client to call `list_organizations`. 2. Choose a workspace from the result. Use its slug as the `organization` value in later tool calls. 3. Ask the client to call `get_workspace` for that workspace. These calls do not change workspace data. ## Disconnect a client Remove the server in the client. The access token expires after 15 minutes. If you allowed **Stay connected when you are not using the app**, the client can get a new token until you remove it. Read the [changelog.](/docs/changelog) # Email us Source: https://vms.dev/docs/links/email # llms.txt Source: https://vms.dev/docs/links/llms # llms-full.txt Source: https://vms.dev/docs/links/llms-full # Set up your first workspace Source: https://vms.dev/docs/quickstart Sign in, create a workspace, and invite a member. In this tutorial, you sign in, create a workspace named Acme, and invite a member. Guide me through the first workspace. Guide me from sign-in to my first invitation. Explain what each step does in one sentence. Do not ask for my email inbox or my sign-in link. ## Before you start You need a work email address that you can open. **1. Sign in** Type your **Work email**, then choose **Email me a sign-in link**. Open the email and choose the link. ![The Sign in to VMS form with the Work email field and the Email me a sign-in link button.](https://mintcdn.com/vms-c6f4e5ac/jQnI_Fj6Glye5aBP/images/account/sign-in/00-sign-in-light.png?fit=max\&auto=format\&n=jQnI_Fj6Glye5aBP\&q=85\&s=3427715fa2cad66090aea44fb504a323) **2. Create the workspace** In **Create a workspace**, type your **First name** and **Last name**, the **Workspace name**, and the **Company website**. The **URL** fills in from the name. Choose a **Default language**, then choose **Create the workspace**. The workspace opens on its **Overview** page. ![The new Acme Inc workspace on its Overview page, with the left rail and the VMS sidebar.](https://mintcdn.com/vms-c6f4e5ac/ik-PVuE4l6A-0My2/images/get-started/introduction/00-app-light.png?fit=max\&auto=format\&n=ik-PVuE4l6A-0My2\&q=85\&s=0258737b020df228c93deb7b650247ea) **3. Invite a member** In the rail, choose **Settings**, then **Members**. Choose **Invite member**, type the **First name**, the **Last name**, and the **Email**, choose a **Role**, and choose **Send invitation**. ![The Invite member sheet with the First name, Last name, and Email fields, the Role select set to Member, and the Send invitation button.](https://mintcdn.com/vms-c6f4e5ac/ik-PVuE4l6A-0My2/images/workspace/members/01-invite-member-light.png?fit=max\&auto=format\&n=ik-PVuE4l6A-0My2\&q=85\&s=23e0e2f6d62b3c65d528bf677e054e98) ## Check the result The **Members** table shows you as **Owner** and the invited person as **Member**. The invited person gets an email with a link that expires in 7 days. ## Next steps * [Change the workspace settings](/docs/workspace/settings). * [Create an API key](/docs/workspace/api-keys). * [Change your profile](/docs/account/profile). Read the [changelog.](/docs/changelog) # Agent registration reference Source: https://vms.dev/docs/reference/agent-registration The auth.md endpoints, registration methods, tokens, limits, errors, and revocation. This reference gives the facts of agent registration. It follows the [auth.md protocol](https://github.com/workos/auth.md). For the steps, see [Register an agent](/docs/api-reference/agent-registration). For the reasons behind the design, see [How agents get access](/docs/explanation/agent-access). Check a fact about agent registration. Ask which endpoint, method, limit, or error I want to check. Give me its facts from this reference. ## Discovery | Document | URL | | - | - | | Agent instructions | `https://vms.dev/auth.md` | | Protected Resource Metadata | `https://vms.dev/.well-known/oauth-protected-resource/api/mcp` | | Authorization Server metadata | `https://vms.dev/api/auth/.well-known/oauth-authorization-server` and `https://vms.dev/.well-known/oauth-authorization-server/api/auth` | The Authorization Server metadata has an `agent_auth` block with the endpoints, the methods, and `identity_assertion.trusted_issuers`. ## Endpoints | Endpoint | Method | Use | | - | - | - | | `/api/auth/agent/identity` | `POST` | Register. Send `type`. | | `/api/auth/agent/identity/claim` | `POST` | Start a claim, or get a new code. Send `claim_token` and `email`. | | `/api/auth/oauth2/token` | `POST` | Exchange an assertion (`urn:ietf:params:oauth:grant-type:jwt-bearer`), or poll a claim (`urn:workos:agent-auth:grant-type:claim`). | | `/api/auth/oauth2/revoke` | `POST` | Revoke one access token. | | `/api/auth/agent/event/notify` | `POST` | Agent providers send revocation events (`application/secevent+jwt`). | ## Registration methods All three methods are on. | Method (`type`) | Body | Result | Claim | | - | - | - | - | | `identity_assertion` | `assertion_type: "urn:ietf:params:oauth:token-type:id-jag"`, `assertion` | An identity assertion at once. If the email has an account that is not linked to the provider, `401 interaction_required` with a claim. | Only to link an existing account | | `service_auth` | `login_hint`: the email of the user | A claim. No credential before the claim. | Necessary | | `anonymous` | none | An identity assertion at once, for an agent with no workspaces | Optional | ## ID-JAG rules | Rule | Value | | - | - | | Issuer | Must be on the trust list, `agent_auth.identity_assertion.trusted_issuers` in the Authorization Server metadata. The keys come from `/.well-known/jwks.json`. | | JOSE `typ` | `oauth-id-jag+jwt` | | `aud` | `https://vms.dev/api/mcp` | | Identity | `email` with `email_verified: true` | | Lifetime | `exp` no more than 10 minutes after `iat` | | `auth_time` | Necessary. No more than 1 hour old, else `401 login_required` with `max_age: 3600`. | | `jti` | Used one time only | A new verified email gets a new account. A known `(iss, sub)` pair gets the account that it is linked to. ## Tokens and limits | Item | Value | | - | - | | Scopes of each registration | `organization:read`, `workspace:read`. Pre-claim and post-claim scopes are the same. | | Access token | A JWT for `https://vms.dev/api/mcp`. Works for 15 minutes. | | Identity assertion | Works for 7 days. Exchange it again for each new access token. There is no refresh token. | | User code | 6 digits. Works for 10 minutes. 5 wrong codes stop it. | | Claim window | 24 hours from registration. An anonymous registration that is not claimed in this window stops working. | | Poll interval | 5 seconds. A faster poll gets `slow_down`. | | Rate limit | 30 requests in one minute for each agent endpoint | A claim gives new tokens and makes the tokens from before the claim stop working. ## Revocation | Layer | Who | Effect | | - | - | - | | One access token | The agent, at `/api/auth/oauth2/revoke` | That token stops. The assertion still works. | | Registration | The agent provider, with a security event | Each registration for the `(iss, sub)` pair stops. `/oauth2/token` returns `invalid_grant`. | | Registration | The user, with **Disconnect** on [Profile](/docs/account/connect-agent#see-and-disconnect-your-agents) | The registration stops, and the link to the provider is removed. | The security event must have the event `https://schemas.workos.com/events/agent/auth/identity/assertion/revoked` with a subject `{ "format": "iss_sub", "iss", "sub" }`. A provider can revoke only its own subjects. ## Errors | Code | Status | Where | | - | - | - | | `invalid_request` | 400 | Identity and claim endpoints | | `issuer_not_enabled` | 400 | Identity endpoint | | `interaction_required` | 401 | Identity endpoint (ID-JAG for an existing account) | | `login_required` | 401 | Identity endpoint (old `auth_time`) | | `invalid_claim_token` | 400 | Claim endpoint | | `claimed_or_in_flight` | 409 | Claim endpoint | | `claim_expired` | 410 | Claim endpoint | | `invalid_grant`, `invalid_target`, `unsupported_grant_type`, `authorization_pending`, `slow_down`, `expired_token` | 400 | Token endpoint | Read the [changelog.](/docs/changelog) # CLI reference Source: https://vms.dev/docs/reference/cli Install the vms command line tool, sign in with your browser or an API key, and use each command: new, ls, ssh, exec, cp, stop, resume, rm, url, fork, template, snapshot, and desktop. `vms` creates and uses sandboxes from your terminal. It is one file with no dependencies, for macOS on Apple silicon, macOS on Intel, and Linux on x86-64. ## Install ### With Homebrew On macOS or Linux: ```bash theme={null} brew install vms-dev-org/tap/vms vms --version ``` To get a new version, run `brew upgrade vms`. ### Download the file Download the file for your computer from the [latest release](https://github.com/vms-dev-org/cli/releases/latest), with `SHA256SUMS`: | Computer | File | | - | - | | macOS, Apple silicon | `vms-darwin-arm64` | | macOS, Intel | `vms-darwin-x64` | | Linux, x86-64 | `vms-linux-x64` | Check the file. Then rename it to `vms`, make it executable, and move it to a folder in your `PATH`: ```bash theme={null} shasum -a 256 -c SHA256SUMS --ignore-missing mv vms-darwin-arm64 vms chmod +x vms sudo mv vms /usr/local/bin/ vms --version ``` The macOS files are not notarized. If you download the file with a browser, remove the quarantine attribute before you run it. If you do not, macOS can refuse to open it: ```bash theme={null} xattr -d com.apple.quarantine /usr/local/bin/vms ``` `vms ssh` needs OpenSSH. `vms cp -r` from a sandbox needs `tar`. macOS and most Linux systems have both. ## Sign in ### With your browser ```bash theme={null} vms login ``` 1. The CLI shows a code and a link, and opens the link in your browser. 2. Sign in, if you are not signed in. 3. Check that the page shows the same code as your terminal. Choose **Approve**. The CLI then makes an API key for one workspace and saves it. If you are a member of more than one workspace, give the workspace: ```bash theme={null} vms login --workspace acme ``` * You need the **Owner** or **Admin** role in the workspace. A member can sign in with an API key from an owner or an admin. * The key has the scopes `workspace:read`, `sandboxes:read`, `sandboxes:write`, `sandboxes:exec`, `sandboxes:files`, `sandboxes:ssh`, `sandboxes:desktop`, `snapshots:read`, `templates:read`, and `templates:write`. It gets only the scopes that your role permits. It expires after 90 days. * The key has the name `vms CLI on `. You can see it and revoke it in **Settings**, then **API keys**. See [API keys](/docs/workspace/api-keys). * The code expires after 10 minutes. On a computer without a browser, open the link on a different computer. * The CLI saves the key in `~/.config/vms/config.json`, which only your user can read. It does not save your password or your sign-in session. ### With an API key Send the key on stdin, so that it does not go into your shell history: ```bash theme={null} vms login --with-api-key < key.txt ``` Or set `VMS_API_KEY`. Each command uses it before the saved key: ```bash theme={null} export VMS_API_KEY="" vms ls ``` The key needs the scopes of the commands that you use. See [Scopes for each command](#scopes-for-each-command). ### Sign out ```bash theme={null} vms logout ``` `vms logout` revokes the key that `vms login` made with the browser, and removes the saved key. It does not revoke a key that you gave with `--with-api-key` or `VMS_API_KEY`. ## Commands Give a sandbox by its name or by its ID, such as `agent-42` or `sbx_06d8k3m7q2v9x4b1n5c0e8f2ja`. Run `vms --help` to see the options of a command. ### new ```bash theme={null} vms new agent-42 --size medium --label team=search --stop-after 2h ``` Creates a sandbox and waits until it is `running`. It writes the sandbox ID to stdout. | Option | Value | | - | - | | `--size ` | `small`, `medium`, `large`, or `xlarge`. The default is `small`. | | `--template