isol8 0.10.2 → 0.11.0

package/dist/cli.js

@@ -54803,6 +54803,13 @@ function mergeConfig(defaults, overrides) {
       seccomp: overrides.security?.seccomp ?? defaults.security.seccomp,
       customProfilePath: overrides.security?.customProfilePath ?? defaults.security.customProfilePath
     },
+    remoteCode: {
+      ...defaults.remoteCode,
+      ...overrides.remoteCode,
+      allowedSchemes: overrides.remoteCode?.allowedSchemes ?? defaults.remoteCode.allowedSchemes,
+      allowedHosts: overrides.remoteCode?.allowedHosts ?? defaults.remoteCode.allowedHosts,
+      blockedHosts: overrides.remoteCode?.blockedHosts ?? defaults.remoteCode.blockedHosts
+    },
     audit: {
       ...defaults.audit,
       ...overrides.audit
@@ -54834,6 +54841,28 @@ var init_config = __esm(() => {
     security: {
       seccomp: "strict"
     },
+    remoteCode: {
+      enabled: false,
+      allowedSchemes: ["https"],
+      allowedHosts: [],
+      blockedHosts: [
+        "^localhost$",
+        "^127(?:\\.[0-9]{1,3}){3}$",
+        "^\\[::1\\]$",
+        "^::1$",
+        "^10(?:\\.[0-9]{1,3}){3}$",
+        "^172\\.(?:1[6-9]|2[0-9]|3[0-1])(?:\\.[0-9]{1,3}){2}$",
+        "^192\\.168(?:\\.[0-9]{1,3}){2}$",
+        "^169\\.254(?:\\.[0-9]{1,3}){2}$",
+        "^metadata\\.google\\.internal$",
+        "^169\\.254\\.169\\.254$"
+      ],
+      maxCodeSize: 10 * 1024 * 1024,
+      fetchTimeoutMs: 30000,
+      requireHash: false,
+      enableCache: true,
+      cacheTtl: 3600
+    },
     audit: {
       enabled: false,
       destination: "filesystem",
@@ -55174,6 +55203,180 @@ var init_audit = __esm(() => {
   init_logger();
 });
 
+// src/engine/code-fetcher.ts
+import { createHash } from "node:crypto";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+function sha256Hex(input) {
+  return createHash("sha256").update(input, "utf-8").digest("hex");
+}
+function normalizeScheme(url) {
+  return url.protocol.replace(/:$/, "").toLowerCase();
+}
+function isBlockedByPattern(host, patterns) {
+  return patterns.some((pattern) => new RegExp(pattern, "i").test(host));
+}
+function isAllowedByPattern(host, patterns) {
+  if (patterns.length === 0) {
+    return true;
+  }
+  return patterns.some((pattern) => new RegExp(pattern, "i").test(host));
+}
+function isPrivateIpv4(ip) {
+  const parts = ip.split(IPV4_SEPARATOR).map((v) => Number.parseInt(v, 10));
+  if (parts.length !== 4 || parts.some((p) => Number.isNaN(p))) {
+    return false;
+  }
+  const a = parts[0];
+  const b = parts[1];
+  if (a === 10 || a === 127 || a === 0) {
+    return true;
+  }
+  if (a === 169 && b === 254) {
+    return true;
+  }
+  if (a === 172 && b >= 16 && b <= 31) {
+    return true;
+  }
+  if (a === 192 && b === 168) {
+    return true;
+  }
+  if (a === 100 && b >= 64 && b <= 127) {
+    return true;
+  }
+  return false;
+}
+function isPrivateIpv6(ip) {
+  const normalized = ip.toLowerCase();
+  if (normalized === IPV6_LOOPBACK) {
+    return true;
+  }
+  return normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb");
+}
+function isPrivateIp(ip) {
+  const family = isIP(ip);
+  if (family === 4) {
+    return isPrivateIpv4(ip);
+  }
+  if (family === 6) {
+    return isPrivateIpv6(ip);
+  }
+  return false;
+}
+async function assertHostResolvesPublic(host, lookupFn) {
+  if (isIP(host) && isPrivateIp(host)) {
+    throw new Error(`Blocked code URL host: ${host}`);
+  }
+  try {
+    const records = await lookupFn(host);
+    for (const record of records) {
+      if (isPrivateIp(record.address)) {
+        throw new Error(`Blocked code URL host: ${host}`);
+      }
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("Blocked code URL host:")) {
+      throw err;
+    }
+    throw new Error(`Failed to resolve code URL host: ${host}`);
+  }
+}
+function decodeUtf8(content) {
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const text = decoder.decode(content);
+  if (text.includes("\x00")) {
+    throw new Error("Fetched code appears to be binary content");
+  }
+  return text;
+}
+async function fetchRemoteCode(request, policy, deps = {}) {
+  if (!policy.enabled) {
+    throw new Error("Remote code fetching is disabled. Set remoteCode.enabled=true to allow it.");
+  }
+  const fetchFn = deps.fetchFn ?? globalThis.fetch;
+  const lookupFn = deps.lookupFn ?? (async (hostname) => {
+    const records = await dnsLookup(hostname, { all: true, verbatim: true });
+    return records;
+  });
+  if (!request.codeUrl) {
+    throw new Error("codeUrl is required for remote code fetching");
+  }
+  const url = new URL(request.codeUrl);
+  const scheme = normalizeScheme(url);
+  if (scheme === "http" && !request.allowInsecureCodeUrl) {
+    throw new Error("Insecure code URL blocked. Use allowInsecureCodeUrl=true to allow HTTP.");
+  }
+  if (!policy.allowedSchemes.map((s) => s.toLowerCase()).includes(scheme)) {
+    throw new Error(`URL scheme not allowed: ${scheme}`);
+  }
+  const host = url.hostname.toLowerCase();
+  if (!isAllowedByPattern(host, policy.allowedHosts) || isBlockedByPattern(host, policy.blockedHosts)) {
+    throw new Error(`Blocked code URL host: ${host}`);
+  }
+  await assertHostResolvesPublic(host, lookupFn);
+  if (policy.requireHash && !request.codeHash) {
+    throw new Error("Hash verification required: provide codeHash for remote code execution.");
+  }
+  const controller = new AbortController;
+  const timeout = setTimeout(() => controller.abort(), policy.fetchTimeoutMs);
+  let response;
+  try {
+    response = await fetchFn(url.toString(), {
+      method: "GET",
+      redirect: "follow",
+      signal: controller.signal
+    });
+  } catch (err) {
+    throw new Error(err instanceof Error && err.name === "AbortError" ? `Remote code fetch timed out after ${policy.fetchTimeoutMs}ms` : `Failed to fetch remote code: ${err instanceof Error ? err.message : String(err)}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+  if (!response.ok) {
+    throw new Error(`Failed to fetch remote code: HTTP ${response.status}`);
+  }
+  const contentLengthHeader = response.headers.get("content-length");
+  if (contentLengthHeader) {
+    const parsedLength = Number.parseInt(contentLengthHeader, 10);
+    if (!Number.isNaN(parsedLength) && parsedLength > policy.maxCodeSize) {
+      throw new Error(`Remote code exceeds maxCodeSize (${policy.maxCodeSize} bytes): ${parsedLength} bytes`);
+    }
+  }
+  if (!response.body) {
+    throw new Error("Remote code response body is empty");
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let totalBytes = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    if (!value) {
+      continue;
+    }
+    totalBytes += value.byteLength;
+    if (totalBytes > policy.maxCodeSize) {
+      throw new Error(`Remote code exceeds maxCodeSize (${policy.maxCodeSize} bytes)`);
+    }
+    chunks.push(value);
+  }
+  const buffer = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    buffer.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  const code = decodeUtf8(buffer);
+  const hash = sha256Hex(code);
+  if (request.codeHash && hash.toLowerCase() !== request.codeHash.toLowerCase()) {
+    throw new Error("Remote code hash mismatch");
+  }
+  return { code, url: url.toString(), hash };
+}
+var IPV4_SEPARATOR = ".", IPV6_LOOPBACK = "::1";
+var init_code_fetcher = () => {};
+
 // src/engine/concurrency.ts
 class Semaphore {
   max;
@@ -55819,10 +56022,30 @@ class DockerIsol8 {
   poolStrategy;
   poolSize;
   auditLogger;
+  remoteCodePolicy;
   container = null;
   persistentRuntime = null;
   pool = null;
   imageCache = new Map;
+  async resolveExecutionRequest(req) {
+    const inlineCode = req.code?.trim();
+    const codeUrl = req.codeUrl?.trim();
+    if (inlineCode && codeUrl) {
+      throw new Error("ExecutionRequest.code and ExecutionRequest.codeUrl are mutually exclusive.");
+    }
+    if (!(inlineCode || codeUrl)) {
+      throw new Error("ExecutionRequest must include either code or codeUrl.");
+    }
+    if (inlineCode) {
+      return { ...req, code: req.code };
+    }
+    const fetched = await fetchRemoteCode({
+      codeUrl,
+      codeHash: req.codeHash,
+      allowInsecureCodeUrl: req.allowInsecureCodeUrl
+    }, this.remoteCodePolicy);
+    return { ...req, code: fetched.code };
+  }
   constructor(options = {}, maxConcurrent = 10) {
     this.docker = options.docker ?? new import_dockerode.default;
     this.mode = options.mode ?? "ephemeral";
@@ -55844,6 +56067,17 @@ class DockerIsol8 {
     this.logNetwork = options.logNetwork ?? false;
     this.poolStrategy = options.poolStrategy ?? "fast";
     this.poolSize = options.poolSize ?? { clean: 1, dirty: 1 };
+    this.remoteCodePolicy = options.remoteCode ?? {
+      enabled: false,
+      allowedSchemes: ["https"],
+      allowedHosts: [],
+      blockedHosts: [],
+      maxCodeSize: 10 * 1024 * 1024,
+      fetchTimeoutMs: 30000,
+      requireHash: false,
+      enableCache: true,
+      cacheTtl: 3600
+    };
     if (options.audit) {
       this.auditLogger = new AuditLogger(options.audit);
     }
@@ -55872,7 +56106,8 @@ class DockerIsol8 {
     await this.semaphore.acquire();
     const startTime = Date.now();
     try {
-      const result = this.mode === "persistent" ? await this.executePersistent(req, startTime) : await this.executeEphemeral(req, startTime);
+      const request = await this.resolveExecutionRequest(req);
+      const result = this.mode === "persistent" ? await this.executePersistent(request, startTime) : await this.executeEphemeral(request, startTime);
       return result;
     } finally {
       this.semaphore.release();
@@ -56026,8 +56261,9 @@ class DockerIsol8 {
   async* executeStream(req) {
     await this.semaphore.acquire();
     try {
-      const adapter = this.getAdapter(req.runtime);
-      const timeoutMs = req.timeoutMs ?? this.defaultTimeoutMs;
+      const request = await this.resolveExecutionRequest(req);
+      const adapter = this.getAdapter(request.runtime);
+      const timeoutMs = request.timeoutMs ?? this.defaultTimeoutMs;
       const image = await this.resolveImage(adapter);
       const container = await this.docker.createContainer({
         Image: image,
@@ -56044,23 +56280,23 @@ class DockerIsol8 {
           await startProxy(container, this.networkFilter);
           await setupIptables(container);
         }
-        const ext = req.fileExtension ?? adapter.getFileExtension();
+        const ext = request.fileExtension ?? adapter.getFileExtension();
         const filePath = `${SANDBOX_WORKDIR}/main${ext}`;
-        await writeFileViaExec(container, filePath, req.code);
-        if (req.installPackages?.length) {
-          await installPackages(container, req.runtime, req.installPackages);
+        await writeFileViaExec(container, filePath, request.code);
+        if (request.installPackages?.length) {
+          await installPackages(container, request.runtime, request.installPackages);
         }
-        if (req.files) {
-          for (const [fPath, fContent] of Object.entries(req.files)) {
+        if (request.files) {
+          for (const [fPath, fContent] of Object.entries(request.files)) {
             await writeFileViaExec(container, fPath, fContent);
           }
         }
-        const rawCmd = adapter.getCommand(req.code, filePath);
+        const rawCmd = adapter.getCommand(request.code, filePath);
         const timeoutSec = Math.ceil(timeoutMs / 1000);
         let cmd;
-        if (req.stdin) {
+        if (request.stdin) {
           const stdinPath = `${SANDBOX_WORKDIR}/_stdin`;
-          await writeFileViaExec(container, stdinPath, req.stdin);
+          await writeFileViaExec(container, stdinPath, request.stdin);
           const cmdStr = rawCmd.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(" ");
           cmd = wrapWithTimeout(["sh", "-c", `cat ${stdinPath} | ${cmdStr}`], timeoutSec);
         } else {
@@ -56068,7 +56304,7 @@ class DockerIsol8 {
         }
         const exec = await container.exec({
           Cmd: cmd,
-          Env: this.buildEnv(req.env),
+          Env: this.buildEnv(request.env),
           AttachStdout: true,
           AttachStderr: true,
           WorkingDir: SANDBOX_WORKDIR,
@@ -56627,6 +56863,7 @@ var init_docker = __esm(() => {
   init_runtime();
   init_logger();
   init_audit();
+  init_code_fetcher();
   init_pool();
   import_dockerode = __toESM(require_docker(), 1);
   MAX_OUTPUT_BYTES = 1024 * 1024;
@@ -56637,7 +56874,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "isol8",
-    version: "0.10.1",
+    version: "0.10.3",
     description: "Secure code execution engine for AI agents",
     author: "Illusion47586",
     license: "MIT",
@@ -58388,7 +58625,7 @@ async function createServer(options) {
   app.post("/execute", async (c) => {
     const body = await c.req.json();
     logger.debug(`[Server] POST /execute runtime=${body.request.runtime} sessionId=${body.sessionId ?? "ephemeral"}`);
-    logger.debug(`[Server] Code length: ${body.request.code.length} chars`);
+    logger.debug(`[Server] Code source: ${body.request.codeUrl ? `url=${body.request.codeUrl}` : `inline (${body.request.code?.length ?? 0} chars)`}`);
     const engineOptions = {
       network: config.defaults.network,
       memoryLimit: config.defaults.memoryLimit,
@@ -58396,6 +58633,7 @@ async function createServer(options) {
       timeoutMs: config.defaults.timeoutMs,
       sandboxSize: config.defaults.sandboxSize,
       tmpSize: config.defaults.tmpSize,
+      remoteCode: config.remoteCode,
       ...body.options,
       mode: body.sessionId ? "persistent" : "ephemeral",
       audit: config.audit
@@ -58407,11 +58645,12 @@ async function createServer(options) {
         logger.debug(`[Server] Reusing existing session: ${body.sessionId}`);
         engine = session.engine;
         session.lastAccessedAt = Date.now();
+        session.isActive = true;
       } else {
         logger.debug(`[Server] Creating new session: ${body.sessionId}`);
         engine = new DockerIsol82(engineOptions, config.maxConcurrent);
         await engine.start();
-        sessions.set(body.sessionId, { engine, lastAccessedAt: Date.now() });
+        sessions.set(body.sessionId, { engine, lastAccessedAt: Date.now(), isActive: true });
       }
     } else {
       logger.debug("[Server] Creating ephemeral engine");
@@ -58433,7 +58672,13 @@ async function createServer(options) {
       logger.debug(`[Server] Execution error: ${message}`);
       return c.json({ error: message }, 500);
     } finally {
-      if (!body.sessionId) {
+      if (body.sessionId) {
+        const session = sessions.get(body.sessionId);
+        if (session) {
+          session.isActive = false;
+          session.lastAccessedAt = Date.now();
+        }
+      } else {
         logger.debug("[Server] Cleaning up ephemeral engine");
         await engine.stop();
       }
@@ -58442,7 +58687,7 @@ async function createServer(options) {
   app.post("/execute/stream", async (c) => {
     const body = await c.req.json();
     logger.debug(`[Server] POST /execute/stream runtime=${body.request.runtime}`);
-    logger.debug(`[Server] Code length: ${body.request.code.length} chars`);
+    logger.debug(`[Server] Code source: ${body.request.codeUrl ? `url=${body.request.codeUrl}` : `inline (${body.request.code?.length ?? 0} chars)`}`);
     const engineOptions = {
       network: config.defaults.network,
       memoryLimit: config.defaults.memoryLimit,
@@ -58450,6 +58695,7 @@ async function createServer(options) {
       timeoutMs: config.defaults.timeoutMs,
       sandboxSize: config.defaults.sandboxSize,
       tmpSize: config.defaults.tmpSize,
+      remoteCode: config.remoteCode,
       ...body.options,
       mode: "ephemeral"
     };
@@ -58543,6 +58789,9 @@ async function createServer(options) {
       const maxAge = config.cleanup.maxContainerAgeMs;
       const now = Date.now();
       for (const [id, session] of sessions) {
+        if (session.isActive) {
+          continue;
+        }
         if (now - session.lastAccessedAt > maxAge) {
           logger.debug(`[Server] Auto-pruning stale session: ${id}`);
           await session.engine.stop();
@@ -58571,13 +58820,13 @@ import {
   chmodSync,
   existsSync as existsSync5,
   mkdirSync as mkdirSync2,
-  readFileSync as readFileSync3,
+  readFileSync as readFileSync4,
   renameSync,
   unlinkSync as unlinkSync2,
   writeFileSync
 } from "node:fs";
 import { arch, homedir as homedir2, platform } from "node:os";
-import { join as join3, resolve as resolve2 } from "node:path";
+import { join as join4, resolve as resolve2 } from "node:path";
 
 // node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
@@ -61971,7 +62220,10 @@ init_docker();
 
 // src/engine/image-builder.ts
 init_runtime();
-import { existsSync as existsSync4 } from "node:fs";
+init_logger();
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "node:fs";
+import { join as join3 } from "node:path";
 function resolveDockerDir() {
   const fromBundled = new URL("./docker", import.meta.url).pathname;
   if (existsSync4(fromBundled)) {
@@ -61980,16 +62232,82 @@ function resolveDockerDir() {
   return new URL("../../docker", import.meta.url).pathname;
 }
 var DOCKERFILE_DIR = resolveDockerDir();
-async function buildBaseImages(docker, onProgress) {
+var LABELS = {
+  dockerHash: "org.isol8.build.hash",
+  depsHash: "org.isol8.deps.hash"
+};
+var DOCKER_BUILD_FILES = ["Dockerfile", "proxy.sh", "proxy-handler.sh"];
+function computeDockerDirHash() {
+  const hash = createHash2("sha256");
+  const files = [...DOCKER_BUILD_FILES].sort();
+  for (const file of files) {
+    const filePath = join3(DOCKERFILE_DIR, file);
+    if (existsSync4(filePath)) {
+      const content = readFileSync3(filePath);
+      hash.update(file);
+      hash.update(content);
+    }
+  }
+  return hash.digest("hex");
+}
+function computeDepsHash(runtime, packages) {
+  const hash = createHash2("sha256");
+  hash.update(runtime);
+  for (const pkg of [...packages].sort()) {
+    hash.update(pkg);
+  }
+  return hash.digest("hex");
+}
+async function getImageLabels(docker, imageName) {
+  try {
+    const image = docker.getImage(imageName);
+    const inspect = await image.inspect();
+    return inspect.Config?.Labels ?? {};
+  } catch {
+    return null;
+  }
+}
+async function removeImage(docker, imageId) {
+  try {
+    const image = docker.getImage(imageId);
+    await image.remove();
+    logger.debug(`[ImageBuilder] Removed old image: ${imageId.slice(0, 12)}`);
+  } catch (err) {
+    logger.debug(`[ImageBuilder] Could not remove image ${imageId.slice(0, 12)}: ${err}`);
+  }
+}
+async function buildBaseImages(docker, onProgress, force = false) {
   const runtimes = RuntimeRegistry.list();
+  const dockerHash = computeDockerDirHash();
+  logger.debug(`[ImageBuilder] Docker directory hash: ${dockerHash.slice(0, 16)}...`);
   for (const adapter of runtimes) {
     const target = adapter.name;
+    const imageName = adapter.image;
+    if (!force) {
+      const labels = await getImageLabels(docker, imageName);
+      if (labels && labels[LABELS.dockerHash] === dockerHash) {
+        logger.debug(`[ImageBuilder] Base image ${target} is up to date, skipping build`);
+        onProgress?.({ runtime: target, status: "done", message: "Up to date" });
+        continue;
+      }
+    }
+    let oldImageId = null;
+    try {
+      const oldImage = await docker.getImage(imageName).inspect();
+      oldImageId = oldImage.Id;
+      logger.debug(`[ImageBuilder] Existing image ${target} ID: ${oldImageId.slice(0, 12)}`);
+    } catch {
+      logger.debug(`[ImageBuilder] No existing image for ${target}`);
+    }
     onProgress?.({ runtime: target, status: "building" });
     try {
-      const stream = await docker.buildImage({ context: DOCKERFILE_DIR, src: ["Dockerfile", "proxy.sh", "proxy-handler.sh"] }, {
-        t: adapter.image,
+      const stream = await docker.buildImage({ context: DOCKERFILE_DIR, src: DOCKER_BUILD_FILES }, {
+        t: imageName,
         target,
-        dockerfile: "Dockerfile"
+        dockerfile: "Dockerfile",
+        labels: {
+          [LABELS.dockerHash]: dockerHash
+        }
       });
       await new Promise((resolve2, reject) => {
         docker.modem.followProgress(stream, (err) => {
@@ -62000,6 +62318,9 @@ async function buildBaseImages(docker, onProgress) {
           }
         });
       });
+      if (oldImageId) {
+        await removeImage(docker, oldImageId);
+      }
       onProgress?.({ runtime: target, status: "done" });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -62008,26 +62329,44 @@ async function buildBaseImages(docker, onProgress) {
     }
   }
 }
-async function buildCustomImages(docker, config, onProgress) {
+async function buildCustomImages(docker, config, onProgress, force = false) {
   const deps = config.dependencies;
   if (deps.python?.length) {
-    await buildCustomImage(docker, "python", deps.python, onProgress);
+    await buildCustomImage(docker, "python", deps.python, onProgress, force);
   }
   if (deps.node?.length) {
-    await buildCustomImage(docker, "node", deps.node, onProgress);
+    await buildCustomImage(docker, "node", deps.node, onProgress, force);
   }
   if (deps.bun?.length) {
-    await buildCustomImage(docker, "bun", deps.bun, onProgress);
+    await buildCustomImage(docker, "bun", deps.bun, onProgress, force);
   }
   if (deps.deno?.length) {
-    await buildCustomImage(docker, "deno", deps.deno, onProgress);
+    await buildCustomImage(docker, "deno", deps.deno, onProgress, force);
   }
   if (deps.bash?.length) {
-    await buildCustomImage(docker, "bash", deps.bash, onProgress);
+    await buildCustomImage(docker, "bash", deps.bash, onProgress, force);
   }
 }
-async function buildCustomImage(docker, runtime, packages, onProgress) {
+async function buildCustomImage(docker, runtime, packages, onProgress, force = false) {
   const tag = `isol8:${runtime}-custom`;
+  const depsHash = computeDepsHash(runtime, packages);
+  logger.debug(`[ImageBuilder] ${runtime} custom deps hash: ${depsHash.slice(0, 16)}...`);
+  if (!force) {
+    const labels = await getImageLabels(docker, tag);
+    if (labels && labels[LABELS.depsHash] === depsHash) {
+      logger.debug(`[ImageBuilder] Custom image ${runtime} is up to date, skipping build`);
+      onProgress?.({ runtime, status: "done", message: "Up to date" });
+      return;
+    }
+  }
+  let oldImageId = null;
+  try {
+    const oldImage = await docker.getImage(tag).inspect();
+    oldImageId = oldImage.Id;
+    logger.debug(`[ImageBuilder] Existing custom image ${runtime} ID: ${oldImageId.slice(0, 12)}`);
+  } catch {
+    logger.debug(`[ImageBuilder] No existing custom image for ${runtime}`);
+  }
   onProgress?.({ runtime, status: "building", message: `Custom: ${packages.join(", ")}` });
   let installCmd;
   switch (runtime) {
@@ -62059,7 +62398,10 @@ ${installCmd}
   const tarBuffer = createTarBuffer2("Dockerfile", dockerfileContent);
   const stream = await docker.buildImage(Readable.from(tarBuffer), {
     t: tag,
-    dockerfile: "Dockerfile"
+    dockerfile: "Dockerfile",
+    labels: {
+      [LABELS.depsHash]: depsHash
+    }
   });
   await new Promise((resolve2, reject) => {
     docker.modem.followProgress(stream, (err) => {
@@ -62070,6 +62412,9 @@ ${installCmd}
       }
     });
   });
+  if (oldImageId) {
+    await removeImage(docker, oldImageId);
+  }
   onProgress?.({ runtime, status: "done" });
 }
 
@@ -62087,7 +62432,7 @@ program2.name("isol8").description("Secure code execution engine").version(VERSI
   logger.debug(`[CLI] Version: ${VERSION}`);
   logger.debug(`[CLI] Platform: ${platform()} ${arch()}`);
 });
-program2.command("setup").description("Check Docker and build isol8 images").option("--python <packages>", "Additional Python packages (comma-separated)").option("--node <packages>", "Additional Node.js packages (comma-separated)").option("--bun <packages>", "Additional Bun packages (comma-separated)").option("--deno <packages>", "Additional Deno packages (comma-separated)").option("--bash <packages>", "Additional Bash packages (comma-separated)").action(async (opts) => {
+program2.command("setup").description("Check Docker and build isol8 images").option("--python <packages>", "Additional Python packages (comma-separated)").option("--node <packages>", "Additional Node.js packages (comma-separated)").option("--bun <packages>", "Additional Bun packages (comma-separated)").option("--deno <packages>", "Additional Deno packages (comma-separated)").option("--bash <packages>", "Additional Bash packages (comma-separated)").option("--force", "Force rebuild even if images are up to date").action(async (opts) => {
   const docker = new import_dockerode2.default;
   logger.debug("[Setup] Connecting to Docker daemon");
   const spinner = ora("Checking Docker...").start();
@@ -62102,7 +62447,7 @@ program2.command("setup").description("Check Docker and build isol8 images").opt
     process.exit(1);
   }
   spinner.start("Building isol8 images...");
-  logger.debug("[Setup] Building base images");
+  logger.debug(`[Setup] Building base images (force=${opts.force ?? false})`);
   await buildBaseImages(docker, (progress) => {
     const status = progress.status === "error" ? "[ERR]" : progress.status === "done" ? "[OK]" : "[..]";
     if (progress.status === "building") {
@@ -62118,7 +62463,7 @@ program2.command("setup").description("Check Docker and build isol8 images").opt
         spinner.start();
       }
     }
-  });
+  }, opts.force ?? false);
   if (spinner.isSpinning) {
     spinner.stop();
   }
@@ -62166,7 +62511,7 @@ program2.command("setup").description("Check Docker and build isol8 images").opt
           spinner.start();
         }
       }
-    });
+    }, opts.force ?? false);
     if (spinner.isSpinning) {
       spinner.stop();
     }
@@ -62174,12 +62519,25 @@ program2.command("setup").description("Check Docker and build isol8 images").opt
   console.log(`
 [DONE] Setup complete!`);
 });
-program2.command("run").description("Execute code in isol8").argument("[file]", "Script file to execute").option("-e, --eval <code>", "Execute inline code string").option("-r, --runtime <name>", "Force runtime (python, node, bun, deno, bash)").option("--net <mode>", "Network mode: none, host, filtered", "none").option("--allow <regex>", "Whitelist regex for filtered mode (repeatable)", collect, []).option("--deny <regex>", "Blacklist regex for filtered mode (repeatable)", collect, []).option("--out <file>", "Write output to file").option("--persistent", "Use persistent container").option("--timeout <ms>", "Execution timeout in milliseconds").option("--memory <limit>", "Memory limit (e.g. 512m, 1g)").option("--cpu <limit>", "CPU limit as fraction (e.g. 0.5, 2.0)").option("--image <name>", "Override Docker image").option("--pids-limit <n>", "Maximum number of processes").option("--writable", "Disable read-only root filesystem").option("--max-output <bytes>", "Maximum output size in bytes").option("--secret <KEY=VALUE>", "Secret env var (repeatable, values masked)", collect, []).option("--sandbox-size <size>", "Sandbox tmpfs size (e.g. 128m, 512m)").option("--tmp-size <size>", "Tmp tmpfs size (e.g. 256m, 512m)").option("--stdin <data>", "Data to pipe to stdin").option("--install <package>", "Install package for runtime (repeatable)", collect, []).option("--host <url>", "Execute on remote server").option("--key <key>", "API key for remote server").option("--no-stream", "Disable real-time output streaming").option("--debug", "Enable debug logging").option("--persist", "Keep container running after execution for inspection").option("--log-network", "Log all network requests (requires --net filtered)").option("--pool-strategy <mode>", "Pool strategy: fast (default) or secure", "fast").option("--pool-size <size>", "Pool size (number or 'clean,dirty' for fast mode)", "1,1").action(async (file, opts) => {
-  const { code, runtime, engineOptions, engine, stdinData, fileExtension } = await resolveRunInput(file, opts);
+program2.command("run").description("Execute code in isol8").argument("[file]", "Script file to execute").option("-e, --eval <code>", "Execute inline code string").option("-r, --runtime <name>", "Force runtime (python, node, bun, deno, bash)").option("--net <mode>", "Network mode: none, host, filtered", "none").option("--allow <regex>", "Whitelist regex for filtered mode (repeatable)", collect, []).option("--deny <regex>", "Blacklist regex for filtered mode (repeatable)", collect, []).option("--out <file>", "Write output to file").option("--persistent", "Use persistent container").option("--timeout <ms>", "Execution timeout in milliseconds").option("--memory <limit>", "Memory limit (e.g. 512m, 1g)").option("--cpu <limit>", "CPU limit as fraction (e.g. 0.5, 2.0)").option("--image <name>", "Override Docker image").option("--pids-limit <n>", "Maximum number of processes").option("--writable", "Disable read-only root filesystem").option("--max-output <bytes>", "Maximum output size in bytes").option("--secret <KEY=VALUE>", "Secret env var (repeatable, values masked)", collect, []).option("--sandbox-size <size>", "Sandbox tmpfs size (e.g. 128m, 512m)").option("--tmp-size <size>", "Tmp tmpfs size (e.g. 256m, 512m)").option("--stdin <data>", "Data to pipe to stdin").option("--install <package>", "Install package for runtime (repeatable)", collect, []).option("--url <url>", "Fetch code from URL").option("--github <path>", "GitHub shorthand: owner/repo/ref/path/to/file").option("--gist <path>", "Gist shorthand: gistId/file.ext").option("--hash <sha256>", "Expected SHA-256 hash of fetched code").option("--allow-insecure-code-url", "Allow insecure HTTP code URLs").option("--host <url>", "Execute on remote server").option("--key <key>", "API key for remote server").option("--no-stream", "Disable real-time output streaming").option("--debug", "Enable debug logging").option("--persist", "Keep container running after execution for inspection").option("--log-network", "Log all network requests (requires --net filtered)").option("--pool-strategy <mode>", "Pool strategy: fast (default) or secure", "fast").option("--pool-size <size>", "Pool size (number or 'clean,dirty' for fast mode)", "1,1").action(async (file, opts) => {
+  const {
+    code,
+    codeUrl,
+    codeHash,
+    allowInsecureCodeUrl,
+    runtime,
+    engineOptions,
+    engine,
+    stdinData,
+    fileExtension
+  } = await resolveRunInput(file, opts);
   logger.debug(`[Run] Runtime: ${runtime}, mode: ${engineOptions.mode}`);
   logger.debug(`[Run] Network: ${engineOptions.network}, timeout: ${engineOptions.timeoutMs}ms`);
   logger.debug(`[Run] Memory: ${engineOptions.memoryLimit}, CPU: ${engineOptions.cpuLimit}`);
-  logger.debug(`[Run] Code length: ${code.length} chars`);
+  logger.debug(`[Run] Code source: ${codeUrl ? `url=${codeUrl}` : "inline/file/stdin"}`);
+  if (code) {
+    logger.debug(`[Run] Code length: ${code.length} chars`);
+  }
   if (stdinData) {
     logger.debug(`[Run] Stdin data provided (${stdinData.length} chars)`);
   }
@@ -62205,9 +62563,12 @@ program2.command("run").description("Execute code in isol8").argument("[file]",
     logger.debug("[Run] Engine started");
     spinner.text = "Running code...";
     const req = {
-      code,
       runtime,
       timeoutMs: engineOptions.timeoutMs,
+      ...code ? { code } : {},
+      ...codeUrl ? { codeUrl } : {},
+      ...codeHash ? { codeHash } : {},
+      ...allowInsecureCodeUrl ? { allowInsecureCodeUrl } : {},
       ...stdinData ? { stdin: stdinData } : {},
       ...opts.install.length > 0 ? { installPackages: opts.install } : {},
       fileExtension
@@ -62367,7 +62728,7 @@ async function downloadServerBinary(binaryPath) {
       }
       process.exit(1);
     }
-    const binDir = join3(homedir2(), ".isol8", "bin");
+    const binDir = join4(homedir2(), ".isol8", "bin");
     mkdirSync2(binDir, { recursive: true });
     const tmpPath = `${binaryPath}.tmp`;
     const buffer = Buffer.from(await response.arrayBuffer());
@@ -62399,8 +62760,8 @@ async function promptYesNo(question) {
   return normalized === "" || normalized === "y" || normalized === "yes";
 }
 async function ensureServerBinary(forceUpdate) {
-  const binDir = join3(homedir2(), ".isol8", "bin");
-  const binaryPath = join3(binDir, "isol8-server");
+  const binDir = join4(homedir2(), ".isol8", "bin");
+  const binaryPath = join4(binDir, "isol8-server");
   logger.debug(`[Serve] Binary path: ${binaryPath}, forceUpdate: ${forceUpdate}`);
   if (forceUpdate) {
     logger.debug("[Serve] Force update requested");
@@ -62430,8 +62791,8 @@ async function ensureServerBinary(forceUpdate) {
 program2.command("config").description("Show the resolved isol8 configuration").option("--json", "Output as raw JSON").action((opts) => {
   const config = loadConfig();
   const searchPaths = [
-    join3(resolve2(process.cwd()), "isol8.config.json"),
-    join3(homedir2(), ".isol8", "config.json")
+    join4(resolve2(process.cwd()), "isol8.config.json"),
+    join4(homedir2(), ".isol8", "config.json")
   ];
   const loadedFrom = searchPaths.find((p) => existsSync5(p));
   logger.debug(`[Config] Config source: ${loadedFrom ?? "defaults"}`);
@@ -62466,6 +62827,13 @@ Isol8 Configuration
   } else {
     console.log("  Whitelist:       (none)");
   }
+  console.log("");
+  console.log("  ── Remote Code ──");
+  console.log(`  Enabled:         ${config.remoteCode.enabled ? "yes" : "no"}`);
+  console.log(`  Schemes:         ${config.remoteCode.allowedSchemes.join(", ")}`);
+  console.log(`  Max code size:   ${config.remoteCode.maxCodeSize} bytes`);
+  console.log(`  Fetch timeout:   ${config.remoteCode.fetchTimeoutMs}ms`);
+  console.log(`  Require hash:    ${config.remoteCode.requireHash ? "yes" : "no"}`);
   if (config.network.blacklist.length > 0) {
     console.log(`  Blacklist:       ${config.network.blacklist.join(", ")}`);
   } else {
@@ -62560,8 +62928,25 @@ async function resolveRunInput(file, opts) {
   const config = loadConfig();
   logger.debug("[Run] Config loaded");
   let code;
+  let codeUrl;
+  let codeHash;
+  let allowInsecureCodeUrl = false;
   let runtime;
-  if (opts.eval) {
+  if (opts.url || opts.github || opts.gist) {
+    if (file || opts.eval) {
+      console.error("[ERR] --url/--github/--gist cannot be used with file input or --eval.");
+      process.exit(1);
+    }
+    codeUrl = resolveCodeUrl(opts);
+    codeHash = opts.hash ?? undefined;
+    allowInsecureCodeUrl = opts.allowInsecureCodeUrl ?? false;
+    runtime = opts.runtime ?? detectRuntimeFromPath(new URL(codeUrl).pathname);
+    if (!runtime) {
+      console.error("[ERR] Cannot detect runtime from URL path. Use --runtime to specify.");
+      process.exit(1);
+    }
+    logger.debug(`[Run] Remote code URL: ${codeUrl}`);
+  } else if (opts.eval) {
     code = opts.eval;
     runtime = opts.runtime ?? "python";
     logger.debug(`[Run] Inline eval, runtime: ${runtime}`);
@@ -62572,7 +62957,7 @@ async function resolveRunInput(file, opts) {
       console.error(`[ERR] File not found: ${file}`);
       process.exit(1);
     }
-    code = readFileSync3(filePath, "utf-8");
+    code = readFileSync4(filePath, "utf-8");
     if (opts.runtime) {
       runtime = opts.runtime;
       logger.debug(`[Run] Runtime specified: ${runtime}`);
@@ -62612,6 +62997,7 @@ async function resolveRunInput(file, opts) {
     debug: opts.debug ?? config.debug,
     persist: opts.persist ?? false,
     ...opts.logNetwork ? { logNetwork: true } : {},
+    remoteCode: config.remoteCode,
     poolStrategy: opts.poolStrategy === "secure" ? "secure" : "fast",
     poolSize: opts.poolSize ? opts.poolSize.includes(",") ? {
       clean: Number.parseInt(opts.poolSize.split(",")[0], 10),
@@ -62650,7 +63036,48 @@ async function resolveRunInput(file, opts) {
     logger.debug("[Run] Using local Docker engine");
     engine = new DockerIsol8(engineOptions, config.maxConcurrent);
   }
-  return { code, runtime, engineOptions, engine, stdinData, fileExtension };
+  return {
+    code,
+    codeUrl,
+    codeHash,
+    allowInsecureCodeUrl,
+    runtime,
+    engineOptions,
+    engine,
+    stdinData,
+    fileExtension
+  };
+}
+function resolveCodeUrl(opts) {
+  if (typeof opts.url === "string") {
+    return opts.url;
+  }
+  if (typeof opts.github === "string") {
+    const parts = opts.github.split("/");
+    if (parts.length < 4) {
+      console.error("[ERR] --github format must be owner/repo/ref/path/to/file");
+      process.exit(1);
+    }
+    const [owner, repo, ref, ...pathParts] = parts;
+    return `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${pathParts.join("/")}`;
+  }
+  if (typeof opts.gist === "string") {
+    const [gistId, ...fileParts] = opts.gist.split("/");
+    if (!gistId || fileParts.length === 0) {
+      console.error("[ERR] --gist format must be gistId/file.ext");
+      process.exit(1);
+    }
+    return `https://gist.githubusercontent.com/${gistId}/raw/${fileParts.join("/")}`;
+  }
+  console.error("[ERR] Missing code URL source.");
+  process.exit(1);
+}
+function detectRuntimeFromPath(pathValue) {
+  try {
+    return RuntimeRegistry.detect(pathValue).name;
+  } catch {
+    return;
+  }
 }
 function collect(value, previous) {
   return previous.concat([value]);
@@ -62661,4 +63088,4 @@ if (!process.argv.slice(2).length) {
 }
 program2.parse();
 
-//# debugId=92C54A0066AB3BEC64756E2164756E21
+//# debugId=280ED4C71DBDC32964756E2164756E21