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

vmIdstring

Target VM id.

Default: required

localPathstring

Local file or directory path.

Default: required

remotePathstring

Destination path inside the VM.

Default: required

opts.fetchTimeoutSecnumber

Timeout on the VM-side /files/fetch call.

Default: 600

opts.execTimeoutSecnumber

Timeout on VM-side tar extraction.

Default: 600

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

vmIdstring

Target VM id.

Default: required

remotePathstring

Source path inside the VM.

Default: required

localPathstring

Destination path on the client.

Default: required

opts.fetchTimeoutSecnumber

Timeout on VM-side /files/fetch.

Default: 600

opts.execTimeoutSecnumber

Timeout on VM-side exec.

Default: 600

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

vmIdstring

Target VM id.

Default: required

opts.pollIntervalMsnumber

Milliseconds between polls.

Default: 2000

opts.timeoutMsnumber

Total wait deadline in ms.

Default: 300000

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( status: VMStatus, ): APIPromise<VM[]>

Description

List VMs

Parameters

statusVMStatus

Restrict to VMs with this status. Accepts any value of VMStatus; unknown values return an empty list.

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

paramsVmLaunchParams

Generated launch params (machineType, snapshotId, name, metadata, firewall).

Default: required

optionsRequestOptions | undefined

Generated per-request options (headers, signal, timeout, etc.).

Default: undefined

launchOpts.waitboolean

Block until RUNNING. Set false for raw 201/202 behavior.

Default: true

launchOpts.pollIntervalMsnumber

Milliseconds between polls (±10% jitter applied).

Default: 2000

launchOpts.timeoutMsnumber

Total polling deadline in ms. Throws VMNotReadyError on exceed.

Default: 300000

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

idstring

VM ID (UUID).

Default: required

Returns

client.vms.update

PATCH/v1/vms/{id}

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

Description

Update a VM

Parameters

idstring

VM ID (UUID).

Default: required

namestring

metadataMetadata

ttlunknown

Returns

client.vms.delete

DELETE/v1/vms/{id}

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

Description

Delete a VM

Parameters

idstring

VM ID (UUID).

Default: required

Returns

client.vms.pause

POST/v1/vms/{id}/pause

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

Description

Pause a VM

Parameters

idstring

VM ID (UUID).

Default: required

Returns

client.vms.resume

POST/v1/vms/{id}/resume

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

Description

Resume a paused VM

Parameters

idstring

VM ID (UUID).

Default: required

Returns

client.vms.refreshTtl

POST/v1/vms/{id}/ttl/refresh

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

Description

Reset the VM's TTL cycle

Parameters

idstring

VM ID (UUID).

Default: required

Returns

client.vms.setFirewall

PUT/v1/vms/{id}/firewall

client.vms.setFirewall( id: string, ingress: IngressPolicy, egress: EgressPolicy, dns: DNSPolicy, ): APIPromise<VM>

Description

Replace firewall policy

Parameters

idstring

VM ID (UUID).

Default: required

ingressIngressPolicy

egressEgressPolicy

dnsDNSPolicy

Returns

client.vms.patchFirewall

PATCH/v1/vms/{id}/firewall

client.vms.patchFirewall( id: string, ingress: IngressPolicy, egress: EgressPolicy, dns: DNSPolicy, ): APIPromise<VM>

Description

Patch firewall policy

Parameters

idstring

VM ID (UUID).

Default: required

ingressIngressPolicy

egressEgressPolicy

dnsDNSPolicy

Returns

client.vms.consoleToken

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

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

Description

Mint a console token

Parameters

idstring

VM ID (UUID).

Default: required

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

idstring

Target VM id.

Default: required

paramsVmRunParams

Request body (command: string[], timeoutSec?: number).

Default: required

optionsRequestOptions | undefined

Generated per-request options.

Default: undefined

Returns

APIPromise<>

Example

typescript

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

client.vms.streamhelper

client.vms.stream( id: string, body: VmRunParams, opts?: StreamOptions, ): AsyncIterable<ExecEvent>

Description

Stream exec output as typed events via Accept: application/x-ndjson.

Same endpoint as vms.run (POST /v1/vms/{id}/exec), but the server emits a newline-delimited stream of ExecEvent objects instead of a single buffered JSON response. Events are:

