TypeScript SDK

Reference for fastvm. Auto-generated from the OpenAPI spec.

Install

shell

npm install fastvm

Import

typescript

import { FastvmClient } from 'fastvm';

const client = new FastvmClient(); // reads FASTVM_API_KEY / FASTVM_BASE_URL

Top-level helpers

client.*

client.health

GET/healthz

client.health(): APIPromise<HealthResponse>

Description

Health check

Returns

client.uploadhelper

client.upload(
  vmId: string,
  localPath: string,
  remotePath: string,
  opts?: { fetchTimeoutSec?: number; execTimeoutSec?: number },
): Promise<void>

Description

Copy a local file or directory into the VM. Uses vms.files.presign and vms.files.fetch under the hood. Directories are tarred on the fly before upload and extracted VM-side after fetch.

Streams end-to-end with no intermediate copy to /tmp on the client, so multi-GB transfers are bounded by VM disk, not RAM. Directory mode needs the tar binary on the client's PATH (standard on macOS and Linux; available on modern Windows via bsdtar).

Parameters

Param	Type	Default	Description
vmId	string	required	Target VM id.
localPath	string	required	Local file or directory path.
remotePath	string	required	Destination path inside the VM.
opts.fetchTimeoutSec	number	600	Timeout on the VM-side /files/fetch call.
opts.execTimeoutSec	number	600	Timeout on VM-side tar extraction.

Returns

Promise<void>

Example

typescript

await client.upload(vm.id, './config.toml', '/etc/app.toml');
await client.upload(vm.id, './src', '/root/src');

client.downloadhelper

client.download(
  vmId: string,
  remotePath: string,
  localPath: string,
  opts?: { fetchTimeoutSec?: number; execTimeoutSec?: number },
): Promise<void>

Description

Copy a file or directory from the VM to the client. Uses vms.files.presign plus a VM-side exec to classify the path and stream its contents out. Directories are tarred VM-side and un-tarred on the client, rooted at ./ so upload and download are symmetric.

Streams end-to-end with no intermediate copy. Missing paths raise FileNotFoundError (Python) or FileTransferError with code: 'ENOENT' (TypeScript).

Parameters

Param	Type	Default	Description
vmId	string	required	Target VM id.
remotePath	string	required	Source path inside the VM.
localPath	string	required	Destination path on the client.
opts.fetchTimeoutSec	number	600	Timeout on VM-side /files/fetch.
opts.execTimeoutSec	number	600	Timeout on VM-side exec.

Returns

Promise<void>

Example

typescript

await client.download(vm.id, '/root/out.log', './out.log');
await client.download(vm.id, '/var/log', './log-backup');

client.waitForVmReadyhelper

client.waitForVmReady(
  vmId: string,
  opts?: { pollIntervalMs?: number; timeoutMs?: number },
): Promise<VM>

Description

Poll GET /v1/vms/{id} until the VM reaches status == "running" or a terminal failure status. Same polling logic as vms.launch; use this when you already have a VM id from vms.list() or another flow.

Parameters

Param	Type	Default	Description
vmId	string	required	Target VM id.
opts.pollIntervalMs	number	2000	Milliseconds between polls.
opts.timeoutMs	number	300000	Total wait deadline in ms.

Returns

Promise<>

Example

typescript

let vm = await client.vms.retrieve(someId);
vm = await client.waitForVmReady(vm.id, { timeoutMs:  });

VMs

client.vms.*

client.vms.list

GET/v1/vms

client.vms.list(): APIPromise<VM[]>

Description

List VMs

Returns

[]

client.vms.launchoverride

POST/v1/vms

client.vms.launch(
  params: VmLaunchParams,
  options?: RequestOptions,
  launchOpts?: { wait?: boolean; pollIntervalMs?: number; timeoutMs?: number },
): APIPromise<VM>

Description

Launch a VM and (by default) block until it reaches status == "running". POST /v1/vms returns 201 for immediately-running VMs and 202 for queued VMs; the override handles both paths transparently by polling GET /v1/vms/{id}.

