Fast VMDocsPythonTypeScriptRESTLaunch a VM

Python SDK

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

Install

shell
pip install fastvm

Import

python
from fastvm import FastvmClient

client = FastvmClient()  # reads FASTVM_API_KEY / FASTVM_BASE_URL

Top-level helpers

client.*

client.health

GET/healthz
client.health() -> HealthResponse

Description

Health check

Returns

client.uploadhelper

client.upload( vm_id: str, local_path: str, remote_path: str, *, fetch_timeout_sec: int = 600, exec_timeout_sec: int = 600, ) -> None

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

vm_idstr
Target VM id.
Default: required
local_pathstr
Local file or directory path.
Default: required
remote_pathstr
Destination path inside the VM.
Default: required
fetch_timeout_secint
Timeout on the VM-side /files/fetch call.
Default: 600
exec_timeout_secint
Timeout on VM-side tar extraction (dir mode only).
Default: 600

Returns

None

Example

python
client.upload(vm.id, "./config.toml", "/etc/app.toml")   # file
client.upload(vm.id, "./src", "/root/src")               # directory (tar-streamed)

client.downloadhelper

client.download( vm_id: str, remote_path: str, local_path: str, *, exec_timeout_sec: int = 600, ) -> None

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

vm_idstr
Target VM id.
Default: required
remote_pathstr
Source path inside the VM.
Default: required
local_pathstr
Destination path on the client.
Default: required
exec_timeout_secint
Timeout on VM-side exec (classify + stream).
Default: 600

Returns

None

Example

python
client.download(vm.id, "/root/out.log", "./out.log")   # file
client.download(vm.id, "/var/log", "./log-backup")     # directory

client.wait_for_vm_readyhelper

client.wait_for_vm_ready( vm_id: str, *, poll_interval: float = 2.0, timeout: float = 300.0, ) -> 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

vm_idstr
Target VM id.
Default: required
poll_intervalfloat
Seconds between polls.
Default: 2.0
timeoutfloat
Total wait deadline in seconds.
Default: 300.0

Returns

Example

python
vm = client.vms.retrieve(some_id)
vm = client.wait_for_vm_ready(vm.id, timeout=120)

VMs

client.vms.*

client.vms.list

GET/v1/vms
client.vms.list( status: VMStatus, ) -> 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( *, machine_type: MachineType | None = None, snapshot_id: str | None = None, name: str | None = None, metadata: dict[str, str] | None = None, firewall: FirewallPolicy | None = None, wait: bool = True, poll_interval: float = 2.0, wait_timeout: float = 300.0, timeout: float | httpx.Timeout | None = None, max_retries: int = 0, ) -> 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

machine_typeMachineType | None
VM flavor (c1m2, c2m4, ...). Required unless snapshot_id is set.
Default: None
snapshot_idstr | None
Restore from snapshot instead of cold-booting.
Default: None
namestr | None
Human-readable VM name.
Default: None
metadatadict[str, str] | None
Free-form key/value labels.
Default: None
firewallFirewallPolicy | None
Initial firewall policy.
Default: None
waitbool
Block until RUNNING. Set False for raw 201/202 behavior.
Default: True
poll_intervalfloat
Seconds between polls when wait=True.
Default: 2.0
wait_timeoutfloat
Max seconds to wait for RUNNING. Raises VMNotReadyError on exceed.
Default: 300.0
timeoutfloat | httpx.Timeout | None
Per-request HTTP timeout (forwarded to generated launch verbatim).
Default: None
max_retriesint
Auto-retry on 5xx/connect errors. POST is non-idempotent, default 0.
Default: 0

Returns

Example

python
from fastvm import FastvmClient

client = FastvmClient()
vm = client.vms.launch(machine_type="c1m2", name="dev")
print(vm.id, vm.status)  # "running"

# Restore from snapshot
vm = client.vms.launch(snapshot_id="snp_...")

# Skip polling — get the raw 201/202 body
vm = client.vms.launch(machine_type="c1m2", wait=False)

client.vms.retrieve

GET/v1/vms/{id}
client.vms.retrieve( id: str, ) -> VM

Description

Get a VM

Parameters

idstr
VM ID (UUID).
Default: required

Returns

client.vms.update

