Skip to main content
For a first script, see Use a sandbox from TypeScript.

Install

The package is an ES module with its TypeScript types. It runs on Node.js 22 or later and on Bun. The ssh helper also needs OpenSSH.

Client

TypeScript

Methods for the API routes

The client has one method for each route of the API reference. The method name is the operation ID of the route, such as createSandbox for POST /v1/sandboxes. The types come from the OpenAPI document. Each method takes one object: The second argument can have a signal to cancel the request.
TypeScript

Helpers

waitUntilRunning

It throws a SandboxWaitError at the time limit, or when the sandbox is stopped, error, failed, deleting, or deleted. The error has the last sandbox.

exec and attach

command is a string, which runs with bash -lc, or a list of the program and its arguments. The exec options are cwd, env, timeoutSeconds, stdin, and signal. The attach options are after, the last seq that you read, and signal.

writeFiles

Each file has an absolute path, a content as a string or bytes, and an optional mode, such as "0755". A new file gets 0644. The SDK sends the files as one gzip tar to the deepest folder that holds all of them. Send gzip: false to send a tar without gzip. The tar can be up to 128 MiB.

ssh

The sandbox must be running. The user name is the name of the sandbox, or its ID if it has no name. ssh checks the host key of ssh.vms.dev, so you get no prompt to trust the host. When ssh adds a new key, it throws SshError if the first connection fails:

fork

TypeScript
The options are the fields of POST /v1/sandboxes, without fromSandbox and template: such as count, freshSnapshot, name, size, and labels. Also idempotencyKey and signal. fork does not wait until the forks are running. See Fork a sandbox.

saveTemplate and waitUntilTemplateReady

TypeScript
The options are timeoutMs, intervalMs, and signal, as for waitUntilRunning. The default time limit is 30 minutes. They throw a TemplateWaitError at the time limit, or when the template is failed. The error has the last template. See Save a sandbox as a template.

latestSnapshot and readSnapshotFile

TypeScript
latestSnapshot needs the sandboxes:read scope. readSnapshotFile needs snapshots:read. To list a folder, use getSnapshotTree. To stream the whole snapshot as a tar, use downloadSnapshot. See Read the files of a snapshot.

desktop

TypeScript
Open the url in a browser within 10 minutes. The option mode is desktop, the default, or browser to show only the Chrome window. See See the desktop of a sandbox.

Errors

When the API answers with an error, the method throws a VmsError:
TypeScript
See the error codes.

Webhooks

readWebhook(request, secret) checks the signature and the time of a webhook request, and returns the event. It throws a WebhookSignatureError if the signature is not correct or the request is older than 5 minutes. verifyWebhook() and WEBHOOK_HEADERS are also exported.
TypeScript
See Webhook events.