Pass wait=false (TS) / wait=False (Python) to skip polling and return the raw 201/202 body. Pass snapshot_id / snapshotId to restore from a snapshot instead of cold-booting.

Terminal failure statuses (error, stopped, deleting) raise VMLaunchError. Polling-deadline exceeded raises VMNotReadyError.

Parameters

Param	Type	Default	Description
params	VmLaunchParams	required	Generated launch params (machineType, snapshotId, name, metadata, firewall).
options	RequestOptions \| undefined	undefined	Generated per-request options (headers, signal, timeout, etc.).
launchOpts.wait	boolean	true	Block until RUNNING. Set false for raw 201/202 behavior.
launchOpts.pollIntervalMs	number	2000	Milliseconds between polls (±10% jitter applied).
launchOpts.timeoutMs	number	300000	Total polling deadline in ms. Throws VMNotReadyError on exceed.

Returns

APIPromise<>

Example

typescript

import { FastvmClient } from 'fastvm';

const client = new FastvmClient();
const vm = await client.vms.launch({ machineType: 'c1m2', name: 'dev' });
console.log(vm.id, vm.status); // "running"

// Restore from snapshot
const fromSnap = await client.vms.launch({ snapshotId: 'snp_...' });

// Skip polling — returns the raw 201/202 body
const queued = await client.vms.launch(
  { machineType: 'c1m2' },
  undefined,
  { wait: false },
);

client.vms.retrieve

GET/v1/vms/{id}

client.vms.retrieve(
  id: string,
): APIPromise<VM>

Description

Get a VM

Parameters

Param	Type	Default	Description
id	string	required	VM ID (UUID).

Returns

client.vms.update

PATCH/v1/vms/{id}

client.vms.update(
  id: string,
  name: string,
  metadata: Metadata,
): APIPromise<VM>

Description

Update a VM

Parameters

Param	Type	Default	Description
id	string	required	VM ID (UUID).
name	string	—
metadata	Metadata	—

Returns

client.vms.delete

DELETE/v1/vms/{id}

client.vms.delete(
  id: string,
): APIPromise<DeleteResponse>

Description

Delete a VM

Parameters

Param	Type	Default	Description
id	string	required	VM ID (UUID).

Returns

client.vms.setFirewall

PUT/v1/vms/{id}/firewall

client.vms.setFirewall(
  id: string,
  mode: FirewallMode,
  ingress: FirewallRule[],
): APIPromise<VM>

Description

Replace firewall policy

Parameters

Param	Type	Default	Description
id	string	required	VM ID (UUID).
mode	FirewallMode	required
ingress	FirewallRule[]	—

Returns

client.vms.patchFirewall

PATCH/v1/vms/{id}/firewall

client.vms.patchFirewall(
  id: string,
  mode: FirewallMode,
  ingress: FirewallRule[],
): APIPromise<VM>

Description

Patch firewall policy

Parameters

Param	Type	Default	Description
id	string	required	VM ID (UUID).
mode	FirewallMode	—
ingress	FirewallRule[]	—

Returns

client.vms.consoleToken

POST/v1/vms/{id}/console-token

client.vms.consoleToken(
  id: string,
): APIPromise<ConsoleTokenResponse>

Description

Mint a console token

Parameters

Param	Type	Default	Description
id	string	required	VM ID (UUID).

Returns

client.vms.runrefresh

POST/v1/vms/{id}/exec

client.vms.run(
  id: string,
  params: VmRunParams,
  options?: RequestOptions,
): APIPromise<ExecVMResponse>

Description

Execute a command inside a VM. Same generated method as upstream. TypeScript doesn't silently iterate strings into characters, so no shell-string auto-wrap helper is needed. Pass an argv array directly.

Parameters

Param	Type	Default	Description
id	string	required	Target VM id.
params	VmRunParams	required	Request body (command: string[], timeoutSec?: number).
options	RequestOptions \| undefined	undefined	Generated per-request options.