"o" — stdout chunk (decoded bytes in data)
"e" — stderr chunk (decoded bytes in data)
"x" — terminal exit event (exit_code, timed_out, duration_ms)

There is no 4 MiB per-stream cap on output. The HTTP connection stays open until the command exits or timeout_sec fires server-side. Use this for long-running processes (builds, test runners, live logs) where you need incremental output without buffering the entire result.

Shell strings (Python only) are auto-wrapped into ["sh", "-c", ...] exactly like vms.run.

Parameters

idstring

Target VM id.

Default: required

bodyVmRunParams

Request body (command: string[], timeoutSec?: number, stdin?: string).

Default: required

opts.timeoutMsnumber

Client-side HTTP abort deadline in milliseconds.

Default: undefined (no client-side timeout)

Returns

AsyncIterable<>

Example

typescript

import { FastvmClient, type ExecEvent } from 'fastvm';

const client = new FastvmClient();
for await (const event of client.vms.stream(vm.id, { command: ['make', '-j8'] })) {
  if (event.type === 'o') process.stdout.write(event.data);
  else if (event.type === 'e') process.stderr.write(event.data);
  else if (event.type === 'x') console.log(`exit ${event.exitCode} in ${event.durationMs}ms`);
}

VMs.Services

client.vms.services.*

client.vms.services.list

GET/v1/vms/{id}/services

client.vms.services.list( id: string, ): APIPromise<Service[]>

Description

List service registrations

Parameters

idstring

VM ID (UUID).

Default: required

Returns

[]

client.vms.services.register

POST/v1/vms/{id}/services

client.vms.services.register( id: string, name: string, port: number, h2c: boolean, ): APIPromise<Service>

Description

Parameters

idstring

VM ID (UUID).

Default: required

namestring

Default: required

portnumber

Default: required

h2cboolean

Optional. When true, the proxy uses HTTP/2 cleartext to the backend (required for gRPC). Defaults to false (HTTP/1.1).

Default: false

Returns

client.vms.services.update

PUT/v1/vms/{id}/services/{serviceName}

client.vms.services.update( id: string, serviceName: string, port: number, h2c: boolean, ): APIPromise<Service>

Description

Parameters

idstring

VM ID (UUID).

Default: required

serviceNamestring

Service registration name. 1–29 chars, lowercase letters and digits with optional single internal hyphens (no leading, trailing, or consecutive hyphens). Embedded in the public URL as the leftmost label.

Default: required

portnumber

New TCP port. Same value as the existing entry is a no-op.

Default: required

h2cboolean

Optional. When true, the proxy uses HTTP/2 cleartext to the backend. Same value as the existing entry is a no-op; a different value updates the registered transport.

Default: false

Returns

client.vms.services.delete

DELETE/v1/vms/{id}/services/{serviceName}

client.vms.services.delete( id: string, serviceName: string, )

Description

Deregister a service from a VM

Parameters

idstring

VM ID (UUID).

Default: required

serviceNamestring

Default: required

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

idstring

VM ID (UUID).

Default: required

pathstring

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.

Default: required

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

idstring

VM ID (UUID).

Default: required

urlstring

Must be the downloadUrl previously returned by POST /v1/vms/{id}/files/presign (URLs from other sources are rejected).

Default: required

pathstring

Absolute destination path inside the guest filesystem.

Default: required

timeoutSecnumber

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',
});

VMs.Volumes

client.vms.volumes.*

client.vms.volumes.attach

POST/v1/vms/{id}/volumes

client.vms.volumes.attach( id: string, volumeId: string, mountPath: string, readOnly: boolean, ): APIPromise<VolumeAttachmentItem>

Description

Attach a volume to a VM

Parameters

idstring

VM ID (UUID).

Default: required

volumeIdstring

Default: required

mountPathstring

Absolute path; must start with /mnt/ or /data/.

Default: required

readOnlyboolean

Default: false

Returns

client.vms.volumes.detach

DELETE/v1/vms/{id}/volumes/{volumeId}

client.vms.volumes.detach( id: string, volumeId: string, ): APIPromise<DetachVolumeResponse>

Description

Detach a volume from a VM

Parameters

idstring

VM ID (UUID).

Default: required

volumeIdstring

Default: required

Returns

