isol8 0.6.1 → 0.7.0

package/dist/cli.js

@@ -54799,6 +54799,10 @@ function mergeConfig(defaults, overrides) {
       ...defaults.dependencies,
       ...overrides.dependencies
     },
+    security: {
+      seccomp: overrides.security?.seccomp ?? defaults.security.seccomp,
+      customProfilePath: overrides.security?.customProfilePath ?? defaults.security.customProfilePath
+    },
     debug: overrides.debug ?? defaults.debug
   };
 }
@@ -54823,6 +54827,9 @@ var init_config = __esm(() => {
       maxContainerAgeMs: 3600000
     },
     dependencies: {},
+    security: {
+      seccomp: "strict"
+    },
     debug: false
   };
 });
@@ -54990,11 +54997,6 @@ var init_runtime = __esm(() => {
 });
 
 // src/utils/logger.ts
-var exports_logger = {};
-__export(exports_logger, {
-  logger: () => logger
-});
-
 class Logger {
   debugMode = false;
   setDebug(enabled) {
@@ -55085,6 +55087,15 @@ class ContainerPool {
       return;
     }
     try {
+      const killExec = await container.exec({
+        Cmd: ["sh", "-c", "pkill -9 -u sandbox 2>/dev/null; true"]
+      });
+      await killExec.start({ Detach: true });
+      let killInfo = await killExec.inspect();
+      while (killInfo.Running) {
+        await new Promise((r) => setTimeout(r, 5));
+        killInfo = await killExec.inspect();
+      }
       const cleanExec = await container.exec({
         Cmd: ["sh", "-c", "rm -rf /sandbox/* /sandbox/.[!.]* 2>/dev/null; true"]
       });
@@ -55269,12 +55280,14 @@ __export(exports_docker, {
   DockerIsol8: () => DockerIsol8
 });
 import { randomUUID } from "node:crypto";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
 import { PassThrough } from "node:stream";
 async function writeFileViaExec(container, filePath, content) {
   const data = typeof content === "string" ? Buffer.from(content, "utf-8") : content;
   const b64 = data.toString("base64");
   const exec = await container.exec({
-    Cmd: ["sh", "-c", `printf '%s' '${b64}' | base64 -d > ${filePath}`]
+    Cmd: ["sh", "-c", `printf '%s' '${b64}' | base64 -d > ${filePath}`],
+    User: "sandbox"
   });
   await exec.start({ Detach: true });
   let info2 = await exec.inspect();
@@ -55290,7 +55303,8 @@ async function readFileViaExec(container, filePath) {
   const exec = await container.exec({
     Cmd: ["base64", filePath],
     AttachStdout: true,
-    AttachStderr: true
+    AttachStderr: true,
+    User: "sandbox"
   });
   const stream = await exec.start({ Tty: false });
   const chunks = [];
@@ -55385,7 +55399,8 @@ async function installPackages(container, runtime, packages) {
     Cmd: cmd,
     AttachStdout: true,
     AttachStderr: true,
-    Env: env2
+    Env: env2,
+    User: runtime === "bash" ? "root" : "sandbox"
   });
   const stream = await exec.start({ Detach: false, Tty: false });
   return new Promise((resolve2, reject) => {
@@ -55428,6 +55443,7 @@ class DockerIsol8 {
   semaphore;
   sandboxSize;
   tmpSize;
+  security;
   persist;
   container = null;
   persistentRuntime = null;
@@ -55449,6 +55465,7 @@ class DockerIsol8 {
     this.sandboxSize = options.sandboxSize ?? "512m";
     this.tmpSize = options.tmpSize ?? "256m";
     this.persist = options.persist ?? false;
+    this.security = options.security ?? { seccomp: "strict" };
     if (options.debug) {
       logger.setDebug(true);
     }
@@ -55554,7 +55571,8 @@ class DockerIsol8 {
           Env: this.buildEnv(req.env),
           AttachStdout: true,
           AttachStderr: true,
-          WorkingDir: SANDBOX_WORKDIR
+          WorkingDir: SANDBOX_WORKDIR,
+          User: "sandbox"
         });
         const execStream = await exec.start({ Tty: false });
         yield* this.streamExecOutput(execStream, exec, container, timeoutMs);
@@ -55633,7 +55651,8 @@ class DockerIsol8 {
         Env: this.buildEnv(req.env),
         AttachStdout: true,
         AttachStderr: true,
-        WorkingDir: SANDBOX_WORKDIR
+        WorkingDir: SANDBOX_WORKDIR,
+        User: "sandbox"
       });
       const start = performance.now();
       const execStream = await exec.start({ Tty: false });
@@ -55706,7 +55725,8 @@ class DockerIsol8 {
       Env: execEnv,
       AttachStdout: true,
       AttachStderr: true,
-      WorkingDir: SANDBOX_WORKDIR
+      WorkingDir: SANDBOX_WORKDIR,
+      User: "sandbox"
     });
     const start = performance.now();
     const execStream = await exec.start({ Tty: false });
@@ -55776,9 +55796,9 @@ class DockerIsol8 {
       ReadonlyRootfs: this.readonlyRootFs,
       Tmpfs: {
         "/tmp": `rw,noexec,nosuid,nodev,size=${this.tmpSize}`,
-        [SANDBOX_WORKDIR]: `rw,exec,nosuid,nodev,size=${this.sandboxSize}`
+        [SANDBOX_WORKDIR]: `rw,exec,nosuid,nodev,size=${this.sandboxSize},uid=100,gid=101`
       },
-      SecurityOpt: ["no-new-privileges"]
+      SecurityOpt: this.buildSecurityOpts()
     };
     if (this.network === "filtered") {
       config.NetworkMode = "bridge";
@@ -55787,6 +55807,43 @@ class DockerIsol8 {
     }
     return config;
   }
+  buildSecurityOpts() {
+    const opts = ["no-new-privileges"];
+    if (this.security.seccomp === "unconfined") {
+      opts.push("seccomp=unconfined");
+      return opts;
+    }
+    if (this.security.seccomp === "custom" && this.security.customProfilePath) {
+      try {
+        const profile = readFileSync2(this.security.customProfilePath, "utf-8");
+        opts.push(`seccomp=${profile}`);
+      } catch (e) {
+        logger.error(`Failed to load custom seccomp profile: ${e}`);
+      }
+      return opts;
+    }
+    try {
+      const profile = this.loadDefaultSeccompProfile();
+      if (profile) {
+        opts.push(`seccomp=${profile}`);
+      }
+    } catch (e) {
+      logger.error(`Failed to load default seccomp profile: ${e}`);
+    }
+    return opts;
+  }
+  loadDefaultSeccompProfile() {
+    const devPath = new URL("../../docker/seccomp-profile.json", import.meta.url);
+    if (existsSync2(devPath)) {
+      return readFileSync2(devPath, "utf-8");
+    }
+    const prodPath = new URL("./docker/seccomp-profile.json", import.meta.url);
+    if (existsSync2(prodPath)) {
+      return readFileSync2(prodPath, "utf-8");
+    }
+    logger.warn("Could not locate default seccomp profile. Running without seccomp filter.");
+    return null;
+  }
   buildEnv(extra) {
     const env2 = [
       "PYTHONUNBUFFERED=1",
@@ -55968,7 +56025,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "isol8",
-    version: "0.6.0",
+    version: "0.6.2",
     description: "Secure code execution engine for AI agents",
     author: "Illusion47586",
     license: "MIT",
@@ -56030,6 +56087,7 @@ var init_package = __esm(() => {
     devDependencies: {
       "@biomejs/biome": "^2.3.15",
       "@semantic-release/changelog": "^6.0.3",
+      "@semantic-release/exec": "^7.1.0",
       "@semantic-release/git": "^10.0.1",
       "@semantic-release/github": "^12.0.6",
       "@semantic-release/npm": "^13.1.4",
@@ -57696,13 +57754,21 @@ __export(exports_server, {
 async function createServer(options) {
   const { DockerIsol8: DockerIsol82 } = await Promise.resolve().then(() => (init_docker(), exports_docker));
   await Promise.resolve().then(() => (init_runtime(), exports_runtime));
+  if (options.debug) {
+    logger.setDebug(true);
+  }
   const config = loadConfig();
+  logger.debug("[Server] Config loaded");
+  logger.debug(`[Server] Max concurrent: ${config.maxConcurrent}`);
+  logger.debug(`[Server] Auto-prune: ${config.cleanup.autoPrune}`);
   const app = new Hono2;
   const globalSemaphore = new Semaphore(config.maxConcurrent);
   app.use("*", authMiddleware(options.apiKey));
   app.get("/health", (c) => c.json({ status: "ok", version: VERSION }));
   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`);
     const engineOptions = {
       network: config.defaults.network,
       memoryLimit: config.defaults.memoryLimit,
@@ -57717,36 +57783,45 @@ async function createServer(options) {
     if (body.sessionId) {
       const session = sessions.get(body.sessionId);
       if (session) {
+        logger.debug(`[Server] Reusing existing session: ${body.sessionId}`);
         engine = session.engine;
         session.lastAccessedAt = Date.now();
       } 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() });
       }
     } else {
+      logger.debug("[Server] Creating ephemeral engine");
       engine = new DockerIsol82(engineOptions, config.maxConcurrent);
       await engine.start();
     }
     try {
+      logger.debug("[Server] Acquiring semaphore for /execute");
       await globalSemaphore.acquire();
       try {
         const result = await engine.execute(body.request);
+        logger.debug(`[Server] Execution completed: exitCode=${result.exitCode} duration=${result.durationMs}ms`);
         return c.json(result);
       } finally {
         globalSemaphore.release();
       }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
+      logger.debug(`[Server] Execution error: ${message}`);
       return c.json({ error: message }, 500);
     } finally {
       if (!body.sessionId) {
+        logger.debug("[Server] Cleaning up ephemeral engine");
         await engine.stop();
       }
     }
   });
   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`);
     const engineOptions = {
       network: config.defaults.network,
       memoryLimit: config.defaults.memoryLimit,
@@ -57763,6 +57838,7 @@ async function createServer(options) {
     const stream = new ReadableStream({
       async start(controller) {
         try {
+          logger.debug("[Server] Acquiring semaphore for /execute/stream");
           await globalSemaphore.acquire();
           try {
             for await (const event of engine.executeStream(body.request)) {
@@ -57771,16 +57847,19 @@ async function createServer(options) {
 `;
               controller.enqueue(encoder.encode(line));
             }
+            logger.debug("[Server] Stream completed");
           } finally {
             globalSemaphore.release();
           }
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
+          logger.debug(`[Server] Stream error: ${message}`);
           const errorEvent = `data: ${JSON.stringify({ type: "error", data: message })}
 
 `;
           controller.enqueue(encoder.encode(errorEvent));
         } finally {
+          logger.debug("[Server] Cleaning up stream engine");
           await engine.stop();
           controller.close();
         }
@@ -57796,35 +57875,45 @@ async function createServer(options) {
   });
   app.post("/file", async (c) => {
     const body = await c.req.json();
+    logger.debug(`[Server] POST /file sessionId=${body.sessionId} path=${body.path}`);
     const session = sessions.get(body.sessionId);
     if (!session) {
+      logger.debug(`[Server] Session not found: ${body.sessionId}`);
       return c.json({ error: "Session not found" }, 404);
     }
     session.lastAccessedAt = Date.now();
     const content = Buffer.from(body.content, "base64");
     await session.engine.putFile(body.path, content);
+    logger.debug(`[Server] File uploaded: ${body.path} (${content.length} bytes)`);
     return c.json({ ok: true });
   });
   app.get("/file", async (c) => {
     const sessionId = c.req.query("sessionId");
     const path = c.req.query("path");
+    logger.debug(`[Server] GET /file sessionId=${sessionId} path=${path}`);
     if (!(sessionId && path)) {
       return c.json({ error: "Missing sessionId or path" }, 400);
     }
     const session = sessions.get(sessionId);
     if (!session) {
+      logger.debug(`[Server] Session not found: ${sessionId}`);
       return c.json({ error: "Session not found" }, 404);
     }
     session.lastAccessedAt = Date.now();
     const content = await session.engine.getFile(path);
+    logger.debug(`[Server] File downloaded: ${path} (${content.length} bytes)`);
     return c.json({ content: content.toString("base64") });
   });
   app.delete("/session/:id", async (c) => {
     const id = c.req.param("id");
+    logger.debug(`[Server] DELETE /session/${id}`);
     const session = sessions.get(id);
     if (session) {
       await session.engine.stop();
       sessions.delete(id);
+      logger.debug(`[Server] Session destroyed: ${id}`);
+    } else {
+      logger.debug(`[Server] Session not found (already cleaned up): ${id}`);
     }
     return c.json({ ok: true });
   });
@@ -57834,6 +57923,7 @@ async function createServer(options) {
       const now = Date.now();
       for (const [id, session] of sessions) {
         if (now - session.lastAccessedAt > maxAge) {
+          logger.debug(`[Server] Auto-pruning stale session: ${id}`);
           await session.engine.stop();
           sessions.delete(id);
         }
@@ -57850,6 +57940,7 @@ var sessions;
 var init_server = __esm(() => {
   init_dist();
   init_config();
+  init_logger();
   init_version();
   sessions = new Map;
 });
@@ -57857,9 +57948,9 @@ var init_server = __esm(() => {
 // src/cli.ts
 import {
   chmodSync,
-  existsSync as existsSync3,
+  existsSync as existsSync4,
   mkdirSync,
-  readFileSync as readFileSync2,
+  readFileSync as readFileSync3,
   renameSync,
   unlinkSync,
   writeFileSync
@@ -58462,7 +58553,7 @@ onetime.callCount = (function_) => {
 };
 var onetime_default = onetime;
 
-// node_modules/restore-cursor/node_modules/signal-exit/dist/mjs/signals.js
+// node_modules/signal-exit/dist/mjs/signals.js
 var signals = [];
 signals.push("SIGHUP", "SIGINT", "SIGTERM");
 if (process.platform !== "win32") {
@@ -58472,7 +58563,7 @@ if (process.platform === "linux") {
   signals.push("SIGIO", "SIGPOLL", "SIGPWR", "SIGSTKFLT");
 }
 
-// node_modules/restore-cursor/node_modules/signal-exit/dist/mjs/index.js
+// node_modules/signal-exit/dist/mjs/index.js
 var processOk = (process3) => !!process3 && typeof process3 === "object" && typeof process3.removeListener === "function" && typeof process3.emit === "function" && typeof process3.reallyExit === "function" && typeof process3.listeners === "function" && typeof process3.kill === "function" && typeof process3.pid === "number" && typeof process3.on === "function";
 var kExitEmitter = Symbol.for("signal-exit emitter");
 var global2 = globalThis;
@@ -61259,10 +61350,10 @@ init_docker();
 
 // src/engine/image-builder.ts
 init_runtime();
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync3 } from "node:fs";
 function resolveDockerDir() {
   const fromBundled = new URL("../docker", import.meta.url).pathname;
-  if (existsSync2(fromBundled)) {
+  if (existsSync3(fromBundled)) {
     return fromBundled;
   }
   return new URL("../../docker", import.meta.url).pathname;
@@ -61362,15 +61453,26 @@ ${installCmd}
 
 // src/cli.ts
 init_runtime();
+init_logger();
 init_version();
 var program2 = new Command;
-program2.name("isol8").description("Secure code execution engine").version(VERSION);
+program2.name("isol8").description("Secure code execution engine").version(VERSION).option("--debug", "Enable debug logging").hook("preAction", (thisCommand) => {
+  const opts = thisCommand.optsWithGlobals();
+  if (opts.debug) {
+    logger.setDebug(true);
+  }
+  logger.debug(`[CLI] Command: ${thisCommand.args?.[0] ?? thisCommand.name()}`);
+  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) => {
   const docker = new import_dockerode2.default;
+  logger.debug("[Setup] Connecting to Docker daemon");
   const spinner = ora("Checking Docker...").start();
   try {
     await docker.ping();
     spinner.stopAndPersist({ symbol: "[OK]", text: "Docker is running" });
+    logger.debug("[Setup] Docker ping successful");
   } catch {
     spinner.stopAndPersist({ symbol: "[ERR]", text: "Docker is not running or not installed." });
     console.error("      Install Docker: https://docs.docker.com/get-docker/");
@@ -61378,11 +61480,14 @@ 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");
   await buildBaseImages(docker, (progress) => {
     const status = progress.status === "error" ? "[ERR]" : progress.status === "done" ? "[OK]" : "[..]";
     if (progress.status === "building") {
       spinner.text = `Building ${progress.runtime}...`;
+      logger.debug(`[Setup] Building base image for ${progress.runtime}`);
     } else if (progress.status === "done" || progress.status === "error") {
+      logger.debug(`[Setup] Base image ${progress.runtime}: ${progress.status}${progress.message ? ` (${progress.message})` : ""}`);
       spinner.stopAndPersist({
         symbol: status,
         text: `${progress.runtime}${progress.message ? `: ${progress.message}` : ""}`
@@ -61396,32 +61501,41 @@ program2.command("setup").description("Check Docker and build isol8 images").opt
     spinner.stop();
   }
   const config = loadConfig();
+  logger.debug("[Setup] Config loaded");
   if (opts.python) {
+    logger.debug(`[Setup] Adding Python packages from CLI: ${opts.python}`);
     config.dependencies.python = [
       ...config.dependencies.python ?? [],
       ...opts.python.split(",")
     ];
   }
   if (opts.node) {
+    logger.debug(`[Setup] Adding Node.js packages from CLI: ${opts.node}`);
     config.dependencies.node = [...config.dependencies.node ?? [], ...opts.node.split(",")];
   }
   if (opts.bun) {
+    logger.debug(`[Setup] Adding Bun packages from CLI: ${opts.bun}`);
     config.dependencies.bun = [...config.dependencies.bun ?? [], ...opts.bun.split(",")];
   }
   if (opts.deno) {
+    logger.debug(`[Setup] Adding Deno packages from CLI: ${opts.deno}`);
     config.dependencies.deno = [...config.dependencies.deno ?? [], ...opts.deno.split(",")];
   }
   if (opts.bash) {
+    logger.debug(`[Setup] Adding Bash packages from CLI: ${opts.bash}`);
     config.dependencies.bash = [...config.dependencies.bash ?? [], ...opts.bash.split(",")];
   }
   const hasDeps = Object.values(config.dependencies).some((pkgs) => pkgs && pkgs.length > 0);
   if (hasDeps) {
+    logger.debug("[Setup] Building custom images with dependencies:", JSON.stringify(config.dependencies));
     spinner.start("Building custom images with dependencies...");
     await buildCustomImages(docker, config, (progress) => {
       const status = progress.status === "error" ? "[ERR]" : progress.status === "done" ? "[OK]" : "[..]";
       if (progress.status === "building") {
         spinner.text = `Building custom ${progress.runtime}...`;
+        logger.debug(`[Setup] Building custom image for ${progress.runtime}`);
       } else if (progress.status === "done" || progress.status === "error") {
+        logger.debug(`[Setup] Custom image ${progress.runtime}: ${progress.status}${progress.message ? ` (${progress.message})` : ""}`);
         spinner.stopAndPersist({
           symbol: status,
           text: `${progress.runtime}${progress.message ? ` (${progress.message})` : ""}`
@@ -61440,6 +61554,22 @@ program2.command("setup").description("Check Docker and build isol8 images").opt
 });
 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)").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").action(async (file, opts) => {
   const { code, 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`);
+  if (stdinData) {
+    logger.debug(`[Run] Stdin data provided (${stdinData.length} chars)`);
+  }
+  if (opts.install?.length > 0) {
+    logger.debug(`[Run] Packages to install: ${opts.install.join(", ")}`);
+  }
+  if (opts.host) {
+    logger.debug(`[Run] Remote execution on ${opts.host}`);
+  }
+  if (engineOptions.persist) {
+    logger.debug("[Run] Persist mode enabled");
+  }
   const cleanup = async () => {
     await engine.stop();
     process.exit(0);
@@ -61450,6 +61580,7 @@ program2.command("run").description("Execute code in isol8").argument("[file]",
   let exitCode = 0;
   try {
     await engine.start();
+    logger.debug("[Run] Engine started");
     spinner.text = "Running code...";
     const req = {
       code,
@@ -61460,6 +61591,7 @@ program2.command("run").description("Execute code in isol8").argument("[file]",
       fileExtension
     };
     if (opts.stream !== false) {
+      logger.debug("[Run] Using streaming mode");
       spinner.stop();
       const stream = engine.executeStream(req);
       for await (const event of stream) {
@@ -61477,7 +61609,9 @@ program2.command("run").description("Execute code in isol8").argument("[file]",
         }
       }
     } else {
+      logger.debug("[Run] Using non-streaming mode");
       const result = await engine.execute(req);
+      logger.debug(`[Run] Execution completed: exitCode=${result.exitCode}, duration=${result.durationMs}ms, truncated=${result.truncated}`);
       spinner.stop();
       if (result.stdout) {
         console.log(result.stdout);
@@ -61500,6 +61634,7 @@ program2.command("run").description("Execute code in isol8").argument("[file]",
     spinner.stop();
     throw err;
   } finally {
+    logger.debug("[Run] Stopping engine");
     const cleanupPromise = engine.stop();
     const timeoutPromise = new Promise((resolve3) => setTimeout(resolve3, 5000));
     await Promise.race([cleanupPromise, timeoutPromise]);
@@ -61508,24 +61643,33 @@ program2.command("run").description("Execute code in isol8").argument("[file]",
     process.exit(exitCode);
   }
 });
-program2.command("serve").description("Start the isol8 remote server").option("-p, --port <port>", "Port to listen on", "3000").option("-k, --key <key>", "API key for authentication").option("--update", "Force re-download the server binary").action(async (opts) => {
+program2.command("serve").description("Start the isol8 remote server").option("-p, --port <port>", "Port to listen on", "3000").option("-k, --key <key>", "API key for authentication").option("--update", "Force re-download the server binary").option("--debug", "Enable debug logging").action(async (opts) => {
   const apiKey = opts.key ?? process.env.ISOL8_API_KEY;
   if (!apiKey) {
     console.error("[ERR] API key required. Use --key or ISOL8_API_KEY env var.");
     process.exit(1);
   }
   const port = Number.parseInt(opts.port, 10);
+  logger.debug(`[Serve] Port: ${port}`);
+  logger.debug(`[Serve] API key: ${"*".repeat(apiKey.length)}`);
   if (typeof globalThis.Bun !== "undefined") {
+    logger.debug("[Serve] Running under Bun, starting server in-process");
     const { createServer: createServer2 } = await Promise.resolve().then(() => (init_server(), exports_server));
-    const server = await createServer2({ port, apiKey });
+    const server = await createServer2({ port, apiKey, debug: opts.debug ?? false });
     console.log(`[INFO] isol8 server v${VERSION} listening on http://localhost:${port}`);
     console.log("       Auth: Bearer token required");
     Bun.serve({ fetch: server.app.fetch, port });
     return;
   }
+  logger.debug("[Serve] Running under Node.js, launching standalone binary");
   const binaryPath = await ensureServerBinary(opts.update ?? false);
+  logger.debug(`[Serve] Binary path: ${binaryPath}`);
   const { spawn: spawnChild } = await import("node:child_process");
-  const child = spawnChild(binaryPath, ["--port", String(port), "--key", apiKey], {
+  const binaryArgs = ["--port", String(port), "--key", apiKey];
+  if (opts.debug) {
+    binaryArgs.push("--debug");
+  }
+  const child = spawnChild(binaryPath, binaryArgs, {
     stdio: "inherit"
   });
   const forwardSignal = (signal) => {
@@ -61540,6 +61684,7 @@ program2.command("serve").description("Start the isol8 remote server").option("-
 function getServerBinaryName() {
   const os2 = platform();
   const cpu = arch();
+  logger.debug(`[Serve] Resolving binary name for ${os2}-${cpu}`);
   const osMap = {
     darwin: "darwin",
     linux: "linux",
@@ -61560,7 +61705,8 @@ function getServerBinaryName() {
   return `isol8-server-${resolvedOs}-${resolvedArch}`;
 }
 async function getServerBinaryVersion(binaryPath) {
-  if (!existsSync3(binaryPath)) {
+  if (!existsSync4(binaryPath)) {
+    logger.debug(`[Serve] No binary found at ${binaryPath}`);
     return null;
   }
   try {
@@ -61569,14 +61715,17 @@ async function getServerBinaryVersion(binaryPath) {
       encoding: "utf-8",
       timeout: 5000
     });
+    logger.debug(`[Serve] Existing binary version: ${output.trim()}`);
     return output.trim();
   } catch {
+    logger.debug("[Serve] Failed to get binary version");
     return null;
   }
 }
 async function downloadServerBinary(binaryPath) {
   const binaryName = getServerBinaryName();
   const url = `https://github.com/Illusion47586/isol8/releases/download/v${VERSION}/${binaryName}`;
+  logger.debug(`[Serve] Download URL: ${url}`);
   const spinner = ora(`Downloading isol8 server v${VERSION}...`).start();
   try {
     const response = await fetch(url, { redirect: "follow" });
@@ -61596,11 +61745,12 @@ async function downloadServerBinary(binaryPath) {
     writeFileSync(tmpPath, buffer);
     chmodSync(tmpPath, 493);
     renameSync(tmpPath, binaryPath);
+    logger.debug(`[Serve] Binary saved to ${binaryPath} (${buffer.length} bytes)`);
     spinner.succeed(`Downloaded isol8 server v${VERSION}`);
   } catch (err) {
     spinner.fail("Failed to download server binary");
     const tmpPath = `${binaryPath}.tmp`;
-    if (existsSync3(tmpPath)) {
+    if (existsSync4(tmpPath)) {
       unlinkSync(tmpPath);
     }
     throw err;
@@ -61622,18 +61772,23 @@ async function promptYesNo(question) {
 async function ensureServerBinary(forceUpdate) {
   const binDir = join2(homedir2(), ".isol8", "bin");
   const binaryPath = join2(binDir, "isol8-server");
+  logger.debug(`[Serve] Binary path: ${binaryPath}, forceUpdate: ${forceUpdate}`);
   if (forceUpdate) {
+    logger.debug("[Serve] Force update requested");
     await downloadServerBinary(binaryPath);
     return binaryPath;
   }
   const existingVersion = await getServerBinaryVersion(binaryPath);
   if (existingVersion === null) {
+    logger.debug("[Serve] No existing binary, downloading");
     await downloadServerBinary(binaryPath);
     return binaryPath;
   }
   if (existingVersion === VERSION) {
+    logger.debug(`[Serve] Binary version ${existingVersion} matches CLI`);
     return binaryPath;
   }
+  logger.debug(`[Serve] Version mismatch: binary=${existingVersion}, CLI=${VERSION}`);
   console.log(`Server binary v${existingVersion} found, but CLI is v${VERSION}.`);
   const shouldUpdate = await promptYesNo("Download updated binary? [Y/n] ");
   if (shouldUpdate) {
@@ -61649,7 +61804,9 @@ program2.command("config").description("Show the resolved isol8 configuration").
     join2(resolve2(process.cwd()), "isol8.config.json"),
     join2(homedir2(), ".isol8", "config.json")
   ];
-  const loadedFrom = searchPaths.find((p) => existsSync3(p));
+  const loadedFrom = searchPaths.find((p) => existsSync4(p));
+  logger.debug(`[Config] Config source: ${loadedFrom ?? "defaults"}`);
+  logger.debug(`[Config] Resolved config: ${JSON.stringify(config)}`);
   if (opts.json) {
     console.log(JSON.stringify(config, null, 2));
     return;
@@ -61713,10 +61870,12 @@ Isol8 Configuration
 });
 program2.command("cleanup").description("Remove orphaned isol8 containers").option("--force", "Skip confirmation prompt").action(async (opts) => {
   const docker = new import_dockerode2.default;
+  logger.debug("[Cleanup] Connecting to Docker daemon");
   const spinner = ora("Checking Docker...").start();
   try {
     await docker.ping();
     spinner.succeed("Docker is running");
+    logger.debug("[Cleanup] Docker ping successful");
   } catch {
     spinner.fail("Docker is not running or not installed.");
     process.exit(1);
@@ -61724,6 +61883,7 @@ program2.command("cleanup").description("Remove orphaned isol8 containers").opti
   spinner.start("Finding isol8 containers...");
   const containers = await docker.listContainers({ all: true });
   const isol8Containers = containers.filter((c) => c.Image.startsWith("isol8:") || c.Image.startsWith("isol8-custom:"));
+  logger.debug(`[Cleanup] Found ${containers.length} total containers, ${isol8Containers.length} isol8 containers`);
   if (isol8Containers.length === 0) {
     spinner.info("No isol8 containers found");
     return;
@@ -61752,7 +61912,9 @@ program2.command("cleanup").description("Remove orphaned isol8 containers").opti
     }
   }
   spinner.start("Removing containers...");
+  logger.debug("[Cleanup] Removing containers");
   const result = await DockerIsol8.cleanup(docker);
+  logger.debug(`[Cleanup] Removed: ${result.removed}, failed: ${result.failed}`);
   if (result.errors.length > 0) {
     console.log("");
     for (const err of result.errors) {
@@ -61767,29 +61929,35 @@ program2.command("cleanup").description("Remove orphaned isol8 containers").opti
 });
 async function resolveRunInput(file, opts) {
   const config = loadConfig();
+  logger.debug("[Run] Config loaded");
   let code;
   let runtime;
   if (opts.eval) {
     code = opts.eval;
     runtime = opts.runtime ?? "python";
+    logger.debug(`[Run] Inline eval, runtime: ${runtime}`);
   } else if (file) {
     const filePath = resolve2(file);
-    if (!existsSync3(filePath)) {
+    logger.debug(`[Run] Reading file: ${filePath}`);
+    if (!existsSync4(filePath)) {
       console.error(`[ERR] File not found: ${file}`);
       process.exit(1);
     }
-    code = readFileSync2(filePath, "utf-8");
+    code = readFileSync3(filePath, "utf-8");
     if (opts.runtime) {
       runtime = opts.runtime;
+      logger.debug(`[Run] Runtime specified: ${runtime}`);
     } else {
       try {
         runtime = RuntimeRegistry.detect(file).name;
+        logger.debug(`[Run] Auto-detected runtime: ${runtime}`);
       } catch {
         console.error(`[ERR] Cannot detect runtime for ${file}. Use --runtime to specify.`);
         process.exit(1);
       }
     }
   } else {
+    logger.debug("[Run] Reading code from stdin");
     const chunks = [];
     for await (const chunk of process.stdin) {
       chunks.push(chunk);
@@ -61815,10 +61983,7 @@ async function resolveRunInput(file, opts) {
     debug: opts.debug ?? config.debug,
     persist: opts.persist ?? false
   };
-  if (engineOptions.debug) {
-    const { logger: logger2 } = await Promise.resolve().then(() => (init_logger(), exports_logger));
-    logger2.setDebug(true);
-  }
+  logger.debug(`[Run] Engine options: mode=${engineOptions.mode}, network=${engineOptions.network}`);
   let fileExtension;
   if (file) {
     const ext = file.substring(file.lastIndexOf("."));
@@ -61839,6 +62004,7 @@ async function resolveRunInput(file, opts) {
   const stdinData = opts.stdin ?? undefined;
   let engine;
   if (opts.host) {
+    logger.debug(`[Run] Using remote engine: ${opts.host}`);
     const apiKey = opts.key ?? process.env.ISOL8_API_KEY;
     if (!apiKey) {
       console.error("[ERR] API key required. Use --key or ISOL8_API_KEY env var.");
@@ -61846,6 +62012,7 @@ async function resolveRunInput(file, opts) {
     }
     engine = new RemoteIsol8({ host: opts.host, apiKey, sessionId: opts.persistent ? `cli-${Date.now()}` : undefined }, engineOptions);
   } else {
+    logger.debug("[Run] Using local Docker engine");
     engine = new DockerIsol8(engineOptions, config.maxConcurrent);
   }
   return { code, runtime, engineOptions, engine, stdinData, fileExtension };
@@ -61859,4 +62026,4 @@ if (!process.argv.slice(2).length) {
 }
 program2.parse();
 
-//# debugId=05A7CFDAF922346964756E2164756E21
+//# debugId=F86C7DBAE803AC0664756E2164756E21