Returns

APIPromise<>

Example

typescript

const result = await client.vms.run(vm.id, {
  command: ['python3', 'main.py', '--flag'],
});
console.log(result.exitCode, result.stdout);

VMs.Files

client.vms.files.*

client.vms.files.presign

POST/v1/vms/{id}/files/presign

client.vms.files.presign(
  id: string,
  path: string,
): APIPromise<FilePresignResponse>

Description

Mint signed URLs for uploading a file to a VM

Parameters

Param	Type	Default	Description
id	string	required	VM ID (UUID).
path	string	required	Absolute destination path inside the guest filesystem (where the file will land after `fetchFileToVm`). Used only to scope the staging object key; any value server-side is accepted here.

Returns

Example

typescript

// High-level helpers — handle presign + PUT/GET + fetch + (for dirs) tar
// for both file and directory transfers automatically.
await client.upload(vm.id, './local/file.txt', '/root/file.txt');
await client.upload(vm.id, './local-dir', '/root/remote-dir');

await client.download(vm.id, '/root/out.log', './out.log');
await client.download(vm.id, '/var/log', './log-backup');

// Raw call if you need manual control over the signed-URL flow:
const presign = await client.vms.files.presign(vm.id, { path: '/root/file.txt' });

client.vms.files.fetch

POST/v1/vms/{id}/files/fetch

client.vms.files.fetch(
  id: string,
  url: string,
  path: string,
  timeoutSec: number,
): APIPromise<ExecVMResponse>

Description

Fetch a file into a VM from a presigned URL

Parameters

Param	Type	Default	Description
id	string	required	VM ID (UUID).
url	string	required	Must be the `downloadUrl` previously returned by `POST /v1/vms/{id}/files/presign` (URLs from other sources are rejected).
path	string	required	Absolute destination path inside the guest filesystem.
timeoutSec	number	—	Per-fetch timeout in seconds.

Returns

Example

typescript

// You usually don't call this directly — client.upload() composes
// presign + PUT + fetch in a single call. Use it when piping an
// already-hosted URL (still from /files/presign) into the VM.
await client.vms.files.fetch(vm.id, {
  url: presign.downloadUrl,
  path: '/root/file.txt',
});

Snapshots

client.snapshots.*

client.snapshots.list

GET/v1/snapshots

client.snapshots.list(): APIPromise<Snapshot[]>

Description

List snapshots

Returns

[]

client.snapshots.create

POST/v1/snapshots

client.snapshots.create(
  vmId: string,
  name: string,
): APIPromise<Snapshot>

Description

Create a snapshot

Parameters

Param	Type	Default	Description
vmId	string	required
name	string	—	Snapshot name (trimmed + whitespace-collapsed, max 64 runes; longer values are truncated server-side). Auto-generated as `snapshot-<8-char-vmId-prefix>` if empty.

Returns

client.snapshots.retrieve

GET/v1/snapshots/{id}

client.snapshots.retrieve(
  id: string,
): APIPromise<Snapshot>

Description

Get a snapshot

Parameters

Param	Type	Default	Description
id	string	required	Snapshot ID (UUID).

Returns

client.snapshots.update

PATCH/v1/snapshots/{id}

client.snapshots.update(
  id: string,
  name: string,
): APIPromise<Snapshot>

Description

Rename a snapshot

Parameters

Param	Type	Default	Description
id	string	required	Snapshot ID (UUID).
name	string	—

Returns

client.snapshots.delete

DELETE/v1/snapshots/{id}

client.snapshots.delete(
  id: string,
): APIPromise<DeleteResponse>

Description

Delete a snapshot

Parameters

Param	Type	Default	Description
id	string	required	Snapshot ID (UUID).

Returns

Builds

client.builds.*

client.builds.create

POST/v1/builds

client.builds.create(
  name: string,
  imageRef: string,
  dockerfileContent: string,
  machineType: MachineType,
  diskGiB: number,
  contextDownloadUrl: string,
): APIPromise<BuildResponse>

