@aerol-ai/aerolvm-sdk 0.1.7 → 0.1.8

package/dist/MicroVM.d.ts

@@ -1,6 +1,6 @@
 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;
@@ -24,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

@@ -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);
     }

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

@@ -1,4 +1,4 @@
-import type { BinaryLike, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, 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
@@ -37,6 +37,7 @@ export declare class APIClient {
     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 +72,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 +121,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

@@ -46,6 +46,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 +146,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 +249,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 +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);
     }
@@ -276,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),
@@ -359,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,
@@ -438,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) {

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[];
@@ -140,6 +153,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 +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.7",
+  "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",