@axiom-lattice/opensandbox-gateway 0.1.2

package/dist/chunk-FTPJIUJT.mjs

@@ -0,0 +1,1081 @@
+// src/services/OpenSandboxRuntimeService.ts
+import { ConnectionConfig, Sandbox } from "@alibaba-group/opensandbox";
+import { SandboxManager } from "@alibaba-group/opensandbox";
+import { SandboxException } from "@alibaba-group/opensandbox";
+
+// src/lib/errors.ts
+var HttpError = class extends Error {
+  constructor(statusCode, code, message) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+  }
+};
+function toErrorResponse(error) {
+  if (error instanceof HttpError) {
+    return {
+      statusCode: error.statusCode,
+      body: {
+        success: false,
+        error: {
+          code: error.code,
+          message: error.message
+        }
+      }
+    };
+  }
+  return {
+    statusCode: 500,
+    body: {
+      success: false,
+      error: {
+        code: "INTERNAL_ERROR",
+        message: error instanceof Error ? error.message : String(error)
+      }
+    }
+  };
+}
+
+// src/services/OpenSandboxRuntimeService.ts
+var NAME_METADATA_KEY = "axiom-lattice/name";
+function getEnv(key, fallback) {
+  return process.env[key] ?? fallback;
+}
+function getEnvNumber(key, fallback) {
+  const v = process.env[key];
+  return v ? Number(v) : fallback;
+}
+var OpenSandboxRuntimeService = class {
+  constructor() {
+    this.cache = /* @__PURE__ */ new Map();
+    this.pendingCreates = /* @__PURE__ */ new Map();
+    this.connectionConfig = new ConnectionConfig({
+      domain: getEnv("OPEN_SANDBOX_DOMAIN", "localhost:8080"),
+      protocol: getEnv("OPEN_SANDBOX_PROTOCOL", "http"),
+      apiKey: process.env["OPEN_SANDBOX_API_KEY"],
+      useServerProxy: getEnv("OPEN_SANDBOX_USE_SERVER_PROXY", "false") === "true"
+    });
+    this.defaultImage = getEnv("OPEN_SANDBOX_DEFAULT_IMAGE", "ubuntu:22.04");
+    this.defaultCpus = getEnvNumber("OPEN_SANDBOX_DEFAULT_CPUS", 1);
+    this.defaultMemoryMib = getEnvNumber("OPEN_SANDBOX_DEFAULT_MEMORY_MIB", 2048);
+    this.defaultTimeout = getEnvNumber("OPEN_SANDBOX_DEFAULT_TIMEOUT", 600);
+    this.idleTimeoutMs = getEnvNumber("SANDBOX_IDLE_TIMEOUT_MS", 6e5);
+  }
+  mapVolumes(volumes) {
+    if (!volumes) return [];
+    return Object.entries(volumes).map(([mountPath, def]) => {
+      if (def.type === "bind" && def.source) {
+        return { name: mountPath, host: { path: def.source }, mountPath, readOnly: def.readonly };
+      }
+      if (def.type === "named" && def.name) {
+        return { name: mountPath, pvc: { claimName: def.name }, mountPath, readOnly: def.readonly };
+      }
+      if (def.type === "tmpfs") {
+        throw new HttpError(400, "INVALID_REQUEST", "tmpfs volumes are not supported by OpenSandbox");
+      }
+      throw new HttpError(400, "INVALID_REQUEST", `Unsupported volume type at ${mountPath}`);
+    });
+  }
+  getCached(name) {
+    const entry = this.cache.get(name);
+    if (!entry) {
+      throw new HttpError(404, "SANDBOX_NOT_FOUND", `Sandbox '${name}' not found`);
+    }
+    return entry;
+  }
+  async findByNameViaMetadata(name) {
+    try {
+      const manager = SandboxManager.create({ connectionConfig: this.connectionConfig });
+      const result = await manager.listSandboxInfos({
+        metadata: { [NAME_METADATA_KEY]: name },
+        pageSize: 1
+      });
+      if (result.items.length === 0) {
+        return null;
+      }
+      const info = result.items[0];
+      const sandbox = await Sandbox.resume({
+        sandboxId: info.id,
+        connectionConfig: this.connectionConfig
+      });
+      const entry = {
+        sandbox,
+        sandboxId: info.id,
+        createdAt: info.createdAt ? new Date(info.createdAt).toISOString() : (/* @__PURE__ */ new Date()).toISOString(),
+        lastUsedAt: Date.now()
+      };
+      this.cache.set(name, entry);
+      return entry;
+    } catch (err) {
+      if (err instanceof SandboxException && err.error.code === "NOT_FOUND") {
+        return null;
+      }
+      console.warn(`[OpenSandboxRuntimeService] metadata lookup for name=${name} failed:`, err);
+      return null;
+    }
+  }
+  async ensureSandbox(name, input) {
+    const cached = this.cache.get(name);
+    if (cached) {
+      try {
+        const info = await cached.sandbox.getInfo();
+        if (info.status.state === "Running") {
+          cached.lastUsedAt = Date.now();
+          await cached.sandbox.renew(this.defaultTimeout).catch(() => {
+          });
+          return { name, status: "running" };
+        }
+        this.cache.delete(name);
+      } catch {
+        this.cache.delete(name);
+      }
+    }
+    const inflight = this.pendingCreates.get(name);
+    if (inflight) {
+      await inflight;
+      return { name, status: "running" };
+    }
+    const recovered = await this.findByNameViaMetadata(name);
+    if (recovered) {
+      return { name, status: "running" };
+    }
+    const creation = this.doCreateSandbox(name, input);
+    this.pendingCreates.set(name, creation);
+    try {
+      await creation;
+      return { name, status: "running" };
+    } finally {
+      this.pendingCreates.delete(name);
+    }
+  }
+  async doCreateSandbox(name, input) {
+    const sandbox = await Sandbox.create({
+      connectionConfig: this.connectionConfig,
+      image: input.image ?? this.defaultImage,
+      timeoutSeconds: this.defaultTimeout,
+      resource: {
+        cpu: String(input.cpus ?? this.defaultCpus),
+        memory: `${input.memoryMib ?? this.defaultMemoryMib}Mi`
+      },
+      env: input.env ?? {},
+      metadata: { [NAME_METADATA_KEY]: name },
+      volumes: this.mapVolumes(input.volumes),
+      entrypoint: ["tail", "-f", "/dev/null"]
+    });
+    const info = await sandbox.getInfo();
+    const entry = {
+      sandbox,
+      sandboxId: info.id,
+      createdAt: info.createdAt ? new Date(info.createdAt).toISOString() : (/* @__PURE__ */ new Date()).toISOString(),
+      lastUsedAt: Date.now()
+    };
+    this.cache.set(name, entry);
+    return entry;
+  }
+  wrapError(err, code, message) {
+    if (err instanceof HttpError) throw err;
+    if (err instanceof SandboxException) {
+      throw new HttpError(
+        err.error.code === "NOT_FOUND" ? 404 : err.error.code === "FORBIDDEN" ? 403 : err.error.code === "CONFLICT" ? 409 : err.error.code === "INVALID_REQUEST" ? 400 : 500,
+        err.error.code,
+        err.error.message ?? message
+      );
+    }
+    throw new HttpError(500, code, message);
+  }
+  async startSandbox(name) {
+    const entry = this.getCached(name);
+    try {
+      const resumed = await Sandbox.resume({
+        sandboxId: entry.sandboxId,
+        connectionConfig: this.connectionConfig
+      });
+      const info = await resumed.getInfo();
+      entry.sandbox = resumed;
+      entry.sandboxId = info.id;
+      entry.lastUsedAt = Date.now();
+      return { name, status: "running" };
+    } catch (err) {
+      throw this.wrapError(err, "SANDBOX_NOT_FOUND", `Failed to start sandbox '${name}'`);
+    }
+  }
+  async stopSandbox(name) {
+    const entry = this.getCached(name);
+    try {
+      await entry.sandbox.pause();
+      return { name, status: "stopped" };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to stop sandbox '${name}'`);
+    }
+  }
+  async killSandbox(name) {
+    const entry = this.cache.get(name);
+    if (!entry) {
+      throw new HttpError(404, "SANDBOX_NOT_FOUND", `Sandbox '${name}' not found`);
+    }
+    try {
+      await entry.sandbox.kill();
+    } catch {
+    }
+    try {
+      await entry.sandbox.close();
+    } catch {
+    }
+    this.cache.delete(name);
+    return { name, status: "unknown" };
+  }
+  async deleteSandbox(name) {
+    return this.killSandbox(name);
+  }
+  async getStatus(name) {
+    const entry = this.cache.get(name);
+    if (entry) {
+      try {
+        const info = await entry.sandbox.getInfo();
+        const status = info.status.state.toLowerCase();
+        return { name, status };
+      } catch {
+        return { name, status: "unknown" };
+      }
+    }
+    try {
+      const manager = SandboxManager.create({ connectionConfig: this.connectionConfig });
+      const result = await manager.listSandboxInfos({
+        metadata: { [NAME_METADATA_KEY]: name },
+        pageSize: 1
+      });
+      if (result.items.length > 0) {
+        return { name, status: result.items[0].status.state.toLowerCase() };
+      }
+    } catch {
+    }
+    return { name, status: "unknown" };
+  }
+  resolvePath(path2) {
+    if (path2 === "~" || path2 === "~/") return "/";
+    if (path2.startsWith("~/")) return `/${path2.slice(2)}`;
+    return path2;
+  }
+  async readFile(sandboxName, path2) {
+    const resolvedPath = this.resolvePath(path2);
+    const entry = this.getCached(sandboxName);
+    try {
+      const content = await entry.sandbox.files.readFile(resolvedPath);
+      return { path: resolvedPath, content };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to read file '${resolvedPath}' in sandbox '${sandboxName}'`);
+    }
+  }
+  async writeFile(sandboxName, path2, content) {
+    const resolvedPath = this.resolvePath(path2);
+    const entry = this.getCached(sandboxName);
+    try {
+      const parentDir = resolvedPath.split("/").slice(0, -1).join("/") || "/";
+      await entry.sandbox.files.createDirectories([{ path: parentDir }]).catch(() => {
+      });
+      await entry.sandbox.files.writeFiles([{ path: resolvedPath, data: content }]);
+      return { path: resolvedPath };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to write file '${resolvedPath}' in sandbox '${sandboxName}'`);
+    }
+  }
+  async listPath(sandboxName, path2, recursive) {
+    const resolvedPath = this.resolvePath(path2);
+    const entry = this.getCached(sandboxName);
+    try {
+      const files = await entry.sandbox.files.listDirectory({
+        path: resolvedPath,
+        depth: recursive ? void 0 : 1
+      });
+      return {
+        entries: files.map((f) => ({
+          path: f.path,
+          type: f.isDir === true ? "directory" : f.isSymlink === true ? "symlink" : "file"
+        }))
+      };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to list path '${resolvedPath}' in sandbox '${sandboxName}'`);
+    }
+  }
+  async findFiles(sandboxName, path2, pattern) {
+    const resolvedPath = this.resolvePath(path2);
+    const entry = this.getCached(sandboxName);
+    try {
+      const results = await entry.sandbox.files.search({
+        path: resolvedPath,
+        pattern: pattern || "*"
+      });
+      return { files: results.map((r) => r.path) };
+    } catch (err) {
+      try {
+        const result = await entry.sandbox.commands.run(
+          `find ${resolvedPath} -name '${pattern}' -type f`,
+          { timeoutSeconds: 30 }
+        );
+        return { files: result.logs.stdout.map((s) => s.text).join("").split("\n").filter(Boolean) };
+      } catch {
+        throw this.wrapError(err, "INTERNAL_ERROR", `Failed to find files in '${resolvedPath}'`);
+      }
+    }
+  }
+  async searchInFile(sandboxName, path2, query) {
+    const resolvedPath = this.resolvePath(path2);
+    const entry = this.getCached(sandboxName);
+    try {
+      const result = await entry.sandbox.commands.run(
+        `grep -n -E '${query.replace(/'/g, "'\\''")}' ${resolvedPath}`,
+        { timeoutSeconds: 30 }
+      );
+      const stdout = result.logs.stdout.map((s) => s.text).join("");
+      if (!stdout.trim()) return { matches: [] };
+      return {
+        matches: stdout.split("\n").filter(Boolean).map((line) => {
+          const idx = line.indexOf(":");
+          return { line: Number(line.slice(0, idx)), content: line.slice(idx + 1) };
+        })
+      };
+    } catch (err) {
+      if (err instanceof SandboxException) return { matches: [] };
+      if (typeof err === "object" && err !== null && "code" in err && err.code === 1) {
+        return { matches: [] };
+      }
+      return { matches: [] };
+    }
+  }
+  async replaceInFile(sandboxName, input) {
+    const resolvedPath = this.resolvePath(input.path);
+    const entry = this.getCached(sandboxName);
+    try {
+      const original = await entry.sandbox.files.readFile(resolvedPath);
+      if (!input.search) return { replaced: 0 };
+      const occurrences = original.split(input.search).length - 1;
+      if (occurrences === 0) return { replaced: 0 };
+      const updated = original.split(input.search).join(input.replace);
+      await entry.sandbox.files.writeFiles([{ path: resolvedPath, data: updated }]);
+      return { replaced: occurrences };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to replace in file '${resolvedPath}'`);
+    }
+  }
+  async uploadFile(sandboxName, path2, contentBase64) {
+    const resolvedPath = this.resolvePath(path2);
+    const entry = this.getCached(sandboxName);
+    try {
+      const data = Buffer.from(contentBase64, "base64").toString("utf-8");
+      await entry.sandbox.files.writeFiles([{ path: resolvedPath, data }]);
+      return { path: resolvedPath };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to upload file '${resolvedPath}'`);
+    }
+  }
+  async downloadFile(sandboxName, path2) {
+    const resolvedPath = this.resolvePath(path2);
+    const entry = this.getCached(sandboxName);
+    try {
+      const data = await entry.sandbox.files.readBytes(resolvedPath);
+      const b64 = Buffer.from(data).toString("base64");
+      return { path: resolvedPath, contentBase64: b64 };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to download file '${resolvedPath}'`);
+    }
+  }
+  async execCommand(input) {
+    const entry = this.getCached(input.sandboxName);
+    try {
+      const result = await entry.sandbox.commands.run(input.command, {
+        workingDirectory: input.exec_dir,
+        timeoutSeconds: input.timeout ? Math.ceil(input.timeout / 1e3) : void 0
+      });
+      return {
+        stdout: result.logs.stdout.map((s) => s.text).join(""),
+        stderr: result.logs.stderr.map((s) => s.text).join(""),
+        exitCode: result.exitCode ?? 0
+      };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Command execution failed in sandbox '${input.sandboxName}'`);
+    }
+  }
+  async getSandbox(name) {
+    const entry = this.cache.get(name);
+    if (entry) {
+      try {
+        const info = await entry.sandbox.getInfo();
+        return {
+          name,
+          status: info.status.state.toLowerCase(),
+          image: info.image?.uri ?? "unknown",
+          cpus: void 0,
+          memoryMib: void 0,
+          env: {},
+          volumes: {},
+          metrics: void 0,
+          createdAt: info.createdAt ? new Date(info.createdAt).toISOString() : entry.createdAt,
+          updatedAt: info.createdAt ? new Date(info.createdAt).toISOString() : entry.createdAt
+        };
+      } catch {
+        this.cache.delete(name);
+      }
+    }
+    try {
+      const manager = SandboxManager.create({ connectionConfig: this.connectionConfig });
+      const result = await manager.listSandboxInfos({
+        metadata: { [NAME_METADATA_KEY]: name },
+        pageSize: 1
+      });
+      if (result.items.length > 0) {
+        const info = result.items[0];
+        return {
+          name,
+          status: info.status.state.toLowerCase(),
+          image: info.image?.uri ?? "unknown",
+          cpus: void 0,
+          memoryMib: void 0,
+          env: {},
+          volumes: {},
+          metrics: void 0,
+          createdAt: info.createdAt ? new Date(info.createdAt).toISOString() : "",
+          updatedAt: info.createdAt ? new Date(info.createdAt).toISOString() : ""
+        };
+      }
+    } catch {
+    }
+    return void 0;
+  }
+  async listSandboxes(_query) {
+    try {
+      const manager = SandboxManager.create({ connectionConfig: this.connectionConfig });
+      const filter = {};
+      if (_query.status) filter.states = [_query.status];
+      const result = await manager.listSandboxInfos(filter);
+      const items = result.items.filter((info) => {
+        if (_query.search) {
+          const haystack = [info.id, info.image?.uri].filter(Boolean).join(" ").toLowerCase();
+          return haystack.includes(_query.search.toLowerCase());
+        }
+        return true;
+      }).map((info) => ({
+        name: info.id,
+        status: info.status.state.toLowerCase(),
+        image: info.image?.uri ?? "unknown",
+        cpus: void 0,
+        memoryMib: void 0,
+        envCount: 0,
+        volumeCount: 0,
+        createdAt: info.createdAt ? new Date(info.createdAt).toISOString() : "",
+        updatedAt: info.createdAt ? new Date(info.createdAt).toISOString() : ""
+      }));
+      return { items, total: items.length };
+    } catch {
+      return { items: [], total: 0 };
+    }
+  }
+  async getSandboxLogs(_name, _opts) {
+    return { entries: [] };
+  }
+};
+
+// src/app.ts
+import cors from "@fastify/cors";
+import multipart from "@fastify/multipart";
+import sensible from "@fastify/sensible";
+import fastify from "fastify";
+
+// src/lib/http.ts
+function ok(data) {
+  return {
+    success: true,
+    data
+  };
+}
+
+// src/routes/health.ts
+function registerHealthRoutes(app) {
+  app.get("/health", async () => ok({ status: "ok" }));
+}
+
+// src/controllers/images.ts
+import { ZodError } from "zod";
+
+// src/schemas/images.ts
+import z from "zod";
+var imageRefQuerySchema = z.object({
+  ref: z.string().min(1)
+});
+var pullImageSchema = z.object({
+  ref: z.string().min(1)
+});
+
+// src/controllers/images.ts
+function parseOrThrow(parse) {
+  try {
+    return parse();
+  } catch (error) {
+    if (error instanceof ZodError) {
+      throw new HttpError(400, "INVALID_REQUEST", error.issues[0]?.message ?? "Invalid request");
+    }
+    throw error;
+  }
+}
+function createImageController(imageService) {
+  return {
+    listImages: async (_request, reply) => {
+      return reply.send(ok(await imageService.listImages()));
+    },
+    pullImage: async (request, reply) => {
+      const body = parseOrThrow(() => pullImageSchema.parse(request.body ?? {}));
+      return reply.send(ok(await imageService.pullImage(body)));
+    },
+    getImage: async (request, reply) => {
+      const query = parseOrThrow(() => imageRefQuerySchema.parse(request.query ?? {}));
+      return reply.send(ok(await imageService.getImage(query.ref)));
+    },
+    deleteImage: async (request, reply) => {
+      const query = parseOrThrow(() => imageRefQuerySchema.parse(request.query ?? {}));
+      return reply.send(ok(await imageService.deleteImage(query.ref)));
+    }
+  };
+}
+
+// src/routes/images.ts
+function registerImageRoutes(app, imageService) {
+  const controller = createImageController(imageService);
+  app.get("/api/images", controller.listImages);
+  app.post("/api/images/pull", controller.pullImage);
+  app.get("/api/images/detail", controller.getImage);
+  app.delete("/api/images/detail", controller.deleteImage);
+}
+
+// src/schemas/sandbox.ts
+import z2 from "zod";
+var bindMountSchema = z2.object({
+  type: z2.literal("bind"),
+  source: z2.string().min(1),
+  readonly: z2.boolean().optional()
+});
+var namedMountSchema = z2.object({
+  type: z2.literal("named"),
+  name: z2.string().min(1),
+  readonly: z2.boolean().optional()
+});
+var tmpfsMountSchema = z2.object({
+  type: z2.literal("tmpfs"),
+  sizeMib: z2.number().int().positive().optional()
+});
+var volumeSchema = z2.union([
+  bindMountSchema,
+  namedMountSchema,
+  tmpfsMountSchema
+]);
+var ensureSandboxSchema = z2.object({
+  image: z2.string().optional(),
+  cpus: z2.number().int().positive().optional(),
+  memoryMib: z2.number().int().positive().optional(),
+  env: z2.record(z2.string()).optional(),
+  volumes: z2.record(volumeSchema).optional()
+});
+var sandboxNameParamsSchema = z2.object({
+  name: z2.string().min(1)
+});
+var listSandboxesQuerySchema = z2.object({
+  status: z2.enum(["running", "stopped", "crashed", "unknown"]).optional(),
+  image: z2.string().min(1).optional(),
+  search: z2.string().min(1).optional()
+});
+var sandboxAndPathSchema = z2.object({
+  sandboxName: z2.string().min(1),
+  path: z2.string().min(1)
+});
+var readFileSchema = sandboxAndPathSchema;
+var writeFileSchema = sandboxAndPathSchema.extend({
+  content: z2.string()
+});
+var listPathSchema = sandboxAndPathSchema.extend({
+  recursive: z2.boolean().optional()
+});
+var findFilesSchema = sandboxAndPathSchema.extend({
+  pattern: z2.string().min(1)
+});
+var searchInFileSchema = sandboxAndPathSchema.extend({
+  query: z2.string().min(1)
+});
+var replaceInFileSchema = sandboxAndPathSchema.extend({
+  search: z2.string(),
+  replace: z2.string()
+});
+var uploadFileSchema = sandboxAndPathSchema.and(
+  z2.union([
+    z2.object({ contentBase64: z2.string() }),
+    z2.object({ content: z2.string().transform((content) => Buffer.from(content).toString("base64")) })
+  ])
+);
+var downloadFileSchema = sandboxAndPathSchema;
+var shellExecSchema = z2.object({
+  sandboxName: z2.string().min(1),
+  command: z2.string().min(1),
+  exec_dir: z2.string().optional(),
+  timeout: z2.number().int().positive().optional()
+});
+var sandboxLogsSchema = z2.object({
+  tail: z2.number().int().positive().optional(),
+  since: z2.string().optional(),
+  until: z2.string().optional(),
+  sources: z2.array(z2.string()).optional()
+});
+
+// src/controllers/sandbox.ts
+function createSandboxController(runtimeService) {
+  return {
+    ensureSandbox: async (request, reply) => {
+      const body = ensureSandboxSchema.parse(request.body ?? {});
+      const result = await runtimeService.ensureSandbox(request.params.name, body);
+      return reply.send(ok(result));
+    },
+    startSandbox: async (request, reply) => {
+      return reply.send(ok(await runtimeService.startSandbox(request.params.name)));
+    },
+    stopSandbox: async (request, reply) => {
+      return reply.send(ok(await runtimeService.stopSandbox(request.params.name)));
+    },
+    killSandbox: async (request, reply) => {
+      return reply.send(ok(await runtimeService.killSandbox(request.params.name)));
+    },
+    deleteSandbox: async (request, reply) => {
+      return reply.send(ok(await runtimeService.deleteSandbox(request.params.name)));
+    },
+    listSandboxes: async (request, reply) => {
+      const query = listSandboxesQuerySchema.parse(request.query ?? {});
+      return reply.send(ok(await runtimeService.listSandboxes(query)));
+    },
+    getSandbox: async (request, reply) => {
+      const params = sandboxNameParamsSchema.parse(request.params ?? {});
+      const sandbox = await runtimeService.getSandbox(params.name);
+      if (!sandbox) {
+        throw new HttpError(404, "SANDBOX_NOT_FOUND", `Sandbox '${params.name}' not found`);
+      }
+      return reply.send(ok(sandbox));
+    },
+    getStatus: async (request, reply) => {
+      return reply.send(ok(await runtimeService.getStatus(request.params.name)));
+    },
+    getSandboxLogs: async (request, reply) => {
+      const body = sandboxLogsSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.getSandboxLogs(request.params.name, body)));
+    },
+    readFile: async (request, reply) => {
+      const body = readFileSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.readFile(body.sandboxName, body.path)));
+    },
+    writeFile: async (request, reply) => {
+      const body = writeFileSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.writeFile(body.sandboxName, body.path, body.content)));
+    },
+    listPath: async (request, reply) => {
+      const body = listPathSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.listPath(body.sandboxName, body.path, body.recursive)));
+    },
+    findFiles: async (request, reply) => {
+      const body = findFilesSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.findFiles(body.sandboxName, body.path, body.pattern)));
+    },
+    searchInFile: async (request, reply) => {
+      const body = searchInFileSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.searchInFile(body.sandboxName, body.path, body.query)));
+    },
+    replaceInFile: async (request, reply) => {
+      const body = replaceInFileSchema.parse(request.body ?? {});
+      return reply.send(
+        ok(
+          await runtimeService.replaceInFile(body.sandboxName, {
+            path: body.path,
+            search: body.search,
+            replace: body.replace
+          })
+        )
+      );
+    },
+    uploadFile: async (request, reply) => {
+      const body = uploadFileSchema.parse(request.body ?? {});
+      const contentBase64 = "contentBase64" in body ? body.contentBase64 : Buffer.from(body.content).toString("base64");
+      return reply.send(ok(await runtimeService.uploadFile(body.sandboxName, body.path, contentBase64)));
+    },
+    downloadFile: async (request, reply) => {
+      const query = downloadFileSchema.parse(request.query ?? {});
+      return reply.send(ok(await runtimeService.downloadFile(query.sandboxName, query.path)));
+    },
+    execCommand: async (request, reply) => {
+      const body = shellExecSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.execCommand(body)));
+    }
+  };
+}
+
+// src/routes/sandbox.ts
+function registerSandboxRoutes(app, runtimeService) {
+  const controller = createSandboxController(runtimeService);
+  app.get("/api/sandboxes", controller.listSandboxes);
+  app.get("/api/sandboxes/:name", controller.getSandbox);
+  app.put("/api/sandboxes/:name", controller.ensureSandbox);
+  app.post("/api/sandboxes/:name/start", controller.startSandbox);
+  app.post("/api/sandboxes/:name/stop", controller.stopSandbox);
+  app.post("/api/sandboxes/:name/kill", controller.killSandbox);
+  app.delete("/api/sandboxes/:name", controller.deleteSandbox);
+  app.get("/api/sandboxes/:name/status", controller.getStatus);
+  app.post("/api/sandboxes/:name/logs", controller.getSandboxLogs);
+  app.post("/api/files/read", controller.readFile);
+  app.post("/api/files/write", controller.writeFile);
+  app.post("/api/files/list", controller.listPath);
+  app.post("/api/files/find", controller.findFiles);
+  app.post("/api/files/search", controller.searchInFile);
+  app.post("/api/files/replace", controller.replaceInFile);
+  app.post("/api/files/upload", controller.uploadFile);
+  app.get("/api/files/download", controller.downloadFile);
+  app.post("/api/shell/exec", controller.execCommand);
+}
+
+// src/controllers/volume-fs.ts
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+import z4 from "zod";
+
+// src/schemas/volume-fs.ts
+import z3 from "zod";
+var volumeFsReadSchema = z3.object({
+  path: z3.string()
+});
+var volumeFsWriteSchema = z3.object({
+  path: z3.string(),
+  content: z3.string()
+});
+var volumeFsListSchema = z3.object({
+  path: z3.string()
+});
+var volumeFsUploadSchema = z3.object({
+  path: z3.string(),
+  contentBase64: z3.string().min(1)
+});
+var volumeFsDownloadSchema = z3.object({
+  path: z3.string()
+});
+
+// src/controllers/volume-fs.ts
+function getVolumeBasePath() {
+  return process.env.VOLUME_BASE_PATH ?? path.join(os.homedir(), ".opensandbox", "volumes");
+}
+function resolveVolumeHostPath(name) {
+  return path.join(getVolumeBasePath(), name);
+}
+function resolveGuestPath(hostRoot, guestPath) {
+  const normalized = guestPath === "~" ? "" : guestPath.replace(/^~\//, "");
+  const resolved = path.join(
+    hostRoot,
+    path.normalize(normalized).replace(/^(\.\.(\/|\\|$))+/, "")
+  );
+  if (!resolved.startsWith(hostRoot + path.sep) && resolved !== hostRoot) {
+    throw new HttpError(403, "PATH_TRAVERSAL", "Path traversal detected");
+  }
+  return resolved;
+}
+function createVolumeFsController() {
+  return {
+    readFile: async (request, reply) => {
+      const { name } = request.params;
+      try {
+        const { path: guestPath } = volumeFsReadSchema.parse(request.body ?? {});
+        const hostRoot = resolveVolumeHostPath(name);
+        const fullPath = resolveGuestPath(hostRoot, guestPath);
+        const content = await fs.readFile(fullPath, "utf-8");
+        return reply.send(ok({ path: guestPath, content }));
+      } catch (err) {
+        if (err instanceof z4.ZodError) {
+          throw new HttpError(400, "VALIDATION_ERROR", err.message);
+        }
+        if (err instanceof HttpError) throw err;
+        throw new HttpError(404, "VOLUME_READ_ERROR", `Failed to read from volume '${name}': ${String(err)}`);
+      }
+    },
+    writeFile: async (request, reply) => {
+      const { name } = request.params;
+      try {
+        const { path: guestPath, content } = volumeFsWriteSchema.parse(request.body ?? {});
+        const hostRoot = resolveVolumeHostPath(name);
+        const fullPath = resolveGuestPath(hostRoot, guestPath);
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        await fs.writeFile(fullPath, content, "utf-8");
+        return reply.send(ok({ path: guestPath }));
+      } catch (err) {
+        if (err instanceof z4.ZodError) {
+          throw new HttpError(400, "VALIDATION_ERROR", err.message);
+        }
+        if (err instanceof HttpError) throw err;
+        throw new HttpError(500, "VOLUME_WRITE_ERROR", `Failed to write to volume '${name}': ${String(err)}`);
+      }
+    },
+    listPath: async (request, reply) => {
+      const { name } = request.params;
+      try {
+        const { path: guestPath } = volumeFsListSchema.parse(request.body ?? {});
+        const hostRoot = resolveVolumeHostPath(name);
+        const fullPath = resolveGuestPath(hostRoot, guestPath);
+        const dirents = await fs.readdir(fullPath, { withFileTypes: true });
+        const entries = dirents.map((d) => ({
+          path: guestPath ? `${guestPath}/${d.name}` : d.name,
+          kind: d.isDirectory() ? "directory" : d.isSymbolicLink() ? "symlink" : "file",
+          size: 0,
+          mode: 0
+        }));
+        return reply.send(ok({ entries }));
+      } catch (err) {
+        if (err instanceof z4.ZodError) {
+          throw new HttpError(400, "VALIDATION_ERROR", err.message);
+        }
+        if (err instanceof HttpError) throw err;
+        throw new HttpError(404, "VOLUME_LIST_ERROR", `Failed to list volume '${name}': ${String(err)}`);
+      }
+    },
+    downloadFile: async (request, reply) => {
+      const { name } = request.params;
+      try {
+        const { path: guestPath } = volumeFsDownloadSchema.parse(request.query ?? {});
+        const hostRoot = resolveVolumeHostPath(name);
+        const fullPath = resolveGuestPath(hostRoot, guestPath);
+        const buf = await fs.readFile(fullPath);
+        const contentBase64 = buf.toString("base64");
+        return reply.send(ok({ path: guestPath, contentBase64 }));
+      } catch (err) {
+        if (err instanceof z4.ZodError) {
+          throw new HttpError(400, "VALIDATION_ERROR", err.message);
+        }
+        if (err instanceof HttpError) throw err;
+        throw new HttpError(404, "VOLUME_DOWNLOAD_ERROR", `Failed to download from volume '${name}': ${String(err)}`);
+      }
+    },
+    uploadFile: async (request, reply) => {
+      const { name } = request.params;
+      try {
+        const { path: guestPath, contentBase64 } = volumeFsUploadSchema.parse(request.body ?? {});
+        const hostRoot = resolveVolumeHostPath(name);
+        const fullPath = resolveGuestPath(hostRoot, guestPath);
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        const data = Buffer.from(contentBase64, "base64");
+        await fs.writeFile(fullPath, data);
+        return reply.send(ok({ path: guestPath }));
+      } catch (err) {
+        if (err instanceof z4.ZodError) {
+          throw new HttpError(400, "VALIDATION_ERROR", err.message);
+        }
+        if (err instanceof HttpError) throw err;
+        throw new HttpError(500, "VOLUME_UPLOAD_ERROR", `Failed to upload to volume '${name}': ${String(err)}`);
+      }
+    }
+  };
+}
+
+// src/routes/volume-fs.ts
+function registerVolumeFsRoutes(app) {
+  const controller = createVolumeFsController();
+  app.post("/api/volumes/:name/fs/read", controller.readFile);
+  app.post("/api/volumes/:name/fs/write", controller.writeFile);
+  app.post("/api/volumes/:name/fs/list", controller.listPath);
+  app.get("/api/volumes/:name/fs/download", controller.downloadFile);
+  app.post("/api/volumes/:name/fs/upload", controller.uploadFile);
+}
+
+// src/services/ImageService.ts
+var ImageService = class {
+  async listImages() {
+    return { items: [], total: 0 };
+  }
+  async pullImage(_input) {
+    throw new Error("Image pull not supported in OpenSandbox gateway");
+  }
+  async getImage(ref) {
+    return {
+      ref,
+      sourceType: "oci",
+      cached: false
+    };
+  }
+  async deleteImage(ref) {
+    return { ref };
+  }
+};
+
+// src/swagger.ts
+import swagger from "@fastify/swagger";
+import swaggerUi from "@fastify/swagger-ui";
+var swaggerConfig = {
+  openapi: {
+    openapi: "3.0.0",
+    info: {
+      title: "OpenSandbox Gateway API",
+      description: "Sandbox lifecycle management backed by OpenSandbox",
+      version: "1.0.0"
+    },
+    servers: [{ url: "http://localhost:4002", description: "Local development" }],
+    components: {
+      securitySchemes: {
+        bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "API Key" }
+      }
+    },
+    tags: [
+      { name: "Sandboxes", description: "Sandbox lifecycle" },
+      { name: "Files", description: "File operations inside sandboxes" },
+      { name: "Shell", description: "Execute commands inside sandboxes" },
+      { name: "Images", description: "Image management (stub)" },
+      { name: "Volumes", description: "Named volume filesystem operations" },
+      { name: "Health", description: "Service health check" }
+    ]
+  }
+};
+var swaggerUiConfig = {
+  routePrefix: "/api-docs",
+  uiConfig: { docExpansion: "list", deepLinking: true },
+  staticCSP: true,
+  transformStaticCSP: (header) => header
+};
+async function configureSwagger(app) {
+  await app.register(swagger, swaggerConfig);
+  await app.register(swaggerUi, swaggerUiConfig);
+}
+
+// src/app.ts
+async function buildApp({
+  apiKey
+} = {}) {
+  const runtimeService = new OpenSandboxRuntimeService();
+  const imageService = new ImageService();
+  const app = fastify({
+    logger: false,
+    bodyLimit: Number(process.env["BODY_LIMIT"]) || 100 * 1024 * 1024
+  });
+  await app.register(cors, {
+    delegator: (request, callback) => {
+      callback(null, {
+        origin: true,
+        methods: request.headers["access-control-request-method"] ?? "*",
+        allowedHeaders: request.headers["access-control-request-headers"]
+      });
+    }
+  });
+  await app.register(sensible);
+  await app.register(multipart);
+  if (apiKey) {
+    app.addHook("onRequest", async (request, reply) => {
+      if (request.method === "OPTIONS" || !request.url.startsWith("/api/")) {
+        return;
+      }
+      if (request.headers.authorization !== `Bearer ${apiKey}`) {
+        await reply.code(401).send({
+          success: false,
+          error: { code: "UNAUTHORIZED", message: "Unauthorized" }
+        });
+      }
+    });
+  }
+  registerHealthRoutes(app);
+  registerSandboxRoutes(app, runtimeService);
+  registerImageRoutes(app, imageService);
+  registerVolumeFsRoutes(app);
+  app.setErrorHandler((error, _request, reply) => {
+    const { statusCode, body } = toErrorResponse(error);
+    reply.status(statusCode).send(body);
+  });
+  await configureSwagger(app);
+  return app;
+}
+
+// src/lib/server-cli.ts
+function parsePort(raw, source) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0 || value > 65535) {
+    throw new Error(`Invalid value for ${source}: ${raw}`);
+  }
+  return value;
+}
+function isMissingOptionValue(raw) {
+  return !raw || raw.startsWith("--");
+}
+function parseServerArgs(argv) {
+  const parsed = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--port") {
+      const raw = argv[index + 1];
+      if (isMissingOptionValue(raw)) {
+        throw new Error("Missing value for --port");
+      }
+      parsed.port = parsePort(raw, "--port");
+      index += 1;
+      continue;
+    }
+    if (token === "--host") {
+      const raw = argv[index + 1];
+      if (isMissingOptionValue(raw)) {
+        throw new Error("Missing value for --host");
+      }
+      parsed.host = raw;
+      index += 1;
+    }
+  }
+  return parsed;
+}
+function resolveServerConfig({
+  args,
+  env
+}) {
+  return {
+    host: args.host ?? env.HOST ?? "0.0.0.0",
+    port: args.port ?? (env.PORT ? parsePort(env.PORT, "PORT") : 4002),
+    apiKey: env.GATEWAY_API_KEY ?? env.MICROSANDBOX_API_KEY
+  };
+}
+
+// src/server.ts
+async function startServer({
+  argv = process.argv.slice(2),
+  env = process.env,
+  app
+} = {}) {
+  const config = resolveServerConfig({ args: parseServerArgs(argv), env });
+  const resolvedApp = app ?? await buildApp({ apiKey: config.apiKey });
+  const removeSignalHandlers = () => {
+    process.off("SIGINT", onSigInt);
+    process.off("SIGTERM", onSigTerm);
+  };
+  const close = async () => {
+    removeSignalHandlers();
+    return resolvedApp.close();
+  };
+  const onSigInt = () => {
+    void shutdown(0);
+  };
+  const onSigTerm = () => {
+    void shutdown(0);
+  };
+  const shutdown = async (code) => {
+    try {
+      await close();
+      process.exit(code);
+    } catch (error) {
+      console.error("Failed to shutdown opensandbox-gateway cleanly", error);
+      process.exit(1);
+    }
+  };
+  process.once("SIGINT", onSigInt);
+  process.once("SIGTERM", onSigTerm);
+  try {
+    await resolvedApp.listen({ port: config.port, host: config.host });
+    return { listen: resolvedApp.listen.bind(resolvedApp), close };
+  } catch (error) {
+    removeSignalHandlers();
+    throw error;
+  }
+}
+
+export {
+  OpenSandboxRuntimeService,
+  buildApp,
+  startServer
+};
+//# sourceMappingURL=chunk-FTPJIUJT.mjs.map