isol8 0.1.0-alpha.1

package/dist/client/remote.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @module client/remote
+ *
+ * HTTP client for communicating with a remote isol8 server. Implements the
+ * {@link Isol8Engine} interface, so it can be used interchangeably with
+ * {@link DockerIsol8} for local-vs-remote execution.
+ */
+import type { ExecutionRequest, ExecutionResult, Isol8Engine, Isol8Options, StreamEvent } from "../types";
+/** Connection options for the remote isol8 client. */
+export interface RemoteIsol8Options {
+    /** Base URL of the isol8 server (e.g. `"http://localhost:3000"`). */
+    host: string;
+    /** API key for Bearer token authentication. */
+    apiKey: string;
+    /** Optional session ID for persistent mode. If set, the server maintains container state across calls. */
+    sessionId?: string;
+}
+/**
+ * Remote isol8 client that communicates with an isol8 server over HTTP.
+ * Implements the {@link Isol8Engine} interface for seamless local/remote switching.
+ *
+ * @example
+ * ```typescript
+ * const isol8 = new RemoteIsol8(
+ *   { host: "http://localhost:3000", apiKey: "secret" },
+ *   { network: "none" }
+ * );
+ * await isol8.start();
+ * const result = await isol8.execute({ code: "print(1)", runtime: "python" });
+ * await isol8.stop();
+ * ```
+ */
+export declare class RemoteIsol8 implements Isol8Engine {
+    private readonly host;
+    private readonly apiKey;
+    private readonly sessionId?;
+    private readonly isol8Options?;
+    /**
+     * @param options - Connection options (host, API key, session ID).
+     * @param isol8Options - Isol8 configuration to send to the server.
+     */
+    constructor(options: RemoteIsol8Options, isol8Options?: Isol8Options);
+    /** Verify the remote server is reachable by hitting the `/health` endpoint. */
+    start(): Promise<void>;
+    /** Destroy the remote session (if persistent). No-op for ephemeral mode. */
+    stop(): Promise<void>;
+    /** Execute code on the remote server and return the result. */
+    execute(req: ExecutionRequest): Promise<ExecutionResult>;
+    /**
+     * Execute code on the remote server and stream output chunks via SSE.
+     * Yields {@link StreamEvent} objects as they arrive from the server.
+     */
+    executeStream(req: ExecutionRequest): AsyncIterable<StreamEvent>;
+    /**
+     * Upload a file to the remote container (persistent mode only).
+     * Content is Base64-encoded for transport.
+     */
+    putFile(path: string, content: Buffer | string): Promise<void>;
+    /** Download a file from the remote container (persistent mode only). */
+    getFile(path: string): Promise<Buffer>;
+    /** Internal fetch wrapper that attaches auth and content-type headers. */
+    private fetch;
+}
+//# sourceMappingURL=remote.d.ts.map

package/dist/client/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/client/remote.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,YAAY,EACZ,WAAW,EACZ,MAAM,UAAU,CAAC;AAElB,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,0GAA0G;IAC1G,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAY,YAAW,WAAW;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;IAE7C;;;OAGG;gBACS,OAAO,EAAE,kBAAkB,EAAE,YAAY,CAAC,EAAE,YAAY;IAOpE,+EAA+E;IACzE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,4EAA4E;IACtE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,+DAA+D;IACzD,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAkB9D;;;OAGG;IACI,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,aAAa,CAAC,WAAW,CAAC;IA0DvE;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBpE,wEAAwE;IAClE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB5C,0EAA0E;YAC5D,KAAK;CAUpB"}

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module config
+ *
+ * Configuration discovery and loading for isol8. Searches for `isol8.config.json`
+ * in the working directory and then in `~/.isol8/config.json`, merging any found
+ * config with built-in defaults.
+ */
+import type { Isol8Config } from "./types";
+/**
+ * Built-in default configuration. Used as the base for all config merges.
+ * All values here are the "safe defaults" — network disabled, conservative limits.
+ */
+declare const DEFAULT_CONFIG: Isol8Config;
+/**
+ * Discovers and loads the isol8 configuration file.
+ *
+ * Search order (first match wins):
+ * 1. `isol8.config.json` in CWD (or the provided `cwd` argument)
+ * 2. `~/.isol8/config.json`
+ *
+ * If no config file is found, returns a copy of {@link DEFAULT_CONFIG}.
+ * Partial configs are deep-merged with defaults — you only need to specify
+ * the fields you want to override.
+ *
+ * @param cwd - Optional working directory to search from (defaults to `process.cwd()`).
+ * @returns The resolved configuration.
+ *
+ * @example
+ * ```typescript
+ * const config = loadConfig();
+ * console.log(config.defaults.timeoutMs); // 30000
+ * ```
+ */
+export declare function loadConfig(cwd?: string): Isol8Config;
+export { DEFAULT_CONFIG };
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;GAGG;AACH,QAAA,MAAM,cAAc,EAAE,WAmBrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAepD;AA6BD,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/docker/Dockerfile