VMs.Bucket_mounts

client.vms.bucket_mounts.*

client.vms.bucket_mounts.list

GET/v1/vms/{id}/bucket-mounts

client.vms.bucket_mounts.list( id: string, ): APIPromise<BucketMount[]>

Description

List bucket-mounts on a VM

Parameters

idstring

VM ID (UUID).

Default: required

Returns

[]

client.vms.bucket_mounts.attach

POST/v1/vms/{id}/bucket-mounts

client.vms.bucket_mounts.attach( id: string, bucketUri: string, mountPath: string, readOnly: boolean, credentials: BucketMountCredentials, ): APIPromise<BucketMount>

Description

Attach a customer GCS / S3 bucket to a VM

Parameters

idstring

VM ID (UUID).

Default: required

bucketUristring

Customer's GCS or S3 bucket URI. gs://<bucket>[/prefix] or s3://<bucket>[/prefix].

Default: required

mountPathstring

Default: required

readOnlyboolean

Default: false

credentialsBucketMountCredentials

Default: required

Returns

client.vms.bucket_mounts.retrieve

GET/v1/vms/{id}/bucket-mounts/{bucketMountId}

client.vms.bucket_mounts.retrieve( id: string, bucketMountId: string, ): APIPromise<BucketMount>

Description

Get a bucket-mount

Parameters

idstring

VM ID (UUID).

Default: required

bucketMountIdstring

BucketMount identifier (e.g. bm_<22-char-lowercase-hex>), unique per VM.

Default: required

Returns

client.vms.bucket_mounts.rotate

PATCH/v1/vms/{id}/bucket-mounts/{bucketMountId}

client.vms.bucket_mounts.rotate( id: string, bucketMountId: string, credentials: BucketMountCredentials, ): APIPromise<BucketMount>

Description

Rotate bucket-mount credentials in-place

Parameters

idstring

VM ID (UUID).

Default: required

bucketMountIdstring

BucketMount identifier (e.g. bm_<22-char-lowercase-hex>), unique per VM.

Default: required

credentialsBucketMountCredentials

Default: required

Returns

client.vms.bucket_mounts.delete

DELETE/v1/vms/{id}/bucket-mounts/{bucketMountId}

client.vms.bucket_mounts.delete( id: string, bucketMountId: string, )

Description

Detach and delete a bucket-mount

Parameters

idstring

VM ID (UUID).

Default: required

bucketMountIdstring

BucketMount identifier (e.g. bm_<22-char-lowercase-hex>), unique per VM.

Default: required

Me.Ssh_keys

client.me.ssh_keys.*

client.me.ssh_keys.list

GET/v1/me/ssh-keys

client.me.ssh_keys.list(): APIPromise<SshKeyListResponse>

Description

List the calling user's authorized SSH keys

Returns

client.me.ssh_keys.add

POST/v1/me/ssh-keys

client.me.ssh_keys.add( name: string, publicKey: string, ): APIPromise<SshKey>

Description

Parameters

namestring

Optional human label.

publicKeystring

OpenSSH-format public key (ssh-ed25519 AAA...). Comments are stripped. Newlines are rejected.

Default: required

Returns

Example

typescript

import { readFileSync } from "node:fs";
await client.me.sshKeys.add({
  publicKey: readFileSync(`${process.env.HOME}/.ssh/id_ed25519.pub`, "utf8"),
  name: "laptop",
});
// then: ssh <vm.id>@ssh.<domain>

client.me.ssh_keys.delete

DELETE/v1/me/ssh-keys/{fingerprint}

client.me.ssh_keys.delete( fingerprint: string, ): APIPromise<DeleteResponse>

Description

Remove an authorized SSH key

Parameters

fingerprintstring

OpenSSH SHA256 fingerprint of the key to delete (e.g. SHA256:abc...). The base64 hash includes + and / and the prefix has :, so callers MUST URL-encode the value into the path segment. SDKs do this automatically.

Default: required

Returns

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 from a VM

Parameters

vmIdstring

Default: required

namestring

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

idstring

Snapshot ID (UUID).

Default: required

Returns

client.snapshots.update

PATCH/v1/snapshots/{id}

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

Description

Rename a snapshot

Parameters

idstring

Snapshot ID (UUID).

Default: required

namestring

Returns

