@capsulos/sdk 0.1.2 → 0.3.0

package/dist/capsule.d.ts

@@ -1,7 +1,7 @@
 import { DaemonClient, type ClientOptions } from './client.js';
 import { Ports } from './ports.js';
 import { PtySession } from './pty.js';
-import { type CapsuleSpec, type ExecOptions, type ExecResult, type FileEntry, type Health, type Provider, type PtyOptions } from './types.js';
+import { type CapsuleSpec, type ExecOptions, type ExecResult, type FileEntry, type Health, type Provider, type PtyOptions, type SnapshotResult } from './types.js';
 export interface CapsuleOptions extends ClientOptions {
     /** How long to wait for the daemon to answer /health after creation. */
     readyTimeoutMs?: number;
@@ -14,6 +14,7 @@ export declare class Capsule {
     readonly id: string;
     private readonly provider;
     private readonly client;
+    private readonly readyTimeoutMs;
     readonly commands: Commands;
     readonly files: Files;
     readonly pty: Pty;
@@ -25,6 +26,20 @@ export declare class Capsule {
     /** Reconnect to a capsule that already exists (it may be suspended: the first request resumes it). */
     static connect(provider: Provider, id: string, opts?: CapsuleOptions): Promise<Capsule>;
     health(): Promise<Health>;
+    /**
+     * Freeze the capsule: processes stop, memory stays. Resume with `resume()`
+     * (or, on providers with auto-resume, with the next request). Throws when
+     * the provider has no explicit pause.
+     */
+    pause(): Promise<void>;
+    /** Wake a paused capsule and wait until the daemon answers again. */
+    resume(): Promise<void>;
+    /**
+     * Save the capsule's disk as a new template under `name`; `Capsule.create`
+     * with that template starts from this state. Not every provider can
+     * (Lambda MicroVMs cannot image a live VM).
+     */
+    snapshot(name: string): Promise<SnapshotResult>;
     /** Put the capsule back in your pocket. */
     kill(): Promise<void>;
 }

package/dist/capsule.js

@@ -1,6 +1,7 @@
 // The public face of a capsule. `Capsule.create()` asks the provider for a
 // machine and waits until capsulod answers; everything after that goes
 // straight to the daemon.
+import { validateNetworkPolicy } from './network.js';
 import { DaemonClient } from './client.js';
 import { Ports } from './ports.js';
 import { PtySession } from './pty.js';
@@ -9,15 +10,17 @@ export class Capsule {
     id;
     provider;
     client;
+    readyTimeoutMs;
     commands;
     files;
     pty;
     /** Servers listening inside the capsule, reachable through the daemon (preview URLs). */
     ports;
-    constructor(id, provider, client) {
+    constructor(id, provider, client, readyTimeoutMs = 120_000) {
         this.id = id;
         this.provider = provider;
         this.client = client;
+        this.readyTimeoutMs = readyTimeoutMs;
         this.commands = new Commands(client);
         this.files = new Files(client);
         this.pty = new Pty(client);
@@ -25,34 +28,76 @@ export class Capsule {
     }
     /** Throw a capsule: create it with the provider and wait until it is ready. */
     static async create(provider, spec, opts = {}) {
+        const network = validateNetworkPolicy(spec.network);
         const handle = await provider.create(spec, { timeoutMs: opts.createTimeoutMs, signal: opts.signal });
         const client = new DaemonClient(handle.connection, opts);
-        const health = await waitReady(client, opts.readyTimeoutMs ?? 120_000, opts.signal);
-        // Providers deliver the mount table through their boot hook. When that did
-        // not happen (no hook, or the hook came without its payload), hand it over
-        // directly. Either way, a mount that failed is an error here, not a
-        // surprise later when a write lands in a plain directory.
-        let results = health.mounts ?? [];
-        const wanted = Object.keys(spec.mounts ?? {});
-        const applied = new Set(results.map((r) => r.path));
-        const hookMissed = !health.configured || wanted.some((p) => !applied.has(p));
-        if (hookMissed && (spec.mounts || spec.metadata)) {
-            results = await client.configure({ mounts: spec.mounts, metadata: spec.metadata });
+        try {
+            const health = await waitReady(client, opts.readyTimeoutMs ?? 120_000, opts.signal);
+            // Providers deliver mounts and network policy through their boot hook.
+            // When that did not happen (no hook, or the hook came without its
+            // payload, or the policy failed there), hand it over directly. Either
+            // way, a mount that failed or a policy that is not enforced is an error
+            // here, not a surprise later.
+            let results = health.mounts ?? [];
+            let status = health.network;
+            const wanted = Object.keys(spec.mounts ?? {});
+            const applied = new Set(results.map((r) => r.path));
+            const hookMissed = !health.configured || wanted.some((p) => !applied.has(p)) || (network && !status?.enforced);
+            if (hookMissed && (spec.mounts || spec.metadata || network)) {
+                ({ mounts: results, network: status } = await client.configure({ mounts: spec.mounts, metadata: spec.metadata, network }));
+            }
+            const failed = results.filter((r) => !r.ok);
+            if (failed.length) {
+                throw new CapsuleError(`mounts failed: ${failed.map((r) => `${r.path} (${r.driver}): ${r.error}`).join('; ')}`);
+            }
+            if (network && !status?.enforced) {
+                throw new CapsuleError(`network policy not enforced: ${status?.error ?? 'the daemon reported no policy (is it 0.3.0 or newer?)'}`);
+            }
         }
-        const failed = results.filter((r) => !r.ok);
-        if (failed.length) {
-            throw new CapsuleError(`mounts failed: ${failed.map((r) => `${r.path} (${r.driver}): ${r.error}`).join('; ')}`);
+        catch (err) {
+            // A capsule that did not get its spec is not handed out: it goes, and
+            // the error says which one it was.
+            await provider.terminate(handle.id).catch(() => { });
+            const e = err instanceof CapsuleError ? err : new CapsuleError(err instanceof Error ? err.message : String(err));
+            throw new CapsuleError(`${e.message} (capsule ${handle.id} terminated)`, e.status, { capsuleId: handle.id });
         }
-        return new Capsule(handle.id, provider, client);
+        return new Capsule(handle.id, provider, client, opts.readyTimeoutMs);
     }
     /** Reconnect to a capsule that already exists (it may be suspended: the first request resumes it). */
     static async connect(provider, id, opts = {}) {
         const conn = await provider.connect(id);
-        return new Capsule(id, provider, new DaemonClient(conn, opts));
+        return new Capsule(id, provider, new DaemonClient(conn, opts), opts.readyTimeoutMs);
     }
     health() {
         return this.client.health();
     }
+    /**
+     * Freeze the capsule: processes stop, memory stays. Resume with `resume()`
+     * (or, on providers with auto-resume, with the next request). Throws when
+     * the provider has no explicit pause.
+     */
+    async pause() {
+        if (!this.provider.pause)
+            throw unsupported(this.provider, 'pause');
+        await this.provider.pause(this.id);
+    }
+    /** Wake a paused capsule and wait until the daemon answers again. */
+    async resume() {
+        if (!this.provider.resume)
+            throw unsupported(this.provider, 'resume');
+        await this.provider.resume(this.id);
+        await waitReady(this.client, this.readyTimeoutMs);
+    }
+    /**
+     * Save the capsule's disk as a new template under `name`; `Capsule.create`
+     * with that template starts from this state. Not every provider can
+     * (Lambda MicroVMs cannot image a live VM).
+     */
+    async snapshot(name) {
+        if (!this.provider.snapshot)
+            throw unsupported(this.provider, 'snapshot');
+        return this.provider.snapshot(this.id, name);
+    }
     /** Put the capsule back in your pocket. */
     async kill() {
         await this.provider.terminate(this.id);
@@ -105,6 +150,9 @@ export class Files {
         return this.client.remove(path);
     }
 }
+function unsupported(provider, op) {
+    return new CapsuleError(`the ${provider.name} provider does not support ${op}()`);
+}
 async function waitReady(client, timeoutMs, signal) {
     const t0 = Date.now();
     let lastErr;

package/dist/capsule.js.map

@@ -1 +1 @@
-{"version":3,"file":"capsule.js","sourceRoot":"","sources":["../src/capsule.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"capsule.js","sourceRoot":"","sources":["../src/capsule.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type Connection, type ExecEvent, type ExecOptions, type ExecResult, type FileEntry, type Health, type MountResult, type MountSpec } from './types.js';
+import { type Connection, type ExecEvent, type ExecOptions, type ExecResult, type FileEntry, type Health, type MountResult, type MountSpec, type NetworkPolicy, type NetworkStatus } from './types.js';
 export interface ClientOptions {
     fetch?: typeof fetch;
     requestTimeoutMs?: number;
@@ -10,11 +10,15 @@ export declare class DaemonClient {
     constructor(connection: Connection, opts?: ClientOptions);
     private request;
     health(): Promise<Health>;
-    /** Apply the mount table when the provider's boot hook did not deliver it. */
+    /** Apply the mount table and network policy when the provider's boot hook did not deliver them. */
     configure(body: {
         mounts?: Record<string, MountSpec>;
         metadata?: Record<string, string>;
-    }): Promise<MountResult[]>;
+        network?: NetworkPolicy;
+    }): Promise<{
+        mounts: MountResult[];
+        network?: NetworkStatus;
+    }>;
     /** Buffered or streamed depending on whether callbacks are given. */
     exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
     readFile(path: string): Promise<Uint8Array>;

package/dist/client.js

@@ -37,7 +37,7 @@ export class DaemonClient {
         const res = await this.request('/health', { timeoutMs: 10_000 });
         return (await res.json());
     }
-    /** Apply the mount table when the provider's boot hook did not deliver it. */
+    /** Apply the mount table and network policy when the provider's boot hook did not deliver them. */
     async configure(body) {
         const res = await this.request('/configure', {
             method: 'POST',
@@ -45,7 +45,8 @@ export class DaemonClient {
             headers: { 'Content-Type': 'application/json' },
             timeoutMs: 60_000,
         });
-        return (await res.json()).mounts ?? [];
+        const out = (await res.json());
+        return { mounts: out.mounts ?? [], network: out.network };
     }
     /** Buffered or streamed depending on whether callbacks are given. */
     async exec(cmd, opts = {}) {

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,gFAAgF;AAChF,OAAO,EACL,YAAY,GAWb,MAAM,YAAY,CAAC;AAOpB,MAAM,OAAO,YAAY;IAKZ;IAJM,SAAS,CAAe;IACxB,gBAAgB,CAAS;IAE1C,YACW,UAAsB,EAC/B,OAAsB,EAAE;QADf,eAAU,GAAV,UAAU,CAAY;QAG/B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QAC7D,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,IAAI,MAAM,CAAC;IAC1D,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,OAA6C,EAAE,EAAE,KAAK,GAAG,KAAK;QAChG,MAAM,OAAO,GAAG,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,GAAI,IAAI,CAAC,OAA8C,EAAE,CAAC;QAC3H,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;YACpE,GAAG,IAAI;YACP,OAAO;YACP,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,gBAAgB,CAAC;SACrE,CAAC,CAAC;QACH,6FAA6F;QAC7F,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACzD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,MAAM,GAAI,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAwB,CAAC,KAAK,IAAI,EAAE,CAAC;YAClE,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;YACD,MAAM,IAAI,YAAY,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK,IAAI,IAAI,WAAW,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3H,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,MAAM;QACV,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;QACjE,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAW,CAAC;IACtC,CAAC;IAED,mGAAmG;IACnG,KAAK,CAAC,SAAS,CAAC,IAIf;QACC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE;YAC3C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAC1B,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,SAAS,EAAE,MAAM;SAClB,CAAC,CAAC;QACH,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAwD,CAAC;QACtF,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;IAC5D,CAAC;IAED,qEAAqE;IACrE,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,OAAoB,EAAE;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;YAC1B,GAAG;YACH,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC,CAAC;QACH,+EAA+E;QAC/E,MAAM,SAAS,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC,GAAG,MAAM,CAAC;QACtD,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE1D,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;YAC9H,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAe,CAAC;QAC1C,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE;YACtC,MAAM,EAAE,MAAM;YACd,IAAI;YACJ,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,EAAE,mBAAmB,EAAE;YAC5E,SAAS;SACV,CAAC,CAAC;QACH,MAAM,MAAM,GAAe,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;QACnG,IAAI,KAAK,EAAE,MAAM,EAAE,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACrC,IAAI,EAAE,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACzB,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,IAAI,CAAC;gBACzB,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YAC3B,CAAC;iBAAM,IAAI,EAAE,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAChC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,IAAI,CAAC;gBACzB,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,QAAQ,GAAG,EAAE,CAAC,QAAQ,IAAI,CAAC,CAAC;gBACnC,MAAM,CAAC,OAAO,GAAG,EAAE,CAAC,OAAO,IAAI,KAAK,CAAC;gBACrC,IAAI,EAAE,CAAC,KAAK;oBAAE,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC;YACxC,CAAC;QACH,CAAC;QACD,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAC3C,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,oBAAoB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/E,OAAO,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,IAAyB,EAAE,OAA0B,EAAE;QACnF,MAAM,CAAC,GAAG,IAAI,eAAe,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACnF,MAAM,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,EAAE;YACtC,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,IAAiB;YAC1D,OAAO,EAAE,EAAE,cAAc,EAAE,0BAA0B,EAAE;SACxD,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,oBAAoB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/E,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAgB,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,oBAAoB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/E,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAc,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,IAAI,CAAC,OAAO,CAAC,qBAAqB,kBAAkB,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1F,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,MAAM,IAAI,CAAC,OAAO,CAAC,eAAe,kBAAkB,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IACtF,CAAC;CACF;AAED,qDAAqD;AACrD,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAa;IAC3C,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;IACrC,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,YAAY,CAAC,yBAAyB,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,SAAS,CAAC;QACR,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5C,IAAI,IAAI;YAAE,MAAM;QAChB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,IAAI,GAAW,CAAC;QAChB,OAAO,CAAC,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YACnC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;YAC/B,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;YACvE,IAAI,QAAQ;gBAAE,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAc,CAAC;QACjE,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export type { CapsuleOptions } from './capsule.js';
 export { DaemonClient, parseSse } from './client.js';
 export type { ClientOptions } from './client.js';
 export * from './types.js';
+export { validateNetworkPolicy } from './network.js';

package/dist/index.js

@@ -3,4 +3,5 @@ export { Ports } from './ports.js';
 export { PtySession } from './pty.js';
 export { DaemonClient, parseSse } from './client.js';
 export * from './types.js';
+export { validateNetworkPolicy } from './network.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAErD,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAErD,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC"}

package/dist/network.d.ts

@@ -0,0 +1,7 @@
+import { type NetworkPolicy } from './types.js';
+/**
+ * Check a network policy before a capsule is created with it (the daemon
+ * applies the same rules; failing here saves a launch). Returns the policy
+ * when it restricts something, undefined when it does not.
+ */
+export declare function validateNetworkPolicy(policy: NetworkPolicy | undefined): NetworkPolicy | undefined;

package/dist/network.js

@@ -0,0 +1,37 @@
+import { CapsuleError } from './types.js';
+/**
+ * Check a network policy before a capsule is created with it (the daemon
+ * applies the same rules; failing here saves a launch). Returns the policy
+ * when it restricts something, undefined when it does not.
+ */
+export function validateNetworkPolicy(policy) {
+    if (!policy)
+        return undefined;
+    if (policy.internet !== 'allow' && policy.internet !== 'deny') {
+        throw new CapsuleError(`network.internet must be 'allow' or 'deny', got ${JSON.stringify(policy.internet)}`);
+    }
+    if (policy.internet === 'allow') {
+        if (policy.allow?.length)
+            throw new CapsuleError("network.allow needs network.internet: 'deny'");
+        return undefined;
+    }
+    for (const entry of policy.allow ?? []) {
+        if (!isAllowEntry(entry)) {
+            throw new CapsuleError(`bad network.allow entry ${JSON.stringify(entry)} (want host, *.domain or host:port)`);
+        }
+    }
+    return policy;
+}
+const HOST = /^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
+function isAllowEntry(entry) {
+    if (typeof entry !== 'string')
+        return false;
+    const m = /^(.*?)(?::(\d{1,5}))?$/.exec(entry.trim());
+    if (!m)
+        return false;
+    const [, host, port] = m;
+    if (port !== undefined && (Number(port) < 1 || Number(port) > 65535))
+        return false;
+    return host !== undefined && HOST.test(host);
+}
+//# sourceMappingURL=network.js.map

package/dist/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../src/network.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAsB,MAAM,YAAY,CAAC;AAE9D;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAiC;IACrE,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QAC9D,MAAM,IAAI,YAAY,CAAC,mDAAmD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC/G,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChC,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM;YAAE,MAAM,IAAI,YAAY,CAAC,8CAA8C,CAAC,CAAC;QACjG,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QACvC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,YAAY,CAAC,2BAA2B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;QAChH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,IAAI,GAAG,2EAA2E,CAAC;AAEzF,SAAS,YAAY,CAAC,KAAa;IACjC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,CAAC,GAAG,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACtD,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrB,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnF,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/C,CAAC"}

package/dist/types.d.ts

@@ -9,6 +9,25 @@ export interface Provider {
     terminate(id: string): Promise<void>;
     /** How to reach the daemon of an existing capsule (endpoint + auth headers). */
     connect(id: string): Promise<Connection>;
+    /**
+     * Freeze the capsule now (memory kept, no CPU, no billing for compute on
+     * providers that stop charging). Optional: a provider without it leaves
+     * suspension to its idle policy.
+     */
+    pause?(id: string): Promise<void>;
+    /** Wake a paused capsule and return when the provider reports it running (the daemon may need a moment more). */
+    resume?(id: string): Promise<void>;
+    /**
+     * Save the capsule's current disk as a new template, usable in `create()`.
+     * Optional: Lambda MicroVMs cannot image a live VM (images are built from
+     * a zip), Docker can (`docker commit`).
+     */
+    snapshot?(id: string, name: string): Promise<SnapshotResult>;
+}
+export interface SnapshotResult {
+    /** The template name to pass to `create()` on the same provider. */
+    template: string;
+    provider: string;
 }
 export interface CreateOptions {
     /**
@@ -81,6 +100,7 @@ export interface Health {
     /** True once the mount table was applied (by the boot hook or /configure). */
     configured: boolean;
     mounts?: MountResult[];
+    network?: NetworkStatus;
     /** The template's long-running process (CAPSULOD_START), when the template declares one. */
     service?: ServiceStatus;
 }
@@ -92,6 +112,33 @@ export interface ServiceStatus {
     lastExitCode?: number;
     startedAt?: string;
 }
+/**
+ * What the capsule may reach. With `internet: 'deny'` the daemon runs an
+ * egress proxy limited to `allow` (HTTP_PROXY/HTTPS_PROXY point at it for
+ * every process) and blackholes the default route, so a process that ignores
+ * the proxy gets "network unreachable" rather than the internet. Needs
+ * CAP_NET_ADMIN in the capsule: Lambda templates built with
+ * `--capabilities all`; the Docker provider adds it. Creation fails if the
+ * policy cannot be enforced.
+ */
+export interface NetworkPolicy {
+    /** 'allow' (default): unrestricted. 'deny': nothing leaves except `allow`. */
+    internet: 'allow' | 'deny';
+    /** Destinations still reachable with 'deny': 'host', '*.domain' (subdomains only) or 'host:port'. */
+    allow?: string[];
+}
+/** The daemon's view of the policy (`health().network`; absent without a policy). */
+export interface NetworkStatus {
+    internet: 'allow' | 'deny';
+    allow?: string[];
+    /** True once the proxy runs and the routes are locked. */
+    enforced: boolean;
+    /** The egress proxy's address inside the capsule (127.0.0.1:3128). */
+    proxy?: string;
+    /** Connections refused so far. */
+    blocked: number;
+    error?: string;
+}
 export interface IdlePolicy {
     /** Suspend after this long without traffic (seconds). */
     suspendAfterSeconds: number;
@@ -107,6 +154,8 @@ export interface CapsuleSpec {
     mounts?: Record<string, MountSpec>;
     /** Opaque per-capsule configuration delivered to the daemon at boot (never secrets). */
     metadata?: Record<string, string>;
+    /** Egress policy, enforced inside the capsule by the daemon (default: unrestricted). */
+    network?: NetworkPolicy;
     /** Idempotency key: creating twice with the same key returns the same capsule. */
     clientToken?: string;
 }

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,0EAA0E;AAC1E,kEAAkE;AAClE,gFAAgF;AAwKhF,MAAM,OAAO,YAAa,SAAQ,KAAK;IAM1B;IALX,sGAAsG;IAC7F,SAAS,CAAU;IAE5B,YACE,OAAe,EACN,MAAe,EACxB,OAA+B,EAAE;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,WAAM,GAAN,MAAM,CAAS;QAIxB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACtD,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,0EAA0E;AAC1E,kEAAkE;AAClE,gFAAgF;AA4NhF,MAAM,OAAO,YAAa,SAAQ,KAAK;IAM1B;IALX,sGAAsG;IAC7F,SAAS,CAAU;IAE5B,YACE,OAAe,EACN,MAAe,EACxB,OAA+B,EAAE;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,WAAM,GAAN,MAAM,CAAS;QAIxB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACtD,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capsulos/sdk",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Throw a capsule, get a computer. Sandboxes for AI agents on your own AWS account (Lambda MicroVMs) or on Docker.",
   "license": "Apache-2.0",
   "keywords": [

package/src/capsule.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { Capsule } from './capsule.js';
+import type { Provider } from './types.js';
+
+const bare: Provider = {
+  name: 'bare',
+  async create() {
+    throw new Error('unused');
+  },
+  async get() {
+    return null;
+  },
+  async list() {
+    return [];
+  },
+  async terminate() {},
+  async connect() {
+    return { baseUrl: 'http://capsule', headers: async () => ({}) };
+  },
+};
+
+describe('Capsule optional operations', () => {
+  it('names the provider and the operation when it is not supported', async () => {
+    const capsule = await Capsule.connect(bare, 'c1');
+    await expect(capsule.pause()).rejects.toThrow(/bare provider does not support pause\(\)/);
+    await expect(capsule.resume()).rejects.toThrow(/does not support resume\(\)/);
+    await expect(capsule.snapshot('x')).rejects.toThrow(/does not support snapshot\(\)/);
+  });
+
+  it('delegates pause and snapshot to the provider', async () => {
+    const calls: string[] = [];
+    const p: Provider = {
+      ...bare,
+      name: 'full',
+      async pause(id) {
+        calls.push(`pause:${id}`);
+      },
+      async snapshot(id, name) {
+        calls.push(`snapshot:${id}:${name}`);
+        return { template: name, provider: 'full' };
+      },
+    };
+    const capsule = await Capsule.connect(p, 'c1');
+    await capsule.pause();
+    expect(await capsule.snapshot('tpl')).toEqual({ template: 'tpl', provider: 'full' });
+    expect(calls).toEqual(['pause:c1', 'snapshot:c1:tpl']);
+  });
+});

package/src/capsule.ts

@@ -1,6 +1,7 @@
 // The public face of a capsule. `Capsule.create()` asks the provider for a
 // machine and waits until capsulod answers; everything after that goes
 // straight to the daemon.
+import { validateNetworkPolicy } from './network.js';
 import { DaemonClient, type ClientOptions } from './client.js';
 import { Ports } from './ports.js';
 import { PtySession } from './pty.js';
@@ -13,6 +14,7 @@ import {
   type Health,
   type Provider,
   type PtyOptions,
+  type SnapshotResult,
 } from './types.js';
 
 export interface CapsuleOptions extends ClientOptions {
@@ -35,6 +37,7 @@ export class Capsule {
     readonly id: string,
     private readonly provider: Provider,
     private readonly client: DaemonClient,
+    private readonly readyTimeoutMs = 120_000,
   ) {
     this.commands = new Commands(client);
     this.files = new Files(client);
@@ -44,37 +47,78 @@ export class Capsule {
 
   /** Throw a capsule: create it with the provider and wait until it is ready. */
   static async create(provider: Provider, spec: CapsuleSpec, opts: CapsuleOptions = {}): Promise<Capsule> {
+    const network = validateNetworkPolicy(spec.network);
     const handle = await provider.create(spec, { timeoutMs: opts.createTimeoutMs, signal: opts.signal });
     const client = new DaemonClient(handle.connection, opts);
-    const health = await waitReady(client, opts.readyTimeoutMs ?? 120_000, opts.signal);
-    // Providers deliver the mount table through their boot hook. When that did
-    // not happen (no hook, or the hook came without its payload), hand it over
-    // directly. Either way, a mount that failed is an error here, not a
-    // surprise later when a write lands in a plain directory.
-    let results = health.mounts ?? [];
-    const wanted = Object.keys(spec.mounts ?? {});
-    const applied = new Set(results.map((r) => r.path));
-    const hookMissed = !health.configured || wanted.some((p) => !applied.has(p));
-    if (hookMissed && (spec.mounts || spec.metadata)) {
-      results = await client.configure({ mounts: spec.mounts, metadata: spec.metadata });
-    }
-    const failed = results.filter((r) => !r.ok);
-    if (failed.length) {
-      throw new CapsuleError(`mounts failed: ${failed.map((r) => `${r.path} (${r.driver}): ${r.error}`).join('; ')}`);
+    try {
+      const health = await waitReady(client, opts.readyTimeoutMs ?? 120_000, opts.signal);
+      // Providers deliver mounts and network policy through their boot hook.
+      // When that did not happen (no hook, or the hook came without its
+      // payload, or the policy failed there), hand it over directly. Either
+      // way, a mount that failed or a policy that is not enforced is an error
+      // here, not a surprise later.
+      let results = health.mounts ?? [];
+      let status = health.network;
+      const wanted = Object.keys(spec.mounts ?? {});
+      const applied = new Set(results.map((r) => r.path));
+      const hookMissed = !health.configured || wanted.some((p) => !applied.has(p)) || (network && !status?.enforced);
+      if (hookMissed && (spec.mounts || spec.metadata || network)) {
+        ({ mounts: results, network: status } = await client.configure({ mounts: spec.mounts, metadata: spec.metadata, network }));
+      }
+      const failed = results.filter((r) => !r.ok);
+      if (failed.length) {
+        throw new CapsuleError(`mounts failed: ${failed.map((r) => `${r.path} (${r.driver}): ${r.error}`).join('; ')}`);
+      }
+      if (network && !status?.enforced) {
+        throw new CapsuleError(`network policy not enforced: ${status?.error ?? 'the daemon reported no policy (is it 0.3.0 or newer?)'}`);
+      }
+    } catch (err) {
+      // A capsule that did not get its spec is not handed out: it goes, and
+      // the error says which one it was.
+      await provider.terminate(handle.id).catch(() => {});
+      const e = err instanceof CapsuleError ? err : new CapsuleError(err instanceof Error ? err.message : String(err));
+      throw new CapsuleError(`${e.message} (capsule ${handle.id} terminated)`, e.status, { capsuleId: handle.id });
     }
-    return new Capsule(handle.id, provider, client);
+    return new Capsule(handle.id, provider, client, opts.readyTimeoutMs);
   }
 
   /** Reconnect to a capsule that already exists (it may be suspended: the first request resumes it). */
   static async connect(provider: Provider, id: string, opts: CapsuleOptions = {}): Promise<Capsule> {
     const conn = await provider.connect(id);
-    return new Capsule(id, provider, new DaemonClient(conn, opts));
+    return new Capsule(id, provider, new DaemonClient(conn, opts), opts.readyTimeoutMs);
   }
 
   health() {
     return this.client.health();
   }
 
+  /**
+   * Freeze the capsule: processes stop, memory stays. Resume with `resume()`
+   * (or, on providers with auto-resume, with the next request). Throws when
+   * the provider has no explicit pause.
+   */
+  async pause(): Promise<void> {
+    if (!this.provider.pause) throw unsupported(this.provider, 'pause');
+    await this.provider.pause(this.id);
+  }
+
+  /** Wake a paused capsule and wait until the daemon answers again. */
+  async resume(): Promise<void> {
+    if (!this.provider.resume) throw unsupported(this.provider, 'resume');
+    await this.provider.resume(this.id);
+    await waitReady(this.client, this.readyTimeoutMs);
+  }
+
+  /**
+   * Save the capsule's disk as a new template under `name`; `Capsule.create`
+   * with that template starts from this state. Not every provider can
+   * (Lambda MicroVMs cannot image a live VM).
+   */
+  async snapshot(name: string): Promise<SnapshotResult> {
+    if (!this.provider.snapshot) throw unsupported(this.provider, 'snapshot');
+    return this.provider.snapshot(this.id, name);
+  }
+
   /** Put the capsule back in your pocket. */
   async kill(): Promise<void> {
     await this.provider.terminate(this.id);
@@ -122,6 +166,10 @@ export class Files {
   }
 }
 
+function unsupported(provider: Provider, op: string): CapsuleError {
+  return new CapsuleError(`the ${provider.name} provider does not support ${op}()`);
+}
+
 async function waitReady(client: DaemonClient, timeoutMs: number, signal?: AbortSignal): Promise<Health> {
   const t0 = Date.now();
   let lastErr: unknown;

package/src/client.ts

@@ -10,6 +10,8 @@ import {
   type Health,
   type MountResult,
   type MountSpec,
+  type NetworkPolicy,
+  type NetworkStatus,
 } from './types.js';
 
 export interface ClientOptions {
@@ -57,15 +59,20 @@ export class DaemonClient {
     return (await res.json()) as Health;
   }
 
-  /** Apply the mount table when the provider's boot hook did not deliver it. */
-  async configure(body: { mounts?: Record<string, MountSpec>; metadata?: Record<string, string> }): Promise<MountResult[]> {
+  /** Apply the mount table and network policy when the provider's boot hook did not deliver them. */
+  async configure(body: {
+    mounts?: Record<string, MountSpec>;
+    metadata?: Record<string, string>;
+    network?: NetworkPolicy;
+  }): Promise<{ mounts: MountResult[]; network?: NetworkStatus }> {
     const res = await this.request('/configure', {
       method: 'POST',
       body: JSON.stringify(body),
       headers: { 'Content-Type': 'application/json' },
       timeoutMs: 60_000,
     });
-    return ((await res.json()) as { mounts: MountResult[] }).mounts ?? [];
+    const out = (await res.json()) as { mounts?: MountResult[]; network?: NetworkStatus };
+    return { mounts: out.mounts ?? [], network: out.network };
   }
 
   /** Buffered or streamed depending on whether callbacks are given. */

package/src/index.ts

@@ -5,3 +5,4 @@ export type { CapsuleOptions } from './capsule.js';
 export { DaemonClient, parseSse } from './client.js';
 export type { ClientOptions } from './client.js';
 export * from './types.js';
+export { validateNetworkPolicy } from './network.js';

package/src/network.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import { Capsule } from './capsule.js';
+import { validateNetworkPolicy } from './network.js';
+import type { CapsuleHandle, Provider } from './types.js';
+
+describe('validateNetworkPolicy', () => {
+  it('accepts hosts, wildcards and host:port, and treats allow-all as no policy', () => {
+    expect(validateNetworkPolicy(undefined)).toBeUndefined();
+    expect(validateNetworkPolicy({ internet: 'allow' })).toBeUndefined();
+    const p = { internet: 'deny' as const, allow: ['api.anthropic.com', '*.npmjs.org', 'db.internal:5432', 'Host.IO'] };
+    expect(validateNetworkPolicy(p)).toBe(p);
+    expect(validateNetworkPolicy({ internet: 'deny' })).toBeDefined();
+  });
+
+  it('rejects what the daemon would reject, before launching anything', () => {
+    expect(() => validateNetworkPolicy({ internet: 'maybe' as 'allow' })).toThrow(/must be 'allow' or 'deny'/);
+    expect(() => validateNetworkPolicy({ internet: 'allow', allow: ['x.com'] })).toThrow(/needs network.internet: 'deny'/);
+    for (const bad of ['https://x.com', '*', 'a.*.com', 'x.com:99999', 'x.com/path', '', 'x com']) {
+      expect(() => validateNetworkPolicy({ internet: 'deny', allow: [bad] }), bad).toThrow(/bad network.allow entry/);
+    }
+  });
+});
+
+function fakeProvider(health: Record<string, unknown>, configure: Record<string, unknown> | Error) {
+  const calls: string[] = [];
+  const fetchStub: typeof fetch = async (input, init) => {
+    const path = new URL(String(input)).pathname;
+    calls.push(`${init?.method ?? 'GET'} ${path}`);
+    if (path === '/health') return new Response(JSON.stringify({ ok: true, ...health }), { status: 200 });
+    if (configure instanceof Error) return new Response(JSON.stringify({ error: configure.message }), { status: 400 });
+    return new Response(JSON.stringify(configure), { status: 200 });
+  };
+  const handle: CapsuleHandle = {
+    id: 'c1',
+    provider: 'fake',
+    state: 'running',
+    template: 't',
+    createdAt: new Date(),
+    connection: { baseUrl: 'http://capsule', headers: async () => ({}) },
+  };
+  const provider: Provider = {
+    name: 'fake',
+    async create() {
+      calls.push('create');
+      return handle;
+    },
+    async get() {
+      return null;
+    },
+    async list() {
+      return [];
+    },
+    async terminate(id) {
+      calls.push(`terminate ${id}`);
+    },
+    async connect() {
+      return handle.connection;
+    },
+  };
+  return { provider, calls, fetch: fetchStub };
+}
+
+describe('Capsule.create with a network policy', () => {
+  const spec = { template: 't', network: { internet: 'deny' as const, allow: ['api.anthropic.com'] } };
+
+  it('is satisfied when the boot hook already enforced it', async () => {
+    const { provider, calls, fetch } = fakeProvider({ configured: true, network: { internet: 'deny', enforced: true, blocked: 0 } }, {});
+    const capsule = await Capsule.create(provider, spec, { fetch });
+    expect(capsule.id).toBe('c1');
+    expect(calls).toEqual(['create', 'GET /health']);
+  });
+
+  it('hands the policy over through /configure when the hook did not apply it', async () => {
+    const { provider, calls, fetch } = fakeProvider(
+      { configured: false },
+      { ok: true, mounts: [], network: { internet: 'deny', enforced: true, blocked: 0 } },
+    );
+    await Capsule.create(provider, spec, { fetch });
+    expect(calls).toEqual(['create', 'GET /health', 'POST /configure']);
+  });
+
+  it('terminates the capsule and says why when the policy cannot be enforced', async () => {
+    const { provider, calls, fetch } = fakeProvider(
+      { configured: true, network: { internet: 'deny', enforced: false, blocked: 0, error: 'network policy needs CAP_NET_ADMIN' } },
+      new Error('network policy needs CAP_NET_ADMIN: build the template with --capabilities all'),
+    );
+    const err = (await Capsule.create(provider, spec, { fetch }).catch((e: unknown) => e)) as Error & { capsuleId?: string };
+    expect(err.message).toMatch(/CAP_NET_ADMIN/);
+    expect(err.message).toMatch(/capsule c1 terminated/);
+    expect(err.capsuleId).toBe('c1');
+    expect(calls.at(-1)).toBe('terminate c1');
+  });
+
+  it('rejects a bad policy before creating anything', async () => {
+    const { provider, calls, fetch } = fakeProvider({}, {});
+    await expect(Capsule.create(provider, { template: 't', network: { internet: 'deny', allow: ['*'] } }, { fetch })).rejects.toThrow(
+      /bad network.allow entry/,
+    );
+    expect(calls).toEqual([]);
+  });
+});

package/src/network.ts

@@ -0,0 +1,34 @@
+import { CapsuleError, type NetworkPolicy } from './types.js';
+
+/**
+ * Check a network policy before a capsule is created with it (the daemon
+ * applies the same rules; failing here saves a launch). Returns the policy
+ * when it restricts something, undefined when it does not.
+ */
+export function validateNetworkPolicy(policy: NetworkPolicy | undefined): NetworkPolicy | undefined {
+  if (!policy) return undefined;
+  if (policy.internet !== 'allow' && policy.internet !== 'deny') {
+    throw new CapsuleError(`network.internet must be 'allow' or 'deny', got ${JSON.stringify(policy.internet)}`);
+  }
+  if (policy.internet === 'allow') {
+    if (policy.allow?.length) throw new CapsuleError("network.allow needs network.internet: 'deny'");
+    return undefined;
+  }
+  for (const entry of policy.allow ?? []) {
+    if (!isAllowEntry(entry)) {
+      throw new CapsuleError(`bad network.allow entry ${JSON.stringify(entry)} (want host, *.domain or host:port)`);
+    }
+  }
+  return policy;
+}
+
+const HOST = /^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
+
+function isAllowEntry(entry: string): boolean {
+  if (typeof entry !== 'string') return false;
+  const m = /^(.*?)(?::(\d{1,5}))?$/.exec(entry.trim());
+  if (!m) return false;
+  const [, host, port] = m;
+  if (port !== undefined && (Number(port) < 1 || Number(port) > 65535)) return false;
+  return host !== undefined && HOST.test(host);
+}

package/src/types.ts

@@ -14,6 +14,26 @@ export interface Provider {
   terminate(id: string): Promise<void>;
   /** How to reach the daemon of an existing capsule (endpoint + auth headers). */
   connect(id: string): Promise<Connection>;
+  /**
+   * Freeze the capsule now (memory kept, no CPU, no billing for compute on
+   * providers that stop charging). Optional: a provider without it leaves
+   * suspension to its idle policy.
+   */
+  pause?(id: string): Promise<void>;
+  /** Wake a paused capsule and return when the provider reports it running (the daemon may need a moment more). */
+  resume?(id: string): Promise<void>;
+  /**
+   * Save the capsule's current disk as a new template, usable in `create()`.
+   * Optional: Lambda MicroVMs cannot image a live VM (images are built from
+   * a zip), Docker can (`docker commit`).
+   */
+  snapshot?(id: string, name: string): Promise<SnapshotResult>;
+}
+
+export interface SnapshotResult {
+  /** The template name to pass to `create()` on the same provider. */
+  template: string;
+  provider: string;
 }
 
 export interface CreateOptions {
@@ -85,6 +105,7 @@ export interface Health {
   /** True once the mount table was applied (by the boot hook or /configure). */
   configured: boolean;
   mounts?: MountResult[];
+  network?: NetworkStatus;
   /** The template's long-running process (CAPSULOD_START), when the template declares one. */
   service?: ServiceStatus;
 }
@@ -98,6 +119,35 @@ export interface ServiceStatus {
   startedAt?: string;
 }
 
+/**
+ * What the capsule may reach. With `internet: 'deny'` the daemon runs an
+ * egress proxy limited to `allow` (HTTP_PROXY/HTTPS_PROXY point at it for
+ * every process) and blackholes the default route, so a process that ignores
+ * the proxy gets "network unreachable" rather than the internet. Needs
+ * CAP_NET_ADMIN in the capsule: Lambda templates built with
+ * `--capabilities all`; the Docker provider adds it. Creation fails if the
+ * policy cannot be enforced.
+ */
+export interface NetworkPolicy {
+  /** 'allow' (default): unrestricted. 'deny': nothing leaves except `allow`. */
+  internet: 'allow' | 'deny';
+  /** Destinations still reachable with 'deny': 'host', '*.domain' (subdomains only) or 'host:port'. */
+  allow?: string[];
+}
+
+/** The daemon's view of the policy (`health().network`; absent without a policy). */
+export interface NetworkStatus {
+  internet: 'allow' | 'deny';
+  allow?: string[];
+  /** True once the proxy runs and the routes are locked. */
+  enforced: boolean;
+  /** The egress proxy's address inside the capsule (127.0.0.1:3128). */
+  proxy?: string;
+  /** Connections refused so far. */
+  blocked: number;
+  error?: string;
+}
+
 export interface IdlePolicy {
   /** Suspend after this long without traffic (seconds). */
   suspendAfterSeconds: number;
@@ -114,6 +164,8 @@ export interface CapsuleSpec {
   mounts?: Record<string, MountSpec>;
   /** Opaque per-capsule configuration delivered to the daemon at boot (never secrets). */
   metadata?: Record<string, string>;
+  /** Egress policy, enforced inside the capsule by the daemon (default: unrestricted). */
+  network?: NetworkPolicy;
   /** Idempotency key: creating twice with the same key returns the same capsule. */
   clientToken?: string;
 }