@@ -0,0 +1,39 @@
+# ── Base ──────────────────────────────────────────────────────────────
+FROM alpine:3.21 AS base
+RUN apk add --no-cache tini curl ca-certificates
+COPY proxy.mjs /usr/local/bin/proxy.mjs
+RUN chmod +x /usr/local/bin/proxy.mjs
+WORKDIR /sandbox
+ENTRYPOINT ["/sbin/tini", "--"]
+
+# ── Python ────────────────────────────────────────────────────────────
+FROM base AS python
+RUN apk add --no-cache python3 py3-pip
+CMD ["python3"]
+
+# ── Node ──────────────────────────────────────────────────────────────
+FROM base AS node
+RUN apk add --no-cache nodejs npm
+CMD ["node"]
+
+# ── Bun ───────────────────────────────────────────────────────────────
+FROM base AS bun
+RUN apk add --no-cache bash unzip libstdc++ libgcc \
+    && curl -fsSL https://bun.sh/install | bash \
+    && mv /root/.bun/bin/bun /usr/local/bin/bun \
+    && ln -s /usr/local/bin/bun /usr/local/bin/bunx
+CMD ["bun"]
+
+# ── Deno ──────────────────────────────────────────────────────────────
+FROM denoland/deno:alpine AS deno
+RUN apk add --no-cache tini curl ca-certificates
+COPY proxy.mjs /usr/local/bin/proxy.mjs
+RUN chmod +x /usr/local/bin/proxy.mjs
+WORKDIR /sandbox
+ENTRYPOINT ["/sbin/tini", "--"]
+CMD ["deno"]
+
+# ── Bash ──────────────────────────────────────────────────────────────
+FROM base AS bash
+RUN apk add --no-cache bash
+CMD ["bash"]

