@aerol-ai/aerolvm-sdk 0.1.6 → 0.1.8

package/dist/MicroVM.d.ts

@@ -1,10 +1,18 @@
+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 type { CreateOptions, CreateSessionOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, Lifecycle, MountSpecRedacted, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
 type FetchLike = typeof fetch;
 export interface MicroVMConfig {
     patToken?: string;
     apiUrl?: string;
     fetch?: FetchLike;
+    /**
+     * Wire version of the sandbox daemon API to call. Defaults to the SDK's
+     * pinned default ("v1" today). The SDK package version and the API wire
+     * version evolve independently — you can pin one without affecting the
+     * other.
+     */
+    apiVersion?: APIVersion;
 }
 export declare class MicroVM {
     readonly apiUrl: string;
@@ -16,6 +24,7 @@ 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>;

package/dist/MicroVM.js

@@ -18,6 +18,7 @@ export class MicroVM {
             baseURL: apiUrl,
             patToken,
             fetch: config.fetch,
+            apiVersion: config.apiVersion,
         });
     }
     async create(options) {
@@ -40,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);
     }

package/dist/index.d.ts

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

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

@@ -0,0 +1 @@
+export declare const PATH_PREFIX = "/v1";

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

@@ -0,0 +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.
+//
+// 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,20 +1,43 @@
-import type { BinaryLike, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, HealthStatus, Lifecycle, MountSpecRedacted, ResizeOptions, Sandbox, Session, SessionAttachHandle, SessionAttachOptions } from "../types.js";
+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";
 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.
