@aerol-ai/aerolvm-sdk 0.3.1 → 0.4.1

package/dist/MicroVM.d.ts

@@ -1,7 +1,7 @@
-import { type APIVersion } from "./internal/client.js";
+import { type APIVersion, type RetryConfig } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 import { Image } from "./Image.js";
-import type { BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, Lifecycle, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
+import type { BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CreateTemplateOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, IngressTarget, Lifecycle, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template } from "./types.js";
 type FetchLike = typeof fetch;
 export interface MicroVMConfig {
     patToken?: string;
@@ -14,6 +14,13 @@ export interface MicroVMConfig {
      * other.
      */
     apiVersion?: APIVersion;
+    /**
+     * Retry policy for transient transport errors (socket closed, connection
+     * reset) and retryable HTTP status codes (429, 502, 503, 504). The SDK
+     * retries up to 3 times with exponential backoff by default. Pass
+     * `{ maxRetries: 0 }` to disable.
+     */
+    retry?: RetryConfig;
 }
 export declare class MicroVM {
     readonly apiUrl: string;
@@ -51,6 +58,42 @@ export declare class MicroVM {
     sessionLog(sandboxID: string, sessionID: string): Promise<Uint8Array>;
     sessionRecording(sandboxID: string, sessionID: string): Promise<Uint8Array>;
     attachSession(sandboxID: string, sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
+    /**
+     * Register a Firecracker rootfs template. Returns immediately with a
+     * `status: "pending"` row; poll {@link MicroVM.getTemplate} until the
+     * status reaches `"ready"` (fast-boot available) or `"ready_no_snapshot"`
+     * (cold boot only — see {@link Template.snapshotError}).
+     *
+     * Idempotent when {@link CreateTemplateOptions.id} is supplied: a
+     * duplicate ID returns 409 so a retried CI step does not create two
+     * rows for the same logical template.
+     */
+    createTemplate(options: CreateTemplateOptions): Promise<Template>;
+    listTemplates(): Promise<Template[]>;
+    getTemplate(id: string): Promise<Template>;
+    deleteTemplate(id: string): Promise<void>;
+    /**
+     * Re-run the snapshot phase against an existing template. Idempotent
+     * under concurrent retry: the daemon's CAS collapses N parallel calls
+     * for the same ready template into one rebuild kick. Returns the row in
+     * its post-transition state (typically `unhealthy`) — poll
+     * {@link MicroVM.getTemplate} to observe the transition back to `ready`.
+     *
+     * Returns 412 (raised as an error) when the template is in a state
+     * where rebuild is not safe (build in flight) or not supported
+     * (`ready_no_snapshot` / `failed` — those need delete+recreate today).
+     */
+    rebuildTemplate(id: string): Promise<Template>;
+    /**
+     * Cluster-level DNS helpers. Exposed as a namespaced accessor (rather
+     * than a flat `ingressDNS()` method) so call sites read like
+     * `microvm.dns.target()`, mirroring the per-sandbox `sandbox.customDomains`
+     * pattern. A fresh object is returned per access so the closures always
+     * see the current client even if MicroVM is later extended.
+     */
+    get dns(): {
+        target(): Promise<IngressTarget>;
+    };
     private wrap;
 }
 export {};

package/dist/MicroVM.js

@@ -19,6 +19,7 @@ export class MicroVM {
             patToken,
             fetch: config.fetch,
             apiVersion: config.apiVersion,
+            retry: config.retry,
         });
     }
     async create(options) {
@@ -109,6 +110,55 @@ export class MicroVM {
     attachSession(sandboxID, sessionID, options = {}) {
         return this.client.attachSession(sandboxID, sessionID, options);
     }
+    /**
+     * Register a Firecracker rootfs template. Returns immediately with a
+     * `status: "pending"` row; poll {@link MicroVM.getTemplate} until the
+     * status reaches `"ready"` (fast-boot available) or `"ready_no_snapshot"`
+     * (cold boot only — see {@link Template.snapshotError}).
+     *
+     * Idempotent when {@link CreateTemplateOptions.id} is supplied: a
+     * duplicate ID returns 409 so a retried CI step does not create two
+     * rows for the same logical template.
+     */
+    async createTemplate(options) {
+        return this.client.createTemplate(options);
+    }
+    async listTemplates() {
+        return this.client.listTemplates();
+    }
+    async getTemplate(id) {
+        return this.client.getTemplate(id);
+    }
+    async deleteTemplate(id) {
+        await this.client.deleteTemplate(id);
+    }
+    /**
+     * Re-run the snapshot phase against an existing template. Idempotent
+     * under concurrent retry: the daemon's CAS collapses N parallel calls
+     * for the same ready template into one rebuild kick. Returns the row in
+     * its post-transition state (typically `unhealthy`) — poll
+     * {@link MicroVM.getTemplate} to observe the transition back to `ready`.
+     *
+     * Returns 412 (raised as an error) when the template is in a state
+     * where rebuild is not safe (build in flight) or not supported
+     * (`ready_no_snapshot` / `failed` — those need delete+recreate today).
+     */
+    async rebuildTemplate(id) {
+        return this.client.rebuildTemplate(id);
+    }
+    /**
+     * Cluster-level DNS helpers. Exposed as a namespaced accessor (rather
+     * than a flat `ingressDNS()` method) so call sites read like
+     * `microvm.dns.target()`, mirroring the per-sandbox `sandbox.customDomains`
+     * pattern. A fresh object is returned per access so the closures always
+     * see the current client even if MicroVM is later extended.
+     */
+    get dns() {
+        const client = this.client;
+        return {
+            target: () => client.ingressDNS(),
+        };
+    }
     wrap(sandbox) {
         return new Sandbox(this.client, sandbox);
     }

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export { MicroVM } from "./MicroVM.js";
 export { Sandbox } from "./Sandbox.js";
 export { Image } from "./Image.js";
 export type { MicroVMConfig } from "./MicroVM.js";
-export type { BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CustomDomain, CustomDomainStatus, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, HealthStatus, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegisterSnapshotOptions, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, UpdateLifecycleOptions, } from "./types.js";
+export type { RetryConfig } from "./internal/client.js";
+export type { AddCustomDomainOptions, BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegisterSnapshotOptions, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, Template, TemplatePushState, TemplateStatus, UpdateLifecycleOptions, } from "./types.js";

package/dist/internal/api/v1/paths.d.ts

@@ -14,3 +14,15 @@ export declare function sandboxCustomDomainsPath(prefix: string, id: string): st
  * `DELETE /v1/sandboxes/{id}/custom-domains/{hostname}`.
  */
 export declare function sandboxCustomDomainPath(prefix: string, id: string, hostname: string): string;
+/**
+ * URL for the cluster's published ingress address(es), used by
+ * `microvm.dns.target()` to render the CNAME/A target a user must point
+ * custom-domain DNS at.
+ */
+export declare function ingressDNSPath(prefix: string): string;
+/**
+ * URL for the ready-to-paste DNS records of one sandbox's custom-domain
+ * bindings. Sibling of {@link sandboxCustomDomainsPath} — same `id` rules
+ * apply.
+ */
+export declare function sandboxCustomDomainDNSPath(prefix: string, id: string): string;

package/dist/internal/api/v1/paths.js

@@ -24,3 +24,19 @@ export function sandboxCustomDomainsPath(prefix, id) {
 export function sandboxCustomDomainPath(prefix, id, hostname) {
     return `${prefix}/sandboxes/${id}/custom-domains/${encodeURIComponent(hostname)}`;
 }
+/**
+ * URL for the cluster's published ingress address(es), used by
+ * `microvm.dns.target()` to render the CNAME/A target a user must point
+ * custom-domain DNS at.
+ */
+export function ingressDNSPath(prefix) {
+    return `${prefix}/ingress/dns`;
+}
+/**
+ * URL for the ready-to-paste DNS records of one sandbox's custom-domain
+ * bindings. Sibling of {@link sandboxCustomDomainsPath} — same `id` rules
+ * apply.
+ */
+export function sandboxCustomDomainDNSPath(prefix, id) {
+    return `${prefix}/sandboxes/${id}/custom-domains/dns`;
+}

package/dist/internal/client.d.ts

@@ -1,5 +1,5 @@
 import { Image } from "../Image.js";
-import type { BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CustomDomain, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, Lifecycle, ListOptions, MountSpecRedacted, NetworkUsage, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "../types.js";
+import type { AddCustomDomainOptions, BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CustomDomain, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, ListOptions, MountSpecRedacted, NetworkUsage, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template } from "../types.js";
 type FetchLike = typeof fetch;
 /**
  * Wire version of the v1-style sandbox endpoints (`/v1/sandboxes`, etc.) this
@@ -16,6 +16,27 @@ type FetchLike = typeof fetch;
  * string image.
  */
 export type APIVersion = "v1";
+/**
+ * Retry configuration for transient transport and server errors.
+ * All fields are optional — the SDK ships sensible defaults.
+ */
+export interface RetryConfig {
+    /**
+     * Maximum number of retry attempts after the initial request fails.
+     * Set to `0` to disable retry entirely. Defaults to `3`.
+     */
+    maxRetries?: number;
+    /**
+     * Initial backoff delay in milliseconds. Subsequent retries double this
+     * value (exponential backoff). Defaults to `200`.
+     */
+    baseDelayMs?: number;
+    /**
+     * Hard ceiling on the computed delay in milliseconds. Prevents unbounded
+     * waits when `maxRetries` is high. Defaults to `5000`.
+     */
+    maxDelayMs?: number;
+}
 export interface APIClientConfig {
     baseURL: string;
     patToken?: string;
@@ -26,6 +47,12 @@ export interface APIClientConfig {
      * a future major SDK release.
      */
     apiVersion?: APIVersion;
+    /**
+     * Retry policy for transient transport errors (socket closed, connection
+     * reset) and retryable HTTP status codes (429, 502, 503, 504). Pass
+     * `{ maxRetries: 0 }` to disable retry entirely.
+     */
+    retry?: RetryConfig;
 }
 export declare class APIClient {
     readonly baseURL: string;
@@ -33,6 +60,7 @@ export declare class APIClient {
     private readonly patToken;
     private readonly fetchFn;
     private readonly versionPrefix;
+    private readonly retryConfig;
     constructor(config: APIClientConfig);
     /**
      * Build a versioned API path. Pass the suffix beginning with "/" (e.g.
@@ -99,17 +127,44 @@ export declare class APIClient {
      * with an already-registered hostname is idempotent and returns the
      * existing list.
      */
-    addCustomDomain(id: string, hostname: string): Promise<CustomDomain[]>;
+    addCustomDomain(id: string, hostname: string, options?: AddCustomDomainOptions): Promise<CustomDomain[]>;
     listCustomDomains(id: string): Promise<CustomDomain[]>;
     removeCustomDomain(id: string, hostname: string): Promise<void>;
+    /**
+     * Fetch the cluster's published ingress address(es) — the CNAME/A target
+     * a user must point custom-domain DNS at. Field names already match the
+     * SDK's camelCase shape on the wire, so no translation is needed.
+     */
+    ingressDNS(): Promise<IngressTarget>;
+    /**
+     * Fetch the ready-to-paste DNS records for one sandbox's custom-domain
+     * bindings, along with the {@link IngressTarget} they were composed from.
+     */
+    customDomainDNS(id: string): Promise<CustomDomainDNSRecords>;
     reconcile(): Promise<void>;
     health(): Promise<HealthStatus>;
     mounts(id: string): Promise<MountSpecRedacted[]>;
     getNetworkUsage(id: string): Promise<NetworkUsage>;
     setNetworkLimits(id: string, options: SetNetworkLimitsOptions): Promise<NetworkUsage>;
+    createTemplate(options: CreateTemplateOptions): Promise<Template>;
+    listTemplates(): Promise<Template[]>;
+    getTemplate(id: string): Promise<Template>;
+    deleteTemplate(id: string): Promise<void>;
+    rebuildTemplate(id: string): Promise<Template>;
     private wrap;
     private doJSON;
     private doBytes;
+    /**
+     * Low-level HTTP request with automatic retry for transient failures.
+     *
+     * Transport-level errors (socket closed, connection reset, DNS blip) are
+     * always retried regardless of HTTP method — the request never reached the
+     * server so there is no idempotency concern.
+     *
+     * HTTP-level retryable codes (429, 502, 503, 504) are retried for ALL
+     * methods because every mutating endpoint in the daemon is already
+     * designed for idempotent retry (e.g. INSERT OR IGNORE + disambiguation).
+     */
     private request;
 }
 export declare class SandboxResource implements Sandbox {
@@ -164,9 +219,10 @@ export declare class SandboxResource implements Sandbox {
      * so the closures always see the current `id` even after `refresh()`.
      */
     get customDomains(): {
-        add(hostname: string): Promise<CustomDomain[]>;
+        add(hostname: string, options?: AddCustomDomainOptions): Promise<CustomDomain[]>;
         remove(hostname: string): Promise<void>;
         list(): Promise<CustomDomain[]>;
+        dns(): Promise<CustomDomainDNSRecords>;
     };
     createSnapshot(name: string): Promise<SandboxSnapshot>;
     start(): Promise<this>;

package/dist/internal/client.js

@@ -1,22 +1,75 @@
 import { basename } from "node:path";
-import { PATH_PREFIX as V1_PATH_PREFIX, sandboxCustomDomainPath as v1SandboxCustomDomainPath, sandboxCustomDomainsPath as v1SandboxCustomDomainsPath, } from "./api/v1/paths.js";
+import { PATH_PREFIX as V1_PATH_PREFIX, ingressDNSPath as v1IngressDNSPath, sandboxCustomDomainDNSPath as v1SandboxCustomDomainDNSPath, sandboxCustomDomainPath as v1SandboxCustomDomainPath, sandboxCustomDomainsPath as v1SandboxCustomDomainsPath, } from "./api/v1/paths.js";
 import { Image } from "../Image.js";
 const DEFAULT_API_VERSION = "v1";
 const PATH_PREFIXES = {
     v1: V1_PATH_PREFIX,
 };
+/** HTTP status codes the retry loop considers transient. */
+const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
+/** Default retry settings when the caller doesn't supply a RetryConfig. */
+const DEFAULT_RETRY = {
+    maxRetries: 3,
+    baseDelayMs: 200,
+    maxDelayMs: 5_000,
+};
+/**
+ * Returns `true` when the thrown `error` looks like a transport-level failure
+ * that vanishes on retry (connection reset, socket closed by peer, DNS
+ * blip). `undici` and Node core use several `cause.code` values; we check
+ * the full cause chain.
+ */
+function isTransientTransportError(error) {
+    const codes = new Set([
+        "UND_ERR_SOCKET",
+        "ECONNRESET",
+        "ECONNREFUSED",
+        "ETIMEDOUT",
+        "EPIPE",
+        "EAI_AGAIN",
+        "UND_ERR_CONNECT_TIMEOUT",
+        "UND_ERR_BODY_TIMEOUT",
+        "UND_ERR_HEADERS_TIMEOUT",
+    ]);
+    let current = error;
+    for (let depth = 0; depth < 5 && current != null; depth++) {
+        if (current instanceof Error) {
+            const code = current.code;
+            if (code && codes.has(code))
+                return true;
+            if (current.message && /socket hang up|other side closed/i.test(current.message))
+                return true;
+            current = current.cause;
+        }
+        else {
+            break;
+        }
+    }
+    return false;
+}
+/** Sleep with ±25% jitter so concurrent callers don't thundering-herd. */
+function jitteredDelay(baseMs) {
+    const jitter = 1 + (Math.random() - 0.5) * 0.5; // 0.75 – 1.25
+    return new Promise((resolve) => setTimeout(resolve, Math.round(baseMs * jitter)));
+}
 export class APIClient {
     baseURL;
     apiVersion;
     patToken;
     fetchFn;
     versionPrefix;
+    retryConfig;
     constructor(config) {
         this.baseURL = config.baseURL.replace(/\/+$/, "");
         this.patToken = config.patToken ?? "";
         this.fetchFn = config.fetch ?? fetch;
         this.apiVersion = config.apiVersion ?? DEFAULT_API_VERSION;
         this.versionPrefix = PATH_PREFIXES[this.apiVersion];
+        this.retryConfig = {
+            maxRetries: config.retry?.maxRetries ?? DEFAULT_RETRY.maxRetries,
+            baseDelayMs: config.retry?.baseDelayMs ?? DEFAULT_RETRY.baseDelayMs,
+            maxDelayMs: config.retry?.maxDelayMs ?? DEFAULT_RETRY.maxDelayMs,
+        };
     }
     /**
      * Build a versioned API path. Pass the suffix beginning with "/" (e.g.
@@ -226,8 +279,12 @@ export class APIClient {
      * with an already-registered hostname is idempotent and returns the
      * existing list.
      */
-    async addCustomDomain(id, hostname) {
-        const response = await this.doJSON("POST", v1SandboxCustomDomainsPath(this.versionPrefix, id), { hostname });
+    async addCustomDomain(id, hostname, options) {
+        const body = { hostname };
+        if (options?.port !== undefined && options.port !== 0) {
+            body.target_port = options.port;
+        }
+        const response = await this.doJSON("POST", v1SandboxCustomDomainsPath(this.versionPrefix, id), body);
         return response.custom_domains.map(fromApiCustomDomain);
     }
     async listCustomDomains(id) {
@@ -237,6 +294,21 @@ export class APIClient {
     async removeCustomDomain(id, hostname) {
         await this.doJSON("DELETE", v1SandboxCustomDomainPath(this.versionPrefix, id, hostname));
     }
+    /**
+     * Fetch the cluster's published ingress address(es) — the CNAME/A target
+     * a user must point custom-domain DNS at. Field names already match the
+     * SDK's camelCase shape on the wire, so no translation is needed.
+     */
+    async ingressDNS() {
+        return this.doJSON("GET", v1IngressDNSPath(this.versionPrefix));
+    }
+    /**
+     * Fetch the ready-to-paste DNS records for one sandbox's custom-domain
+     * bindings, along with the {@link IngressTarget} they were composed from.
+     */
+    async customDomainDNS(id) {
+        return this.doJSON("GET", v1SandboxCustomDomainDNSPath(this.versionPrefix, id));
+    }
     async reconcile() {
         await this.doJSON("POST", this.versioned("/admin/reconcile"));
     }
@@ -256,6 +328,31 @@ export class APIClient {
         const response = await this.doJSON("PATCH", `${this.versionPrefix}/sandboxes/${id}/network/limits`, toApiSetNetworkLimitsOptions(options));
         return fromApiNetworkUsage(response);
     }
+    async createTemplate(options) {
+        const response = await this.doJSON("POST", this.versioned("/templates"), {
+            id: options.id,
+            image: options.image,
+            min_size_mib: options.minSizeMiB,
+        });
+        return fromApiTemplate(response);
+    }
+    async listTemplates() {
+        const response = await this.doJSON("GET", this.versioned("/templates"));
+        // The daemon returns `null` rather than `[]` when the table is empty;
+        // normalize so callers always get an array.
+        return (response ?? []).map(fromApiTemplate);
+    }
+    async getTemplate(id) {
+        const response = await this.doJSON("GET", `${this.versionPrefix}/templates/${id}`);
+        return fromApiTemplate(response);
+    }
+    async deleteTemplate(id) {
+        await this.doJSON("DELETE", `${this.versionPrefix}/templates/${id}`);
+    }
+    async rebuildTemplate(id) {
+        const response = await this.doJSON("POST", `${this.versionPrefix}/templates/${id}/rebuild`);
+        return fromApiTemplate(response);
+    }
     wrap(sandbox) {
         return new SandboxResource(this, fromApiSandbox(sandbox));
     }
@@ -283,16 +380,49 @@ export class APIClient {
         }
         return new Uint8Array(await response.arrayBuffer());
     }
-    request(method, path, init = {}) {
+    /**
+     * Low-level HTTP request with automatic retry for transient failures.
+     *
+     * Transport-level errors (socket closed, connection reset, DNS blip) are
+     * always retried regardless of HTTP method — the request never reached the
+     * server so there is no idempotency concern.
+     *
+     * HTTP-level retryable codes (429, 502, 503, 504) are retried for ALL
+     * methods because every mutating endpoint in the daemon is already
+     * designed for idempotent retry (e.g. INSERT OR IGNORE + disambiguation).
+     */
+    async request(method, path, init = {}) {
         const headers = new Headers(init.headers);
         if (this.patToken !== "") {
             headers.set("Authorization", `Bearer ${this.patToken}`);
         }
-        return this.fetchFn(`${this.baseURL}${path}`, {
-            ...init,
-            method,
-            headers,
-        });
+        const url = `${this.baseURL}${path}`;
+        const requestInit = { ...init, method, headers };
+        const { maxRetries, baseDelayMs, maxDelayMs } = this.retryConfig;
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const response = await this.fetchFn(url, requestInit);
+                // Retry on transient HTTP status codes.
+                if (RETRYABLE_STATUS_CODES.has(response.status) && attempt < maxRetries) {
+                    const delay = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+                    await jitteredDelay(delay);
+                    continue;
+                }
+                return response;
+            }
+            catch (error) {
+                lastError = error;
+                // Only retry transport-level failures; anything else propagates.
+                if (!isTransientTransportError(error) || attempt >= maxRetries) {
+                    throw error;
+                }
+                const delay = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+                await jitteredDelay(delay);
+            }
+        }
+        // Should be unreachable — the loop always throws or returns.
+        throw lastError;
     }
 }
 export class SandboxResource {
@@ -363,9 +493,10 @@ export class SandboxResource {
         const client = this.client;
         const id = this.id;
         return {
-            add: (hostname) => client.addCustomDomain(id, hostname),
+            add: (hostname, options) => client.addCustomDomain(id, hostname, options),
             remove: (hostname) => client.removeCustomDomain(id, hostname),
             list: () => client.listCustomDomains(id),
+            dns: () => client.customDomainDNS(id),
         };
     }
     async createSnapshot(name) {
@@ -524,6 +655,25 @@ function fromApiCreateSandboxResponse(response) {
         sshPrivateKey: response.ssh_private_key,
     };
 }
+function fromApiTemplate(template) {
+    return {
+        id: template.id,
+        image: template.image,
+        status: template.status,
+        rootfsSizeBytes: template.rootfs_size_bytes,
+        minSizeMiB: template.min_size_mib,
+        lastError: template.last_error,
+        createdAt: template.created_at,
+        updatedAt: template.updated_at,
+        readyAt: template.ready_at,
+        snapshotSizeBytes: template.snapshot_size_bytes,
+        snapshotError: template.snapshot_error,
+        hasSnapshot: template.has_snapshot,
+        hasOverlay: template.has_overlay,
+        pushState: template.push_state,
+        pushError: template.push_error,
+    };
+}
 function fromApiSandboxSnapshot(snapshot) {
     return {
         name: snapshot.name,
@@ -564,6 +714,7 @@ function fromApiCustomDomain(domain) {
         lastError: domain.last_error,
         createdAt: domain.created_at,
         updatedAt: domain.updated_at,
+        targetPort: domain.target_port,
     };
 }
 function fromApiExposedPort(port) {

package/dist/types.d.ts

@@ -164,7 +164,7 @@ export interface CreateOptions {
      *
      * GPU access is not supported with `"gvisor"`.
      */
-    runtime?: "docker" | "gvisor" | "kata";
+    runtime?: "docker" | "gvisor" | "kata" | "firecracker";
     /**
      * Attach GPU resources to the sandbox. Omit for CPU-only workloads.
      * Not compatible with runtime="gvisor".
@@ -240,6 +240,70 @@ export interface CustomDomain {
     lastError?: string;
     createdAt: string;
     updatedAt: string;
+    /**
+     * Target container port traffic to this hostname dials. `0` (or omitted)
+     * means the sandbox's toolbox port — the default that preserves the
+     * pre-target-port behavior. Set once at attach time; to change it, remove
+     * the binding and re-add it with the new port.
+     */
+    targetPort?: number;
+}
+/**
+ * Options for `sandbox.customDomains.add()`. `port` pins the container port
+ * traffic to this hostname dials; omit it to route to the sandbox's toolbox
+ * port (the default). Re-adding the same hostname with a different `port`
+ * returns 409 — detach first.
+ */
+export interface AddCustomDomainOptions {
+    port?: number;
+}
+/**
+ * Where the SDK derived the ingress address(es) from. Reflects how the
+ * operator deployed the cluster:
+ *   - "hostname": the cluster gossips a stable hostname (CNAME target).
+ *   - "ips":      one or more raw ingress IPs (one A/AAAA record per IP).
+ *   - "mixed":    some nodes gossip a hostname, others raw IPs — prefer
+ *                 the hostname but render both so apex domains still work.
+ *   - "unknown":  no ingress node has gossiped a public address yet; the
+ *                 target is unusable and callers should surface that, not
+ *                 guess.
+ */
+export type IngressTargetSource = "hostname" | "ips" | "mixed" | "unknown";
+/**
+ * The cluster's published ingress address(es) — the value that DNS for a
+ * custom domain must ultimately resolve to. Returned by `microvm.dns.target()`
+ * and embedded in {@link CustomDomainDNSRecords}.
+ */
+export interface IngressTarget {
+    hostname?: string;
+    ips?: string[];
+    source: IngressTargetSource;
+}
+/** DNS record types the daemon emits for custom-domain wiring. */
+export type DNSRecordType = "CNAME" | "A" | "AAAA";
+/**
+ * One ready-to-paste DNS record a user adds at their DNS provider to make a
+ * custom domain reach the cluster. `name` is the leftmost label (or "@" for
+ * apex) the way DNS UIs accept it. `notes` carries provider-specific gotchas
+ * the daemon pre-renders (e.g. Cloudflare "DNS only, gray cloud") when
+ * applicable.
+ */
+export interface DNSRecord {
+    hostname: string;
+    type: DNSRecordType;
+    name: string;
+    value: string;
+    notes?: string;
+}
+/**
+ * Response from `sandbox.customDomains.dns()`. `records` is the flat
+ * ready-to-paste list (one row per custom domain × per ingress address);
+ * `target` is the raw aggregation the records were composed from, included
+ * so callers can render their own UI without a second round trip.
+ */
+export interface CustomDomainDNSRecords {
+    records: DNSRecord[];
+    target: IngressTarget;
 }
 /**
  * Wire protocol an exposure publishes through:
@@ -311,7 +375,7 @@ export interface Sandbox {
      * Container runtime this sandbox is running under. Empty string indicates
      * a pre-migration row that resolves to the host default at start time.
      */
-    runtime: "" | "docker" | "gvisor" | "kata";
+    runtime: "" | "docker" | "gvisor" | "kata" | "firecracker";
     /** GPU configuration this sandbox was created with. Absent means no GPU. */
     gpus?: GPUOptions;
 }
@@ -406,3 +470,63 @@ export interface HealthStatus {
     version: string;
 }
 export type BinaryLike = Uint8Array | ArrayBuffer | Blob | string;
+/**
+ * Lifecycle states reported by a Firecracker rootfs template. See
+ * `plans/snapshot-clone-fast-boot.md` for the state machine.
+ *
+ * - `pending`, `building_rootfs`, `snapshotting`: the build pipeline is in
+ *   flight; no sandbox creation against this template will succeed yet.
+ * - `ready`: cold boot + fast snapshot clone both available.
+ * - `ready_no_snapshot`: cold boot works; snapshot phase failed and
+ *   sandboxes will not get the fast-boot path until a rebuild succeeds.
+ * - `unhealthy`: snapshot was detected as corrupt; an async rebuild is in
+ *   flight (or pending the next daemon restart).
+ * - `failed`: terminal state from a failed initial build; the row must be
+ *   deleted and recreated.
+ */
+export type TemplateStatus = "pending" | "building_rootfs" | "snapshotting" | "ready" | "ready_no_snapshot" | "failed" | "unhealthy";
+/**
+ * Background-push state for the template's artifacts (rootfs.ext4 +
+ * snapshot.*). "active" means push succeeded or push is disabled; "pending"
+ * / "pushing" are in-flight states; "error" carries `pushError` for the
+ * last failure.
+ */
+export type TemplatePushState = "active" | "pending" | "pushing" | "error";
+/**
+ * A Firecracker rootfs template. Created once from an OCI image and
+ * boot-shared across many sandboxes. Use {@link MicroVM.createTemplate} to
+ * register one, then pass its {@link Template.id} on subsequent sandbox
+ * `create` calls (when the sandbox runtime is `firecracker`).
+ */
+export interface Template {
+    id: string;
+    image: string;
+    status: TemplateStatus;
+    rootfsSizeBytes?: number;
+    /** Optional floor for the ext4 image size, in MiB. */
+    minSizeMiB?: number;
+    /** Last build-pipeline error, populated when `status` is `failed`. */
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+    /** First time the template reached `ready` / `ready_no_snapshot`. */
+    readyAt?: string;
+    snapshotSizeBytes?: number;
+    /** Populated when `status` is `ready_no_snapshot` — why the snapshot phase failed. */
+    snapshotError?: string;
+    /** True when the template has a usable snapshot for fast-boot. */
+    hasSnapshot: boolean;
+    /** True when the template was built with a per-sandbox writable overlay placeholder. */
+    hasOverlay: boolean;
+    pushState?: TemplatePushState;
+    /** Populated when `pushState` is `error` — the last push failure. */
+    pushError?: string;
+}
+export interface CreateTemplateOptions {
+    /** Optional explicit ID. Empty means the daemon generates one. Supplying an explicit ID lets retries be idempotent — a duplicate ID returns 409. */
+    id?: string;
+    /** skopeo-style image reference, e.g. `"docker://python:3.11"`. */
+    image: string;
+    /** Optional floor for the ext4 image size, in MiB. */
+    minSizeMiB?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,7 @@
     "test": "tsc -p tsconfig.test.json --outDir dist-test && node --test dist-test/*.test.js dist-test/internal/*.test.js"
   },
   "devDependencies": {
-    "@types/node": "^25.8.0",
+    "@types/node": "^25.9.1",
     "typescript": "^6.0.3",
     "tsx": "^4.22.3"
   }