@gigadrive/sdk 0.9.4 → 0.10.0

package/dist/index.d.ts

@@ -131,6 +131,14 @@ declare class HttpClient {
      * @internal
      */
     fetchRaw(url: string, init: RequestInit): Promise<Response>;
+    /**
+     * Fetch an arbitrary URL without authentication and without throwing on a
+     * non-2xx status, using the client's configured `fetch`. Used to probe
+     * public URLs such as microVM preview URLs.
+     *
+     * @internal
+     */
+    fetchPublic(url: string, init?: RequestInit): Promise<Response>;
     private request;
     /** Perform the request with auth injection and a single 401 refresh-retry. */
     private fetchWithAuth;
@@ -150,6 +158,585 @@ declare class BaseResource {
     constructor(httpClient: HttpClient);
 }
 
+/**
+ * A duration in milliseconds, or a string such as `'500ms'`, `'30s'`, `'10m'`
+ * or `'2h'`.
+ *
+ * Unlike queue durations, a bare number here is **milliseconds**, matching the
+ * `timeoutMs` fields of the microVM API.
+ */
+type MicroVmDuration = number | `${number}${'ms' | 's' | 'm' | 'h'}`;
+/**
+ * Converts a {@link MicroVmDuration} to whole milliseconds, rounding up.
+ *
+ * @throws {RangeError} When the value is negative, not finite, or not a recognised duration string.
+ *
+ * @example
+ * ```ts
+ * durationToMs('10m'); // 600000
+ * durationToMs(1500); // 1500
+ * ```
+ */
+declare const durationToMs: (value: MicroVmDuration) => number;
+/** The longest lifetime a microVM can have: 24 hours (plans may allow less). */
+declare const MICROVM_MAX_TIMEOUT_MS: number;
+
+/**
+ * Wire types of the microVM REST API (`/microvms`, `/microvm-images`).
+ *
+ * These are the JSON shapes the API returns. The ergonomic {@link MicroVM} and
+ * {@link Command} classes wrap them; the low-level `client.microvms` resource
+ * returns them as is.
+ */
+/**
+ * Lifecycle of a microVM.
+ *
+ * `pending` (accepted, not placed yet) → `starting` (booting) → `running`
+ * (commands, files and ports are available) → `stopping` → `stopped`.
+ * `failed` can follow any state that is not terminal. `stopped` and `failed`
+ * are terminal. `pausing`, `paused` and `resuming` are reserved for pause and
+ * resume.
+ */
+type MicroVmStatus = 'pending' | 'starting' | 'running' | 'pausing' | 'paused' | 'resuming' | 'stopping' | 'stopped' | 'failed';
+/** vCPU counts a microVM can be created with. */
+type MicroVmVcpus = 1 | 2 | 4;
+/** Outbound network policy. Private ranges are always blocked, whatever the policy. */
+type MicroVmEgress = 'allow' | 'deny';
+/** Network policy of a microVM. */
+interface MicroVmNetworkPolicy {
+    /** `allow` (default) reaches the internet; `deny` blocks all outbound traffic. */
+    egress: MicroVmEgress;
+}
+/** A port exposed by a microVM and its public preview URL. */
+interface MicroVmPort {
+    /** Port inside the microVM. */
+    port: number;
+    /** Public HTTPS URL that forwards to the port, e.g. `https://3000-k3j9x2m1q8zt.vm.gigadrive.app`. */
+    url: string;
+}
+/** A microVM as the API returns it. */
+interface MicroVmInfo {
+    /** Stable UUID. */
+    id: string;
+    /** Unguessable label used in preview hostnames (`<port>-<slug>.vm.<domain>`). */
+    slug: string;
+    applicationId: string;
+    organizationId: string;
+    status: MicroVmStatus;
+    /** The image the microVM booted from. */
+    image: {
+        id: string;
+        name: string;
+    };
+    vcpus: number;
+    memoryMb: number;
+    diskMb: number;
+    region: string;
+    /** Exposed ports with their preview URLs. */
+    ports: MicroVmPort[];
+    network: MicroVmNetworkPolicy;
+    /** Metadata given at create. */
+    metadata: Record<string, string>;
+    /** Lifetime in milliseconds, as set at create or by the last extension. */
+    timeoutMs: number;
+    /** ISO 8601 time the microVM stops automatically, or `null` before it started. */
+    expiresAt: string | null;
+    createdAt: string;
+    startedAt: string | null;
+    stoppedAt: string | null;
+    /** Why the microVM stopped, such as `timeout`, `user`, `host_lost` or `maintenance`. */
+    stopReason: string | null;
+}
+/** Body of `POST /microvms`. */
+interface CreateMicroVmInput {
+    /**
+     * Application the microVM belongs to. Optional when the credentials belong to
+     * an application or deployment; the SDK also fills it from the client's
+     * `applicationId` or `GIGADRIVE_APPLICATION_ID`.
+     */
+    applicationId?: string;
+    /** Built-in image name (`node22`, `python3.13`, ...), custom image name, or image id. Default `node22`. */
+    image?: string;
+    /** Default 1. */
+    vcpus?: MicroVmVcpus;
+    /** Memory in MiB, 512 to 8192. Default 2048. */
+    memoryMb?: number;
+    /** Writable disk in MiB, 1024 to 51200. Default 10240. */
+    diskMb?: number;
+    /** Lifetime in milliseconds before the microVM stops automatically. Default 300000 (5 minutes), at most 24 hours and the plan's maximum. */
+    timeoutMs?: number;
+    /** Up to 8 ports to expose with public preview URLs (10000 and 10001 are reserved). */
+    ports?: number[];
+    /** Environment variables for every command. Never stored by the platform. */
+    env?: Record<string, string>;
+    /** String metadata to tag the microVM with. */
+    metadata?: Record<string, string>;
+    /** Region to place the microVM in. Defaults to the platform's choice. */
+    region?: string;
+    network?: MicroVmNetworkPolicy;
+}
+/** Query of `GET /microvms`. */
+interface ListMicroVmsQuery {
+    applicationId?: string;
+    status?: MicroVmStatus;
+    cursor?: string;
+    limit?: number;
+}
+/** One page of microVMs. */
+interface MicroVmPage {
+    items: MicroVmInfo[];
+    /** Pass to the next `list` call to continue; absent on the last page. */
+    nextCursor?: string;
+    /** Whether another page follows. */
+    hasMore: boolean;
+}
+/** Signals that can be sent to a command. */
+type CommandSignal = 'SIGTERM' | 'SIGKILL' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT' | 'SIGUSR1' | 'SIGUSR2';
+/** Size of a pseudo-terminal. */
+interface PtySize {
+    cols: number;
+    rows: number;
+}
+/** A command as the API returns it. */
+interface CommandInfo {
+    /** Command id (`cmd_...`). */
+    id: string;
+    cmd: string;
+    args: string[];
+    /** Working directory the command runs in. */
+    cwd: string | null;
+    /** User the command runs as. */
+    user?: string;
+    status: 'running' | 'exited';
+    /** Exit code, or `null` while running or when a signal killed the process. */
+    exitCode: number | null;
+    /** Signal that killed the process, such as `SIGKILL`. */
+    signal: string | null;
+    pid: number | null;
+    /** Whether the command runs in a pseudo-terminal. */
+    pty: boolean;
+    /** Whether the command was killed because it ran past its `timeoutMs`. */
+    timedOut: boolean;
+    /** ISO 8601 start time. */
+    startedAt: string | number;
+    finishedAt: string | number | null;
+}
+/** Body of `POST /microvms/:id/commands`. */
+interface StartCommandInput {
+    /**
+     * Executable to run. Without `args`, a `cmd` containing whitespace runs
+     * through `/bin/sh -c` (shell form, e.g. `npm install && npm test`).
+     */
+    cmd: string;
+    /** Arguments; when present `cmd` is executed directly, without a shell. */
+    args?: string[];
+    /** Working directory. Defaults to the image's working directory. */
+    cwd?: string;
+    /** Environment merged over the microVM's environment. */
+    env?: Record<string, string>;
+    /** User name, `root` or a numeric uid. Defaults to the image's user. */
+    user?: string;
+    /** Keep stdin open for `POST .../stdin`. Implied by `pty`. */
+    stdin?: boolean;
+    /** Run in a pseudo-terminal of this size (stdout and stderr are merged). */
+    pty?: PtySize;
+    /** Kill the command with SIGKILL after this many milliseconds. */
+    timeoutMs?: number;
+}
+/** Result of a command run with `wait: true`. */
+interface CommandRunResult {
+    id: string;
+    exitCode: number | null;
+    /** Signal that killed the process, if any. */
+    signal: string | null;
+    /** Whether the command was killed because it ran past its `timeoutMs`. */
+    timedOut: boolean;
+    /** UTF-8 decoded stdout, at most 1 MiB. */
+    stdout: string;
+    /** UTF-8 decoded stderr, at most 1 MiB. */
+    stderr: string;
+    /** Whether output was left out (over 1 MiB, or no longer retained). */
+    truncated: boolean;
+    durationMs: number;
+}
+/** Query of `GET /microvms/:id/commands/:cmdId/logs`. */
+interface CommandLogsQuery {
+    /** Keep the stream open until the command exits. Default `true`. */
+    follow?: boolean;
+    /** Absolute stdout byte offset to resume from. Default 0. */
+    stdoutOffset?: number;
+    /** Absolute stderr byte offset to resume from. Default 0. */
+    stderrOffset?: number;
+}
+/** Which output stream a chunk belongs to. */
+type CommandStream = 'stdout' | 'stderr';
+/** One event of a command log stream. */
+type CommandLogEvent = {
+    type: 'output';
+    stream: CommandStream;
+    /** The bytes of this chunk. */
+    data: Uint8Array;
+    /** Absolute byte offset of the first byte of {@link data} in its stream. */
+    offset: number;
+} | {
+    /** Output before the requested offsets is no longer retained (each stream keeps its last 8 MiB). */
+    type: 'truncated';
+} | {
+    /** With `follow: false` on a running command: the buffered output was sent; the command keeps running. */
+    type: 'end';
+    reason: string;
+} | {
+    type: 'exit';
+    exitCode: number | null;
+    signal: string | null;
+    /** The command ran past its timeout. Absent from APIs that predate it. */
+    timedOut?: boolean;
+    /** When the command exited. Absent from APIs that predate it. */
+    finishedAt?: string | null;
+};
+/** Type of a file system entry. */
+type FileEntryType = 'file' | 'directory' | 'symlink' | 'other';
+/** A file or directory inside a microVM. */
+interface FileEntry {
+    /** Absolute path. */
+    path: string;
+    /** Last path segment. */
+    name: string;
+    type: FileEntryType;
+    /** Size in bytes. */
+    size: number;
+    /** Octal permission bits, e.g. `0644`. */
+    mode: string;
+    /** ISO 8601 modification time. */
+    modifiedAt: string | number;
+    /** Link target, for symlinks; otherwise `null`. */
+    target?: string | null;
+}
+/** A directory listing. */
+interface FileListing {
+    entries: FileEntry[];
+    /** The listing hit its size limit; list a narrower directory. */
+    truncated: boolean;
+}
+/** Result of a file write. */
+interface FileWriteResult {
+    path: string;
+    /** Bytes written. */
+    bytes: number;
+}
+/** Where a custom image comes from. */
+type MicroVmImageSource = {
+    type: 'registry';
+    ref: string;
+} | {
+    type: 'dockerfile';
+    dockerfile: string;
+};
+/** Build state of an image. A new image starts `pending`. */
+type MicroVmImageStatus = 'pending' | 'building' | 'ready' | 'failed';
+/** A bootable microVM image. Built-in images have no application. */
+interface MicroVmImage {
+    id: string;
+    /** Name to pass as `image` when creating a microVM. */
+    name: string;
+    builtin: boolean;
+    status: MicroVmImageStatus;
+    applicationId: string | null;
+    organizationId: string | null;
+    source?: MicroVmImageSource | null;
+    /** Registry digest the build resolved. */
+    sourceDigest?: string | null;
+    /** Size of the unpacked root filesystem. */
+    sizeBytes?: number | null;
+    /** Why the last build failed. */
+    error?: string | null;
+    buildStartedAt?: string | null;
+    buildFinishedAt?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** Body of `POST /microvm-images`. */
+interface CreateMicroVmImageInput {
+    /** Owning application. Filled from the client's default application when omitted. */
+    applicationId?: string;
+    /** `^[a-z0-9][a-z0-9._-]{0,62}$`, unique per application. */
+    name: string;
+    /**
+     * The image to build: a public `linux/amd64` registry reference such as
+     * `python:3.13` or `ghcr.io/acme/tool:1`, or `{ dockerfile }` with the
+     * Dockerfile contents. Shorthand for {@link source}.
+     */
+    from?: string | {
+        dockerfile: string;
+    } | {
+        registry: string;
+    };
+    /** Raw API source. Use this or {@link from}. */
+    source?: MicroVmImageSource;
+}
+
+/** Options of a resumable command log stream. */
+interface CommandLogStreamOptions {
+    /** Keep streaming until the command exits. Default `true`. */
+    follow?: boolean;
+    /** Absolute stdout offset to start from. Default 0. */
+    stdoutOffset?: number;
+    /** Absolute stderr offset to start from. Default 0. */
+    stderrOffset?: number;
+    /**
+     * Reconnect after a dropped connection, resuming from the last received
+     * offsets. Default `true`. Set to `false` to see exactly one connection.
+     */
+    reconnect?: boolean;
+    /**
+     * How many reconnects in a row may fail to deliver anything before the
+     * stream gives up and throws. Default 5.
+     */
+    maxReconnectAttempts?: number;
+    /** Cancels the stream. */
+    signal?: AbortSignal;
+    /**
+     * Called when a following connection closes without an `exit` event. Return
+     * the exit status if the command has exited (the stream then ends with it),
+     * or `null` to reconnect.
+     */
+    resolveExit?: () => Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    } | null>;
+}
+
+/** Content accepted by file writes: text (UTF-8), bytes, a `Blob`/`File`, or a web `ReadableStream`. */
+type MicroVmFileContent = string | Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array>;
+/** Per-call request options. */
+interface MicroVmRequestOptions {
+    /** Cancels the request. */
+    signal?: AbortSignal;
+}
+/**
+ * Commands inside a microVM: `client.microvms.commands`. Every method maps to
+ * one route of `/microvms/:id/commands`. For a friendlier API use
+ * {@link MicroVM.run} and {@link MicroVM.spawn}.
+ */
+declare class MicroVmCommandsResource extends BaseResource {
+    /**
+     * Run a command and wait for it to exit (`POST /microvms/:id/commands`, `wait: true`).
+     *
+     * @example
+     * ```ts
+     * const { exitCode, stdout } = await client.microvms.commands.run(id, { cmd: 'node', args: ['-v'] });
+     * ```
+     */
+    run(microvmId: string, input: StartCommandInput, options?: MicroVmRequestOptions): Promise<CommandRunResult>;
+    /**
+     * Start a detached command and return at once (`POST /microvms/:id/commands`, `wait: false`).
+     * Follow its output with {@link logs}.
+     */
+    start(microvmId: string, input: StartCommandInput, options?: MicroVmRequestOptions): Promise<CommandInfo>;
+    /** List the microVM's commands, newest first (`GET /microvms/:id/commands`). */
+    list(microvmId: string, options?: MicroVmRequestOptions): Promise<CommandInfo[]>;
+    /** Get one command (`GET /microvms/:id/commands/:cmdId`). */
+    get(microvmId: string, commandId: string, options?: MicroVmRequestOptions): Promise<CommandInfo>;
+    /**
+     * Stream a command's output (`GET /microvms/:id/commands/:cmdId/logs`, SSE).
+     *
+     * Yields `output` events with the raw bytes and a final `exit` event. A
+     * dropped connection is reopened from the last received offsets, so no byte
+     * is lost or repeated; pass `reconnect: false` to disable that.
+     *
+     * @example
+     * ```ts
+     * for await (const event of client.microvms.commands.logs(id, commandId)) {
+     *   if (event.type === 'output') process.stdout.write(event.data);
+     *   else console.log('exit', event.exitCode);
+     * }
+     * ```
+     */
+    logs(microvmId: string, commandId: string, options?: CommandLogStreamOptions): AsyncGenerator<CommandLogEvent>;
+    /**
+     * Wait up to `timeoutMs` (at most 60000) for the command to exit
+     * (`POST /microvms/:id/commands/:cmdId/wait`). The returned command is still
+     * `running` when the wait timed out.
+     */
+    wait(microvmId: string, commandId: string, options?: {
+        timeoutMs?: number;
+    } & MicroVmRequestOptions): Promise<CommandInfo>;
+    /**
+     * Write to the command's stdin (`POST /microvms/:id/commands/:cmdId/stdin`).
+     * The command must have been started with `stdin: true` or a `pty`.
+     *
+     * @param options.eof - Close stdin after writing.
+     */
+    stdin(microvmId: string, commandId: string, data: string | Uint8Array | ArrayBuffer | Blob, options?: {
+        eof?: boolean;
+    } & MicroVmRequestOptions): Promise<void>;
+    /** Send a signal to the command's process group (`POST /microvms/:id/commands/:cmdId/signal`). */
+    signal(microvmId: string, commandId: string, signal: CommandSignal, options?: MicroVmRequestOptions): Promise<void>;
+    /** Resize a PTY command's terminal (`POST /microvms/:id/commands/:cmdId/resize`). */
+    resize(microvmId: string, commandId: string, size: PtySize, options?: MicroVmRequestOptions): Promise<void>;
+}
+/** Options of a file read. */
+interface ReadFileOptions extends MicroVmRequestOptions {
+    /** Byte offset to start reading at. */
+    offset?: number;
+    /** Maximum number of bytes to read. */
+    length?: number;
+}
+/** Options of a file write. */
+interface WriteFileOptions extends MicroVmRequestOptions {
+    /** Permission bits, as an octal string (`'0755'`) or number (`0o755`). Default `0644`. */
+    mode?: string | number;
+    /** Create missing parent directories. Default `true`. */
+    mkdirs?: boolean;
+}
+/**
+ * Files inside a microVM: `client.microvms.files`. Every method maps to one
+ * route of `/microvms/:id/files`. `vm.files` on a {@link MicroVM} binds the id.
+ * Relative paths resolve against the user's home directory.
+ */
+declare class MicroVmFilesResource extends BaseResource {
+    /** Read a file as bytes (`GET /microvms/:id/files/content`). */
+    read(microvmId: string, path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    /** Read a file as a stream of bytes, without buffering it (`GET /microvms/:id/files/content`). */
+    readStream(microvmId: string, path: string, options?: ReadFileOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Write a file, replacing it atomically (`PUT /microvms/:id/files/content`).
+     * Missing parent directories are created unless `mkdirs: false`.
+     */
+    write(microvmId: string, path: string, content: MicroVmFileContent, options?: WriteFileOptions): Promise<FileWriteResult>;
+    /**
+     * List a directory (`GET /microvms/:id/files`). `truncated` is set when the
+     * listing hit its size limit; list a narrower directory then.
+     */
+    list(microvmId: string, path: string, options?: {
+        recursive?: boolean;
+        depth?: number;
+    } & MicroVmRequestOptions): Promise<FileListing>;
+    /** Describe a file or directory without following a final symlink (`GET /microvms/:id/files/stat`). */
+    stat(microvmId: string, path: string, options?: MicroVmRequestOptions): Promise<FileEntry>;
+    /** Create a directory, with its parents unless `parents: false` (`POST /microvms/:id/files/mkdir`). */
+    mkdir(microvmId: string, path: string, options?: {
+        parents?: boolean;
+    } & MicroVmRequestOptions): Promise<FileEntry>;
+    /** Move or rename a file or directory (`POST /microvms/:id/files/move`). */
+    move(microvmId: string, from: string, to: string, options?: MicroVmRequestOptions): Promise<FileEntry>;
+    /** Delete a file, or a directory (non-empty ones need `recursive`) (`DELETE /microvms/:id/files`). */
+    remove(microvmId: string, path: string, options?: {
+        recursive?: boolean;
+    } & MicroVmRequestOptions): Promise<void>;
+    private open;
+}
+/** Options of {@link MicroVmImagesResource.waitUntilReady}. */
+interface WaitForImageOptions extends MicroVmRequestOptions {
+    /** Give up after this long. Default `'15m'`. */
+    timeout?: MicroVmDuration;
+    /** Pause between polls. Default `'2s'`. */
+    interval?: MicroVmDuration;
+    /** Called whenever the polled status changes. */
+    onStatus?: (image: MicroVmImage) => void;
+}
+/**
+ * microVM images: `client.microvms.images`. Built-in images (`node22`,
+ * `node24`, `python3.13`, `python3.12`, `bun1`, `debian12`, `ubuntu24.04`)
+ * are always available; custom images are built from a registry reference or
+ * a Dockerfile.
+ */
+declare class MicroVmImagesResource extends BaseResource {
+    private readonly defaultApplicationId;
+    constructor(httpClient: HttpClient, defaultApplicationId?: string);
+    /** List the built-in images and the application's custom images (`GET /microvm-images`). */
+    list(query?: {
+        applicationId?: string;
+    }, options?: MicroVmRequestOptions): Promise<MicroVmImage[]>;
+    /**
+     * Start building a custom image (`POST /microvm-images`). The image is
+     * `building` until {@link waitUntilReady} resolves.
+     *
+     * @example
+     * ```ts
+     * const image = await client.microvms.images.create({ name: 'py-ml', from: 'python:3.13' });
+     * await client.microvms.images.waitUntilReady(image.id);
+     * const vm = await MicroVM.create({ image: 'py-ml' });
+     * ```
+     */
+    create(input: CreateMicroVmImageInput, options?: MicroVmRequestOptions): Promise<MicroVmImage>;
+    /** Get one image (`GET /microvm-images/:id`). */
+    get(imageId: string, options?: MicroVmRequestOptions): Promise<MicroVmImage>;
+    /** Delete a custom image (`DELETE /microvm-images/:id`). */
+    delete(imageId: string, options?: MicroVmRequestOptions): Promise<void>;
+    /**
+     * Poll an image until its build finished.
+     *
+     * @throws {@link MicroVmImageBuildError} when the build failed.
+     * @throws {@link MicroVmTimeoutError} when it is still building after `timeout`.
+     */
+    waitUntilReady(imageId: string, options?: WaitForImageOptions): Promise<MicroVmImage>;
+}
+/**
+ * The microVM REST API: `client.microvms`. Every method maps to exactly one
+ * route; responses are the raw JSON shapes. Most code wants the ergonomic
+ * {@link MicroVM} class instead (`MicroVM.create`, `vm.run`, `vm.files`).
+ *
+ * @example
+ * ```ts
+ * const client = new GigadriveClient();
+ * const vm = await client.microvms.create({ image: 'python3.13', ports: [8000] });
+ * const result = await client.microvms.commands.run(vm.id, { cmd: 'python3 --version' });
+ * await client.microvms.delete(vm.id);
+ * ```
+ */
+declare class MicroVmsResource extends BaseResource {
+    /** Commands: run, start, logs, wait, stdin, signal, resize. */
+    readonly commands: MicroVmCommandsResource;
+    /** Files: read, write, list, stat, mkdir, move, remove. */
+    readonly files: MicroVmFilesResource;
+    /** Built-in and custom images. */
+    readonly images: MicroVmImagesResource;
+    private readonly defaultApplicationId;
+    constructor(httpClient: HttpClient, defaultApplicationId?: string);
+    /**
+     * Create a microVM (`POST /microvms`). Resolves once it is `running`; with
+     * `wait: false` it resolves at once with a `starting` microVM.
+     *
+     * `applicationId` defaults to the client's `applicationId` or
+     * `GIGADRIVE_APPLICATION_ID`, and may be omitted entirely with application
+     * or deployment credentials.
+     */
+    create(input?: CreateMicroVmInput, options?: {
+        wait?: boolean;
+    } & MicroVmRequestOptions): Promise<MicroVmInfo>;
+    /** List one page of microVMs, newest first (`GET /microvms`). */
+    list(query?: ListMicroVmsQuery, options?: MicroVmRequestOptions): Promise<MicroVmPage>;
+    /**
+     * Iterate every microVM across all pages.
+     *
+     * @example
+     * ```ts
+     * for await (const vm of client.microvms.listAll({ status: 'running' })) console.log(vm.id);
+     * ```
+     */
+    listAll(query?: Omit<ListMicroVmsQuery, 'cursor'>, options?: MicroVmRequestOptions): AsyncGenerator<MicroVmInfo>;
+    /** Get one microVM (`GET /microvms/:id`). */
+    get(microvmId: string, options?: MicroVmRequestOptions): Promise<MicroVmInfo>;
+    /**
+     * Set the remaining lifetime to `timeoutMs` from now (`POST /microvms/:id/timeout`),
+     * up to the plan's maximum lifetime.
+     */
+    extendTimeout(microvmId: string, timeoutMs: number, options?: MicroVmRequestOptions): Promise<MicroVmInfo>;
+    /** Stop a microVM (`POST /microvms/:id/stop`). Its disk and memory are discarded. */
+    stop(microvmId: string, options?: MicroVmRequestOptions): Promise<MicroVmInfo>;
+    /** Delete a microVM, stopping it first if needed (`DELETE /microvms/:id`). */
+    delete(microvmId: string, options?: MicroVmRequestOptions): Promise<void>;
+    /**
+     * Request a public preview URL with the client's `fetch`, without
+     * credentials and without throwing on error statuses. Used by
+     * `MicroVM.waitForPort`.
+     *
+     * @internal
+     */
+    fetchPreview(url: string, init?: RequestInit): Promise<Response>;
+}
+
 /**
  * Types for the AI Gateway runtime endpoints (`/ai/v1`). The chat/responses
  * shapes are OpenAI-compatible; additional fields are passed through, so request
@@ -3998,9 +4585,652 @@ declare class GigadriveClient {
      * handle bound to one queue.
      */
     readonly queues: QueuesResource;
+    /**
+     * microVMs: isolated Linux machines to run commands in, move files to and
+     * from, and expose ports from. This is the low-level REST surface; the
+     * {@link MicroVM} class (`MicroVM.create({ client })`) is the friendlier API.
+     */
+    readonly microvms: MicroVmsResource;
     constructor(config?: GigadriveClientConfig);
 }
 
+/** One chunk of command output. */
+interface CommandLogChunk {
+    /** `stdout` or `stderr`. PTY commands write everything to `stdout`. */
+    stream: CommandStream;
+    /** The raw bytes. */
+    data: Uint8Array;
+    /**
+     * The bytes decoded as UTF-8. A multi-byte character split across two
+     * chunks is completed in the later chunk, so concatenating `text` is safe.
+     */
+    text: string;
+    /** Absolute byte offset of the chunk in its stream. */
+    offset: number;
+}
+/** Options of {@link Command.logs}. */
+interface CommandLogsOptions {
+    /** Keep streaming until the command exits. Default `true`; `false` returns what is buffered. */
+    follow?: boolean;
+    /** Start at these absolute offsets instead of the beginning of the retained output. */
+    stdoutOffset?: number;
+    stderrOffset?: number;
+    /** Stops the stream; the iterator then throws the abort reason. */
+    signal?: AbortSignal;
+}
+/** Options of {@link Command.wait}. */
+interface CommandWaitOptions {
+    /** Give up after this long (milliseconds or `'5m'`). Default: wait indefinitely. */
+    timeout?: MicroVmDuration;
+    /** Throw {@link CommandFailedError} when the command exits non-zero or is killed. */
+    throwOnError?: boolean;
+    signal?: AbortSignal;
+}
+/** Receives output while a command runs. Returning a promise applies backpressure. */
+type CommandOutputCallback = (text: string, chunk: CommandLogChunk) => void | Promise<void>;
+/**
+ * A command running (or finished) inside a microVM. Get one from
+ * {@link MicroVM.spawn} or reattach with `vm.commands.get(id)`.
+ *
+ * Output stays in the microVM (the last 8 MiB of each stream), so any number
+ * of {@link logs} readers can replay it, from any process, and a dropped
+ * connection resumes where it stopped.
+ *
+ * @example
+ * ```ts
+ * const server = await vm.spawn('node', ['server.js']);
+ * for await (const chunk of server.logs()) {
+ *   process.stdout.write(chunk.text);
+ *   if (chunk.text.includes('listening')) break;
+ * }
+ * await vm.waitForPort(3000);
+ * await server.kill();
+ * ```
+ */
+declare class Command {
+    private readonly resource;
+    /** The microVM this command runs in. */
+    readonly microvmId: string;
+    private current;
+    private pump;
+    private pumpError;
+    private skippedOutput;
+    /** @internal Use {@link MicroVM.spawn} or `vm.commands.get(id)`. */
+    constructor(resource: MicroVmCommandsResource, 
+    /** The microVM this command runs in. */
+    microvmId: string, info: CommandInfo);
+    /** Command id (`cmd_...`). Pass it to `vm.commands.get(id)` to reattach later. */
+    get id(): string;
+    /** The latest known state. Updated by {@link refresh}, {@link wait} and the end of {@link logs}. */
+    get info(): CommandInfo;
+    get status(): CommandInfo['status'];
+    /** Exit code once exited; `null` while running or when a signal killed it. */
+    get exitCode(): number | null;
+    /** Signal that killed the process, if any. */
+    get signal(): string | null;
+    get pid(): number | null;
+    /** Whether the command was killed because it ran past its `timeout`. */
+    get timedOut(): boolean;
+    /**
+     * Whether a {@link logs} read found older output already dropped (each
+     * stream keeps its last 8 MiB), so what it delivered starts mid-stream.
+     */
+    get truncated(): boolean;
+    /** Fetch the latest state from the API. */
+    refresh(): Promise<CommandInfo>;
+    /**
+     * Stream the command's output, from the beginning of the retained output by
+     * default, until it exits. With `follow: false` it delivers what is
+     * buffered and ends, even while the command keeps running. Reconnects transparently after a dropped
+     * connection. Breaking out of the loop closes the stream; the command keeps
+     * running.
+     *
+     * @example
+     * ```ts
+     * for await (const { stream, text } of command.logs()) {
+     *   (stream === 'stdout' ? process.stdout : process.stderr).write(text);
+     * }
+     * ```
+     */
+    logs(options?: CommandLogsOptions): AsyncGenerator<CommandLogChunk>;
+    /**
+     * Collect the output from the start until the command exits.
+     *
+     * @example
+     * ```ts
+     * const { stdout } = await (await vm.spawn('ls', ['-la'])).output();
+     * ```
+     */
+    output(options?: Pick<CommandLogsOptions, 'signal'>): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /** The complete stdout as text, once the command exited. */
+    stdout(options?: Pick<CommandLogsOptions, 'signal'>): Promise<string>;
+    /** The complete stderr as text, once the command exited. */
+    stderr(options?: Pick<CommandLogsOptions, 'signal'>): Promise<string>;
+    /**
+     * Wait for the command to exit and return its final state. Output callbacks
+     * given to `spawn` have received all output when this resolves.
+     *
+     * @throws {@link MicroVmTimeoutError} when `timeout` elapses first (the command keeps running).
+     * @throws {@link CommandFailedError} with `throwOnError` when it exits non-zero or is killed.
+     */
+    wait(options?: CommandWaitOptions): Promise<CommandInfo>;
+    /**
+     * Send a signal to the command's process group. Default `SIGTERM`; use
+     * `SIGKILL` to stop it unconditionally.
+     */
+    kill(signal?: CommandSignal): Promise<void>;
+    /**
+     * Write to stdin. The command must have been spawned with `stdin: true` or a `pty`.
+     *
+     * @example
+     * ```ts
+     * const cat = await vm.spawn('cat', [], { stdin: true });
+     * await cat.write('hello\n');
+     * await cat.end();
+     * console.log(await cat.stdout()); // "hello\n"
+     * ```
+     */
+    write(data: string | Uint8Array): Promise<void>;
+    /** Close stdin, optionally writing a last piece of data first. */
+    end(data?: string | Uint8Array): Promise<void>;
+    /** Resize the terminal of a PTY command. */
+    resize(cols: number, rows: number): Promise<void>;
+    /** JSON form: the command's latest state. */
+    toJSON(): CommandInfo;
+    /**
+     * Deliver output to callbacks in the background, for `spawn` with
+     * `onStdout`/`onStderr`. {@link wait} waits for it and rethrows its error.
+     *
+     * @internal
+     */
+    startOutputPump(onStdout: CommandOutputCallback | undefined, onStderr: CommandOutputCallback | undefined): void;
+}
+
+/**
+ * The microVM is not `running` (it is still starting, or it stopped or
+ * failed), so commands, files and preview URLs are unavailable. The API
+ * answers `409 microvm_not_running`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await vm.run('ls');
+ * } catch (err) {
+ *   if (err instanceof MicroVmNotRunningError) await vm.refresh();
+ * }
+ * ```
+ */
+declare class MicroVmNotRunningError extends ApiError {
+    constructor(message?: string, code?: string, reason?: string);
+}
+/** The microVM, command or image does not exist, or the credentials cannot see it (`404`). */
+declare class MicroVmNotFoundError extends ApiError {
+    constructor(message?: string, code?: string, reason?: string);
+}
+/** A file or directory does not exist inside the microVM (`404` from a file route). */
+declare class MicroVmFileNotFoundError extends MicroVmNotFoundError {
+    /** The path that was not found. */
+    readonly path: string;
+    constructor(path: string, message?: string, code?: string);
+}
+/**
+ * The microVM is too busy to take the operation right now (`429`/`503`
+ * `microvm_busy`). Reads and log streams are retried with backoff before this
+ * surfaces; retry later.
+ */
+declare class MicroVmBusyError extends ApiError {
+    constructor(message: string, status: number, code?: string, reason?: string);
+}
+/** The platform could not reach the microVM (`502 microvm_unreachable`). Usually transient. */
+declare class MicroVmUnreachableError extends ApiError {
+    constructor(message: string, code?: string, reason?: string);
+}
+/** The image is still building or failed to build, so no microVM can boot from it yet (`409 image_not_ready`). */
+declare class MicroVmImageNotReadyError extends ApiError {
+    constructor(message: string, code?: string, reason?: string);
+}
+/**
+ * A plan limit or quota was reached, such as the number of concurrent
+ * microVMs, their size or lifetime (`429 quota_exceeded`, `403 plan_limit_exceeded`).
+ */
+declare class MicroVmQuotaExceededError extends ApiError {
+    constructor(message: string, status: number, code?: string, reason?: string);
+}
+/** The output a command produced, attached to {@link CommandFailedError}. */
+interface CommandOutput {
+    commandId: string;
+    exitCode: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+}
+/**
+ * A command exited with a non-zero code or was killed by a signal, and the
+ * caller asked for `throwOnError`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await vm.run('npm', ['test'], { throwOnError: true });
+ * } catch (err) {
+ *   if (err instanceof CommandFailedError) console.error(err.exitCode, err.stderr);
+ * }
+ * ```
+ */
+declare class CommandFailedError extends GigadriveError {
+    readonly commandId: string;
+    /** Exit code, or `null` when a signal killed the process. */
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    constructor(output: CommandOutput, label?: string);
+    /** Builds the error from a finished command whose output was not collected. */
+    static fromInfo(info: CommandInfo): CommandFailedError;
+}
+/** A wait (`waitForPort`, `waitUntilRunning`, `images.waitUntilReady`, `command.wait`) ran out of time. */
+declare class MicroVmTimeoutError extends GigadriveError {
+    constructor(message: string);
+}
+/** The microVM is not exposing the port, so it has no preview URL. Expose ports with `ports` at create. */
+declare class MicroVmPortNotExposedError extends GigadriveError {
+    readonly port: number;
+    constructor(port: number, exposed: readonly number[]);
+}
+/** The microVM failed while starting, or stopped before it was ready. */
+declare class MicroVmStartError extends GigadriveError {
+    readonly microvmId: string;
+    readonly status: string;
+    readonly stopReason: string | null;
+    constructor(microvmId: string, status: string, stopReason: string | null);
+}
+/**
+ * {@link MicroVM.create} gave up on a microVM and could not delete it either.
+ * The microVM may still boot and bill: delete it by {@link microvmId}.
+ */
+declare class MicroVmCleanupError extends GigadriveError {
+    readonly microvmId: string;
+    /** Why deleting the microVM failed. {@link Error.cause} is why creating it failed. */
+    readonly cleanupError: unknown;
+    constructor(microvmId: string, cause: unknown, cleanupError: unknown);
+}
+/** A custom image build failed. */
+declare class MicroVmImageBuildError extends GigadriveError {
+    readonly imageId: string;
+    constructor(imageId: string, message: string | null | undefined);
+}
+
+/** How a {@link MicroVM} reaches the API. */
+interface MicroVmClientOptions {
+    /**
+     * A configured {@link GigadriveClient}, or the configuration to create one.
+     * Default: a shared client configured from the environment
+     * (`GIGADRIVE_CLIENT_ID`/`GIGADRIVE_CLIENT_SECRET`, `GIGADRIVE_BEARER_TOKEN`,
+     * `GIGADRIVE_APPLICATION_ID`), which deployments and Functions receive
+     * automatically.
+     */
+    client?: GigadriveClient | GigadriveClientConfig;
+}
+/** Options of {@link MicroVM.create}. */
+interface CreateMicroVmOptions extends Omit<CreateMicroVmInput, 'network'>, MicroVmClientOptions {
+    /**
+     * Lifetime before the microVM stops automatically: milliseconds or a string
+     * such as `'10m'`. Default 5 minutes; extend it later with
+     * {@link MicroVM.extendTimeout}. Wins over `timeoutMs`.
+     */
+    timeout?: MicroVmDuration;
+    /** `'deny'` blocks all outbound traffic. Default `'allow'`. */
+    network?: MicroVmEgress | MicroVmNetworkPolicy;
+    /**
+     * Wait until the microVM is running (polling, up to 10 minutes, which covers
+     * a wait for capacity). Default `true`. With `false` the returned microVM may
+     * still be pending or starting; call {@link MicroVM.waitUntilRunning}.
+     */
+    wait?: boolean;
+    signal?: AbortSignal;
+}
+/** Options of {@link MicroVM.list}. */
+type ListMicroVmsOptions = Omit<ListMicroVmsQuery, 'cursor'> & MicroVmClientOptions;
+/** Options shared by {@link MicroVM.run} and {@link MicroVM.spawn}. */
+interface CommandOptions {
+    /** Working directory. Default: the image's working directory. */
+    cwd?: string;
+    /** Environment variables merged over the microVM's. */
+    env?: Record<string, string>;
+    /** Run as this user (name, `root` or uid). Default: the image's user. */
+    user?: string;
+    /** Run as root. Shorthand for `user: 'root'`. */
+    sudo?: boolean;
+    /** Kill the command (SIGKILL) after this long: milliseconds or `'10m'`. */
+    timeout?: MicroVmDuration;
+    /** Called with stdout text as it arrives. */
+    onStdout?: CommandOutputCallback;
+    /** Called with stderr text as it arrives. */
+    onStderr?: CommandOutputCallback;
+}
+/** Options of {@link MicroVM.run}. */
+interface RunOptions extends CommandOptions {
+    /** Data written to stdin, which is then closed. */
+    stdin?: string | Uint8Array;
+    /** Throw {@link CommandFailedError} when the command exits non-zero or is killed. */
+    throwOnError?: boolean;
+    /** Aborting kills the command (SIGKILL) and rejects with the abort reason. */
+    signal?: AbortSignal;
+}
+/** Options of {@link MicroVM.spawn}. */
+interface SpawnOptions extends CommandOptions {
+    /** Keep stdin open for {@link Command.write}. */
+    stdin?: boolean;
+    /** Run in a pseudo-terminal (`true` is 80x24). Output is merged into stdout. */
+    pty?: boolean | PtySize;
+}
+/** What {@link MicroVM.run} returns. */
+interface CommandResult {
+    commandId: string;
+    /** Exit code; `null` when a signal killed the process. */
+    exitCode: number | null;
+    /** Signal that killed the process, if any. */
+    signal: string | null;
+    /** Whether the command was killed because it ran past its `timeout`. */
+    timedOut: boolean;
+    stdout: string;
+    stderr: string;
+    /**
+     * Whether output was left out: over 1 MiB per stream for a call without
+     * callbacks, or output older than the retained 8 MiB per stream.
+     */
+    truncated: boolean;
+    durationMs: number;
+}
+/** Options of {@link MicroVM.waitForPort}. */
+interface WaitForPortOptions {
+    /** Give up after this long. Default `'60s'`. */
+    timeout?: MicroVmDuration;
+    /** Pause between probes. Default `'500ms'`. */
+    interval?: MicroVmDuration;
+    /** Path to request. Default `/`. */
+    path?: string;
+    signal?: AbortSignal;
+}
+/** Options of {@link MicroVM.waitUntilRunning}. */
+interface WaitUntilRunningOptions {
+    /** Give up after this long. Default `'2m'`. */
+    timeout?: MicroVmDuration;
+    /** Pause between polls. Default `'500ms'`. */
+    interval?: MicroVmDuration;
+    signal?: AbortSignal;
+}
+/** One file of {@link MicroVmFiles.writeMany}. */
+interface FileToWrite {
+    path: string;
+    content: MicroVmFileContent;
+    /** Permission bits, e.g. `'0755'` or `0o755`. */
+    mode?: string | number;
+}
+/**
+ * Files of one microVM: `vm.files`. Paths are absolute or relative to the
+ * user's home directory. All content is binary safe.
+ */
+declare class MicroVmFiles {
+    private readonly resource;
+    private readonly microvmId;
+    /** @internal */
+    constructor(resource: MicroVmFilesResource, microvmId: string);
+    /** Read a file as bytes. @throws {@link MicroVmFileNotFoundError} */
+    read(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    /** Read a file as UTF-8 text. */
+    readText(path: string, options?: ReadFileOptions): Promise<string>;
+    /** Read a file as a stream, for files too large to buffer. */
+    readStream(path: string, options?: ReadFileOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Write a file atomically, creating parent directories.
+     *
+     * @example
+     * ```ts
+     * await vm.files.write('/app/index.js', 'console.log("hi")');
+     * await vm.files.write('/app/logo.png', await (await fetch(url)).blob());
+     * ```
+     */
+    write(path: string, content: MicroVmFileContent, options?: WriteFileOptions): Promise<FileWriteResult>;
+    /**
+     * Write several files, a few at a time. Resolves in input order once all
+     * succeeded; rejects with the first failure.
+     *
+     * @example
+     * ```ts
+     * await vm.files.writeMany([
+     *   { path: 'app/package.json', content: JSON.stringify(pkg) },
+     *   { path: 'app/run.sh', content: '#!/bin/sh\nnode .', mode: '0755' },
+     * ]);
+     * ```
+     */
+    writeMany(files: readonly FileToWrite[], options?: {
+        concurrency?: number;
+        signal?: AbortSignal;
+    }): Promise<FileWriteResult[]>;
+    /**
+     * List a directory. `recursive` descends into subdirectories (up to `depth`
+     * levels). Very large listings are cut off; `client.microvms.files.list`
+     * reports that as `truncated`.
+     */
+    list(path?: string, options?: {
+        recursive?: boolean;
+        depth?: number;
+    }): Promise<FileEntry[]>;
+    /** Describe a file or directory. @throws {@link MicroVmFileNotFoundError} */
+    stat(path: string): Promise<FileEntry>;
+    /** Whether a file or directory exists. */
+    exists(path: string): Promise<boolean>;
+    /** Create a directory and its parents (pass `parents: false` to require the parent). */
+    mkdir(path: string, options?: {
+        parents?: boolean;
+    }): Promise<FileEntry>;
+    /** Delete a file, or a directory with `recursive: true`. */
+    remove(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Move or rename a file or directory. */
+    move(from: string, to: string): Promise<FileEntry>;
+}
+/** Commands of one microVM: `vm.commands`, for reattaching to detached commands. */
+declare class MicroVmCommands {
+    private readonly resource;
+    private readonly microvmId;
+    /** @internal */
+    constructor(resource: MicroVmCommandsResource, microvmId: string);
+    /**
+     * Reattach to a command, for example one spawned by another process.
+     *
+     * @example
+     * ```ts
+     * const command = await vm.commands.get(savedCommandId);
+     * for await (const chunk of command.logs()) process.stdout.write(chunk.data);
+     * ```
+     */
+    get(commandId: string): Promise<Command>;
+    /** All commands the microVM still remembers, newest first. */
+    list(): Promise<Command[]>;
+}
+/**
+ * An isolated Linux machine on Gigadrive Network that you can run commands
+ * in, read and write files on, and expose ports from.
+ *
+ * @example
+ * ```ts
+ * import { MicroVM } from '@gigadrive/sdk';
+ *
+ * await using vm = await MicroVM.create({ image: 'node22', ports: [3000], timeout: '10m' });
+ * await vm.files.write('server.js', 'require("http").createServer((_, r) => r.end("hi")).listen(3000)');
+ * await vm.run('npm init -y');
+ * const server = await vm.spawn('node', ['server.js']);
+ * await vm.waitForPort(3000);
+ * console.log(vm.url(3000));
+ * ```
+ */
+declare class MicroVM {
+    private readonly resource;
+    /** Files inside the microVM. */
+    readonly files: MicroVmFiles;
+    /** Reattach to commands by id. */
+    readonly commands: MicroVmCommands;
+    private current;
+    /** @internal Use {@link MicroVM.create} or {@link MicroVM.get}. */
+    constructor(resource: MicroVmsResource, info: MicroVmInfo);
+    /**
+     * Create a microVM and wait until it runs.
+     *
+     * @throws {RangeError} When `timeout` is longer than 24 hours.
+     *
+     * The application is taken from `applicationId`, the client's
+     * `applicationId` or `GIGADRIVE_APPLICATION_ID`; inside a Gigadrive
+     * deployment or Function nothing needs configuring.
+     *
+     * @example
+     * ```ts
+     * const vm = await MicroVM.create({
+     *   image: 'python3.13',
+     *   vcpus: 2,
+     *   memoryMb: 4096,
+     *   timeout: '15m',
+     *   ports: [8000],
+     *   env: { PYTHONUNBUFFERED: '1' },
+     *   metadata: { user: 'u_123' },
+     *   network: 'deny',
+     * });
+     * ```
+     */
+    static create(options?: CreateMicroVmOptions): Promise<MicroVM>;
+    /**
+     * Connect to an existing microVM by id.
+     *
+     * @throws {@link MicroVmNotFoundError} when it does not exist.
+     */
+    static get(microvmId: string, options?: MicroVmClientOptions): Promise<MicroVM>;
+    /** Alias of {@link MicroVM.get}. */
+    static connect(microvmId: string, options?: MicroVmClientOptions): Promise<MicroVM>;
+    /**
+     * Iterate microVMs, newest first, across all pages.
+     *
+     * @example
+     * ```ts
+     * for await (const vm of MicroVM.list({ status: 'running' })) {
+     *   console.log(vm.id, vm.metadata);
+     * }
+     * ```
+     */
+    static list(options?: ListMicroVmsOptions): AsyncGenerator<MicroVM>;
+    /** Stable UUID. */
+    get id(): string;
+    /** Label used in preview URLs. */
+    get slug(): string;
+    get applicationId(): string;
+    /** Status as of the last API response; call {@link refresh} for the current one. */
+    get status(): MicroVmStatus;
+    /** Exposed ports. */
+    get ports(): number[];
+    get metadata(): Record<string, string>;
+    /** When the microVM stops automatically. */
+    get expiresAt(): Date | null;
+    /** The full API object as of the last response. */
+    get info(): MicroVmInfo;
+    /**
+     * The public preview URL of an exposed port.
+     *
+     * @throws {@link MicroVmPortNotExposedError} when the port was not in `ports` at create.
+     *
+     * @example
+     * ```ts
+     * vm.url(3000); // "https://3000-k3j9x2m1q8zt.vm.gigadrive.app"
+     * ```
+     */
+    url(port: number): string;
+    /** Fetch the latest state. */
+    refresh(options?: {
+        signal?: AbortSignal;
+    }): Promise<MicroVmInfo>;
+    /**
+     * Run a command and wait for it to exit.
+     *
+     * Pass `args` to execute the program directly, or a single string to run it
+     * through `/bin/sh -c` (pipes, `&&`, globbing). Without output callbacks the
+     * call makes one request; with `onStdout`/`onStderr`, `stdin` or `signal` it
+     * starts the command detached and streams its output.
+     *
+     * A non-zero exit code is a normal result; pass `throwOnError: true` to
+     * reject with {@link CommandFailedError} instead.
+     *
+     * @example
+     * ```ts
+     * const { exitCode, stdout } = await vm.run('ls -la /app');
+     * await vm.run('npm', ['install'], { cwd: '/app', onStdout: (text) => process.stdout.write(text) });
+     * await vm.run('pytest -q', { throwOnError: true, timeout: '5m' });
+     * ```
+     */
+    run(cmd: string, options?: RunOptions): Promise<CommandResult>;
+    run(cmd: string, args: string[], options?: RunOptions): Promise<CommandResult>;
+    /**
+     * Start a command in the background and return a {@link Command} handle at
+     * once. Use it for servers, watchers and interactive programs.
+     *
+     * @example
+     * ```ts
+     * const dev = await vm.spawn('npm', ['run', 'dev'], { cwd: '/app', onStdout: console.log });
+     * await vm.waitForPort(3000);
+     *
+     * const repl = await vm.spawn('python3', [], { pty: { cols: 120, rows: 40 } });
+     * await repl.write('print(1 + 1)\n');
+     * ```
+     */
+    spawn(cmd: string, options?: SpawnOptions): Promise<Command>;
+    spawn(cmd: string, args: string[], options?: SpawnOptions): Promise<Command>;
+    /**
+     * Set the remaining lifetime to `duration` from now (up to the plan's
+     * maximum lifetime).
+     *
+     * @example
+     * ```ts
+     * await vm.extendTimeout('30m');
+     * ```
+     */
+    extendTimeout(duration: MicroVmDuration): Promise<MicroVmInfo>;
+    /** Stop the microVM. Its disk, memory and running commands are discarded. */
+    stop(): Promise<MicroVmInfo>;
+    /** Delete the microVM, stopping it first if needed. */
+    delete(): Promise<void>;
+    /**
+     * Poll until the microVM is running, for microVMs created with `wait: false`.
+     *
+     * @throws {@link MicroVmStartError} when it failed or stopped instead.
+     * @throws {@link MicroVmTimeoutError} when it is still starting after `timeout`.
+     */
+    waitUntilRunning(options?: WaitUntilRunningOptions): Promise<this>;
+    /**
+     * Poll an exposed port's preview URL until a server answers (any status
+     * other than 502, 503 or 504, which the gateway returns while nothing
+     * listens).
+     *
+     * @returns The preview URL.
+     * @throws {@link MicroVmPortNotExposedError} when the port is not exposed.
+     * @throws {@link MicroVmNotRunningError} when the microVM has stopped.
+     * @throws {@link MicroVmTimeoutError} when nothing answers within `timeout`.
+     *
+     * @example
+     * ```ts
+     * await vm.spawn('python3', ['-m', 'http.server', '8000']);
+     * const url = await vm.waitForPort(8000);
+     * ```
+     */
+    waitForPort(port: number, options?: WaitForPortOptions): Promise<string>;
+    /** Stops the microVM at the end of an `await using` block. Already stopped microVMs are fine. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** JSON form: the API object. */
+    toJSON(): MicroVmInfo;
+}
+
 /**
  * Lazily iterate every item across all pages of a cursor-paginated endpoint.
  * Pass a function that fetches one page for a given cursor; iteration stops when
@@ -4216,14 +5446,42 @@ declare function createWorkflowQueue<TMessageId extends string = string>(options
 
 /**
  * Server-Sent Events (SSE) parsing for streamed API responses (e.g. streamed
- * chat completions). Works in browsers and Node.js 18+ where `Response.body` is
- * a web `ReadableStream`.
+ * chat completions and command logs). Works in browsers, Node.js 18+, Bun,
+ * Deno and edge runtimes, wherever `Response.body` is a web `ReadableStream`.
  *
  * @internal
  */
+/** One dispatched Server-Sent Event. */
+interface ServerSentEvent {
+    /** The `event:` field, or `message` when the server sent none. */
+    event: string;
+    /** The `data:` lines of the event, joined with `\n`. */
+    data: string;
+    /** The `id:` field of this event, when the server sent one. */
+    id: string | undefined;
+    /** The `retry:` reconnection delay in milliseconds, when the server sent one. */
+    retry: number | undefined;
+}
+/**
+ * Parse an SSE stream into events, keeping the event name, id and retry
+ * fields. Comment and keep-alive blocks are skipped; iteration ends when the
+ * underlying stream closes. Breaking out of the loop cancels the response body.
+ *
+ * @param response - A streaming `fetch` response.
+ *
+ * @example
+ * ```ts
+ * for await (const event of parseSSEEvents(response)) {
+ *   if (event.event === 'exit') break;
+ *   console.log(event.event, event.data);
+ * }
+ * ```
+ */
+declare function parseSSEEvents(response: Response): AsyncGenerator<ServerSentEvent>;
 /**
  * Parse an SSE stream, yielding each event's `data` payload parsed as JSON.
- * The `[DONE]` sentinel and empty keep-alive events are skipped; iteration ends
+ * Event names are ignored (use {@link parseSSEEvents} to read them). The
+ * `[DONE]` sentinel and empty keep-alive events are skipped; iteration ends
  * when the underlying stream closes.
  *
  * @typeParam T - The shape of each streamed JSON chunk.
@@ -4231,4 +5489,4 @@ declare function createWorkflowQueue<TMessageId extends string = string>(options
  */
 declare function parseSSEStream<T = unknown>(response: Response): AsyncGenerator<T>;
 
-export { type AddCustomDomainInput, AiGatewayAudioResource, type AiGatewayBudget, type AiGatewayBudgetInput, AiGatewayBudgetsResource, AiGatewayPoliciesResource, type AiGatewayPolicy, type AiGatewayPolicyInput, type AiGatewayProviderAttempt, type AiGatewayRequestEvent, type AiGatewayRequestsQuery, AiGatewayResource, type AiGatewayUsageBreakdown, type AiGatewayUsageQuery, AiGatewayUsageResource, type AiGatewayUsageSummary, AiGatewayVideosResource, type AiModel, type AiModelCapabilities, type AiModelRoutingProvider, ApiError, type ApiKey, ApiKeysResource, type Application, ApplicationDomainsResource, ApplicationEnvVarsResource, type ApplicationHostnameList, ApplicationRequestsResource, ApplicationStorageResource, ApplicationsResource, AuthenticationError, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionContentPart, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionUsage, ConfigurationError, type CreateApiKeyInput, type CreateApiKeyResult, type CreateDeploymentInput, type CreateEnvVarInput, type CreateOrganizationInput, type CreateStickySessionUrlInput, type CreateStickySessionUrlResult, type CreateStorageBucketInput, type CreateUploadSessionInput, type CreateUploadSessionResponse, type CustomDomain, type CustomDomainState, type CustomDomainTarget, type CustomDomainTargetInput, type Deployment, type DeploymentLog, type DeploymentLogPage, type DeploymentLogType, type DeploymentStatus, DeploymentsResource, DomainNotActiveError, type DomainOwnership, type DomainProblem, type EmptyStorageTrashResult, type EnvVar, type GatewayRequestOptions, type GatewayResult, GigadriveClient, type GigadriveClientConfig, GigadriveError, type Hostname, type HostnameAvailability, type ImageCacheInspection, type ImageCachePurgeResult, ImageOptimizationResource, type ListApiKeysQuery, type ListApplicationsQuery, type ListDeploymentLogsQuery, type ListDeploymentsQuery, type ListQuery, type ListRequestsQuery, type ListStorageBucketsQuery, type ListStorageObjectsQuery, type ListStorageTrashQuery, type ListStorageUploadSessionsQuery, type ManagedImageUrlOptions, type NetworkRequest, type NetworkRequestApplicationRef, type NetworkRequestAssetRef, type NetworkRequestBucketRef, type NetworkRequestDeploymentRef, type NetworkRequestDetails, type NetworkRequestFunctionRef, type NetworkRequestMetrics, type NetworkRequestObjectRef, type NetworkRequestSummary, type NetworkResponseDetails, type NodeReadableLike, NonRetryableError, type Organization, OrganizationAiGatewayResource, OrganizationDomainsResource, OrganizationEnvVarsResource, type OrganizationMember, OrganizationMembersResource, type OrganizationMembershipRole, type OrganizationProductAccess, type OrganizationProductEntitlement, type OrganizationProductEntitlementCheck, type OrganizationProductSubscription, OrganizationProductsResource, OrganizationsResource, type Paginated, type PresignedUrlResult, type ProductAccessMode, type ProductAccessResolutionSource, type ProductDefaultAccessPolicy, type ProductDefinition, type ProductEntitlementStatus, type ProductPlan, type ProductSubscriptionStatus, type ProviderRouting, type PullEnvVarsQuery, type PullEnvVarsResult, QUEUE_DELIVERY_HEADERS, QUEUE_RESPONSE_HEADERS, QUEUE_SIGNATURE_HEADER, QUEUE_SIGNATURE_TOLERANCE_MS, QUEUE_SIGNING_SECRET_ENV, type QueryValue, Queue, type QueueAckResult, type QueueBatchSent, type QueueCodec, type QueueDuration, type QueueInfo, type QueueMessageHandler, type QueueMessageInput, type QueueMessageMeta, type QueueMessageRecord, type QueueNackResult, type QueueOptions, type QueueSchedule, type QueueScheduleInput, type QueueScopeOptions, type QueueSendOptions, type QueueSendResult, type QueueSent, type QueueSettings, type QueueSignatureInput, type QueueStats, QueuesResource, type ReceivedQueueMessage, type RequiredDnsRecord, type ResolvedEnvVar, type ResponsesRequest, type ResponsesResponse, RetryLaterError, type RunUploadOptions, type SetProductionHostnameResult, type SpeechRequest, type StartUploadResult, StickySessionsResource, type StorageBucket, type StorageBucketReference, StorageBucketsResource, type StorageEnvironmentOptions, type StorageObject, type StorageObjectAccess, type StorageObjectAccessOptions, type StorageObjectList, StorageObjectsResource, type StorageTrashList, StorageTrashResource, type StorageUploadSession, StorageUploadSessionsResource, type TranscriptionRequest, type TranscriptionResponse, type TrashedStorageObject, type UpdateCustomDomainInput, type UpdateEnvVarInput, type UploadBatchItemResult, type UploadBatchOptions, type UploadByteSource, type UploadData, UploadError, type UploadFileInput, type UploadFileResult, type UploadPart, UploadSessionExpiredError, type UploadUrlStorage, type VideoGenerationRequest, type VideoGenerationResponse, type VideoModelList, WORKFLOW_CONSUMER_PATH, WORKFLOW_QUEUE_NAME_HEADER, type WaitForCompletionOptions, type WaitUntilActiveOptions, type WorkflowQueue, type WorkflowQueueHandlerMeta, type WorkflowQueueOptions, type WorkflowQueueSendOptions, createManagedImageUrl, createWorkflowQueue, defaultQueueCodec, durationToSeconds, paginate, parseSSEStream, queue, signQueueDelivery, verifyQueueSignature };
+export { type AddCustomDomainInput, AiGatewayAudioResource, type AiGatewayBudget, type AiGatewayBudgetInput, AiGatewayBudgetsResource, AiGatewayPoliciesResource, type AiGatewayPolicy, type AiGatewayPolicyInput, type AiGatewayProviderAttempt, type AiGatewayRequestEvent, type AiGatewayRequestsQuery, AiGatewayResource, type AiGatewayUsageBreakdown, type AiGatewayUsageQuery, AiGatewayUsageResource, type AiGatewayUsageSummary, AiGatewayVideosResource, type AiModel, type AiModelCapabilities, type AiModelRoutingProvider, ApiError, type ApiKey, ApiKeysResource, type Application, ApplicationDomainsResource, ApplicationEnvVarsResource, type ApplicationHostnameList, ApplicationRequestsResource, ApplicationStorageResource, ApplicationsResource, AuthenticationError, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionContentPart, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionUsage, Command, CommandFailedError, type CommandInfo, type CommandLogChunk, type CommandLogEvent, type CommandLogStreamOptions, type CommandLogsOptions, type CommandLogsQuery, type CommandOptions, type CommandOutput, type CommandOutputCallback, type CommandResult, type CommandRunResult, type CommandSignal, type CommandStream, type CommandWaitOptions, ConfigurationError, type CreateApiKeyInput, type CreateApiKeyResult, type CreateDeploymentInput, type CreateEnvVarInput, type CreateMicroVmImageInput, type CreateMicroVmInput, type CreateMicroVmOptions, type CreateOrganizationInput, type CreateStickySessionUrlInput, type CreateStickySessionUrlResult, type CreateStorageBucketInput, type CreateUploadSessionInput, type CreateUploadSessionResponse, type CustomDomain, type CustomDomainState, type CustomDomainTarget, type CustomDomainTargetInput, type Deployment, type DeploymentLog, type DeploymentLogPage, type DeploymentLogType, type DeploymentStatus, DeploymentsResource, DomainNotActiveError, type DomainOwnership, type DomainProblem, type EmptyStorageTrashResult, type EnvVar, type FileEntry, type FileEntryType, type FileListing, type FileToWrite, type FileWriteResult, type GatewayRequestOptions, type GatewayResult, GigadriveClient, type GigadriveClientConfig, GigadriveError, type Hostname, type HostnameAvailability, type ImageCacheInspection, type ImageCachePurgeResult, ImageOptimizationResource, type ListApiKeysQuery, type ListApplicationsQuery, type ListDeploymentLogsQuery, type ListDeploymentsQuery, type ListMicroVmsOptions, type ListMicroVmsQuery, type ListQuery, type ListRequestsQuery, type ListStorageBucketsQuery, type ListStorageObjectsQuery, type ListStorageTrashQuery, type ListStorageUploadSessionsQuery, MICROVM_MAX_TIMEOUT_MS, type ManagedImageUrlOptions, MicroVM, MicroVmBusyError, MicroVmCleanupError, type MicroVmClientOptions, MicroVmCommands, MicroVmCommandsResource, type MicroVmDuration, type MicroVmEgress, type MicroVmFileContent, MicroVmFileNotFoundError, MicroVmFiles, MicroVmFilesResource, type MicroVmImage, MicroVmImageBuildError, MicroVmImageNotReadyError, type MicroVmImageSource, type MicroVmImageStatus, MicroVmImagesResource, type MicroVmInfo, type MicroVmNetworkPolicy, MicroVmNotFoundError, MicroVmNotRunningError, type MicroVmPage, type MicroVmPort, MicroVmPortNotExposedError, MicroVmQuotaExceededError, type MicroVmRequestOptions, MicroVmStartError, type MicroVmStatus, MicroVmTimeoutError, MicroVmUnreachableError, type MicroVmVcpus, MicroVmsResource, type NetworkRequest, type NetworkRequestApplicationRef, type NetworkRequestAssetRef, type NetworkRequestBucketRef, type NetworkRequestDeploymentRef, type NetworkRequestDetails, type NetworkRequestFunctionRef, type NetworkRequestMetrics, type NetworkRequestObjectRef, type NetworkRequestSummary, type NetworkResponseDetails, type NodeReadableLike, NonRetryableError, type Organization, OrganizationAiGatewayResource, OrganizationDomainsResource, OrganizationEnvVarsResource, type OrganizationMember, OrganizationMembersResource, type OrganizationMembershipRole, type OrganizationProductAccess, type OrganizationProductEntitlement, type OrganizationProductEntitlementCheck, type OrganizationProductSubscription, OrganizationProductsResource, OrganizationsResource, type Paginated, type PresignedUrlResult, type ProductAccessMode, type ProductAccessResolutionSource, type ProductDefaultAccessPolicy, type ProductDefinition, type ProductEntitlementStatus, type ProductPlan, type ProductSubscriptionStatus, type ProviderRouting, type PtySize, type PullEnvVarsQuery, type PullEnvVarsResult, QUEUE_DELIVERY_HEADERS, QUEUE_RESPONSE_HEADERS, QUEUE_SIGNATURE_HEADER, QUEUE_SIGNATURE_TOLERANCE_MS, QUEUE_SIGNING_SECRET_ENV, type QueryValue, Queue, type QueueAckResult, type QueueBatchSent, type QueueCodec, type QueueDuration, type QueueInfo, type QueueMessageHandler, type QueueMessageInput, type QueueMessageMeta, type QueueMessageRecord, type QueueNackResult, type QueueOptions, type QueueSchedule, type QueueScheduleInput, type QueueScopeOptions, type QueueSendOptions, type QueueSendResult, type QueueSent, type QueueSettings, type QueueSignatureInput, type QueueStats, QueuesResource, type ReadFileOptions, type ReceivedQueueMessage, type RequiredDnsRecord, type ResolvedEnvVar, type ResponsesRequest, type ResponsesResponse, RetryLaterError, type RunOptions, type RunUploadOptions, type ServerSentEvent, type SetProductionHostnameResult, type SpawnOptions, type SpeechRequest, type StartCommandInput, type StartUploadResult, StickySessionsResource, type StorageBucket, type StorageBucketReference, StorageBucketsResource, type StorageEnvironmentOptions, type StorageObject, type StorageObjectAccess, type StorageObjectAccessOptions, type StorageObjectList, StorageObjectsResource, type StorageTrashList, StorageTrashResource, type StorageUploadSession, StorageUploadSessionsResource, type TranscriptionRequest, type TranscriptionResponse, type TrashedStorageObject, type UpdateCustomDomainInput, type UpdateEnvVarInput, type UploadBatchItemResult, type UploadBatchOptions, type UploadByteSource, type UploadData, UploadError, type UploadFileInput, type UploadFileResult, type UploadPart, UploadSessionExpiredError, type UploadUrlStorage, type VideoGenerationRequest, type VideoGenerationResponse, type VideoModelList, WORKFLOW_CONSUMER_PATH, WORKFLOW_QUEUE_NAME_HEADER, type WaitForCompletionOptions, type WaitForImageOptions, type WaitForPortOptions, type WaitUntilActiveOptions, type WaitUntilRunningOptions, type WorkflowQueue, type WorkflowQueueHandlerMeta, type WorkflowQueueOptions, type WorkflowQueueSendOptions, type WriteFileOptions, createManagedImageUrl, createWorkflowQueue, defaultQueueCodec, durationToMs, durationToSeconds, paginate, parseSSEEvents, parseSSEStream, queue, signQueueDelivery, verifyQueueSignature };