Description

Build a snapshot from an image ref or Dockerfile

Parameters

Param	Type	Default	Description
name	string	—	Optional human-readable name for the resulting snapshot. If omitted, the build ID is used.
imageRef	string	—	Docker image reference (e.g. `python:3.13-slim`, `ghcr.io/user/repo:tag`). Used directly on the no-Dockerfile path, and as a fallback `FROM` source otherwise.
dockerfileContent	string	—	Raw Dockerfile content to feed to `buildah bud` inside the build VM. Multi-stage, `SHELL`, `RUN --mount`, and every standard Dockerfile feature is supported (handled natively by buildah). Container-runtime metadata (`CMD`, `ENTRYPOINT`, `EXPOSE`, `LABEL`, `HEALTHCHECK`) is consumed by buildah but does not surface on the resulting FastVM snapshot — when the snapshot boots, systemd takes over, not the container's CMD.
machineType	MachineType	—
diskGiB	number	—	Disk size for the build VM. Defaults to 10 GiB if omitted.
contextDownloadUrl	string	—	Presigned GET URL for a `tar.gz` of the build context. The worker downloads and extracts this into `/tmp/buildctx` before invoking buildah, so `COPY` instructions resolve against the user's files. Obtain via `POST /v1/build-contexts/presign`.

Returns

Example

typescript

// Raw call (returns 202 immediately; poll for completion).
const build = await client.builds.create({
  imageRef: 'python:3.13-slim',
  dockerfileContent: 'FROM python:3.13-slim\nRUN pip install flask\n',
});

client.builds.retrieve

GET/v1/builds/{id}

client.builds.retrieve(
  id: string,
): APIPromise<BuildResponse>

Description

Get build status

Parameters

Param	Type	Default	Description
id	string	required	Build ID (UUID).

Returns

Build_contexts

client.build_contexts.*

client.build_contexts.presign

POST/v1/build-contexts/presign

client.build_contexts.presign(): APIPromise<FilePresignResponse>

Description

Mint signed URLs for uploading a build context tarball

Returns

Quotas

client.quotas.*

client.quotas.retrieve

GET/v1/org/quotas

client.quotas.retrieve(): APIPromise<OrgQuotaUsage>

Description

Get org quotas and usage

Returns

Types

Shared schemas referenced in parameters and return values.

DeleteResponse

object

Field	Type	Description
id	string
deleted	boolean

VMStatus

primitive

Lifecycle status. Known values: provisioning, running, stopped, deleting, error. Terminal failure statuses are error and stopped; any other non-running value indicates the VM is still transitioning. Additional values may be introduced in future server versions; clients should treat unknown values as "in transition" rather than as hard errors.

SnapshotStatus

primitive

Snapshot lifecycle status. Known values: creating, ready, error. Additional values may be introduced in future server versions.

MachineType

primitive

Machine size identifier (e.g. c1m2, c2m4). Controls CPU and memory allocation. Must be supplied on launch unless restoring from a snapshot.

VM

object

Field	Type	Description
id	string
name	string
orgId	string
machineName	string
sourceName	string	Source snapshot or image name (empty on fresh boot).
firewall	FirewallPolicy
metadata	Metadata
portMappings	PortMappings
publicIpv6	string
cpu	number
memoryMiB	number
diskGiB	number
status	VMStatus
createdAt	string
deletedAt	unknown

Snapshot

object

Field	Type	Description
id	string
name	string
orgId	string
vmId	string
firewall	FirewallPolicy
metadata	Metadata
status	SnapshotStatus
createdAt	string

FirewallMode

primitive

Firewall mode. Known values: open (allow all inbound traffic), restricted (deny by default; only rules listed in ingress are allowed). Additional values may be introduced in future server versions.

FirewallRule

object

