@aerol-ai/aerolvm-sdk 0.3.2 → 0.5.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, IngressTarget, 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,32 @@ 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

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,42 @@ 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

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, 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, 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/client.d.ts

@@ -1,5 +1,5 @@
 import { Image } from "../Image.js";
-import type { BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CustomDomain, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, 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,7 +127,7 @@ 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>;
     /**
@@ -118,9 +146,25 @@ export declare class APIClient {
     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 {
@@ -175,7 +219,7 @@ 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>;

package/dist/internal/client.js

@@ -5,18 +5,71 @@ 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) {
@@ -271,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));
     }
@@ -298,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 {
@@ -378,7 +493,7 @@ 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),
@@ -540,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,
@@ -580,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,22 @@ 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
@@ -263,8 +279,13 @@ export interface IngressTarget {
     ips?: string[];
     source: IngressTargetSource;
 }
-/** DNS record types the daemon emits for custom-domain wiring. */
-export type DNSRecordType = "CNAME" | "A" | "AAAA";
+/**
+ * DNS record types the daemon emits for custom-domain wiring. `ANAME` and
+ * `ALIAS` only appear for an apex domain on a hostname ingress, where they are
+ * mutually-exclusive flattening alternatives to `CNAME` (add the one your
+ * provider supports — see each record's `notes`).
+ */
+export type DNSRecordType = "CNAME" | "A" | "AAAA" | "ANAME" | "ALIAS";
 /**
  * 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
@@ -359,7 +380,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;
 }
@@ -454,3 +475,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.2",
+  "version": "0.5.1",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -23,6 +23,6 @@
   "devDependencies": {
     "@types/node": "^25.9.1",
     "typescript": "^6.0.3",
-    "tsx": "^4.22.3"
+    "tsx": "^4.22.4"
   }
 }