@aerol-ai/aerolvm-sdk 0.1.7 → 0.1.9

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, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
+import { Image } from "./Image.js";
+import type { BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, Lifecycle, MountSpecRedacted, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
 type FetchLike = typeof fetch;
 export interface MicroVMConfig {
     patToken?: string;
@@ -24,10 +25,18 @@ export declare class MicroVM {
     get(id: string): Promise<Sandbox>;
     start(id: string): Promise<Sandbox>;
     stop(id: string): Promise<Sandbox>;
+    createSnapshot(id: string, name: string): 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

@@ -41,6 +41,9 @@ export class MicroVM {
         const sandbox = await this.client.stop(id);
         return this.wrap(sandbox.toJSON());
     }
+    async createSnapshot(id, name) {
+        return this.client.createSnapshot(id, name);
+    }
     async destroy(id) {
         await this.client.destroy(id);
     }
@@ -55,6 +58,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, 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, 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, ResizeOptions, Sandbox, 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, 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,15 +37,29 @@ 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>;
     destroy(id: string): Promise<void>;
     resize(id: string, options: ResizeOptions): Promise<SandboxResource>;
     updateLifecycle(id: string, lifecycle: Lifecycle): Promise<SandboxResource>;
@@ -71,6 +94,8 @@ export declare class APIClient {
     reconcile(): Promise<void>;
     health(): Promise<HealthStatus>;
     mounts(id: string): Promise<MountSpecRedacted[]>;
+    getNetworkUsage(id: string): Promise<NetworkUsage>;
+    setNetworkLimits(id: string, options: SetNetworkLimitsOptions): Promise<NetworkUsage>;
     private wrap;
     private doJSON;
     private doBytes;
@@ -118,11 +143,14 @@ export declare class SandboxResource implements Sandbox {
     downloadFile(targetPath: string): Promise<Uint8Array>;
     exposePort(port: number, options?: ExposePortOptions): Promise<ExposeResult>;
     unexposePort(port: number): Promise<void>;
+    createSnapshot(name: string): Promise<SandboxSnapshot>;
     start(): Promise<this>;
     stop(): Promise<this>;
     destroy(): Promise<void>;
     resize(options: ResizeOptions): Promise<this>;
     updateLifecycle(lifecycle: Lifecycle): Promise<this>;
+    getNetworkUsage(): Promise<NetworkUsage>;
+    setNetworkLimits(options: SetNetworkLimitsOptions): Promise<NetworkUsage>;
     toJSON(): Sandbox;
     private apply;
 }

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));
@@ -46,6 +101,10 @@ export class APIClient {
         const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/stop`);
         return this.wrap(response);
     }
+    async createSnapshot(id, name) {
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/snapshot`, { name });
+        return fromApiSandboxSnapshot(response);
+    }
     async destroy(id) {
         await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}`);
     }
@@ -142,6 +201,14 @@ export class APIClient {
         const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/mounts`);
         return response.mounts.map(fromApiMountSpecRedacted);
     }