PATCH/v1/vms/{id}
client.vms.update( id: str, name: str, metadata: Metadata, ttl: unknown, ) -> VM

Description

Update a VM

Parameters

idstr
VM ID (UUID).
Default: required
namestr
metadataMetadata
ttlunknown

Returns

client.vms.delete

DELETE/v1/vms/{id}
client.vms.delete( id: str, ) -> DeleteResponse

Description

Delete a VM

Parameters

idstr
VM ID (UUID).
Default: required

Returns

client.vms.pause

POST/v1/vms/{id}/pause
client.vms.pause( id: str, ) -> VM

Description

Pause a VM

Parameters

idstr
VM ID (UUID).
Default: required

Returns

client.vms.resume

POST/v1/vms/{id}/resume
client.vms.resume( id: str, ) -> VM

Description

Resume a paused VM

Parameters

idstr
VM ID (UUID).
Default: required

Returns

client.vms.refresh_ttl

POST/v1/vms/{id}/ttl/refresh
client.vms.refresh_ttl( id: str, ) -> VM

Description

Reset the VM's TTL cycle

Parameters

idstr
VM ID (UUID).
Default: required

Returns

client.vms.set_firewall

PUT/v1/vms/{id}/firewall
client.vms.set_firewall( id: str, ingress: IngressPolicy, egress: EgressPolicy, dns: DNSPolicy, ) -> VM

Description

Replace firewall policy

Parameters

idstr
VM ID (UUID).
Default: required
ingressIngressPolicy
egressEgressPolicy
dnsDNSPolicy

Returns

client.vms.patch_firewall

PATCH/v1/vms/{id}/firewall
client.vms.patch_firewall( id: str, ingress: IngressPolicy, egress: EgressPolicy, dns: DNSPolicy, ) -> VM

Description

Patch firewall policy

Parameters

idstr
VM ID (UUID).
Default: required
ingressIngressPolicy
egressEgressPolicy
dnsDNSPolicy

Returns

client.vms.console_token

POST/v1/vms/{id}/console-token
client.vms.console_token( id: str, ) -> ConsoleTokenResponse

Description

Mint a console token

Parameters

idstr
VM ID (UUID).
Default: required

Returns

client.vms.runoverride

POST/v1/vms/{id}/exec
client.vms.run( id: str, *, command: str | Sequence[str], timeout_sec: int | None = None, max_retries: int = 0, ) -> ExecVMResponse

Description

Execute a command inside a VM. The override accepts str in addition to Sequence[str]: plain shell strings are auto-wrapped into ["sh", "-c", "<cmd>"] before hitting the API. Argv-style calls pass through unchanged.

The wrap guards against Python's silent string-to-chars iteration when a Sequence[str] parameter is passed a bare string, which would otherwise produce a nonsensical argv like ["l","s"," ","-","l","a"].

Parameters

idstr
Target VM id.
Default: required
commandstr | Sequence[str]
Shell string (auto-wrapped) or argv.
Default: required
timeout_secint | None
Server-side execution timeout.
Default: None
max_retriesint
Auto-retry on 5xx. Non-idempotent, default 0.
Default: 0

Returns

Example

python
# Shell strings work — auto-wrapped into ["sh", "-c", ...]
result = client.vms.run(vm.id, command="ls -la /root")

# Argv lists pass through unchanged
result = client.vms.run(vm.id, command=["python3", "main.py", "--flag"])

print(result.exit_code, result.stdout)

client.vms.streamhelper

client.vms.stream( id: str, *, command: str | Sequence[str], timeout_sec: int | None = None, ) -> Iterator[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

idstr
Target VM id.
Default: required
commandstr | Sequence[str]
Shell string (auto-wrapped) or argv list.
Default: required
timeout_secint | None
Server-side execution timeout in seconds.
Default: None

Returns

Iterator[]

Example

python
from fastvm import FastvmClient, ExecEvent

client = FastvmClient()
for event in client.vms.stream(vm.id, command="make -j8"):
    if event.type == "o":
        sys.stdout.buffer.write(event.data)
    elif event.type == "e":
        sys.stderr.buffer.write(event.data)
    elif event.type == "x":
        print(f"exit {event.exit_code} in {event.duration_ms} ms")

VMs.Services

client.vms.services.*

client.vms.services.list

GET/v1/vms/{id}/services
client.vms.services.list( id: str, ) -> Service[]

Description

List service registrations

Parameters

idstr
VM ID (UUID).
Default: required

Returns

[]

client.vms.services.register

POST/v1/vms/{id}/services
client.vms.services.register( id: str, name: str, port: int, h2c: bool, ) -> Service

Description

Register a service on a VM

Parameters

idstr
VM ID (UUID).
Default: required
namestr
Default: required
portint
Default: required
h2cbool
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: str, service_name: str, port: int, h2c: bool, ) -> Service