client.snapshots.delete

DELETE/v1/snapshots/{id}

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

Description

Delete a snapshot

Parameters

idstring

Snapshot ID (UUID).

Default: required

Returns

Snapshot_imports

client.snapshot_imports.*

client.snapshot_imports.list

GET/v1/snapshot-imports

client.snapshot_imports.list(): APIPromise<SnapshotImportResponse[]>

Description

List the calling org's snapshot imports

Returns

[]

client.snapshot_imports.create

POST/v1/snapshot-imports

client.snapshot_imports.create( machineType: MachineType, diskGiB: number, name: string, source: SnapshotImportSourceSpec, ): APIPromise<SnapshotImportResponse>

Description

Build a snapshot from a Docker / OCI image or a Dockerfile

Parameters

machineTypeMachineType

diskGiBnumber

Disk size for the produced snapshot. Defaults to the machine type's catalog default (typically 10 GiB).

namestring

Optional human-readable label for the resulting import and snapshot. If omitted, the import id is used.

sourceSnapshotImportSourceSpec

Default: required

Returns

Example

typescript

// Raw call (returns 202 immediately; poll for completion).
const imp = await client.snapshotImports.create({
  machineType: 'c2m4',
  source: { type: 'image', image: 'python:3.13-slim' },
});

client.snapshot_imports.presignContext

POST/v1/snapshot-imports/context-presign

client.snapshot_imports.presignContext( sizeBytes: number, ): APIPromise<ContextPresignResponse>

Description

Mint a signed URL for uploading a Dockerfile build-context archive

Parameters

sizeBytesnumber

Planned upload size. The server rejects this request with 400 when it exceeds the platform-wide cap (the same cap is also enforced by the signed URL itself).

Returns

client.snapshot_imports.retrieve

GET/v1/snapshot-imports/{id}

client.snapshot_imports.retrieve( id: string, ): APIPromise<SnapshotImportResponse>

Description

Get a snapshot import's state

Parameters

idstring

Snapshot import ID (UUID).

Default: required

Returns

client.snapshot_imports.delete

DELETE/v1/snapshot-imports/{id}

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

Description

Delete a terminal snapshot import (cascades to its snapshot)

Parameters

idstring

Snapshot import ID (UUID).

Default: required

Returns

client.snapshot_imports.cancel

POST/v1/snapshot-imports/{id}/cancel

client.snapshot_imports.cancel( id: string, ): APIPromise<SnapshotImportResponse>

Description

Cancel an in-flight snapshot import

Parameters

idstring

Snapshot import ID (UUID).

Default: required

Returns

Quotas

client.quotas.*

client.quotas.retrieve

GET/v1/org/quotas

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

Description

Get org quotas and usage

Returns

Volumes

client.volumes.*

client.volumes.list

GET/v1/volumes

client.volumes.list(): APIPromise<Volume[]>

Description

List volumes

Returns

[]

client.volumes.create

POST/v1/volumes

client.volumes.create( name: string, sizeGiB: number, accessMode: "rw" | "ro", ): APIPromise<Volume>

Description

Create a managed volume

Parameters

namestring

Default: required

sizeGiBnumber

Default: required

accessMode"rw" | "ro"

Default: required

Returns

client.volumes.retrieve

GET/v1/volumes/{id}

client.volumes.retrieve( id: string, ): APIPromise<Volume>

Description

Get a volume

Parameters

idstring

Volume identifier (e.g. vol_<22-char-lowercase-hex>).

Default: required

Returns

client.volumes.update

PATCH/v1/volumes/{id}

client.volumes.update( id: string, name: string, sizeGiB: number, accessMode: "rw" | "ro", ): APIPromise<Volume>

Description

Update a volume's name, sizeGiB (grow / shrink-if-not-overfull), or accessMode

Parameters

idstring

Volume identifier (e.g. vol_<22-char-lowercase-hex>).

Default: required

namestring

sizeGiBnumber

accessMode"rw" | "ro"

Returns

client.volumes.delete

DELETE/v1/volumes/{id}

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

Description

Delete a volume

Parameters

idstring

Volume identifier (e.g. vol_<22-char-lowercase-hex>).

Default: required

Returns

client.volumes.listAttachments

GET/v1/volumes/{id}/attachments