+    async getNetworkUsage(id) {
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/network/usage`);
+        return fromApiNetworkUsage(response);
+    }
+    async setNetworkLimits(id, options) {
+        const response = await this.doJSON("PATCH", `${this.versionPrefix}/sandboxes/${id}/network/limits`, toApiSetNetworkLimitsOptions(options));
+        return fromApiNetworkUsage(response);
+    }
     wrap(sandbox) {
         return new SandboxResource(this, fromApiSandbox(sandbox));
     }
@@ -237,6 +304,9 @@ export class SandboxResource {
     async unexposePort(port) {
         await this.client.unexposePort(this.id, port);
     }
+    async createSnapshot(name) {
+        return this.client.createSnapshot(this.id, name);
+    }
     async start() {
         const updated = await this.client.start(this.id);
         this.apply(updated.toJSON());
@@ -260,6 +330,12 @@ export class SandboxResource {
         this.apply(updated.toJSON());
         return this;
     }
+    async getNetworkUsage() {
+        return this.client.getNetworkUsage(this.id);
+    }
+    async setNetworkLimits(options) {
+        return this.client.setNetworkLimits(this.id, options);
+    }
     toJSON() {
         return cloneSandbox(this);
     }
@@ -276,6 +352,8 @@ function toApiCreateOptions(options) {
         env: options.env,
         os_user: options.osUser,
         network_block_all: options.networkBlockAll,
+        network_bytes_in_limit: options.networkBytesInLimit,
+        network_bytes_out_limit: options.networkBytesOutLimit,
         registry: options.registry,
         container_command: options.containerCommand,
         mounts: options.mounts?.map(toApiMountSpec),
@@ -359,6 +437,15 @@ function fromApiCreateSandboxResponse(response) {
         sshPrivateKey: response.ssh_private_key,
     };
 }
+function fromApiSandboxSnapshot(snapshot) {
+    return {
+        name: snapshot.name,
+        image: snapshot.image,
+        imageID: snapshot.image_id,
+        sourceSandboxID: snapshot.source_sandbox_id,
+        createdAt: snapshot.created_at,
+    };
+}
 function fromApiSession(session) {
     return {
         id: session.id,
@@ -438,6 +525,24 @@ function fromApiMountSpecRedacted(mount) {
         hasCredentials: mount.has_credentials,
     };
 }
+function fromApiNetworkUsage(usage) {
+    return {
+        sandboxID: usage.sandbox_id,
+        bytesIn: usage.bytes_in,
+        bytesOut: usage.bytes_out,
+        bytesInLimit: usage.bytes_in_limit,
+        bytesOutLimit: usage.bytes_out_limit,
+        quotaExceeded: usage.quota_exceeded,
+        quotaExceededAt: usage.quota_exceeded_at ?? undefined,
+        lastSampledAt: usage.last_sampled_at ?? undefined,
+    };
+}
+function toApiSetNetworkLimitsOptions(options) {
+    return {
+        network_bytes_in_limit: options.networkBytesInLimit,
+        network_bytes_out_limit: options.networkBytesOutLimit,
+    };
+}
 function fromApiLifecycle(lifecycle) {
     const result = {};
     if (lifecycle?.stop_if_idle_for !== undefined) {

package/dist/types.d.ts

@@ -4,6 +4,30 @@ 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 type MountType = "s3" | "nfs" | "sshfs" | "rclone";
 export interface MountSpec {
     type: MountType;
@@ -60,8 +84,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;
@@ -69,6 +102,19 @@ export interface CreateOptions {
     env?: Record<string, string>;
     osUser?: string;
     networkBlockAll?: boolean;
+    /**
+     * Cap on bytes the sandbox may receive from outside the container before its
+     * ingress is dropped via per-IP iptables rule. `0` (default) is unlimited.
+     * Limits can be raised or lifted at runtime via `setNetworkLimits`.
+     */
+    networkBytesInLimit?: number;
+    /**
+     * Cap on bytes the sandbox may send to outside the container before its
+     * egress is dropped. `0` (default) is unlimited. The block reuses the same
+     * iptables row as `networkBlockAll`; clearing the quota does not lift an
+     * operator-set blanket egress block.
+     */
+    networkBytesOutLimit?: number;
     registry?: RegistryAuth;
     containerCommand?: string[];
     mounts?: MountSpec[];
@@ -140,6 +186,13 @@ export interface ExposePortOptions {
     /** Defaults to "http" when omitted. */
     protocol?: ExposeProtocol;
 }
+export interface SandboxSnapshot {
+    name: string;
+    image: string;
+    imageID?: string;
+    sourceSandboxID: string;
+    createdAt: string;
+}
 /**
  * Discriminated result from `exposePort`. Branch on `protocol` to access the
  * fields that are meaningful for the chosen wire protocol — only the raw-TCP
@@ -189,6 +242,29 @@ export interface Sandbox {
     /** GPU configuration this sandbox was created with. Absent means no GPU. */
     gpus?: GPUOptions;
 }
+/**
+ * Per-sandbox network byte counters and the configured caps that drive the
+ * quota enforcer. `bytesIn` is traffic the container received (ingress);
+ * `bytesOut` is traffic the container sent (egress). A `*Limit` of `0` means
+ * unlimited. `quotaExceeded` flips true the first time the meter crosses
+ * either configured cap and stays true until the operator raises the limit.
+ */
+export interface NetworkUsage {
+    sandboxID: string;
+    bytesIn: number;
+    bytesOut: number;
+    bytesInLimit: number;
+    bytesOutLimit: number;
+    quotaExceeded: boolean;
+    quotaExceededAt?: string;
+    /** Absent until the netstats poller has produced at least one sample. */
+    lastSampledAt?: string;
+}
+export interface SetNetworkLimitsOptions {
+    /** Omit (undefined) to leave unchanged. `0` means unlimited. */
+    networkBytesInLimit?: number;
+    networkBytesOutLimit?: number;
+}
 export interface ExecRequest {
     command: string;
     workDir?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -13,11 +13,12 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "example:browser-isolation:src": "npx tsx src/examples/browserIsolation.ts",
     "example:create": "npm run build && node dist/examples/createSandbox.js",
     "example:create:src": "npx tsx src/examples/createSandbox.ts",
     "example:delete": "npm run build && node dist/examples/deleteSandbox.js",
     "example:delete:src": "npx tsx src/examples/deleteSandbox.ts",
-    "test": "tsc -p tsconfig.test.json --outDir dist-test && node --test dist-test/*.test.js"
+    "test": "tsc -p tsconfig.test.json --outDir dist-test && node --test dist-test/*.test.js dist-test/internal/*.test.js"
   },
   "devDependencies": {
     "@types/node": "^25.6.2",