Install
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 ascreateSandbox 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 absolutepath, 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
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
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
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 aVmsError:
TypeScript
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