@aerol-ai/aerolvm-sdk 0.1.8 → 0.1.10

package/dist/Image.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Image is a fluent Dockerfile builder. The shape mirrors the Daytona SDK's
+ * Image API so examples port across by changing the import. The output is a
+ * Dockerfile string accessible via `.dockerfile` — the SDK ships it to
+ * `POST /v1/images/build` when an Image is passed to `MicroVM.create`.
+ *
+ * Caller-side context (COPY/ADD from local files) needs the
+ * SB_IMAGE_BUILD_CONTEXT_ENABLED operator flag on the daemon. Without that,
+ * use only `runCommands`, `env`, `workdir`, `entrypoint`, `cmd`, `user`, and
+ * `expose` — every step they emit is RUN/ENV/WORKDIR/etc. against the base
+ * image, no local files involved.
+ */
+export declare class Image {
+    private _dockerfile;
+    private constructor();
+    get dockerfile(): string;
+    /** Start a new image from `FROM <image>`. */
+    static base(image: string): Image;
+    /**
+     * Build from a raw Dockerfile string. Use when you need full control
+     * (multi-stage builds, ARG, ONBUILD, HEALTHCHECK, etc.) that the fluent
+     * API doesn't expose. Caller is responsible for the Dockerfile validity.
+     */
+    static fromDockerfile(dockerfile: string): Image;
+    /**
+     * Append one or more RUN steps. Each argument becomes its own RUN line;
+     * an array argument is joined with `&&` so the commands share one layer.
+     */
+    runCommands(...commands: (string | string[])[]): Image;
+    /** Append ENV K=V pairs (one ENV line per call, all vars on it). */
+    env(envVars: Record<string, string>): Image;
+    workdir(dirPath: string): Image;
+    entrypoint(entrypointCommands: string[]): Image;
+    cmd(cmd: string[]): Image;
+    user(username: string): Image;
+    expose(port: number): Image;
+}

package/dist/Image.js