Description

Register or update a service on a VM

Parameters

idstr
VM ID (UUID).
Default: required
service_namestr
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
portint
New TCP port. Same value as the existing entry is a no-op.
Default: required
h2cbool
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: str, service_name: str, )

Description

Deregister a service from a VM

Parameters

idstr
VM ID (UUID).
Default: required
service_namestr
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

VMs.Files

client.vms.files.*

client.vms.files.presign

POST/v1/vms/{id}/files/presign
client.vms.files.presign( id: str, path: str, ) -> FilePresignResponse

Description

Mint signed URLs for uploading a file to a VM

Parameters

idstr
VM ID (UUID).
Default: required
pathstr
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

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

client.download(vm.id, "/root/out.log", "./out.log")
client.download(vm.id, "/var/log", "./log-backup")

# Raw call if you need manual control over the signed-URL flow:
presign = 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: str, url: str, path: str, timeout_sec: int, ) -> ExecVMResponse

Description

Fetch a file into a VM from a presigned URL

Parameters

idstr
VM ID (UUID).
Default: required
urlstr
Must be the downloadUrl previously returned by POST /v1/vms/{id}/files/presign (URLs from other sources are rejected).
Default: required
pathstr
Absolute destination path inside the guest filesystem.
Default: required
timeout_secint
Per-fetch timeout in seconds.

Returns

Example

python
# You usually don't call this directly — client.upload() composes
# presign + PUT + fetch in a single call. Use it when you need to
# pipe an already-hosted URL (still from /files/presign) into the VM.
client.vms.files.fetch(vm.id, url=presign.download_url, path="/root/file.txt")

VMs.Volumes

client.vms.volumes.*

client.vms.volumes.attach

POST/v1/vms/{id}/volumes
client.vms.volumes.attach( id: str, volume_id: str, mount_path: str, read_only: bool, ) -> VolumeAttachmentItem

Description

Attach a volume to a VM

Parameters

idstr
VM ID (UUID).
Default: required
volume_idstr
Default: required
mount_pathstr
Absolute path; must start with /mnt/ or /data/.
Default: required
read_onlybool
Default: false

Returns

client.vms.volumes.detach

DELETE/v1/vms/{id}/volumes/{volumeId}
client.vms.volumes.detach( id: str, volume_id: str, ) -> DetachVolumeResponse

Description

Detach a volume from a VM

Parameters

idstr
VM ID (UUID).
Default: required
volume_idstr
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: str, ) -> BucketMount[]

Description

List bucket-mounts on a VM

Parameters

idstr
VM ID (UUID).
Default: required

Returns

[]

client.vms.bucket_mounts.attach

POST/v1/vms/{id}/bucket-mounts
client.vms.bucket_mounts.attach( id: str, bucket_uri: str, mount_path: str, read_only: bool, credentials: BucketMountCredentials, ) -> BucketMount

Description

Attach a customer GCS / S3 bucket to a VM

Parameters

idstr
VM ID (UUID).
Default: required
bucket_uristr
Customer's GCS or S3 bucket URI. gs://<bucket>[/prefix] or s3://<bucket>[/prefix].
Default: required
mount_pathstr
Default: required
read_onlybool
Default: false
credentialsBucketMountCredentials
Default: required

Returns

client.vms.bucket_mounts.retrieve

GET/v1/vms/{id}/bucket-mounts/{bucketMountId}
client.vms.bucket_mounts.retrieve( id: str, bucket_mount_id: str, ) -> BucketMount

Description

Get a bucket-mount

Parameters

idstr
VM ID (UUID).
Default: required
bucket_mount_idstr
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: str, bucket_mount_id: str, credentials: BucketMountCredentials, ) -> BucketMount

Description

Rotate bucket-mount credentials in-place