client.volumes.listAttachments( id: string, ): APIPromise<VolumeAttachmentItemWithVm[]>

Description

List VMs currently attached to this volume

Parameters

idstring

Volume identifier (e.g. vol_<22-char-lowercase-hex>).

Default: required

Returns

VolumeAttachmentItemWithVm[]

Pricing

client.pricing.*

client.pricing.retrieve

GET/v1/pricing

client.pricing.retrieve(): APIPromise<PricingResponse>

Description

Get public list pricing

Returns

Types

Shared schemas referenced in parameters and return values.

PricingResponse

object

Public list price for each billable resource type.

computeComputePricing

volumeStorageVolumeStoragePricing

ComputePricing

object

Graduated vCPU-hour ladder; the rate steps down as monthly cumulative usage crosses a tier boundary.

tiersPricingTier[]

PricingTier

object

tiernumber

1-indexed tier number.

fromVcpuHoursnumber

Inclusive lower bound, in vCPU-hours.

toVcpuHoursunknown

Inclusive upper bound; null for the open-ended top tier.

ratePerVcpuHourstring

USD per vCPU-hour as a decimal string, e.g. "0.09".

VolumeStoragePricing

object

ratePerGiBMonthstring

USD per GiB-month as a decimal string, e.g. "0.09".

DeleteResponse

object

idstring

deletedboolean

VMStatus

primitive

Lifecycle status. Known values: provisioning, running, stopped, pausing, paused, resuming, deleting, error. Terminal failure statuses are error and stopped; transitional values (provisioning, pausing, resuming, deleting) indicate the VM is in flight. 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

idstring

namestring

orgIdstring

machineNamestring

sourceNamestring

Source snapshot or image name (empty on fresh boot).

firewallFirewallPolicy

effectiveFirewallunknown

Read-only composed view: firewall (the user policy) unioned with per-service auto-rules from this VM's registered services. Each auto-rule has source CIDR ::/0 and a description of the form auto: proxy service <name>. The same policy is what the worker firewall actually enforces. Set firewall to mutate; this field is computed per-response from firewall and the current service registry, never persisted.

metadataMetadata

envVarsEnvVars

publicIpv6string

cpunumber

memoryMiBnumber

diskGiBnumber

statusVMStatus

createdAtstring

deletedAtunknown

ttlunknown

Optional auto-action timer. Null when no TTL is configured. See TTL for semantics.

expiresAtMsnumber

Absolute timestamp in ms when the TTL fires. Set only while the VM is running (the countdown freezes on pause).

ttlRemainingMsnumber

Remaining cycle budget in ms. Set only while the VM is paused; restored to expiresAtMs on resume.

pausedAtunknown

When the VM became paused; null otherwise.

volumesVolumeAttachmentItem[]

Currently-attached volumes on this VM.

bucketMountsBucketMount[]

Currently-attached bucket-mounts on this VM.

Snapshot

object

idstring

namestring

orgIdstring

vmIdstring

machineNamestring

Machine type the snapshot was captured on (e.g. c1m2). VMs launched from this snapshot inherit it. Omitted for older snapshots captured before this was recorded.

firewallFirewallPolicy

metadataMetadata

envVarsEnvVars

servicesSnapshotService[]

Captured service registrations from the source VM at snapshot time.

volumesSnapshotVolumeAttachment[]

Volume attachments captured at snapshot time.

bucketMountsSnapshotBucketMountAttachment[]

BucketMount metadata captured at snapshot time (no credentials).

statusSnapshotStatus

createdAtstring

PolicyAction

enum

Allow/deny verb. Used both as the per-direction default posture and as each rule's action.

allowdeny

IngressRuleKind

enum

Ingress rule kind. Only cidr is supported — inbound packets don't carry a domain the worker could match on without TLS interception.

cidr

EgressRuleKind

enum

Egress rule kind. - cidr: match by destination IP/CIDR + port/proto. - fqdn: match by destination domain (resolved through the in-process DNS resolver) + port/proto. Resolved IPs land in a per-rule dynamic nft set; the chain emits one rule per fqdn rule keyed on (set, proto, port). Port/proto enforcement on fqdn rules is honest — the prior kind: domain shape with a shared allow-set silently ignored them. Fqdn values accept an optional leading *. wildcard (e.g. *.example.com). Bare wildcards and non-leading wildcards are rejected. Wildcards match one-or-more labels left of the suffix and do not match the apex (matches DNS wildcard semantics).

