@aerol-ai/aerolvm-sdk 0.5.3 → 0.6.4

package/dist/MicroVM.d.ts

@@ -1,7 +1,7 @@
 import { type APIVersion, type RetryConfig } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 import { Image } from "./Image.js";
-import type { BuildImageOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, ExecStreamHandle, ExecStreamOptions, HealthStatus, IngressTarget, Lifecycle, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule } from "./types.js";
+import type { BuildImageOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, ExecStreamHandle, ExecStreamOptions, HealthStatus, EgressProfile, EgressProfileList, EgressProfileOptions, ListEgressProfilesOptions, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule } from "./types.js";
 type FetchLike = typeof fetch;
 export interface MicroVMConfig {
     patToken?: string;
@@ -16,7 +16,7 @@ export interface MicroVMConfig {
     apiVersion?: APIVersion;
     /**
      * Retry policy for transient transport errors (socket closed, connection
-     * reset) and retryable HTTP status codes (429, 502, 503, 504). The SDK
+     * reset) and retryable HTTP status codes (421, 429, 502, 503, 504). The SDK
      * retries up to 3 times with exponential backoff by default. Pass
      * `{ maxRetries: 0 }` to disable.
      */
@@ -29,7 +29,18 @@ export declare class MicroVM {
     constructor(config?: MicroVMConfig);
     create(options: CreateOptions): Promise<Sandbox>;
     list(options?: ListOptions): Promise<Sandbox[]>;
-    get(id: string): Promise<Sandbox>;
+    /**
+     * Iterates one server page at a time. Use this for large fleet inventories so
+     * the SDK does not retain every sandbox in memory.
+     */
+    listPages(options?: ListOptions): AsyncGenerator<Sandbox[]>;
+    get(id: string, options?: GetOptions): Promise<Sandbox>;
+    /**
+     * Returns the caller's sandbox with this name, or `null` when there is none.
+     * Names are unique per owner. Throws when the server predates name lookup
+     * (it ignores `?name=`), rather than guessing from an unfiltered list.
+     */
+    getByName(name: string, options?: GetOptions): Promise<Sandbox | null>;
     start(id: string): Promise<Sandbox>;
     stop(id: string): Promise<Sandbox>;
     createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
@@ -47,6 +58,22 @@ export declare class MicroVM {
      */
     buildImage(image: Image, options?: BuildImageOptions): Promise<BuildImageResult>;
     health(): Promise<HealthStatus>;
+    /**
+     * Asks whether a sandbox created with these egress fields would reach a
+     * destination, using the same matcher the filter enforces. No sandbox is
+     * needed.
+     */
+    checkNetworkPolicy(options: NetworkPolicyCheckOptions): Promise<NetworkPolicyCheckResult>;
+    /**
+     * Creates or replaces a named egress profile (a full replace: the same body
+     * twice is a no-op). Sandboxes reference it through `egressProfiles`, and a
+     * change reaches every one of them.
+     */
+    putEgressProfile(name: string, options: EgressProfileOptions): Promise<EgressProfile>;
+    getEgressProfile(name: string): Promise<EgressProfile>;
+    listEgressProfiles(options?: ListEgressProfilesOptions): Promise<EgressProfileList>;
+    /** Deletes a profile; one that sandboxes still reference is refused (409). */
+    deleteEgressProfile(name: string): Promise<void>;
     mounts(sandboxID: string): Promise<MountSpecRedacted[]>;
     /**
      * Read a sandbox's clone-generation token. The token changes whenever the

package/dist/MicroVM.js

@@ -30,10 +30,28 @@ export class MicroVM {
         const sandboxes = await this.client.list(options);
         return sandboxes.map((sandbox) => this.wrap(sandbox.toJSON()));
     }
-    async get(id) {
-        const sandbox = await this.client.get(id);
+    /**
+     * Iterates one server page at a time. Use this for large fleet inventories so
+     * the SDK does not retain every sandbox in memory.
+     */
+    async *listPages(options) {
+        for await (const page of this.client.listPages(options)) {
+            yield page.map((sandbox) => this.wrap(sandbox.toJSON()));
+        }
+    }
+    async get(id, options) {
+        const sandbox = await this.client.get(id, options);
         return this.wrap(sandbox.toJSON());
     }
+    /**
+     * Returns the caller's sandbox with this name, or `null` when there is none.
+     * Names are unique per owner. Throws when the server predates name lookup
+     * (it ignores `?name=`), rather than guessing from an unfiltered list.
+     */
+    async getByName(name, options) {
+        const sandbox = await this.client.getByName(name, options);
+        return sandbox === null ? null : this.wrap(sandbox.toJSON());
+    }
     async start(id) {
         const sandbox = await this.client.start(id);
         return this.wrap(sandbox.toJSON());
@@ -77,6 +95,32 @@ export class MicroVM {
     async health() {
         return this.client.health();
     }
+    /**
+     * Asks whether a sandbox created with these egress fields would reach a
+     * destination, using the same matcher the filter enforces. No sandbox is
+     * needed.
+     */
+    async checkNetworkPolicy(options) {
+        return this.client.checkNetworkPolicy(options);
+    }
+    /**
+     * Creates or replaces a named egress profile (a full replace: the same body
+     * twice is a no-op). Sandboxes reference it through `egressProfiles`, and a
+     * change reaches every one of them.
+     */
+    async putEgressProfile(name, options) {
+        return this.client.putEgressProfile(name, options);
+    }
+    async getEgressProfile(name) {
+        return this.client.getEgressProfile(name);
+    }
+    async listEgressProfiles(options) {
+        return this.client.listEgressProfiles(options);
+    }
+    /** Deletes a profile; one that sandboxes still reference is refused (409). */
+    async deleteEgressProfile(name) {
+        return this.client.deleteEgressProfile(name);
+    }
     async mounts(sandboxID) {
         return this.client.mounts(sandboxID);
     }

package/dist/index.d.ts

@@ -3,4 +3,4 @@ export { Sandbox } from "./Sandbox.js";
 export { Image } from "./Image.js";
 export type { MicroVMConfig } from "./MicroVM.js";
 export type { RetryConfig } from "./internal/client.js";
-export type { AddCustomDomainOptions, BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegisterSnapshotOptions, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, Template, TemplatePushState, TemplateStatus, WasmModule, WasmModuleStatus, PushWasmModuleOptions, PushWasmModuleResult, UpdateLifecycleOptions, } from "./types.js";
+export type { AddCustomDomainOptions, AuditEvent, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressInject, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkLearnedEntry, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, GetOptions, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, ListOptions, MountSpec, MountSpecRedacted, MountType, PlatformVolumeMount, RegisterSnapshotOptions, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, Template, TemplatePushState, TemplateStatus, WasmModule, WasmModuleStatus, PushWasmModuleOptions, PushWasmModuleResult, UpdateLifecycleOptions, } from "./types.js";

package/dist/internal/client.d.ts

@@ -1,5 +1,5 @@
 import { Image } from "../Image.js";
-import type { AddCustomDomainOptions, BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, CustomDomain, CloneGeneration, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, ListOptions, MountSpecRedacted, NetworkUsage, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule } from "../types.js";
+import type { AddCustomDomainOptions, BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, CustomDomain, CloneGeneration, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, NetworkUsage, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule } from "../types.js";
 type FetchLike = typeof fetch;
 /**
  * Wire version of the v1-style sandbox endpoints (`/v1/sandboxes`, etc.) this
@@ -49,7 +49,7 @@ export interface APIClientConfig {
     apiVersion?: APIVersion;
     /**
      * Retry policy for transient transport errors (socket closed, connection
-     * reset) and retryable HTTP status codes (429, 502, 503, 504). Pass
+     * reset) and retryable HTTP status codes (421, 429, 502, 503, 504). Pass
      * `{ maxRetries: 0 }` to disable retry entirely.
      */
     retry?: RetryConfig;
@@ -90,7 +90,17 @@ export declare class APIClient {
     buildImage(image: Image, options?: BuildImageOptions): Promise<BuildImageResult>;
     private resolveImage;
     list(options?: ListOptions): Promise<SandboxResource[]>;
-    get(id: string): Promise<SandboxResource>;
+    /** Streams bounded cluster-list pages and never accumulates the full fleet. */
+    listPages(options?: ListOptions): AsyncGenerator<SandboxResource[]>;
+    /**
+     * Looks up the caller's sandbox by name with one request. The reply is only
+     * trusted when it holds at most one sandbox and that sandbox carries the
+     * requested name: a server that predates `?name=` ignores the filter and
+     * returns an ordinary list page, and acting on its first row would target
+     * the wrong sandbox.
+     */
+    getByName(name: string, options?: GetOptions): Promise<SandboxResource | null>;
+    get(id: string, options?: GetOptions): Promise<SandboxResource>;
     start(id: string): Promise<SandboxResource>;
     stop(id: string): Promise<SandboxResource>;
     createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
@@ -149,10 +159,18 @@ export declare class APIClient {
     customDomainDNS(id: string): Promise<CustomDomainDNSRecords>;
     reconcile(): Promise<void>;
     health(): Promise<HealthStatus>;
+    checkNetworkPolicy(options: NetworkPolicyCheckOptions): Promise<NetworkPolicyCheckResult>;
     mounts(id: string): Promise<MountSpecRedacted[]>;
     cloneGeneration(id: string): Promise<CloneGeneration>;
     getNetworkUsage(id: string): Promise<NetworkUsage>;
+    getAudit(id: string, options?: AuditOptions): Promise<AuditPage>;
     setNetworkLimits(id: string, options: SetNetworkLimitsOptions): Promise<NetworkUsage>;
+    setNetworkPolicy(id: string, options: NetworkPolicyOptions): Promise<NetworkPolicy>;
+    getNetworkLearned(id: string): Promise<NetworkLearned>;
+    putEgressProfile(name: string, options: EgressProfileOptions): Promise<EgressProfile>;
+    getEgressProfile(name: string): Promise<EgressProfile>;
+    listEgressProfiles(options?: ListEgressProfilesOptions): Promise<EgressProfileList>;
+    deleteEgressProfile(name: string): Promise<void>;
     createTemplate(options: CreateTemplateOptions): Promise<Template>;
     listTemplates(): Promise<Template[]>;
     getTemplate(id: string): Promise<Template>;
@@ -173,7 +191,7 @@ export declare class APIClient {
      * always retried regardless of HTTP method — the request never reached the
      * server so there is no idempotency concern.
      *
-     * HTTP-level retryable codes (429, 502, 503, 504) are retried for ALL
+     * HTTP-level retryable codes (421, 429, 502, 503, 504) are retried for ALL
      * methods because every mutating endpoint in the daemon is already
      * designed for idempotent retry (e.g. INSERT OR IGNORE + disambiguation).
      */
@@ -192,6 +210,11 @@ export declare class SandboxResource implements Sandbox {
     osUser: string;
     env?: Record<string, string>;
     networkBlockAll: boolean;
+    egressStatus?: string;
+    egressProfiles?: string[];
+    egressProfilesApplied?: EgressProfileRef[];
+    networkEgressMode?: string;
+    networkEgressRules?: EgressRule[];
     toolboxEnabled: boolean;
     sshPublicKey?: string;
     sshPrivateKey?: string;
@@ -199,6 +222,8 @@ export declare class SandboxResource implements Sandbox {
     createdAt: string;
     updatedAt: string;
     lastActiveAt: string;
+    name?: string;
+    tags?: Record<string, string>;
     lastError?: string;
     containerCommand?: string[];
     lifecycle: Lifecycle;
@@ -251,6 +276,24 @@ export declare class SandboxResource implements Sandbox {
     updateLifecycle(lifecycle: Lifecycle): Promise<this>;
     getNetworkUsage(): Promise<NetworkUsage>;
     setNetworkLimits(options: SetNetworkLimitsOptions): Promise<NetworkUsage>;
+    /**
+     * Replaces this sandbox's egress policy while it runs. The call returns
+     * once the new policy is enforced; sending the same policy again is a
+     * no-op, so it is safe to retry.
+     */
+    setNetworkPolicy(options: NetworkPolicyOptions): Promise<NetworkPolicy>;
+    /**
+     * Reads what this sandbox reached in learn mode and the allow list that
+     * would have allowed it. A recording stays readable after the sandbox
+     * switches to enforce, until it is destroyed.
+     */
+    learned(): Promise<NetworkLearned>;
+    /**
+     * Reads this sandbox's audit log: outbound connections and egress denials
+     * (`kind: "egress"`), and secret reads. Denials carry `result: "failure"`
+     * and the policy `reason`.
+     */
+    audit(options?: AuditOptions): Promise<AuditPage>;
     toJSON(): Sandbox;
     private apply;
 }

package/dist/internal/client.js

@@ -5,8 +5,30 @@ const DEFAULT_API_VERSION = "v1";
 const PATH_PREFIXES = {
     v1: V1_PATH_PREFIX,
 };
+function fromApiEgressProfile(p) {
+    const out = {
+        name: p.name,
+        allowOut: p.allow_out ?? [],
+        generation: p.generation,
+        createdAt: p.created_at,
+        updatedAt: p.updated_at,
+    };
+    if (p.description)
+        out.description = p.description;
+    return out;
+}
+function toApiEgressRule({ inject, ...rule }) {
+    return inject ? { ...rule, inject: { header: inject.header, secret_ref: inject.secretRef } } : rule;
+}
+function fromApiEgressRule({ inject, ...rule }) {
+    return inject ? { ...rule, inject: { header: inject.header, secretRef: inject.secret_ref } } : rule;
+}
 /** HTTP status codes the retry loop considers transient. */
-const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
+// 421 Misdirected Request: an owner answered for a sandbox it doesn't hold
+// (HTTP/2 connection coalescing, or a stale ingress route after failover).
+// The server closes the connection, so the retry reconnects and the ingress
+// re-routes it (plans/ingress-proxy-routing.md, review 2A).
+const RETRYABLE_STATUS_CODES = new Set([421, 429, 502, 503, 504]);
 /** Default retry settings when the caller doesn't supply a RetryConfig. */
 const DEFAULT_RETRY = {
     maxRetries: 3,
@@ -151,12 +173,62 @@ export class APIClient {
         return { ...options, image: result.image };
     }
     async list(options) {
-        const path = this.versioned("/sandboxes") + buildTagQuery(options?.tags);
-        const response = await this.doJSON("GET", path);
-        return response.map((item) => this.wrap(item));
+        const items = [];
+        for await (const page of this.listPages(options)) {
+            items.push(...page);
+        }
+        return items;
+    }
+    /** Streams bounded cluster-list pages and never accumulates the full fleet. */
+    async *listPages(options) {
+        const basePath = this.versioned("/sandboxes") + buildSandboxListQuery(options);
+        let pageToken = "";
+        for (let page = 0; page < 100000; page++) {
+            const path = appendQueryParam(basePath, "page_token", pageToken);
+            const response = await this.request("GET", path);
+            if (!response.ok) {
+                throw await decodeError(response);
+            }
+            const partial = response.headers.get("X-Cluster-List-Partial");
+            const placementReady = response.headers.get("X-Cluster-List-Placement-Ready");
+            if (partial === "true" || placementReady === "false") {
+                throw new Error("incomplete cluster list");
+            }
+            const body = (await response.json());
+            yield (body ?? []).map((item) => this.wrap(item));
+            pageToken = (response.headers.get("X-Cluster-List-Next-Page-Token") ?? "").trim();
+            if (pageToken === "") {
+                return;
+            }
+        }
+        throw new Error("incomplete cluster list: exceeded max pages");
+    }
+    /**
+     * Looks up the caller's sandbox by name with one request. The reply is only
+     * trusted when it holds at most one sandbox and that sandbox carries the
+     * requested name: a server that predates `?name=` ignores the filter and
+     * returns an ordinary list page, and acting on its first row would target
+     * the wrong sandbox.
+     */
+    async getByName(name, options) {
+        const trimmed = name.trim();
+        if (trimmed === "") {
+            throw new Error("sandbox name is required");
+        }
+        const path = this.versioned("/sandboxes") + buildSandboxListQuery({ name: trimmed, includeEnv: options?.includeEnv });
+        const body = await this.doJSON("GET", path);
+        const items = body ?? [];
+        if (items.length === 0) {
+            return null;
+        }
+        if (items.length > 1 || items[0].name !== trimmed) {
+            throw new Error(`${this.baseURL} does not support sandbox name lookup; use the sandbox ID or upgrade the server`);
+        }
+        return this.wrap(items[0]);
     }
-    async get(id) {
-        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}`);
+    async get(id, options) {
+        const q = buildIncludeEnvQuery(options?.includeEnv);
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}${q}`);
         return this.wrap(response);
     }
     async start(id) {
@@ -328,6 +400,22 @@ export class APIClient {
         const response = await this.doJSON("GET", "/health");
         return fromApiHealthStatus(response);
     }
+    async checkNetworkPolicy(options) {
+        const response = await this.doJSON("POST", this.versioned("/network/policy/check"), {
+            network_block_all: options.networkBlockAll,
+            network_allow_out: options.networkAllowOut,
+            network_deny_out: options.networkDenyOut,
+            destination: options.destination,
+        });
+        const result = {
+            allowed: response.allowed,
+            matchedRule: response.matched_rule ?? "",
+            defaultVerdict: response.default_verdict,
+        };
+        if (response.outside_ceiling)
+            result.outsideCeiling = response.outside_ceiling;
+        return result;
+    }
     async mounts(id) {
         const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/mounts`);
         return response.mounts.map(fromApiMountSpecRedacted);
@@ -340,10 +428,86 @@ export class APIClient {
         const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/network/usage`);
         return fromApiNetworkUsage(response);
     }
+    async getAudit(id, options = {}) {
+        const params = new URLSearchParams();
+        if (options.kind)
+            params.set("kind", options.kind);
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options.cursor)
+            params.set("cursor", options.cursor);
+        if (options.incarnationID)
+            params.set("incarnation_id", options.incarnationID);
+        const query = params.toString();
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/audit${query ? `?${query}` : ""}`);
+        return fromApiAuditPage(response);
+    }
     async setNetworkLimits(id, options) {
         const response = await this.doJSON("PATCH", `${this.versionPrefix}/sandboxes/${id}/network/limits`, toApiSetNetworkLimitsOptions(options));
         return fromApiNetworkUsage(response);
     }
+    async setNetworkPolicy(id, options) {
+        const response = await this.doJSON("PUT", `${this.versionPrefix}/sandboxes/${id}/network/policy`, {
+            network_block_all: options.networkBlockAll ?? false,
+            network_allow_out: options.networkAllowOut ?? [],
+            network_deny_out: options.networkDenyOut ?? [],
+            egress_profiles: options.egressProfiles ?? [],
+            network_egress_mode: options.networkEgressMode,
+            network_egress_rules: options.networkEgressRules?.map(toApiEgressRule),
+        });
+        const policy = {
+            networkBlockAll: response.network_block_all,
+            networkAllowOut: response.network_allow_out ?? [],
+            networkDenyOut: response.network_deny_out ?? [],
+            egressProfiles: response.egress_profiles ?? [],
+            networkEgressMode: response.network_egress_mode ?? "enforce",
+            networkEgressRules: (response.network_egress_rules ?? []).map(fromApiEgressRule),
+            effectiveHostnameCount: response.effective_hostname_count ?? 0,
+        };
+        if (response.egress_status)
+            policy.egressStatus = response.egress_status;
+        return policy;
+    }
+    async getNetworkLearned(id) {
+        const r = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/network/learned`);
+        const learned = {
+            mode: r.mode,
+            truncated: r.truncated,
+            entries: (r.entries ?? []).map((e) => ({ host: e.host, ports: e.ports ?? [], firstSeen: e.first_seen, lastSeen: e.last_seen, hits: e.hits })),
+            cidrs: r.cidrs ?? [],
+            suggestedAllowOut: r.suggested_allow_out ?? [],
+        };
+        if (r.suggested_profile) {
+            learned.suggestedProfile = { allowOut: r.suggested_profile.allow_out ?? [], description: r.suggested_profile.description };
+        }
+        return learned;
+    }
+    async putEgressProfile(name, options) {
+        const response = await this.doJSON("PUT", this.versioned(`/egress-profiles/${encodeURIComponent(name)}`), {
+            allow_out: options.allowOut,
+            description: options.description,
+        });
+        return fromApiEgressProfile(response);
+    }
+    async getEgressProfile(name) {
+        return fromApiEgressProfile(await this.doJSON("GET", this.versioned(`/egress-profiles/${encodeURIComponent(name)}`)));
+    }
+    async listEgressProfiles(options = {}) {
+        const params = new URLSearchParams();
+        if (options.cursor)
+            params.set("cursor", options.cursor);
+        if (options.limit)
+            params.set("limit", String(options.limit));
+        const query = params.toString();
+        const response = await this.doJSON("GET", this.versioned(`/egress-profiles${query ? `?${query}` : ""}`));
+        const list = { profiles: (response.profiles ?? []).map(fromApiEgressProfile) };
+        if (response.next_cursor)
+            list.nextCursor = response.next_cursor;
+        return list;
+    }
+    async deleteEgressProfile(name) {
+        await this.doJSON("DELETE", this.versioned(`/egress-profiles/${encodeURIComponent(name)}`));
+    }
     async createTemplate(options) {
         const response = await this.doJSON("POST", this.versioned("/templates"), {
             id: options.id,
@@ -441,7 +605,7 @@ export class APIClient {
      * always retried regardless of HTTP method — the request never reached the
      * server so there is no idempotency concern.
      *
-     * HTTP-level retryable codes (429, 502, 503, 504) are retried for ALL
+     * HTTP-level retryable codes (421, 429, 502, 503, 504) are retried for ALL
      * methods because every mutating endpoint in the daemon is already
      * designed for idempotent retry (e.g. INSERT OR IGNORE + disambiguation).
      */
@@ -594,6 +758,36 @@ export class SandboxResource {
     async setNetworkLimits(options) {
         return this.client.setNetworkLimits(this.id, options);
     }
+    /**
+     * Replaces this sandbox's egress policy while it runs. The call returns
+     * once the new policy is enforced; sending the same policy again is a
+     * no-op, so it is safe to retry.
+     */
+    async setNetworkPolicy(options) {
+        const policy = await this.client.setNetworkPolicy(this.id, options);
+        this.networkBlockAll = policy.networkBlockAll;
+        this.egressStatus = policy.egressStatus;
+        this.egressProfiles = policy.egressProfiles.length ? policy.egressProfiles : undefined;
+        this.networkEgressMode = policy.networkEgressMode === "learn" ? "learn" : undefined;
+        this.networkEgressRules = policy.networkEgressRules.length ? policy.networkEgressRules : undefined;
+        return policy;
+    }
+    /**
+     * Reads what this sandbox reached in learn mode and the allow list that
+     * would have allowed it. A recording stays readable after the sandbox
+     * switches to enforce, until it is destroyed.
+     */
+    async learned() {
+        return this.client.getNetworkLearned(this.id);
+    }
+    /**
+     * Reads this sandbox's audit log: outbound connections and egress denials
+     * (`kind: "egress"`), and secret reads. Denials carry `result: "failure"`
+     * and the policy `reason`.
+     */
+    async audit(options) {
+        return this.client.getAudit(this.id, options);
+    }
     toJSON() {
         return cloneSandbox(this);
     }
@@ -603,6 +797,8 @@ export class SandboxResource {
 }
 function toApiCreateOptions(options) {
     return {
+        name: options.name,
+        tags: options.tags,
         image: options.image,
         cpu: options.cpu,
         memory_mb: options.memoryMB,
@@ -612,6 +808,9 @@ function toApiCreateOptions(options) {
         network_block_all: options.networkBlockAll,
         network_allow_out: options.networkAllowOut,
         network_deny_out: options.networkDenyOut,
+        egress_profiles: options.egressProfiles,
+        network_egress_mode: options.networkEgressMode,
+        network_egress_rules: options.networkEgressRules?.map(toApiEgressRule),
         allow_public_traffic: options.allowPublicTraffic,
         mask_request_host: options.maskRequestHost,
         network_bytes_in_limit: options.networkBytesInLimit,
@@ -619,9 +818,13 @@ function toApiCreateOptions(options) {
         registry: options.registry,
         container_command: options.containerCommand,
         mounts: options.mounts?.map(toApiMountSpec),
+        platform_volumes: options.platformVolumes?.map(toApiPlatformVolumeMount),
         lifecycle: options.lifecycle ? toApiLifecycle(options.lifecycle) : undefined,
         failover: options.failover ? toApiFailover(options.failover) : undefined,
         runtime: options.runtime,
+        durability: options.durability,
+        module_ref: options.moduleRef,
+        tenant_id: options.tenantId,
         custom_domains: options.customDomains,
     };
 }
@@ -683,6 +886,8 @@ function toApiFailover(failover) {
 function fromApiSandbox(sandbox) {
     return {
         id: sandbox.id,
+        name: sandbox.name || undefined,
+        tags: sandbox.tags,
         image: sandbox.image,
         status: sandbox.status,
         publicURL: sandbox.public_url,
@@ -694,6 +899,11 @@ function fromApiSandbox(sandbox) {
         osUser: sandbox.os_user,
         env: sandbox.env,
         networkBlockAll: sandbox.network_block_all,
+        egressStatus: sandbox.egress_status || undefined,
+        egressProfiles: sandbox.egress_profiles?.length ? sandbox.egress_profiles : undefined,
+        egressProfilesApplied: sandbox.egress_profiles_applied?.length ? sandbox.egress_profiles_applied : undefined,
+        networkEgressMode: sandbox.network_egress_mode || undefined,
+        networkEgressRules: sandbox.network_egress_rules?.length ? sandbox.network_egress_rules.map(fromApiEgressRule) : undefined,
         toolboxEnabled: sandbox.toolbox_enabled,
         sshPublicKey: sandbox.ssh_public_key,
         exposedPorts: sandbox.exposed_ports?.map(fromApiExposedPort),
@@ -705,13 +915,22 @@ function fromApiSandbox(sandbox) {
         lifecycle: fromApiLifecycle(sandbox.lifecycle),
         failover: fromApiFailover(sandbox.failover),
         runtime: normalizeRuntime(sandbox.runtime),
+        durability: sandbox.durability,
+        moduleRef: sandbox.module_ref,
+        moduleDigest: sandbox.module_digest,
+        tenantId: sandbox.tenant_id,
     };
 }
 // normalizeRuntime narrows the wire-level string to the union we expose, while
 // tolerating older sandboxd versions that don't send the field at all (treat
 // as "" — i.e. host default at start time).
 function normalizeRuntime(value) {
-    if (value === "docker" || value === "gvisor" || value === "kata") {
+    if (value === "docker" ||
+        value === "gvisor" ||
+        value === "kata" ||
+        value === "firecracker" ||
+        value === "wasm" ||
+        value === "isolate") {
         return value;
     }
     return "";
@@ -856,6 +1075,13 @@ function toApiMountSpec(mount) {
         read_only: mount.readOnly,
     };
 }
+function toApiPlatformVolumeMount(volume) {
+    return {
+        name: volume.name,
+        path: volume.path,
+        read_only: volume.readOnly,
+    };
+}
 function fromApiMountSpecRedacted(mount) {
     return {
         type: mount.type,
@@ -866,6 +1092,31 @@ function fromApiMountSpecRedacted(mount) {
         hasCredentials: mount.has_credentials,
     };
 }
+function fromApiAuditPage(page) {
+    const out = {
+        events: (page.events ?? []).map((e) => ({
+            time: e.time,
+            kind: e.kind,
+            result: e.result,
+            reason: e.reason,
+            destination: e.destination,
+            network: e.network,
+            actor: e.actor,
+            ref: e.ref,
+            eventID: e.event_id,
+            incarnationID: e.incarnation_id,
+            dropped: e.dropped,
+        })),
+        coverage: {
+            answered: page.coverage?.answered ?? [],
+            missing: page.coverage?.missing ?? [],
+            partial: page.coverage?.partial ?? false,
+        },
+    };
+    if (page.next_cursor)
+        out.nextCursor = page.next_cursor;
+    return out;
+}
 function fromApiNetworkUsage(usage) {
     return {
         sandboxID: usage.sandbox_id,
@@ -925,10 +1176,32 @@ function buildTagQuery(tags) {
     const parts = entries.map(([key, value]) => `tag.${encodeURIComponent(key)}=${encodeURIComponent(value)}`);
     return "?" + parts.join("&");
 }
+function buildIncludeEnvQuery(includeEnv) {
+    return includeEnv ? "?include_env=true" : "";
+}
+function buildSandboxListQuery(options) {
+    let query = buildTagQuery(options?.tags);
+    if (options?.includeEnv) {
+        query = appendQueryParam(query, "include_env", "true");
+    }
+    const name = options?.name?.trim();
+    if (name) {
+        query = appendQueryParam(query, "name", name);
+    }
+    return query;
+}
+function appendQueryParam(path, key, value) {
+    if (!value) {
+        return path;
+    }
+    const sep = path.includes("?") ? "&" : "?";
+    return `${path}${sep}${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+}
 function cloneSandbox(sandbox) {
     return {
         ...sandbox,
         env: sandbox.env ? { ...sandbox.env } : undefined,
+        tags: sandbox.tags ? { ...sandbox.tags } : undefined,
         exposedPorts: sandbox.exposedPorts?.map((port) => ({ ...port })),
         containerCommand: sandbox.containerCommand ? [...sandbox.containerCommand] : undefined,
         lifecycle: { ...sandbox.lifecycle },

package/dist/types.d.ts

@@ -65,6 +65,20 @@ export interface MountSpecRedacted {
     readOnly: boolean;
     hasCredentials: boolean;
 }
+/**
+ * A named, operator-backed persistent volume to attach by name. The operator
+ * configures the shared backend (S3/NFS); you never supply storage coordinates
+ * or credentials. Persists across the sandbox lifecycle and can be re-attached
+ * by name from another sandbox.
+ */
+export interface PlatformVolumeMount {
+    /** Volume name, scoped to your tenant. */
+    name: string;
+    /** Absolute path to mount it at inside the sandbox. */
+    path: string;
+    /** Mount read-only. Defaults to read-write. */
+    readOnly?: boolean;
+}
 export interface Lifecycle {
     /** Duration in integer nanoseconds. */
     stopIfIdleFor?: number;
@@ -121,6 +135,15 @@ export interface GPUOptions {
 }
 import type { Image } from "./Image.js";
 export interface CreateOptions {
+    /**
+     * Optional name, unique among the caller's sandboxes (another account may
+     * use the same name). A repeat create with a name the caller already holds
+     * returns HTTP 409. Names starting with `owner:` or shaped like a sandbox
+     * ID (`sb-` plus 16 hex) are rejected.
+     */
+    name?: string;
+    /** Free-form key/value labels; filter on them with `ListOptions.tags`. */
+    tags?: Record<string, 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
@@ -138,21 +161,42 @@ export interface CreateOptions {
     osUser?: string;
     networkBlockAll?: boolean;
     /**
-     * Egress allowlist of CIDRs. When set, the sandbox may reach only these
-     * destinations; all other outbound traffic is dropped by the host firewall.
-     * Mutually exclusive with `networkDenyOut`. For a full block use
-     * `networkBlockAll` instead.
+     * Egress allowlist: CIDRs, hostnames (`pypi.org`), `*.suffix` wildcards and
+     * `host:port` entries. Alone, the sandbox may reach only these. With
+     * `networkDenyOut`, allow wins, then deny, then the default is allow; a
+     * deny of `0.0.0.0/0` makes it an allowlist. For a full block use
+     * `networkBlockAll`.
      */
     networkAllowOut?: string[];
     /**
-     * Egress blocklist of CIDRs. When set, the sandbox may reach anything except
-     * these destinations. Mutually exclusive with `networkAllowOut`.
+     * Egress blocklist of CIDRs (never hostnames). Alone, the sandbox may reach
+     * anything except these destinations.
      */
     networkDenyOut?: string[];
     /**
-     * Whether the sandbox may be exposed to the public internet. Defaults to
-     * true; set `false` to make `exposePort` fail — the sandbox stays reachable
-     * only via the toolbox proxy and SSH gateway, not a public URL.
+     * Named egress profiles whose entries join `networkAllowOut` (see
+     * `putEgressProfile`). A profile change reaches every sandbox that
+     * references it.
+     */
+    egressProfiles?: string[];
+    /**
+     * `"learn"` gives the sandbox open egress and records what it reaches, so
+     * `learned()` can suggest an allow list. Trusted runs only. Needs no lists,
+     * profiles or block-all. Omitted is `"enforce"`.
+     */
+    networkEgressMode?: "enforce" | "learn";
+    /**
+     * Method and path rules that refine hosts the allow list already admits
+     * (at most 32). A rule with `inspect: true` makes the egress gateway
+     * terminate TLS on 443 with the node's CA, which only a sandbox created
+     * with such a rule trusts, so set inspect rules here rather than adding
+     * them later.
+     */
+    networkEgressRules?: EgressRule[];
+    /**
+     * Whether the sandbox may be exposed to the public internet. Omitted defaults
+     * to private (no public URL, `exposePort` fails). Set `true` to opt in to
+     * public exposure; `false` permanently refuses it for this sandbox.
      */
     allowPublicTraffic?: boolean;
     /**
@@ -179,6 +223,12 @@ export interface CreateOptions {
     registry?: RegistryAuth;
     containerCommand?: string[];
     mounts?: MountSpec[];
+    /**
+     * Named, operator-backed persistent volumes to attach by name. Requires the
+     * operator to have enabled platform volumes; otherwise the create is rejected
+     * with 412. Only supported on the docker/gvisor runtimes.
+     */
+    platformVolumes?: PlatformVolumeMount[];
     lifecycle?: Lifecycle;
     failover?: Failover;
     /**
@@ -191,15 +241,22 @@ export interface CreateOptions {
      *
      * GPU access is not supported with `"gvisor"`.
      */
-    runtime?: "docker" | "gvisor" | "kata" | "firecracker" | "wasm";
+    runtime?: "docker" | "gvisor" | "kata" | "firecracker" | "wasm" | "isolate";
     /**
      * Survival class across daemon restarts. Omit for the runtime default:
-     * `passivatable` for docker/gvisor/firecracker, `ephemeral` for wasm.
+     * `passivatable` for docker/gvisor/firecracker, `ephemeral` for wasm/isolate.
      * `durable` is wasm-only and not yet implemented.
      */
     durability?: Durability;
-    /** WASM module reference. When runtime is wasm, may be used instead of image. */
+    /** WASM module / isolate bundle reference. When runtime is wasm or isolate, may be used instead of image. */
     moduleRef?: string;
+    /**
+     * Isolate-group key for `runtime: "isolate"`. Sandboxes with the same
+     * tenant share one workerd process. Server-authorized; when omitted the
+     * group key falls back to the authenticated identity. Ignored by other
+     * runtimes.
+     */
+    tenantId?: string;
     /**
      * Attach GPU resources to the sandbox. Omit for CPU-only workloads.
      * Not compatible with runtime="gvisor".
@@ -227,6 +284,25 @@ export interface ListOptions {
      * or pass an empty map to list every sandbox visible to the PAT.
      */
     tags?: Record<string, string>;
+    /**
+     * When true, include sandbox env vars in the response (`?include_env=true`).
+     * Env is omitted by default — opt-in reads are audited server-side.
+     */
+    includeEnv?: boolean;
+    /**
+     * Filter to the caller's sandbox with exactly this name (`?name=<name>`);
+     * the result has zero or one entries. Names are unique per owner. Servers
+     * that predate name lookup ignore the filter and return a normal list, so
+     * prefer `MicroVM.getByName`, which checks the reply.
+     */
+    name?: string;
+}
+export interface GetOptions {
+    /**
+     * When true, include sandbox env vars in the response (`?include_env=true`).
+     * Env is omitted by default — opt-in reads are audited server-side.
+     */
+    includeEnv?: boolean;
 }
 export interface CreateSessionOptions {
     name?: string;
@@ -389,6 +465,10 @@ export type ExposeResult = {
 };
 export interface Sandbox {
     id: string;
+    /** Name set at create time, unique per owner. Absent for unnamed sandboxes. */
+    name?: string;
+    /** Labels set at create time. */
+    tags?: Record<string, string>;
     image: string;
     status: SandboxStatus;
     publicURL: string;
@@ -400,6 +480,23 @@ export interface Sandbox {
     osUser: string;
     env?: Record<string, string>;
     networkBlockAll: boolean;
+    /**
+     * Hostname-egress state on `get` for a sandbox whose allow list names
+     * hosts (container runtimes): "active", "held" or "unavailable". Absent
+     * otherwise, and on list results.
+     */
+    egressStatus?: string;
+    /** Egress profiles this sandbox references. */
+    egressProfiles?: string[];
+    /**
+     * The generation of each referenced profile that is live on the sandbox,
+     * so a caller can see when a profile change has reached it.
+     */
+    egressProfilesApplied?: EgressProfileRef[];
+    /** `"learn"` while the sandbox records its egress; absent otherwise. */
+    networkEgressMode?: string;
+    /** Method and path rules on the sandbox's egress; absent when it has none. */
+    networkEgressRules?: EgressRule[];
     toolboxEnabled: boolean;
     sshPublicKey?: string;
     sshPrivateKey?: string;
@@ -415,13 +512,15 @@ export interface Sandbox {
      * Container runtime this sandbox is running under. Empty string indicates
      * a pre-migration row that resolves to the host default at start time.
      */
-    runtime: "" | "docker" | "gvisor" | "kata" | "firecracker" | "wasm";
+    runtime: "" | "docker" | "gvisor" | "kata" | "firecracker" | "wasm" | "isolate";
     /** Survival class this sandbox was created with. */
     durability?: Durability;
-    /** Resolved WASM module reference when runtime is wasm. */
+    /** Resolved WASM module / isolate bundle reference when runtime is wasm or isolate. */
     moduleRef?: string;
     /** sha256 hex digest of the resolved WASM module bytes. */
     moduleDigest?: string;
+    /** Isolate-group key this sandbox was created under (`runtime: "isolate"` only). */
+    tenantId?: string;
     /** GPU configuration this sandbox was created with. Absent means no GPU. */
     gpus?: GPUOptions;
 }
@@ -443,6 +542,214 @@ export interface NetworkUsage {
     /** Absent until the netstats poller has produced at least one sample. */
     lastSampledAt?: string;
 }
+/** One record from a sandbox's audit log (`sandbox.audit()`). */
+export interface AuditEvent {
+    time: string;
+    /** "egress" for outbound connections and denials; secret kinds otherwise. */
+    kind?: string;
+    /** "success", or "failure" for a denial. */
+    result: string;
+    /** Why it was denied, e.g. "host_not_allowed", "sni_not_allowed". */
+    reason?: string;
+    /** host:port (or host) the sandbox tried to reach. */
+    destination?: string;
+    network?: string;
+    actor?: string;
+    ref?: string;
+    eventID?: string;
+    incarnationID?: string;
+    /** Records lost at this point (a gap record). */
+    dropped?: number;
+}
+export interface AuditPage {
+    events: AuditEvent[];
+    /** Which nodes answered; `partial` is true when some could not. */
+    coverage: {
+        answered: string[];
+        missing: string[];
+        partial: boolean;
+    };
+    /** Pass to `audit({ cursor })` for the next page. */
+    nextCursor?: string;
+}
+export interface AuditOptions {
+    /** Only this kind, e.g. "egress". */
+    kind?: string;
+    limit?: number;
+    cursor?: string;
+    incarnationID?: string;
+}
+/**
+ * Would a sandbox created with these egress fields reach `destination`?
+ * `destination` is "host", "host:port", "IP" or "IP:port"; a bare host is
+ * checked as the web ports.
+ */
+export interface NetworkPolicyCheckOptions {
+    networkBlockAll?: boolean;
+    networkAllowOut?: string[];
+    networkDenyOut?: string[];
+    destination: string;
+}
+export interface NetworkPolicyCheckResult {
+    allowed: boolean;
+    /** The entry that decided; "" when the default verdict did. */
+    matchedRule: string;
+    /** "allow" or "deny": what happens to a destination no entry matches. */
+    defaultVerdict: string;
+    /** The first allow entry outside this deployment's ceiling, if any. */
+    outsideCeiling?: string;
+}
+/**
+ * A sandbox's whole egress policy, for `setNetworkPolicy`. It replaces the
+ * current policy: a field left out is cleared, so `{}` means open egress.
+ * The grammar is the create one (hostnames, `*.` wildcards, `host:port` and
+ * CIDRs in the allow list; CIDRs only in the deny list).
+ */
+export interface NetworkPolicyOptions {
+    networkBlockAll?: boolean;
+    networkAllowOut?: string[];
+    networkDenyOut?: string[];
+    egressProfiles?: string[];
+    networkEgressMode?: "enforce" | "learn";
+    /**
+     * Replaces the method and path rules. Adding an inspect rule to a
+     * container sandbox created without one is refused with 409: recreate it
+     * with the rule.
+     */
+    networkEgressRules?: EgressRule[];
+}
+/** The policy a sandbox enforces after `setNetworkPolicy`. */
+export interface NetworkPolicy {
+    networkBlockAll: boolean;
+    networkAllowOut: string[];
+    networkDenyOut: string[];
+    egressProfiles: string[];
+    /** `"enforce"` or `"learn"`. */
+    networkEgressMode: string;
+    networkEgressRules: EgressRule[];
+    /** Hostname entries in force: inline plus every profile's (at most 1024). */
+    effectiveHostnameCount: number;
+    /** "active", "held" or "unavailable" for hostname rules on a container. */
+    egressStatus?: string;
+}
+/**
+ * One method, path or program rule. Rules refine a host the allow list
+ * already admits: a request to a ruled host passes when some rule for that
+ * host admits its program, method and path, and gets a 403 otherwise. A host
+ * no rule names keeps its allow-list decision.
+ */
+export interface EgressRule {
+    /** An exact name or `*.` wildcard, without a port. */
+    host: string;
+    /**
+     * `[80]` by default, or `[443]` with `inspect`; only 80 and 443, except
+     * that a rule with only `binaries` may name any port the allow list opens.
+     */
+    ports?: number[];
+    /** Exact, upper case (`GET`, `POST`); empty allows any. */
+    methods?: string[];
+    /**
+     * Path globs: `*` within one segment, `**` as a whole segment for any
+     * number of them. Empty allows any path.
+     */
+    paths?: string[];
+    /**
+     * Terminate TLS on 443 with the node's CA so the rule can see requests.
+     * The request's Host must then equal the TLS server name.
+     */
+    inspect?: boolean;
+    /**
+     * Replace a header on the requests this rule allows with a secret from
+     * the sandbox's own `env`, which the sandbox itself only sees as a
+     * placeholder. Needs `inspect: true`.
+     */
+    inject?: EgressInject;
+    /**
+     * Limit the rule to connections opened by these executables: clean
+     * absolute paths inside the sandbox, at most 16. For an interpreter
+     * (python, node, a shell) the script it runs counts too, so
+     * `/usr/local/bin/pip` works. A rule with only `binaries` decides whole
+     * connections, on any port the allow list opens. Runc sandboxes only
+     * (docker and containerd); least privilege for trusted tooling, not a
+     * security boundary.
+     */
+    binaries?: string[];
+}
+/**
+ * A rule's credential injection. The sandbox's env holds
+ * `aerolvm-placeholder:<KEY>` in place of the value, and the egress gateway
+ * replaces `header` with the real value on each request the rule allows, so
+ * code in the sandbox never holds the secret.
+ */
+export interface EgressInject {
+    /**
+     * The header to replace, such as `Authorization`. It is replaced, never
+     * added to a body or URL. Headers that frame or route the request, such as
+     * `Host` or `Content-Length`, can't be injected.
+     */
+    header: string;
+    /**
+     * `"env:<KEY>"`: a key in the create's `env`, whose value is the whole
+     * header value (for example `Bearer ghp_...`). Rotating it means
+     * recreating the sandbox.
+     */
+    secretRef: string;
+}
+/**
+ * A named allowlist sandboxes reference through `egressProfiles`. Profiles
+ * belong to your account; `generation` goes up by one on every change.
+ */
+export interface EgressProfile {
+    name: string;
+    /** Hostnames, `*.` wildcards, `host:port` entries and CIDRs (at most 512 hostnames). */
+    allowOut: string[];
+    description?: string;
+    generation: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** The body of `putEgressProfile`: a full replace. */
+export interface EgressProfileOptions {
+    allowOut: string[];
+    description?: string;
+}
+export interface ListEgressProfilesOptions {
+    cursor?: string;
+    limit?: number;
+}
+export interface EgressProfileList {
+    profiles: EgressProfile[];
+    /** Pass back as `cursor` for the next page; absent on the last one. */
+    nextCursor?: string;
+}
+/** One destination a learn-mode sandbox reached. */
+export interface NetworkLearnedEntry {
+    host: string;
+    /** Connection ports; empty when the name was only resolved. */
+    ports: number[];
+    firstSeen: string;
+    lastSeen: string;
+    hits: number;
+}
+/**
+ * What a sandbox reached in learn mode, and the allow list that would have
+ * allowed it: `suggestedAllowOut` when it fits 64 hostnames, otherwise
+ * `suggestedProfile` (a body for `putEgressProfile`).
+ */
+export interface NetworkLearned {
+    mode: string;
+    /** Recording stopped at its cap. */
+    truncated: boolean;
+    entries: NetworkLearnedEntry[];
+    cidrs: string[];
+    suggestedAllowOut: string[];
+    suggestedProfile?: EgressProfileOptions;
+}
+/** A referenced profile and the generation of it that is live on a sandbox. */
+export interface EgressProfileRef {
+    name: string;
+    generation: number;
+}
 export interface SetNetworkLimitsOptions {
     /** Omit (undefined) to leave unchanged. `0` means unlimited. */
     networkBytesInLimit?: number;

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.5.3",
+  "version": "0.6.4",
   "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aerol-ai/microvm.git",
+    "directory": "sdk/typescript"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,8 +26,8 @@
     "test": "tsc -p tsconfig.test.json --outDir dist-test && node --test dist-test/*.test.js dist-test/internal/*.test.js"
   },
   "devDependencies": {
-    "@types/node": "^25.9.3",
-    "typescript": "^6.0.3",
-    "tsx": "^4.22.4"
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2",
+    "tsx": "^4.23.15"
   }
 }