+ */
+export type APIVersion = "v1";
 export interface APIClientConfig {
     baseURL: string;
     patToken?: string;
     fetch?: FetchLike;
+    /**
+     * Wire version to call. Defaults to "v1". Pin this if you need a specific
+     * version — otherwise the SDK will track its own default, which may move in
+     * a future major SDK release.
+     */
+    apiVersion?: APIVersion;
 }
 export declare class APIClient {
     readonly baseURL: string;
+    readonly apiVersion: APIVersion;
     private readonly patToken;
     private readonly fetchFn;
+    private readonly versionPrefix;
     constructor(config: APIClientConfig);
+    /**
+     * 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
+     * apiVersion option without touching call sites.
+     */
+    private versioned;
     create(options: CreateOptions): Promise<SandboxResource>;
     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>;
@@ -31,24 +54,26 @@ export declare class APIClient {
     attachSession(id: string, sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
     uploadFile(id: string, targetPath: string, data: BinaryLike): Promise<void>;
     downloadFile(id: string, targetPath: string): Promise<Uint8Array>;
-    exposePort(id: string, port: number): Promise<string>;
-    /**
-     * Publish a raw TCP port through caddy-l4. The returned URL is in
-     * `tcp://<host>:<port>` form and works directly with `psql`, `redis-cli`,
-     * `mysql`, `mongosh`, and any other native-protocol client.
-     */
-    exposeTCPPort(id: string, port: number): Promise<string>;
     /**
-     * Publish a TCP port behind the shared TLS-SNI multiplexer. Returns
-     * `tls://<id>-<port>.<domain>:<l4-port>`. Requires the daemon to have a
-     * domain configured AND `SB_L4_TLS_LISTEN` set.
+     * Publish a sandbox container port. The chosen wire protocol is selected by
+     * `options.protocol` (defaults to `"http"`):
+     *
+     *   - `"http"`: Caddy HTTP reverse proxy at `https://<id>-<port>.<domain>`.
+     *   - `"tcp"`:  raw caddy-l4 listener on a parent-host port — pair with
+     *               native protocol clients (psql, redis-cli, mysql, mongosh).
+     *   - `"tls"`:  caddy-l4 TLS-SNI route on the shared listener. Requires the
+     *               daemon to have a domain configured AND `SB_L4_TLS_LISTEN` set.
+     *
+     * Returns a discriminated result keyed on `protocol`. Only the `"tcp"`
+     * variant carries `host` / `hostPort` — everything else is in `url`.
      */
-    exposeTLSPort(id: string, port: number): Promise<string>;
-    private exposePortWithProtocol;
+    exposePort(id: string, port: number, options?: ExposePortOptions): Promise<ExposeResult>;
     unexposePort(id: string, port: number): Promise<void>;
     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;
@@ -94,15 +119,16 @@ export declare class SandboxResource implements Sandbox {
     attachSession(sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
     uploadFile(targetPath: string, data: BinaryLike): Promise<void>;
     downloadFile(targetPath: string): Promise<Uint8Array>;
-    exposePort(port: number): Promise<string>;
-    exposeTCPPort(port: number): Promise<string>;
-    exposeTLSPort(port: number): Promise<string>;
+    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,135 +1,159 @@
 import { basename } from "node:path";
+import { PATH_PREFIX as V1_PATH_PREFIX } from "./api/v1/paths.js";
+const DEFAULT_API_VERSION = "v1";
+const PATH_PREFIXES = {
+    v1: V1_PATH_PREFIX,
+};
 export class APIClient {
     baseURL;
+    apiVersion;
     patToken;
     fetchFn;
+    versionPrefix;
     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];
+    }
+    /**
+     * 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
+     * apiVersion option without touching call sites.
+     */
+    versioned(suffix) {
+        return `${this.versionPrefix}${suffix}`;
     }
     async create(options) {
-        const response = await this.doJSON("POST", "/v1/sandboxes", toApiCreateOptions(options));
+        const response = await this.doJSON("POST", this.versioned("/sandboxes"), toApiCreateOptions(options));
         return new SandboxResource(this, fromApiCreateSandboxResponse(response));
     }
     async list() {
-        const response = await this.doJSON("GET", "/v1/sandboxes");
+        const response = await this.doJSON("GET", this.versioned("/sandboxes"));
         return response.map((item) => this.wrap(item));
     }
     async get(id) {
-        const response = await this.doJSON("GET", `/v1/sandboxes/${id}`);
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}`);
         return this.wrap(response);
     }
     async start(id) {
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/start`);
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/start`);
         return this.wrap(response);
     }
     async stop(id) {
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/stop`);
+        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", `/v1/sandboxes/${id}`);
+        await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}`);
     }
     async resize(id, options) {
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/resize`, toApiResizeOptions(options));
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/resize`, toApiResizeOptions(options));
         return this.wrap(response);
     }
     async updateLifecycle(id, lifecycle) {
-        const response = await this.doJSON("PUT", `/v1/sandboxes/${id}/lifecycle`, toApiLifecycle(lifecycle));
+        const response = await this.doJSON("PUT", `${this.versionPrefix}/sandboxes/${id}/lifecycle`, toApiLifecycle(lifecycle));
         return this.wrap(response);
     }
     async exec(id, request) {
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/toolbox/process/execute`, toApiExecRequest(request));
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/toolbox/process/execute`, toApiExecRequest(request));
         return fromApiExecResult(response);
     }
     execStream(id, options) {
-        return openExecStream(this.baseURL, this.patToken, id, options);
+        return openExecStream(this.baseURL, this.versionPrefix, this.patToken, id, options);
     }
     async createSession(id, options) {
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/sessions`, toApiCreateSessionOptions(options));
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/sessions`, toApiCreateSessionOptions(options));
         return fromApiSession(response);
     }
     async listSessions(id) {
-        const response = await this.doJSON("GET", `/v1/sandboxes/${id}/sessions`);
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/sessions`);
         return response.sessions.map(fromApiSession);
     }
     async getSession(id, sessionID) {
-        const response = await this.doJSON("GET", `/v1/sandboxes/${id}/sessions/${sessionID}`);
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}`);
         return fromApiSession(response);
     }
     async deleteSession(id, sessionID) {
-        await this.doJSON("DELETE", `/v1/sandboxes/${id}/sessions/${sessionID}`);
+        await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}`);
     }
     async signalSession(id, sessionID, signal) {
-        await this.doJSON("POST", `/v1/sandboxes/${id}/sessions/${sessionID}/signal`, { signal });
+        await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}/signal`, { signal });
     }
     async resizeSession(id, sessionID, cols, rows) {
-        await this.doJSON("POST", `/v1/sandboxes/${id}/sessions/${sessionID}/resize`, { cols, rows });
+        await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}/resize`, { cols, rows });
     }
     async sessionLog(id, sessionID) {
-        return this.doBytes(`/v1/sandboxes/${id}/sessions/${sessionID}/log`);
+        return this.doBytes(`${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}/log`);
     }
     async sessionRecording(id, sessionID) {
-        return this.doBytes(`/v1/sandboxes/${id}/sessions/${sessionID}/recording`);
+        return this.doBytes(`${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}/recording`);
     }
     attachSession(id, sessionID, options = {}) {
-        return openSessionAttach(this.baseURL, this.patToken, id, sessionID, options);
+        return openSessionAttach(this.baseURL, this.versionPrefix, this.patToken, id, sessionID, options);
     }
     async uploadFile(id, targetPath, data) {
         const form = new FormData();
         form.set("path", targetPath);
         form.set("file", toBlob(data), basename(targetPath));
-        const response = await this.request("POST", `/v1/sandboxes/${id}/toolbox/files/upload`, { body: form });
+        const response = await this.request("POST", `${this.versionPrefix}/sandboxes/${id}/toolbox/files/upload`, { body: form });
         if (!response.ok) {
             throw await decodeError(response);
         }
     }
     async downloadFile(id, targetPath) {
-        const response = await this.request("GET", `/v1/sandboxes/${id}/toolbox/files/download?path=${encodeURIComponent(targetPath)}`);
+        const response = await this.request("GET", `${this.versionPrefix}/sandboxes/${id}/toolbox/files/download?path=${encodeURIComponent(targetPath)}`);
         if (!response.ok) {
             throw await decodeError(response);
         }
         return new Uint8Array(await response.arrayBuffer());
     }