cidrfqdn

DNSMode

enum

Toggles the meaning of dns.domains. - allow: allowlist — only listed domains can resolve; any other query returns NXDOMAIN. - deny: blocklist — listed domains return NXDOMAIN; all other queries resolve through the upstream resolver. Default is deny with an empty list, which means "resolve everything" — the safe default that preserves existing behavior when callers omit the dns block.

allowdeny

IngressRule

object

actionPolicyAction

kindIngressRuleKind

valuestring

CIDR (e.g. ::/0, 10.0.0.0/8). IPv4 and IPv6 CIDRs are both accepted in the schema; L3 enforcement coverage per family is a worker-side concern.

protocol"tcp" | "udp" | "any"

portsstring

Single port (443), inclusive range (8080-8090), or any. When protocol is any, ports MUST be any.

descriptionstring

IngressPolicy

object

defaultPolicyAction

rulesIngressRule[]

EgressRule

object

actionPolicyAction

kindEgressRuleKind

valuestring

For kind: cidr, an IPv4 or IPv6 CIDR. For kind: fqdn, a domain name with optional leading *. wildcard. Must be reachable through the dns gate — a fqdn value blocked by dns.mode/dns.domains is rejected at PUT time as a dead rule.

protocol"tcp" | "udp" | "any"

portsstring

Single port (443), inclusive range (8080-8090), or any. When protocol is any, ports MUST be any.

descriptionstring

EgressPolicy

object

defaultPolicyAction

rulesEgressRule[]

DNSPolicy

object

DNS-layer filtering, independent of egress L4 rules. The resolver applies the DNS gate BEFORE L4 enforcement; a domain blocked here returns NXDOMAIN regardless of what egress.rules says about its IPs. All fields are optional — the server defaults mode to deny when missing, domains to [], and blockBypass to false (see normalizeDNSPolicy in scheduler/internal/httpapi/firewall.go).

modeDNSMode

domainsstring[]

blockBypassboolean

When true, the worker denies DoT (TCP 853) and the known public DoH endpoint IPs at the nft layer so guests cannot sidestep the in-process resolver. Default false — turning this on breaks workloads that legitimately reach 1.1.1.1 / 8.8.8.8 / etc. on TCP/443 for non-DoH reasons (e.g. services whose data plane lives on a Cloudflare anycast IP). Operators who enable DNS allowlist mode typically also flip this on explicitly.

FirewallPolicy

object

Top-level firewall policy with three independent axes. All sub-blocks are optional — the server substitutes the safe default (ingress deny / egress allow / dns mode=deny + empty) for missing blocks. Sending firewall: null on VM create is also valid.

ingressIngressPolicy

egressEgressPolicy

dnsDNSPolicy

SnapshotService

object

Captured (name, port, h2c) tuple for a single service registration on a snapshotted VM. Carried across snapshot/ restore by POST /v1/vms (snapshot-restore branch) so the new VM gets the same service registrations the source VM had at snapshot time.

namestring

portnumber

h2cboolean

SnapshotImportSourceSpec

object

Discriminated source descriptor. type selects which other fields are consumed. The opposite-variant fields must be omitted; mixing them is a 400 at the API boundary.

type"image" | "dockerfile"

image: pull an existing Docker / OCI image reference. - dockerfile: build a user-supplied Dockerfile against an uploaded build context.

imagestring

OCI image reference (e.g. ghcr.io/foo/bar:v1, nginx:1.27, alpine@sha256:…). Required when type=image.

platformstring

OCI platform selector for multi-arch image indexes, format <os>/<arch> (e.g. linux/amd64). Defaults to linux/amd64. Image-variant only.

registryUsernamestring

Optional username for private registry pulls. Applies to both source kinds: type=image authenticates the OCI pull, type=dockerfile authenticates the FROM pulls performed by buildah inside the sandbox VM.

registryPasswordstring

Optional password / PAT / OAuth token for private registry pulls. Applies to both source kinds. Held in scheduler process memory between create and dispatch (never persisted) and wiped after the build VM is torn down.

registryHoststring