package/dist/docker/proxy.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+/**
+ * isol8 network proxy — lightweight HTTP/HTTPS filtering proxy.
+ *
+ * Reads whitelist/blacklist regex patterns from env vars and blocks
+ * non-matching outbound requests with 403.
+ *
+ * Env vars:
+ *   ISOL8_WHITELIST - JSON array of regex strings (allow these)
+ *   ISOL8_BLACKLIST - JSON array of regex strings (block these)
+ *   ISOL8_PROXY_PORT - Port to listen on (default: 8118)
+ *
+ * Logic:
+ *   1. If blacklist matches → BLOCK
+ *   2. If whitelist is non-empty and hostname doesn't match → BLOCK
+ *   3. Otherwise → ALLOW
+ */
+
+import http from "node:http";
+import net from "node:net";
+
+const port = Number.parseInt(process.env.ISOL8_PROXY_PORT || "8118", 10);
+
+const whitelist = parsePatterns(process.env.ISOL8_WHITELIST);
+const blacklist = parsePatterns(process.env.ISOL8_BLACKLIST);
+
+function parsePatterns(envVar) {
+  if (!envVar) {
+    return [];
+  }
+  try {
+    const arr = JSON.parse(envVar);
+    return arr.map((p) => new RegExp(p));
+  } catch {
+    return [];
+  }
+}
+
+function isAllowed(hostname) {
+  // Check blacklist first
+  for (const re of blacklist) {
+    if (re.test(hostname)) {
+      return false;
+    }
+  }
+
+  // If whitelist is empty, allow all (only blacklist applies)
+  if (whitelist.length === 0) {
+    return true;
+  }
+
+  // Otherwise, must match at least one whitelist pattern
+  for (const re of whitelist) {
+    if (re.test(hostname)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url, `http://${req.headers.host}`);
+  const hostname = url.hostname;
+
+  if (!isAllowed(hostname)) {
+    res.writeHead(403, { "Content-Type": "text/plain" });
+    res.end(`isol8: request to ${hostname} blocked by network filter`);
+    return;
+  }
+
+  // Forward HTTP request
+  const proxyReq = http.request(
+    {
+      hostname: url.hostname,
+      port: url.port || 80,
+      path: url.pathname + url.search,
+      method: req.method,
+      headers: req.headers,
+    },
+    (proxyRes) => {
+      res.writeHead(proxyRes.statusCode, proxyRes.headers);
+      proxyRes.pipe(res);
+    }
+  );
+
+  proxyReq.on("error", (err) => {
+    res.writeHead(502, { "Content-Type": "text/plain" });
+    res.end(`isol8: proxy error: ${err.message}`);
+  });
+
+  req.pipe(proxyReq);
+});
+
+// Handle HTTPS CONNECT tunneling
+server.on("connect", (req, clientSocket, head) => {
+  const [hostname, port] = req.url.split(":");
+
+  if (!isAllowed(hostname)) {
+    clientSocket.write(
+      "HTTP/1.1 403 Forbidden\r\nContent-Type: text/plain\r\n\r\n" +
+        `isol8: CONNECT to ${hostname} blocked by network filter`
+    );
+    clientSocket.end();
+    return;
+  }
+
+  const serverSocket = net.connect(Number.parseInt(port || "443", 10), hostname, () => {
+    clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+    serverSocket.write(head);
+    serverSocket.pipe(clientSocket);
+    clientSocket.pipe(serverSocket);
+  });
+
+  serverSocket.on("error", (err) => {
+    clientSocket.write(
+      "HTTP/1.1 502 Bad Gateway\r\nContent-Type: text/plain\r\n\r\n" +
+        `isol8: tunnel error: ${err.message}`
+    );
+    clientSocket.end();
+  });
+});
+
+server.listen(port, "127.0.0.1", () => {
+  console.log(`isol8 proxy listening on 127.0.0.1:${port}`);
+});

package/dist/engine/concurrency.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @module engine/concurrency
+ *
+ * Async semaphore for limiting the number of concurrent container executions.
+ * Used by {@link DockerIsol8} to prevent resource exhaustion.
+ */
+/**
+ * A counting semaphore for limiting concurrent async operations.
+ *
+ * @example
+ * ```typescript
+ * const sem = new Semaphore(3); // allow 3 concurrent operations
+ *
+ * await sem.acquire();
+ * try {
+ *   await doWork();
+ * } finally {
+ *   sem.release();
+ * }
+ * ```
+ */
+export declare class Semaphore {
+    private readonly max;
+    private current;
+    private readonly queue;
+    /**
+     * @param max - Maximum number of concurrent acquisitions. Must be ≥ 1.
+     * @throws {Error} If `max` is less than 1.
+     */
+    constructor(max: number);
+    /** The number of permits currently available. */
+    get available(): number;
+    /** The number of callers waiting to acquire a permit. */
+    get pending(): number;
+    /**
+     * Acquire a permit. Resolves immediately if one is available,
+     * otherwise queues the caller until a permit is released.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Release a permit. If callers are queued, the next one is resolved.
+     * Must be called exactly once for each successful `acquire()`.
+     */
+    release(): void;
+}
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/engine/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/engine/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAS;IAQR,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPhC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAE5C;;;OAGG;gBAC0B,GAAG,EAAE,MAAM;IAMxC,iDAAiD;IACjD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,yDAAyD;IACzD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAW9B;;;OAGG;IACH,OAAO,IAAI,IAAI;CAQhB"}