@@ -0,0 +1,107 @@
+/**
+ * Image is a fluent Dockerfile builder. The shape mirrors the Daytona SDK's
+ * Image API so examples port across by changing the import. The output is a
+ * Dockerfile string accessible via `.dockerfile` — the SDK ships it to
+ * `POST /v1/images/build` when an Image is passed to `MicroVM.create`.
+ *
+ * Caller-side context (COPY/ADD from local files) needs the
+ * SB_IMAGE_BUILD_CONTEXT_ENABLED operator flag on the daemon. Without that,
+ * use only `runCommands`, `env`, `workdir`, `entrypoint`, `cmd`, `user`, and
+ * `expose` — every step they emit is RUN/ENV/WORKDIR/etc. against the base
+ * image, no local files involved.
+ */
+export class Image {
+    _dockerfile = "";
+    constructor(dockerfile) {
+        this._dockerfile = dockerfile;
+    }
+    get dockerfile() {
+        return this._dockerfile;
+    }
+    /** Start a new image from `FROM <image>`. */
+    static base(image) {
+        if (typeof image !== "string" || image.trim() === "") {
+            throw new TypeError("Image.base requires a non-empty image string");
+        }
+        return new Image(`FROM ${image.trim()}\n`);
+    }
+    /**
+     * Build from a raw Dockerfile string. Use when you need full control
+     * (multi-stage builds, ARG, ONBUILD, HEALTHCHECK, etc.) that the fluent
+     * API doesn't expose. Caller is responsible for the Dockerfile validity.
+     */
+    static fromDockerfile(dockerfile) {
+        if (typeof dockerfile !== "string" || dockerfile.trim() === "") {
+            throw new TypeError("Image.fromDockerfile requires a non-empty Dockerfile string");
+        }
+        return new Image(dockerfile.endsWith("\n") ? dockerfile : dockerfile + "\n");
+    }
+    /**
+     * Append one or more RUN steps. Each argument becomes its own RUN line;
+     * an array argument is joined with `&&` so the commands share one layer.
+     */
+    runCommands(...commands) {
+        for (const entry of commands) {
+            if (Array.isArray(entry)) {
+                const joined = entry.map((c) => c.trim()).filter(Boolean).join(" && ");
+                if (joined !== "") {
+                    this._dockerfile += `RUN ${joined}\n`;
+                }
+                continue;
+            }
+            const cmd = entry.trim();
+            if (cmd !== "") {
+                this._dockerfile += `RUN ${cmd}\n`;
+            }
+        }
+        return this;
+    }
+    /** Append ENV K=V pairs (one ENV line per call, all vars on it). */
+    env(envVars) {
+        const parts = Object.entries(envVars).map(([k, v]) => `${k}=${dockerQuote(v)}`);
+        if (parts.length > 0) {
+            this._dockerfile += `ENV ${parts.join(" ")}\n`;
+        }
+        return this;
+    }
+    workdir(dirPath) {
+        if (dirPath.trim() === "") {
+            throw new TypeError("Image.workdir requires a non-empty path");
+        }
+        this._dockerfile += `WORKDIR ${dirPath}\n`;
+        return this;
+    }
+    entrypoint(entrypointCommands) {
+        this._dockerfile += `ENTRYPOINT ${jsonExecForm(entrypointCommands)}\n`;
+        return this;
+    }
+    cmd(cmd) {
+        this._dockerfile += `CMD ${jsonExecForm(cmd)}\n`;
+        return this;
+    }
+    user(username) {
+        if (username.trim() === "") {
+            throw new TypeError("Image.user requires a non-empty username");
+        }
+        this._dockerfile += `USER ${username}\n`;
+        return this;
+    }
+    expose(port) {
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new RangeError(`Image.expose: port ${port} is out of range`);
+        }
+        this._dockerfile += `EXPOSE ${port}\n`;
+        return this;
+    }
+}
+function dockerQuote(value) {
+    // Quote when the value contains whitespace or a special char; otherwise
+    // leave bare to match canonical Dockerfile style.
+    if (/^[A-Za-z0-9_\-./:@]+$/.test(value)) {
+        return value;
+    }
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function jsonExecForm(parts) {
+    return JSON.stringify(parts);
+}

package/dist/MicroVM.d.ts

@@ -1,6 +1,7 @@
 import { type APIVersion } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
-import type { CreateOptions, CreateSessionOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, Lifecycle, MountSpecRedacted, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
+import { Image } from "./Image.js";
+import type { BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, Lifecycle, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
 type FetchLike = typeof fetch;
 export interface MicroVMConfig {
     patToken?: string;
@@ -25,10 +26,19 @@ export declare class MicroVM {
     start(id: string): Promise<Sandbox>;
     stop(id: string): Promise<Sandbox>;
     createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
+    registerSnapshot(options: RegisterSnapshotOptions): Promise<SandboxSnapshot>;
+    registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">): Promise<SandboxSnapshot>;
     destroy(id: string): Promise<void>;
     resize(id: string, options: ResizeOptions): Promise<Sandbox>;
     updateLifecycle(id: string, lifecycle: Lifecycle): Promise<Sandbox>;
     reconcile(): Promise<void>;
+    /**
+     * Build an {@link Image} on the daemon and optionally push the result to a
+     * remote registry. Push credentials are forwarded per request and never
+     * persisted by the daemon. Returns the local content-addressed tag and,
+     * when push was requested, the pushed reference.
+     */
+    buildImage(image: Image, options?: BuildImageOptions): Promise<BuildImageResult>;
     health(): Promise<HealthStatus>;
     mounts(sandboxID: string): Promise<MountSpecRedacted[]>;
     execStream(sandboxID: string, options: ExecStreamOptions): ExecStreamHandle;

package/dist/MicroVM.js

@@ -44,6 +44,12 @@ export class MicroVM {
     async createSnapshot(id, name) {
         return this.client.createSnapshot(id, name);
     }
+    async registerSnapshot(options) {
+        return this.client.registerSnapshot(options);
+    }
+    async registerSnapshotFromImage(name, image, options = {}) {
+        return this.client.registerSnapshotFromImage(name, image, options);
+    }
     async destroy(id) {
         await this.client.destroy(id);
     }
@@ -58,6 +64,15 @@ export class MicroVM {
     async reconcile() {
         await this.client.reconcile();
     }
+    /**
+     * Build an {@link Image} on the daemon and optionally push the result to a
+     * remote registry. Push credentials are forwarded per request and never
+     * persisted by the daemon. Returns the local content-addressed tag and,
+     * when push was requested, the pushed reference.
+     */
+    async buildImage(image, options) {
+        return this.client.buildImage(image, options);
+    }
     async health() {
         return this.client.health();
     }

package/dist/index.d.ts

@@ -1,4 +1,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, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, HealthStatus, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, UpdateLifecycleOptions, } from "./types.js";
+export type { BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, HealthStatus, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegisterSnapshotOptions, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, UpdateLifecycleOptions, } from "./types.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { MicroVM } from "./MicroVM.js";
 export { Sandbox } from "./Sandbox.js";
+export { Image } from "./Image.js";

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

@@ -1,7 +1,7 @@
 // v1 path-prefix constant. The TypeScript SDK uses this to build URLs against
-// the v1 surface of the sandbox daemon. When v2 lands, a sibling
-// internal/api/v2/paths.ts will export its own PATH_PREFIX, and the client
-// constructor's apiVersion option selects which one to use.
+// the v1 surface of the sandbox daemon. When a new wire version lands, a
+// sibling internal/api/vN/paths.ts will export its own PATH_PREFIX, and the
+// client constructor's apiVersion option selects which one to use.
 //
 // Keep this in sync with pkg/api/v1/dto.go::PathPrefix on the server.
 export const PATH_PREFIX = "/v1";

package/dist/internal/client.d.ts

@@ -1,10 +1,19 @@
-import type { BinaryLike, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, HealthStatus, Lifecycle, MountSpecRedacted, NetworkUsage, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "../types.js";
+import { Image } from "../Image.js";
+import type { BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, HealthStatus, Lifecycle, MountSpecRedacted, NetworkUsage, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "../types.js";
 type FetchLike = typeof fetch;
 /**
- * Wire version of the sandbox daemon API this client speaks. The SDK and the
- * server version independently — bumping the SDK package does not move the
- * wire version. Today only "v1" exists; "v2" will be added when a wire-level
- * breaking change is needed on the server.
+ * Wire version of the v1-style sandbox endpoints (`/v1/sandboxes`, etc.) this
+ * client speaks. The SDK and the server version independently — bumping the
+ * SDK package does not move the wire version. Today only "v1" exists; future
+ * breaking changes to the sandbox endpoints will land in a new version
+ * prefix.
+ *
+ * The `/v1/images/build` endpoint used by {@link Image}-shaped image inputs
+ * is called unconditionally when an Image is supplied to
+ * {@link APIClient.create}, regardless of `apiVersion`. Daemons older than
+ * the image-build feature return 404; the SDK turns that into a clear
+ * "daemon does not support image builds" error so the user can switch to a
+ * string image.
  */
 export type APIVersion = "v1";
 export interface APIClientConfig {
@@ -28,16 +37,31 @@ export declare class APIClient {
     /**
      * Build a versioned API path. Pass the suffix beginning with "/" (e.g.
      * "/sandboxes") and the active version's prefix is prepended. Use this for
-     * every versioned API call so v2 (when it lands) can be selected by the
+     * every versioned API call so a future wire version can be selected by the
      * apiVersion option without touching call sites.
      */
     private versioned;
     create(options: CreateOptions): Promise<SandboxResource>;
+    /**
+     * Compile a fluent {@link Image} into a content-addressed image tag by
+     * POSTing its Dockerfile to `/v1/images/build`. The daemon caches by
+     * content hash, so repeated calls with the same Dockerfile are a no-op.
+     * String images are passed through unchanged.
+     *
+     * Daemons predating the image-build feature do not register the route and
+     * return 404; this method translates that into a clear error telling the
+     * caller to pass a string image instead, rather than the generic "request
+     * failed with status 404" the JSON decoder would otherwise produce.
+     */
+    buildImage(image: Image, options?: BuildImageOptions): Promise<BuildImageResult>;
+    private resolveImage;
     list(): Promise<SandboxResource[]>;
     get(id: string): Promise<SandboxResource>;
     start(id: string): Promise<SandboxResource>;
     stop(id: string): Promise<SandboxResource>;
     createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
+    registerSnapshot(options: RegisterSnapshotOptions): Promise<SandboxSnapshot>;
+    registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">): Promise<SandboxSnapshot>;
     destroy(id: string): Promise<void>;
     resize(id: string, options: ResizeOptions): Promise<SandboxResource>;
     updateLifecycle(id: string, lifecycle: Lifecycle): Promise<SandboxResource>;

package/dist/internal/client.js

@@ -1,5 +1,6 @@
 import { basename } from "node:path";
 import { PATH_PREFIX as V1_PATH_PREFIX } from "./api/v1/paths.js";
+import { Image } from "../Image.js";
 const DEFAULT_API_VERSION = "v1";
 const PATH_PREFIXES = {
     v1: V1_PATH_PREFIX,
@@ -20,16 +21,70 @@ export class APIClient {
     /**
      * Build a versioned API path. Pass the suffix beginning with "/" (e.g.
      * "/sandboxes") and the active version's prefix is prepended. Use this for
-     * every versioned API call so v2 (when it lands) can be selected by the
+     * every versioned API call so a future wire version can be selected by the
      * apiVersion option without touching call sites.
      */
     versioned(suffix) {
         return `${this.versionPrefix}${suffix}`;
     }
     async create(options) {
-        const response = await this.doJSON("POST", this.versioned("/sandboxes"), toApiCreateOptions(options));
+        const resolved = await this.resolveImage(options);
+        const response = await this.doJSON("POST", this.versioned("/sandboxes"), toApiCreateOptions(resolved));
         return new SandboxResource(this, fromApiCreateSandboxResponse(response));
     }
+    /**
+     * Compile a fluent {@link Image} into a content-addressed image tag by
+     * POSTing its Dockerfile to `/v1/images/build`. The daemon caches by
+     * content hash, so repeated calls with the same Dockerfile are a no-op.
+     * String images are passed through unchanged.
+     *
+     * Daemons predating the image-build feature do not register the route and
+     * return 404; this method translates that into a clear error telling the
+     * caller to pass a string image instead, rather than the generic "request
+     * failed with status 404" the JSON decoder would otherwise produce.
+     */
+    async buildImage(image, options) {
+        const body = { dockerfile_content: image.dockerfile };
+        if (options?.push) {
+            const p = options.push;
+            if (!p.registry) {
+                throw new Error("buildImage: push.registry is required when push is set");
+            }
+            if (!p.username || !p.password) {
+                throw new Error("buildImage: push.username and push.password are required when push is set");
+            }
+            body.push = {
+                registry: p.registry,
+                tag: p.tag,
+                server: p.server,
+                username: p.username,
+                password: p.password,
+            };
+        }
+        const response = await this.request("POST", "/v1/images/build", {
+            body: JSON.stringify(body),
+            headers: { "Content-Type": "application/json" },
+        });
+        if (response.status === 404) {
+            await response.text().catch(() => undefined);
+            throw new Error("this daemon does not support Image builds (POST /v1/images/build is not registered) — pass a string image reference (e.g. \"ubuntu:22.04\") instead, or upgrade the daemon");
+        }
+        if (!response.ok) {
+            throw await decodeError(response);
+        }
+        const payload = (await response.json());
+        return { image: payload.image, pushed: payload.pushed };
+    }
+    async resolveImage(options) {
+        if (typeof options.image === "string") {
+            return options;
+        }
+        if (!(options.image instanceof Image)) {
+            throw new TypeError("CreateOptions.image must be a string or Image");
+        }
+        const result = await this.buildImage(options.image);
+        return { ...options, image: result.image };
+    }
     async list() {
         const response = await this.doJSON("GET", this.versioned("/sandboxes"));
         return response.map((item) => this.wrap(item));
@@ -50,6 +105,35 @@ export class APIClient {
         const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/snapshot`, { name });
         return fromApiSandboxSnapshot(response);
     }
+    async registerSnapshot(options) {
+        const name = options.name.trim();
+        if (name === "") {
+            throw new Error("name is required");
+        }
+        const image = options.image?.trim() ?? "";
+        const dockerfileContent = options.dockerfileContent?.trim() ?? "";
+        if (image === "" && dockerfileContent === "") {
+            throw new Error("image or dockerfile_content is required");
+        }
+        if (image !== "" && dockerfileContent !== "") {
+            throw new Error("image and dockerfile_content are mutually exclusive");
+        }
+        const response = await this.doJSON("POST", this.versioned("/snapshots"), toApiRegisterSnapshotOptions({
+            ...options,
+            name,
+            image: image || undefined,
+            dockerfileContent: dockerfileContent || undefined,
+            regionID: options.regionID?.trim() || undefined,
+        }));
+        return fromApiSandboxSnapshot(response);
+    }
+    async registerSnapshotFromImage(name, image, options = {}) {
+        return this.registerSnapshot({
+            ...options,
+            name,
+            dockerfileContent: image.dockerfile,
+        });
+    }
     async destroy(id) {
         await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}`);
     }
@@ -306,6 +390,20 @@ function toApiCreateOptions(options) {
         runtime: options.runtime,
     };
 }
+function toApiRegisterSnapshotOptions(options) {
+    return {
+        name: options.name,
+        image: options.image,
+        dockerfile_content: options.dockerfileContent,
+        context_hashes: options.contextHashes,
+        entrypoint: options.entrypoint,
+        region_id: options.regionID,
+        cpu: options.cpu,
+        gpu: options.gpu,
+        memory_mb: options.memoryMB,
+        disk_gb: options.diskGB,
+    };
+}
 function toApiResizeOptions(options) {
     return {
         cpu: options.cpu,
@@ -389,6 +487,12 @@ function fromApiSandboxSnapshot(snapshot) {
         imageID: snapshot.image_id,
         sourceSandboxID: snapshot.source_sandbox_id,
         createdAt: snapshot.created_at,
+        entrypoint: snapshot.entrypoint,
+        regionID: snapshot.region_id,
+        cpu: snapshot.cpu,
+        gpu: snapshot.gpu,
+        memoryMB: snapshot.memory_mb,
+        diskGB: snapshot.disk_gb,
     };
 }
 function fromApiSession(session) {

package/dist/types.d.ts

@@ -4,6 +4,49 @@ export interface RegistryAuth {
     username: string;
     password: string;
 }
+/**
+ * Per-request push directive for `MicroVM.buildImage`. Credentials are
+ * forwarded to the daemon as a one-shot `X-Registry-Auth` header on the
+ * push call and are never persisted.
+ */
+export interface BuildImagePushOptions {
+    /** Destination repository, e.g. "ghcr.io/my-org/my-image". */
+    registry: string;
+    /** Destination tag. Defaults to "latest" on the daemon when omitted. */
+    tag?: string;
+    /** Registry serveraddress, e.g. "ghcr.io". Sent inside X-Registry-Auth. */
+    server?: string;
+    username: string;
+    password: string;
+}
+export interface BuildImageOptions {
+    push?: BuildImagePushOptions;
+}
+export interface BuildImageResult {
+    /** Local content-addressed tag (always returned). */
+    image: string;
+    /** Pushed reference, e.g. "ghcr.io/my-org/my-image:v1.2.3". */
+    pushed?: string;
+}
+export interface RegisterSnapshotOptions {
+    /** Human-readable identifier other callers use in `CreateOptions.snapshot`. */
+    name: string;
+    /** Pre-built registry reference. Mutually exclusive with `dockerfileContent`. */
+    image?: string;
+    /** Literal Dockerfile the daemon will build. Mutually exclusive with `image`. */
+    dockerfileContent?: string;
+    /** Uploaded build-context hashes for future COPY/ADD resolution. */
+    contextHashes?: string[];
+    /** Optional command override persisted on the snapshot row. */
+    entrypoint?: string[];
+    /** Region hint persisted for read-back. */
+    regionID?: string;
+    /** Resource hints surfaced back on the snapshot row. */
+    cpu?: number;
+    gpu?: number;
+    memoryMB?: number;
+    diskGB?: number;
+}
 export type MountType = "s3" | "nfs" | "sshfs" | "rclone";
 export interface MountSpec {
     type: MountType;
@@ -60,8 +103,17 @@ export interface GPUOptions {
      */
     deviceIDs?: string[];
 }
+import type { Image } from "./Image.js";
 export interface CreateOptions {
-    image: string;
+    /**
+     * The base image for this sandbox. A bare image reference (e.g.
+     * `"ubuntu:22.04"`) is pulled by the daemon as-is. An {@link Image} builder
+     * is compiled to a Dockerfile and sent to the daemon's
+     * `POST /v1/images/build` endpoint; the resulting content-addressed tag is
+     * used for the sandbox. The daemon must have an image builder configured
+     * (every official deployment does); otherwise the build call returns 503.
+     */
+    image: string | Image;
     /** Number of CPU cores to allocate. Fractional values are supported (e.g. 0.5 = half a core). */
     cpu?: number;
     memoryMB?: number;
@@ -159,6 +211,12 @@ export interface SandboxSnapshot {
     imageID?: string;
     sourceSandboxID: string;
     createdAt: string;
+    entrypoint?: string[];
+    regionID?: string;
+    cpu?: number;
+    gpu?: number;
+    memoryMB?: number;
+    diskGB?: number;
 }
 /**
  * Discriminated result from `exposePort`. Branch on `protocol` to access the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",