Registry hostname the registryUsername / registryPassword authenticate against (e.g. docker.io, ghcr.io, 1234.dkr.ecr.us-east-1.amazonaws.com). Required when credentials are set on type=dockerfile: the baker keys the auth.json entry against this host. Tolerated but ignored for type=image (the host is derived from the image reference). Optional port: e.g. registry.example.com:5000.

contextRefstring

Opaque one-shot token returned by POST /v1/snapshot-imports/context-presign. Required when type=dockerfile. The platform validates that the referenced upload belongs to the calling org and consumes the token on use.

dockerfilePathstring

Path to the Dockerfile relative to the context root. Defaults to Dockerfile. Must not be absolute and must not contain ...

buildArgsobject

Optional --build-arg KEY=VALUE pairs forwarded to the build. Capped at 64 entries, 8 KiB total.

targetstring

Optional multi-stage --target selector. Empty means the final stage.

SnapshotImportEvent

object

One entry in an import's append-only event log. Phase + status pairs describe the sub-stages of running (preparing → network → pull → export → saving → warming).

phasestring

Pipeline sub-phase. Known values include preparing, network, pull (image source), fetch_context, build (dockerfile source), export, saving, warming, done.

statusstring

Event status. Known values include started, completed, failed, skipped, cancelled.

timestampMsnumber

Unix-epoch milliseconds.

messagestring

Optional user-safe summary. Never contains credentials or internal paths.

SnapshotImportSourceView

object

Publicly-rendered source descriptor returned on GET /v1/snapshot-imports/{id}. Strips secrets (registryPassword, raw context object keys) — only fields safe to echo back to the caller appear here.

type"image" | "dockerfile"

imagestring

platformstring

registryUsernamestring

registryHoststring

Registry hostname for dockerfile-source private builds. Empty for image-source (derived from the image reference, not stored).

dockerfilePathstring

buildArgsobject

targetstring

contextSizeBytesnumber

SnapshotImportResponse

object

Current state of a snapshot import. Returned by POST /v1/snapshot-imports (initial pending state), GET /v1/snapshot-imports/{id}, GET /v1/snapshot-imports (in the array elements), and POST /v1/snapshot-imports/{id}/cancel.

idstring

Import id (UUID).

namestring

sourceSnapshotImportSourceView

statusstring

Current state. Known values: pending (queued, no worker yet), claimed (worker assigned, dispatch in flight), running (worker executing the pipeline), succeeded / failed / cancelled (terminal).

snapshotIdstring

Set when status is succeeded. Fetch the corresponding Snapshot record via GET /v1/snapshots/{id}.

errorstring

Set when status is failed. User-safe diagnostic.

eventsSnapshotImportEvent[]

machineNamestring

cpunumber

memoryMiBnumber

diskGiBnumber

createdAtstring

startedAtstring

updatedAtstring

finishedAtstring

ContextPresignResponse

object

One-shot upload handle for the dockerfile-source flow.

contextRefstring

Opaque token to pass as source.contextRef on the subsequent POST /v1/snapshot-imports. Single-use; the create call consumes the entry.

uploadUrlstring

Short-lived signed PUT URL. Upload the build-context ZIP archive here with Content-Type: application/zip.

expiresInSecnumber

TTL of uploadUrl, in seconds.

maxUploadBytesnumber

Server-side cap on upload size. The signed URL also enforces this server-side.

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.

EnvVars

object

Environment variable string→string map injected into the VM at boot. Keys must be 1–256 bytes and match shell-variable name ([A-Za-z_][A-Za-z0-9_]*); values may not contain newline, carriage return, or null bytes. Total JSON encoding ≤65536 bytes.

ExecEvent

object

One event in the NDJSON exec stream returned by POST /v1/vms/{id}/exec under Accept: application/x-ndjson. Short field names (t, d, c, to, ms) keep per-chunk overhead small since high-output commands can produce thousands of events per exec.

t"o" | "e" | "x"

Event type: o = stdout chunk, e = stderr chunk, x = terminal exit event.

dstring

For o/e: base64-encoded raw bytes of the chunk. For x: optional diagnostic string (e.g. spawn failure) when non-empty.

cnumber

Exit code. Present on x events only.

toboolean

True if the command was killed by the timeout. x events only.

msnumber