package/dist/engine/docker.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @module engine/docker
+ *
+ * The Docker-backed isol8 engine. Creates and manages Docker containers
+ * for executing untrusted code with resource limits, network controls, and
+ * output sanitization.
+ */
+import Docker from "dockerode";
+import type { ExecutionRequest, ExecutionResult, Isol8Engine, Isol8Options, StreamEvent } from "../types";
+/** Options for constructing a {@link DockerIsol8} instance. Extends {@link Isol8Options} with Docker-specific settings. */
+export interface DockerIsol8Options extends Isol8Options {
+    /** Custom dockerode instance. Defaults to connecting to the local Docker socket. */
+    docker?: Docker;
+}
+/**
+ * Docker-backed isol8 engine that executes code in isolated containers.
+ *
+ * Supports two modes:
+ * - **Ephemeral** — a new container is created and destroyed per `execute()` call.
+ * - **Persistent** — a long-lived container is reused across calls, preserving state.
+ *
+ * @example
+ * ```typescript
+ * const isol8 = new DockerIsol8({ network: "none", memoryLimit: "256m" });
+ * await isol8.start();
+ * const result = await isol8.execute({ code: "print(1+1)", runtime: "python" });
+ * await isol8.stop();
+ * ```
+ */
+export declare class DockerIsol8 implements Isol8Engine {
+    private readonly docker;
+    private readonly mode;
+    private readonly network;
+    private readonly networkFilter?;
+    private readonly cpuLimit;
+    private readonly memoryLimit;
+    private readonly pidsLimit;
+    private readonly readonlyRootFs;
+    private readonly maxOutputSize;
+    private readonly secrets;
+    private readonly defaultTimeoutMs;
+    private readonly overrideImage?;
+    private readonly semaphore;
+    private readonly sandboxSize;
+    private readonly tmpSize;
+    private container;
+    private persistentRuntime;
+    private pool;
+    /**
+     * @param options - Sandbox configuration options.
+     * @param maxConcurrent - Maximum number of concurrent executions (controls the internal semaphore).
+     */
+    constructor(options?: DockerIsol8Options, maxConcurrent?: number);
+    /**
+     * Initialize isol8. Currently a no-op — containers are created
+     * lazily on first `execute()` call.
+     */
+    start(): Promise<void>;
+    /** Stop and remove the container (if one exists). Safe to call multiple times. */
+    stop(): Promise<void>;
+    /**
+     * Execute code in isol8. Acquires a semaphore permit to enforce
+     * the concurrency limit, then delegates to ephemeral or persistent execution.
+     */
+    execute(req: ExecutionRequest): Promise<ExecutionResult>;
+    /**
+     * Upload a file into the running container via a tar archive.
+     * Only available in persistent mode after at least one `execute()` call.
+     *
+     * @param path - Absolute path inside the container.
+     * @param content - File contents.
+     * @throws {Error} If no container is active.
+     */
+    putFile(path: string, content: Buffer | string): Promise<void>;
+    /**
+     * Download a file from the running container.
+     *
+     * @param path - Absolute path inside the container.
+     * @returns File contents as a Buffer.
+     * @throws {Error} If no container is active.
+     */
+    getFile(path: string): Promise<Buffer>;
+    /** The Docker container ID, or `null` if no container is active. Used by the server for session tracking. */
+    get containerId(): string | null;
+    /**
+     * Execute code and stream output chunks as they arrive.
+     * Yields {@link StreamEvent} objects for stdout, stderr, exit, and error events.
+     */
+    executeStream(req: ExecutionRequest): AsyncIterable<StreamEvent>;
+    private resolveImage;
+    private executeEphemeral;
+    private executePersistent;
+    private retrieveFiles;
+    private getFileFromContainer;
+    private startPersistentContainer;
+    private getAdapter;
+    private buildHostConfig;
+    private buildEnv;
+    private streamExecOutput;
+    private collectExecOutput;
+    private postProcessOutput;
+}
+//# sourceMappingURL=docker.d.ts.map

package/dist/engine/docker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker.d.ts","sourceRoot":"","sources":["../../src/engine/docker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,MAAM,MAAM,WAAW,CAAC;AAG/B,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EAEX,YAAY,EAGZ,WAAW,EACZ,MAAM,UAAU,CAAC;AAwNlB,2HAA2H;AAC3H,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACtD,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAY,YAAW,WAAW;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAsB;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,IAAI,CAA8B;IAE1C;;;OAGG;gBACS,OAAO,GAAE,kBAAuB,EAAE,aAAa,SAAK;IAkBhE;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,kFAAkF;IAC5E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB3B;;;OAGG;IACG,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAW9D;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpE;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB5C,6GAA6G;IAC7G,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IAED;;;OAGG;IACI,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,aAAa,CAAC,WAAW,CAAC;YA+EzD,YAAY;YAcZ,gBAAgB;YAmGhB,iBAAiB;YA4FjB,aAAa;YAkBb,oBAAoB;YASpB,wBAAwB;IA2BtC,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,eAAe;IAsBvB,OAAO,CAAC,QAAQ;YA+BD,gBAAgB;YA8EjB,iBAAiB;IA8D/B,OAAO,CAAC,iBAAiB;CAW1B"}