Parameters

idstr
VM ID (UUID).
Default: required
bucket_mount_idstr
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: str, bucket_mount_id: str, )

Description

Detach and delete a bucket-mount

Parameters

idstr
VM ID (UUID).
Default: required
bucket_mount_idstr
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() -> 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: str, public_key: str, ) -> SshKey

Description

Register an SSH public key for the calling user

Parameters

namestr
Optional human label.
public_keystr
OpenSSH-format public key (ssh-ed25519 AAA...). Comments are stripped. Newlines are rejected.
Default: required

Returns

Example

python
with open(os.path.expanduser("~/.ssh/id_ed25519.pub")) as f:
    client.me.ssh_keys.add(public_key=f.read(), 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: str, ) -> DeleteResponse

Description

Remove an authorized SSH key

Parameters

fingerprintstr
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() -> Snapshot[]

Description

List snapshots

Returns

[]

client.snapshots.create

POST/v1/snapshots
client.snapshots.create( vm_id: str, name: str, ) -> Snapshot

Description

Create a snapshot from a VM

Parameters

vm_idstr
Default: required
namestr
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: str, ) -> Snapshot

Description

Get a snapshot

Parameters

idstr
Snapshot ID (UUID).
Default: required

Returns

client.snapshots.update

PATCH/v1/snapshots/{id}
client.snapshots.update( id: str, name: str, ) -> Snapshot

Description

Rename a snapshot

Parameters

idstr
Snapshot ID (UUID).
Default: required
namestr

Returns

client.snapshots.delete

DELETE/v1/snapshots/{id}
client.snapshots.delete( id: str, ) -> DeleteResponse

Description

Delete a snapshot

Parameters

idstr
Snapshot ID (UUID).
Default: required

Returns

Snapshot_imports

client.snapshot_imports.*

client.snapshot_imports.list

GET/v1/snapshot-imports
client.snapshot_imports.list() -> SnapshotImportResponse[]

Description

List the calling org's snapshot imports

Returns

[]

client.snapshot_imports.create

POST/v1/snapshot-imports
client.snapshot_imports.create( machine_type: MachineType, disk_gi_b: int, name: str, source: SnapshotImportSourceSpec, ) -> SnapshotImportResponse

Description

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

Parameters

machine_typeMachineType
disk_gi_bint
Disk size for the produced snapshot. Defaults to the machine type's catalog default (typically 10 GiB).
namestr
Optional human-readable label for the resulting import and snapshot. If omitted, the import id is used.
sourceSnapshotImportSourceSpec
Default: required

Returns

Example

python
# High-level: builds, polls, returns the completed Snapshot.
snapshot = await client.build(image_ref="python:3.13-slim")

# Dockerfile + context (zipped in-SDK, presigned + PUT,
# then snapshot import created):
snapshot = await client.build(
    dockerfile=Path("./Dockerfile").read_text(),
    context_dir="./my-app",
)

client.snapshot_imports.presign_context

POST/v1/snapshot-imports/context-presign
client.snapshot_imports.presign_context( size_bytes: int, ) -> ContextPresignResponse

Description

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

Parameters

size_bytesint
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: str, ) -> SnapshotImportResponse

Description

Get a snapshot import's state

Parameters

idstr
Snapshot import ID (UUID).
Default: required

Returns

client.snapshot_imports.delete

DELETE/v1/snapshot-imports/{id}
client.snapshot_imports.delete( id: str, ) -> DeleteResponse

Description

Delete a terminal snapshot import (cascades to its snapshot)

Parameters

idstr
Snapshot import ID (UUID).
Default: required

Returns

client.snapshot_imports.cancel

POST/v1/snapshot-imports/{id}/cancel
client.snapshot_imports.cancel( id: str, ) -> SnapshotImportResponse

Description

Cancel an in-flight snapshot import

Parameters

idstr
Snapshot import ID (UUID).
Default: required

Returns

Quotas

client.quotas.*

client.quotas.retrieve

GET/v1/org/quotas
client.quotas.retrieve() -> OrgQuotaUsage

Description

Get org quotas and usage

Returns

Volumes

client.volumes.*

client.volumes.list

GET/v1/volumes
client.volumes.list() -> Volume[]

Description

List volumes

Returns

[]

client.volumes.create