Guest-reported duration in milliseconds. x events only.

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.

exitCodenumber

stdoutstring

stderrstring

timedOutboolean

stdoutTruncatedboolean

True if the collector dropped stdout bytes past the 4 MiB cap.

stderrTruncatedboolean

True if the collector dropped stderr bytes past the 4 MiB cap.

durationMsnumber

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.

uploadUrlstring

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.

downloadUrlstring

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.

expiresInSecnumber

Lifetime of both URLs in seconds.

maxUploadBytesnumber

Upper bound on upload size (equals the VM's disk size in bytes).

ConsoleTokenResponse

object

tokenstring

expiresInSecnumber

websocketPathstring

Relative WebSocket path; combine with your API host as wss://<host><websocketPath>?session=<token>.

SshKey

object

namestring

Optional human label.

publicKeystring

OpenSSH-format public key, of the form <type> <base64-blob> — the optional comment is stripped server-side. Supported types: ssh-ed25519, ssh-rsa, ecdsa-sha2-nistp{256,384,521}, plus FIDO2 hardware-backed variants (sk-...@openssh.com).

fingerprintstring

OpenSSH SHA256 fingerprint, e.g. SHA256:abc.... This is the identifier — matches what ssh-keygen -lf prints and what your ssh client shows on first connect; pass it back as the {fingerprint} path segment to deleteSshKey.

createdAtstring

SshKeyListResponse

object

keysSshKey[]

OrgQuotaValues

object

vcpunumber

memoryMiBnumber

diskGiBnumber

snapshotCountnumber

volumeCountnumber

volumeGiBnumber

OrgQuotaUsage

object

orgIdstring

limitsOrgQuotaValues

usageOrgQuotaValues

Service

object

namestring

Service name (1–29 chars). Embedded in the public URL as <name>--<vmIdHexNoHyphens>.proxy.<stack-domain>.

portnumber

TCP port the service listens on inside the VM. Privileged ports (<1024) are rejected.

h2cboolean

When true, the proxy speaks HTTP/2 cleartext (h2c) to the backend. Required for gRPC and h2c-only apps. When false (default), the proxy uses HTTP/1.1 — covers HTTP/1.1 apps, Server-Sent Events, and WebSocket pass-through.

Volume

object

idstring

namestring

orgIdstring

accessModestring

Access mode. Known values: rw, ro. Future server versions may introduce additional values.

sizeGiBnumber

statusstring

Lifecycle status. Known values: - creating — the substrate-create saga is in flight. Set by the server briefly between the customer's POST /v1/volumes and the worker substrate provisioning; attach attempts are rejected with VOL_NOT_READY until the saga commits. Clients polling immediately after create may observe this state. - ready — substrate is up; attachable. - deleting — cleanup is in progress; not attachable. Future server versions may introduce additional values.

pendingSizeGiBnumber

When non-zero, a resize saga is in flight; sizeGiB is still the pre-resize value and pendingSizeGiB is the target. Set briefly between PATCH /v1/volumes/{id} and the substrate resize commit. Clients polling immediately after a resize may observe a non-zero value.

mountedCountnumber

Number of currently-running VMs with this volume attached (paused VMs are NOT counted).

usedGiBnumber

Bytes used inside the volume (rounded down to GiB). Fetched on-demand from the substrate; omitted when the substrate is unreachable.

createdAtstring

VolumeAttachmentItem

object

volumeIdstring

mountPathstring

readOnlyboolean

mountStatusstring

Known values: mounted, failed, pending. pending appears on attachments to paused VMs (mount happens on resume) and briefly during in-flight hot-attach.

statusMessagestring

DetachVolumeResponse

object

detachedboolean

warningsDetachWarning[]

DetachWarning

object

typestring

Known values: ack_timeout, guest_unresponsive.

messagestring

BucketMount

object

idstring

vmIdstring

bucketUristring

gs://... or s3://...; future schemes may be added.

mountPathstring

readOnlyboolean

mountStatusstring

Known values: mounted, failed, pending.

statusMessagestring

createdAtstring

SnapshotVolumeAttachment

object

volumeIdstring

mountPathstring

readOnlyboolean

SnapshotBucketMountAttachment

object

bucketUristring

mountPathstring

readOnlyboolean

HealthResponse

object

Health check

statusstring