package/dist/engine/image-builder.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @module engine/image-builder
+ *
+ * Builds Docker images for each supported runtime. Base images are built from
+ * the multi-stage `docker/Dockerfile`. Custom images layer user-specified
+ * packages on top of the base images.
+ */
+import type Docker from "dockerode";
+import type { Isol8Config } from "../types";
+/** Progress update emitted during image builds. */
+interface BuildProgress {
+    /** Runtime being built (e.g. `"python"`). */
+    runtime: string;
+    /** Current build status. */
+    status: "building" | "done" | "error";
+    /** Optional status message (error text, package list, etc). */
+    message?: string;
+}
+type ProgressCallback = (progress: BuildProgress) => void;
+/**
+ * Builds the base `isol8:<runtime>` images for all registered runtimes.
+ * Each image is built from the multi-stage Dockerfile in `docker/`.
+ *
+ * @param docker - Dockerode instance.
+ * @param onProgress - Optional callback for build progress updates.
+ */
+export declare function buildBaseImages(docker: Docker, onProgress?: ProgressCallback): Promise<void>;
+/**
+ * Builds custom images with user-specified dependencies layered on top of
+ * the base images. Reads package lists from the config's `dependencies` field.
+ *
+ * @param docker - Dockerode instance.
+ * @param config - Resolved isol8 configuration.
+ * @param onProgress - Optional callback for build progress updates.
+ */
+export declare function buildCustomImages(docker: Docker, config: Isol8Config, onProgress?: ProgressCallback): Promise<void>;
+/**
+ * Checks if an image exists locally.
+ */
+export declare function imageExists(docker: Docker, imageName: string): Promise<boolean>;
+/**
+ * Ensures all base images are built.
+ */
+export declare function ensureImages(docker: Docker, onProgress?: ProgressCallback): Promise<void>;
+export {};
+//# sourceMappingURL=image-builder.d.ts.map

package/dist/engine/image-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-builder.d.ts","sourceRoot":"","sources":["../../src/engine/image-builder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,MAAM,WAAW,CAAC;AAEpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAI5C,mDAAmD;AACnD,UAAU,aAAa;IACrB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;IACtC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,gBAAgB,GAAG,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,gBAAgB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,EACnB,UAAU,CAAC,EAAE,gBAAgB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAkBf;AA4DD;;GAEG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOrF;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAa/F"}