POST/v1/volumes
client.volumes.create( name: str, size_gi_b: int, access_mode: "rw" | "ro", ) -> Volume

Description

Create a managed volume

Parameters

namestr
Default: required
size_gi_bint
Default: required
access_mode"rw" | "ro"
Default: required

Returns

client.volumes.retrieve

GET/v1/volumes/{id}
client.volumes.retrieve( id: str, ) -> Volume

Description

Get a volume

Parameters

idstr
Volume identifier (e.g. vol_<22-char-lowercase-hex>).
Default: required

Returns

client.volumes.update

PATCH/v1/volumes/{id}
client.volumes.update( id: str, name: str, size_gi_b: int, access_mode: "rw" | "ro", ) -> Volume

Description

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

Parameters

idstr
Volume identifier (e.g. vol_<22-char-lowercase-hex>).
Default: required
namestr
size_gi_bint
access_mode"rw" | "ro"

Returns

client.volumes.delete

DELETE/v1/volumes/{id}
client.volumes.delete( id: str, ) -> DeleteResponse

Description

Delete a volume

Parameters

idstr
Volume identifier (e.g. vol_<22-char-lowercase-hex>).
Default: required

Returns

client.volumes.list_attachments

GET/v1/volumes/{id}/attachments
client.volumes.list_attachments( id: str, ) -> VolumeAttachmentItemWithVm[]

Description

List VMs currently attached to this volume

Parameters

idstr
Volume identifier (e.g. vol_<22-char-lowercase-hex>).
Default: required

Returns

VolumeAttachmentItemWithVm[]

Types

Shared schemas referenced in parameters and return values.

DeleteResponse

object
idstr
deletedbool

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
idstr
namestr
org_idstr
machine_namestr
source_namestr
Source snapshot or image name (empty on fresh boot).
firewallFirewallPolicy
effective_firewallunknown
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
env_varsEnvVars
public_ipv6str
cpuint
memory_mi_bint
disk_gi_bint
statusVMStatus
created_atstr
deleted_atunknown
ttlunknown
Optional auto-action timer. Null when no TTL is configured. See TTL for semantics.
expires_at_msint
Absolute timestamp in ms when the TTL fires. Set only while the VM is running (the countdown freezes on pause).
ttl_remaining_msint
Remaining cycle budget in ms. Set only while the VM is paused; restored to expiresAtMs on resume.
paused_atunknown
When the VM became paused; null otherwise.
volumesVolumeAttachmentItem[]
Currently-attached volumes on this VM.
bucket_mountsBucketMount[]
Currently-attached bucket-mounts on this VM.

Snapshot

object
idstr
namestr
org_idstr
vm_idstr
firewallFirewallPolicy
metadataMetadata
env_varsEnvVars
servicesSnapshotService[]
Captured service registrations from the source VM at snapshot time.
volumesSnapshotVolumeAttachment[]
Volume attachments captured at snapshot time.
bucket_mountsSnapshotBucketMountAttachment[]
BucketMount metadata captured at snapshot time (no credentials).
statusSnapshotStatus
created_atstr

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
valuestr
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"
portsstr
Single port (443), inclusive range (8080-8090), or any. When protocol is any, ports MUST be any.
descriptionstr

IngressPolicy

object
defaultPolicyAction
rulesIngressRule[]

EgressRule