-    async exposePort(id, port) {
-        return this.exposePortWithProtocol(id, port);
-    }
-    /**
-     * Publish a raw TCP port through caddy-l4. The returned URL is in
-     * `tcp://<host>:<port>` form and works directly with `psql`, `redis-cli`,
-     * `mysql`, `mongosh`, and any other native-protocol client.
-     */
-    async exposeTCPPort(id, port) {
-        return this.exposePortWithProtocol(id, port, "tcp");
-    }
     /**
-     * Publish a TCP port behind the shared TLS-SNI multiplexer. Returns
-     * `tls://<id>-<port>.<domain>:<l4-port>`. Requires the daemon to have a
-     * domain configured AND `SB_L4_TLS_LISTEN` set.
+     * Publish a sandbox container port. The chosen wire protocol is selected by
+     * `options.protocol` (defaults to `"http"`):
+     *
+     *   - `"http"`: Caddy HTTP reverse proxy at `https://<id>-<port>.<domain>`.
+     *   - `"tcp"`:  raw caddy-l4 listener on a parent-host port — pair with
+     *               native protocol clients (psql, redis-cli, mysql, mongosh).
+     *   - `"tls"`:  caddy-l4 TLS-SNI route on the shared listener. Requires the
+     *               daemon to have a domain configured AND `SB_L4_TLS_LISTEN` set.
+     *
+     * Returns a discriminated result keyed on `protocol`. Only the `"tcp"`
+     * variant carries `host` / `hostPort` — everything else is in `url`.
      */
-    async exposeTLSPort(id, port) {
-        return this.exposePortWithProtocol(id, port, "tls");
-    }
-    async exposePortWithProtocol(id, port, protocol) {
-        const body = protocol ? { protocol } : undefined;
-        const response = await this.doJSON("POST", `/v1/sandboxes/${id}/ports/${port}`, body);
-        return response.public_url;
+    async exposePort(id, port, options = {}) {
+        const body = options.protocol ? { protocol: options.protocol } : undefined;
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/ports/${port}`, body);
+        return fromApiExposePortResponse(response);
     }
     async unexposePort(id, port) {
-        await this.doJSON("DELETE", `/v1/sandboxes/${id}/ports/${port}`);
+        await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}/ports/${port}`);
     }
     async reconcile() {
-        await this.doJSON("POST", "/v1/admin/reconcile");
+        await this.doJSON("POST", this.versioned("/admin/reconcile"));
     }
     async health() {
         const response = await this.doJSON("GET", "/health");
         return fromApiHealthStatus(response);
     }
     async mounts(id) {
-        const response = await this.doJSON("GET", `/v1/sandboxes/${id}/mounts`);
+        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));
     }