package/dist/engine/pool.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @module engine/pool
+ *
+ * Warm container pool for fast ephemeral execution. Pre-creates and
+ * starts containers so they're ready for immediate use, eliminating
+ * the create+start overhead (~100-200ms per execution).
+ *
+ * After execution, containers are cleaned (sandbox wiped) and returned
+ * to the pool for reuse rather than destroyed.
+ */
+import type Docker from "dockerode";
+/** Configuration for the container pool. */
+export interface PoolOptions {
+    /** Docker client instance. */
+    docker: Docker;
+    /** Max containers to keep warm per image. @default 2 */
+    poolSize?: number;
+    /** Container creation options (HostConfig, Env, etc). */
+    createOptions: Omit<Docker.ContainerCreateOptions, "Image">;
+}
+/**
+ * A per-image warm container pool. Maintains pre-started containers
+ * ready for immediate exec, recycling them after use.
+ */
+export declare class ContainerPool {
+    private readonly docker;
+    private readonly poolSize;
+    private readonly createOptions;
+    private readonly pools;
+    private readonly replenishing;
+    constructor(options: PoolOptions);
+    /**
+     * Acquire a started container for the given image.
+     * Returns a warm container from the pool if available,
+     * otherwise creates and starts a new one.
+     */
+    acquire(image: string): Promise<Docker.Container>;
+    /**
+     * Return a container to the pool after use. The container's /sandbox
+     * tmpfs is wiped clean so it's ready for the next execution.
+     * If the pool is full, the container is destroyed instead.
+     */
+    release(container: Docker.Container, image: string): Promise<void>;
+    /**
+     * Pre-warm the pool for a specific image.
+     * Creates containers up to poolSize.
+     */
+    warm(image: string): Promise<void>;
+    /**
+     * Destroy all pooled containers and clear the pool.
+     */
+    drain(): Promise<void>;
+    private createContainer;
+    /** Replenish the pool in the background (non-blocking). */
+    private replenish;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/engine/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/engine/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,MAAM,MAAM,WAAW,CAAC;AAEpC,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC;CAC7D;AAOD;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+C;IAC7E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;gBAEtC,OAAO,EAAE,WAAW;IAMhC;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC;IAcvD;;;;OAIG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BxE;;;OAGG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAad,eAAe;IAW7B,2DAA2D;IAC3D,OAAO,CAAC,SAAS;CAoClB"}

package/dist/engine/utils.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module engine/utils
+ *
+ * Low-level utility functions used by the Docker engine: memory parsing,
+ * output truncation, secret masking, and POSIX tar archive creation/extraction.
+ */
+/**
+ * Parses a human-readable memory limit string into bytes.
+ *
+ * @param limit - Memory string (e.g. `"512m"`, `"1g"`, `"256k"`, `"1024"`).
+ * @returns The limit in bytes.
+ * @throws {Error} If the format is invalid.
+ *
+ * @example
+ * ```typescript
+ * parseMemoryLimit("512m"); // 536870912
+ * parseMemoryLimit("1g");   // 1073741824
+ * ```
+ */
+export declare function parseMemoryLimit(limit: string): number;
+/**
+ * Truncates output to a maximum byte length. If truncated, appends a
+ * summary line indicating the original and limit sizes.
+ *
+ * @param output - The full output string.
+ * @param maxBytes - Maximum allowed byte length.
+ * @returns Object with the (possibly truncated) text and a truncation flag.
+ */
+export declare function truncateOutput(output: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Replaces all occurrences of secret values in a string with `***`.
+ * Empty secret values are skipped.
+ *
+ * @param text - The text to sanitize.
+ * @param secrets - Map of secret names to values.
+ * @returns The sanitized text.
+ */
+export declare function maskSecrets(text: string, secrets: Record<string, string>): string;
+/**
+ * Creates a POSIX tar archive buffer containing a single file.
+ *
+ * Uses a minimal tar header (512-byte blocks) followed by data blocks
+ * and a 1024-byte end-of-archive marker.
+ *
+ * @param filePath - Path for the file inside the archive (leading `/` is stripped).
+ * @param content - File contents as a string or Buffer.
+ * @returns A Buffer containing the complete tar archive.
+ */
+export declare function createTarBuffer(filePath: string, content: Buffer | string): Buffer;
+/**
+ * Extracts a single file from a tar archive buffer.
+ *
+ * @param tarBuffer - The tar archive buffer.
+ * @param targetPath - Path of the file to extract (leading `/` is stripped for matching).
+ * @returns The extracted file contents as a Buffer.
+ * @throws {Error} If the file is not found in the archive.
+ */
+export declare function extractFromTar(tarBuffer: Buffer, targetPath: string): Buffer;
+//# sourceMappingURL=utils.d.ts.map

package/dist/engine/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/engine/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBtD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAetC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAQjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CA8ClF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAoC5E"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @module isol8
+ *
+ * Public API for the isol8 secure code execution engine.
+ * Import from `"isol8"` to access the engine, client, config, runtime registry, and server.
+ */
+export type { RemoteIsol8Options } from "./client/remote";
+export { RemoteIsol8 } from "./client/remote";
+export { loadConfig } from "./config";
+export type { DockerIsol8Options } from "./engine/docker";
+export { DockerIsol8 } from "./engine/docker";
+export { BunAdapter, bashAdapter, DenoAdapter, NodeAdapter, PythonAdapter, RuntimeRegistry, } from "./runtime";
+export type { RuntimeAdapter } from "./runtime/adapter";
+export { createServer } from "./server/index";
+export type { ExecutionRequest, ExecutionResult, Isol8Config, Isol8Engine, Isol8Mode, Isol8Options, NetworkFilterConfig, NetworkMode, Runtime, StreamEvent, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EACL,UAAU,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,WAAW,EACX,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACX,OAAO,EACP,WAAW,GACZ,MAAM,SAAS,CAAC"}