Field	Type	Description
protocol	string	IP protocol. Known values: `tcp`, `udp`. Additional values may be introduced in future server versions.
portStart	number	Start of port range (inclusive). Required.
portEnd	number	End of port range (inclusive). Omit for single-port rules.
sourceCidrs	string[]	Allowed source CIDRs in IPv6 notation (e.g. `2001:db8::/32`). Omit or empty to allow any source. IPv4 CIDRs are rejected.
description	string

FirewallPolicy

object

Field	Type	Description
mode	FirewallMode
ingress	FirewallRule[]

PortMappings

object

Map of <service-name> → TCP port exposed by the VM's guest. Service names must be RFC 1123 DNS labels (lowercase alphanumerics + dash, no leading/trailing dash, ≤32 chars) — they become DNS subdomain components in <service>.<vm-id>.proxy.fastvm.org. Maximum 64 entries per VM.

BuildResponse

object

Build state snapshot. Returned by POST /v1/builds (initial pending state) and GET /v1/builds/{id} (current state on each poll).

Field	Type	Description
id	string	Build ID (UUID). Use this to poll status.
name	string
status	string	Current state. Known values: `pending` (accepted, not yet started), `running` (worker is executing), `completed` (snapshot is ready), `failed` (build did not produce a snapshot). Additional values may be introduced in future server versions; clients should treat unknown values as "in progress" rather than as hard errors.
snapshotId	string	Set when `status` is `completed`. Fetch the corresponding Snapshot record via `GET /v1/snapshots/{id}`.
imageRef	string
progress	string	Human-readable phase string while the build runs (e.g. `creating build VM`, `buildah pull`, `buildah bud`, `applying image`, `settling VM`, `creating snapshot`). Not present after a terminal status.
error	string	Set when `status` is `failed`. Diagnostic from the worker (truncated to ~4 KiB).
createdAt	string

Metadata

object

Free-form string→string map. Server-enforced limits: up to 256 keys, key length 1–256 bytes, value length ≤4096 bytes, total JSON encoding ≤65536 bytes.

ExecVMResponse

object

Buffered response shape for POST /v1/vms/{id}/exec under Accept: application/json. The server collects the streamed events and returns this aggregate once the command exits. Per-stream output is capped at 4 MiB; overflow bytes are dropped and signalled via stdoutTruncated / stderrTruncated. Streaming clients (Accept: application/x-ndjson) receive every byte without a cap.

Field	Type	Description
exitCode	number
stdout	string
stderr	string
timedOut	boolean
stdoutTruncated	boolean	True if the collector dropped stdout bytes past the 4 MiB cap.
stderrTruncated	boolean	True if the collector dropped stderr bytes past the 4 MiB cap.
durationMs	number

FilePresignResponse

object

Pair of signed URLs scoped to the same per-VM staging object. Usable in either direction: either side (client or VM) PUTs bytes to uploadUrl, and either side GETs them back via downloadUrl. URLs expire after expiresInSec seconds and the staging object is auto-deleted after about a day.

Field	Type	Description
uploadUrl	string	Presigned PUT URL for the staging object. Accepts `Content-Type: application/octet-stream`. Used by the client on upload, or by the VM (via an exec'd `curl -T -`) on download.
downloadUrl	string	Presigned GET URL for the same staging object. Used by the VM (via `POST /v1/vms/{id}/files/fetch`) on upload, or by the client (via `httpx.stream` / `curl`) on download.
expiresInSec	number	Lifetime of both URLs in seconds.
maxUploadBytes	number	Upper bound on upload size (equals the VM's disk size in bytes).

ConsoleTokenResponse

object

Field	Type	Description
token	string
expiresInSec	number
websocketPath	string	Relative WebSocket path; combine with your API host as `wss://<host><websocketPath>?session=<token>`.

OrgQuotaValues

object

Field	Type	Description
vcpu	number
memoryMiB	number
diskGiB	number
snapshotCount	number

OrgQuotaUsage

object

Field	Type	Description
orgId	string
limits	OrgQuotaValues
usage	OrgQuotaValues

HealthResponse

object

Health check

Field	Type	Description
status	string