object
actionPolicyAction
kindEgressRuleKind
valuestr
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"
portsstr
Single port (443), inclusive range (8080-8090), or any. When protocol is any, ports MUST be any.
descriptionstr

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
domainslist[str]
block_bypassbool
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.
namestr
portint
h2cbool

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.
imagestr
OCI image reference (e.g. ghcr.io/foo/bar:v1, nginx:1.27, alpine@sha256:…). Required when type=image.
platformstr
OCI platform selector for multi-arch image indexes, format <os>/<arch> (e.g. linux/amd64). Defaults to linux/amd64. Image-variant only.
registry_usernamestr
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.
registry_passwordstr
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.
registry_hoststr
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.
context_refstr
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.
dockerfile_pathstr
Path to the Dockerfile relative to the context root. Defaults to Dockerfile. Must not be absolute and must not contain ...
build_argsdict
Optional --build-arg KEY=VALUE pairs forwarded to the build. Capped at 64 entries, 8 KiB total.
targetstr
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).
phasestr
Pipeline sub-phase. Known values include preparing, network, pull (image source), fetch_context, build (dockerfile source), export, saving, warming, done.
statusstr
Event status. Known values include started, completed, failed, skipped, cancelled.
timestamp_msint
Unix-epoch milliseconds.
messagestr
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"
imagestr
platformstr
registry_usernamestr
registry_hoststr
Registry hostname for dockerfile-source private builds. Empty for image-source (derived from the image reference, not stored).
dockerfile_pathstr
build_argsdict
targetstr
context_size_bytesint

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.
idstr
Import id (UUID).
namestr
sourceSnapshotImportSourceView
statusstr
Current state. Known values: pending (queued, no worker yet), claimed (worker assigned, dispatch in flight), running (worker executing the pipeline), succeeded / failed / cancelled (terminal).
snapshot_idstr
Set when status is succeeded. Fetch the corresponding Snapshot record via GET /v1/snapshots/{id}.
errorstr
Set when status is failed. User-safe diagnostic.
eventsSnapshotImportEvent[]
machine_namestr
cpuint
memory_mi_bint
disk_gi_bint
created_atstr
started_atstr
updated_atstr
finished_atstr

ContextPresignResponse

object
One-shot upload handle for the dockerfile-source flow.
context_refstr
Opaque token to pass as source.contextRef on the subsequent POST /v1/snapshot-imports. Single-use; the create call consumes the entry.
upload_urlstr
Short-lived signed PUT URL. Upload the build-context ZIP archive here with Content-Type: application/zip.
expires_in_secint
TTL of uploadUrl, in seconds.
max_upload_bytesint
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.
dstr
For o/e: base64-encoded raw bytes of the chunk. For x: optional diagnostic string (e.g. spawn failure) when non-empty.
cint
Exit code. Present on x events only.
tobool
True if the command was killed by the timeout. x events only.
msint
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.
exit_codeint
stdoutstr
stderrstr
timed_outbool
stdout_truncatedbool
True if the collector dropped stdout bytes past the 4 MiB cap.
stderr_truncatedbool
True if the collector dropped stderr bytes past the 4 MiB cap.
duration_msint

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.
upload_urlstr
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.
download_urlstr
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.
expires_in_secint
Lifetime of both URLs in seconds.
max_upload_bytesint
Upper bound on upload size (equals the VM's disk size in bytes).

ConsoleTokenResponse

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

SshKey

object
namestr
Optional human label.
public_keystr
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).
fingerprintstr
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.
created_atstr

SshKeyListResponse

object
keysSshKey[]

OrgQuotaValues

object
vcpuint
memory_mi_bint
disk_gi_bint
snapshot_countint
volume_countint
volume_gi_bint

OrgQuotaUsage

object
org_idstr
limitsOrgQuotaValues
usageOrgQuotaValues

Service

object
namestr
Service name (1–29 chars). Embedded in the public URL as <name>--<vmIdHexNoHyphens>.proxy.<stack-domain>.
portint
TCP port the service listens on inside the VM. Privileged ports (<1024) are rejected.
h2cbool
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
idstr
namestr
org_idstr
access_modestr
Access mode. Known values: rw, ro. Future server versions may introduce additional values.
size_gi_bint
statusstr
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.
pending_size_gi_bint
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.
mounted_countint
Number of currently-running VMs with this volume attached (paused VMs are NOT counted).
used_gi_bint
Bytes used inside the volume (rounded down to GiB). Fetched on-demand from the substrate; omitted when the substrate is unreachable.
created_atstr

VolumeAttachmentItem

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

DetachVolumeResponse

object
detachedbool
warningsDetachWarning[]

DetachWarning

object
typestr
Known values: ack_timeout, guest_unresponsive.
messagestr

BucketMount

object
idstr
vm_idstr
bucket_uristr
gs://... or s3://...; future schemes may be added.
mount_pathstr
read_onlybool
mount_statusstr
Known values: mounted, failed, pending.
status_messagestr
created_atstr

SnapshotVolumeAttachment

object
volume_idstr
mount_pathstr
read_onlybool

SnapshotBucketMountAttachment

object
bucket_uristr
mount_pathstr
read_onlybool

HealthResponse

object
Health check
statusstr