@@ -219,18 +243,15 @@ export class SandboxResource {
     async downloadFile(targetPath) {
         return this.client.downloadFile(this.id, targetPath);
     }
-    async exposePort(port) {
-        return this.client.exposePort(this.id, port);
-    }
-    async exposeTCPPort(port) {
-        return this.client.exposeTCPPort(this.id, port);
-    }
-    async exposeTLSPort(port) {
-        return this.client.exposeTLSPort(this.id, port);
+    async exposePort(port, options) {
+        return this.client.exposePort(this.id, port, options);
     }
     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());
@@ -254,6 +275,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);
     }
@@ -270,6 +297,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),
@@ -353,6 +382,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,
@@ -379,6 +417,21 @@ function fromApiExposedPort(port) {
         createdAt: port.created_at,
     };
 }
+function fromApiExposePortResponse(response) {
+    switch (response.protocol) {
+        case "tcp":
+            return {
+                protocol: "tcp",
+                url: response.public_url,
+                host: response.host ?? "",
+                hostPort: response.host_port ?? 0,
+            };
+        case "tls":
+            return { protocol: "tls", url: response.public_url };
+        case "http":
+            return { protocol: "http", url: response.public_url };
+    }
+}
 function fromApiExecResult(result) {
     return {
         stdout: result.stdout,
@@ -417,6 +470,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) {
@@ -503,8 +574,8 @@ function toWebSocketBinaryFrame(data) {
     frame.set(bytes);
     return frame;
 }
-function openExecStream(baseURL, patToken, sandboxID, options) {
-    const wsURL = baseURL.replace(/^http/, "ws") + `/v1/sandboxes/${encodeURIComponent(sandboxID)}/toolbox/process/exec/stream`;
+function openExecStream(baseURL, versionPrefix, patToken, sandboxID, options) {
+    const wsURL = baseURL.replace(/^http/, "ws") + `${versionPrefix}/sandboxes/${encodeURIComponent(sandboxID)}/toolbox/process/exec/stream`;
     const WS = globalThis.WebSocket;
     if (!WS) {
         throw new Error("WebSocket is not available in this runtime — Node 22+ or a browser is required");
@@ -609,8 +680,8 @@ function openExecStream(baseURL, patToken, sandboxID, options) {
         done,
     };
 }
-function openSessionAttach(baseURL, patToken, sandboxID, sessionID, options) {
-    const wsURL = baseURL.replace(/^http/, "ws") + `/v1/sandboxes/${encodeURIComponent(sandboxID)}/sessions/${encodeURIComponent(sessionID)}/attach`;
+function openSessionAttach(baseURL, versionPrefix, patToken, sandboxID, sessionID, options) {
+    const wsURL = baseURL.replace(/^http/, "ws") + `${versionPrefix}/sandboxes/${encodeURIComponent(sandboxID)}/sessions/${encodeURIComponent(sessionID)}/attach`;
     const WS = globalThis.WebSocket;
     if (!WS) {
         throw new Error("WebSocket is not available in this runtime — Node 22+ or a browser is required");

package/dist/types.d.ts

@@ -69,6 +69,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[];
@@ -129,6 +142,42 @@ export interface ExposedPort {
     publicURL: string;
     createdAt: string;
 }
+/**
+ * Wire protocol an exposure publishes through:
+ *   - "http": Caddy HTTP reverse proxy at https://<id>-<port>.<domain>.
+ *   - "tcp":  raw caddy-l4 listener on a parent-host port.
+ *   - "tls":  caddy-l4 TLS-SNI route on the shared :443 listener.
+ */
+export type ExposeProtocol = "http" | "tcp" | "tls";
+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
+ * variant carries `host` and `hostPort`, which are what native protocol
+ * clients (psql, redis-cli, mysql, mongosh, …) need to dial.
+ */
+export type ExposeResult = {
+    protocol: "http";
+    url: string;
+} | {
+    protocol: "tcp";
+    url: string;
+    host: string;
+    hostPort: number;
+} | {
+    protocol: "tls";
+    url: string;
+};
 export interface Sandbox {
     id: string;
     image: string;
@@ -160,6 +209,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.6",
+  "version": "0.1.8",
   "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",