tensorlake 0.5.9 → 0.5.11

package/dist/sandbox-image.js

@@ -61,7 +61,7 @@ var SDK_VERSION, API_URL, API_KEY, NAMESPACE, SANDBOX_PROXY_URL, DEFAULT_HTTP_TI
 var init_defaults = __esm({
   "src/defaults.ts"() {
     "use strict";
-    SDK_VERSION = "0.5.9";
+    SDK_VERSION = "0.5.11";
     API_URL = process.env.TENSORLAKE_API_URL ?? "https://api.tensorlake.ai";
     API_KEY = process.env.TENSORLAKE_API_KEY ?? void 0;
     NAMESPACE = process.env.INDEXIFY_NAMESPACE ?? "default";
@@ -3316,11 +3316,10 @@ var init_sandbox = __esm({
         await client.resume(this.lifecycleIdentifier, options);
       }
       /**
-       * Create a snapshot of this sandbox's filesystem and wait for it to
-       * be committed.
+       * Create a checkpoint of this sandbox and wait for it to be locally ready.
        *
-       * By default blocks until the snapshot artifact is ready and returns
-       * the completed `SnapshotInfo`. Pass `{ wait: false }` to fire-and-return
+       * By default blocks until the checkpoint is resumable and returns
+       * `SnapshotInfo`. Pass `{ wait: false }` to fire-and-return
        * (returns `undefined`).
        */
       async checkpoint(options) {
@@ -3332,7 +3331,8 @@ var init_sandbox = __esm({
         return client.snapshotAndWait(this.lifecycleIdentifier, {
           timeout: options?.timeout,
           pollInterval: options?.pollInterval,
-          snapshotType: options?.checkpointType
+          snapshotType: options?.checkpointType,
+          waitUntil: options?.waitUntil
         });
       }
       /**
@@ -3727,6 +3727,12 @@ __export(client_exports, {
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function snapshotStatusSatisfiesWaitCondition(status, waitUntil) {
+  if (waitUntil === "local_ready") {
+    return status === "local_ready" /* LOCAL_READY */ || status === "completed" /* COMPLETED */;
+  }
+  return status === "completed" /* COMPLETED */;
+}
 function formatStartupFailureMessage(sandboxId, status, options) {
   const prefix = status === "terminated" /* TERMINATED */ ? `Sandbox ${sandboxId} terminated during startup` : `Sandbox ${sandboxId} became ${status} during startup`;
   const detail = formatErrorDetails(options.errorDetails);
@@ -4027,7 +4033,8 @@ var init_client = __esm({
        *
        * This call **returns immediately** with a `snapshotId` and `in_progress`
        * status — the snapshot is created asynchronously. Poll `getSnapshot()` until
-       * `completed` or `failed`, or use `snapshotAndWait()` to block automatically.
+       * `local_ready`, `completed`, or `failed`, or use `snapshotAndWait()` to
+       * block automatically.
        *
        * @param options.snapshotType - `"filesystem"` for cold-boot snapshots (e.g. image builds).
        *   Omit to use the server default (`filesystem`).
@@ -4068,9 +4075,11 @@ var init_client = __esm({
         );
       }
       /**
-       * Create a snapshot and block until it is committed.
+       * Create a snapshot and block until it is locally ready.
        *
-       * Combines `snapshot()` with polling `getSnapshot()` until `completed`.
+       * Combines `snapshot()` with polling `getSnapshot()` until `local_ready`
+       * or `completed`. Pass `{ waitUntil: "completed" }` when durable
+       * `snapshotUri` metadata is required.
        * Prefer `sandbox.checkpoint()` on a `Sandbox` handle for the same behavior
        * without managing the client separately.
        *
@@ -4083,13 +4092,14 @@ var init_client = __esm({
       async snapshotAndWait(sandboxId, options) {
         const timeout = options?.timeout ?? 300;
         const pollInterval = options?.pollInterval ?? 1;
+        const waitUntil = options?.waitUntil ?? "local_ready";
         const result = await this.snapshot(sandboxId, {
           snapshotType: options?.snapshotType
         });
         const deadline = Date.now() + timeout * 1e3;
         while (Date.now() < deadline) {
           const info = await this.getSnapshot(result.snapshotId);
-          if (info.status === "completed" /* COMPLETED */) return info;
+          if (snapshotStatusSatisfiesWaitCondition(info.status, waitUntil)) return info;
           if (info.status === "failed" /* FAILED */) {
             throw new SandboxError(
               `Snapshot ${result.snapshotId} failed: ${info.error}`
@@ -4098,7 +4108,7 @@ var init_client = __esm({
           await sleep2(pollInterval * 1e3);
         }
         throw new SandboxError(
-          `Snapshot ${result.snapshotId} did not complete within ${timeout}s`
+          `Snapshot ${result.snapshotId} did not reach ${waitUntil} within ${timeout}s`
         );
       }
       // --- Pools ---
@@ -4283,6 +4293,7 @@ var init_image = __esm({
 
 // src/sandbox-image.ts
 import { readFile, readdir, stat } from "fs/promises";
+import { homedir } from "os";
 import path from "path";
 import { parseArgs } from "util";
 function defaultRegisteredName(dockerfilePath) {
@@ -4413,12 +4424,6 @@ function shellSplit(input) {
   }
   return tokens;
 }
-function shellQuote(value) {
-  if (!value) {
-    return "''";
-  }
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
 function stripLeadingFlags(value) {
   const flags = {};
   let remaining = value.trimStart();
@@ -4456,75 +4461,6 @@ function parseFromValue(value, lineNumber) {
   }
   return tokens[0];
 }
-function parseCopyLikeValues(value, lineNumber, keyword) {
-  const { flags, remaining } = stripLeadingFlags(value);
-  if ("from" in flags) {
-    throw new Error(
-      `line ${lineNumber}: ${keyword} --from is not supported for sandbox image creation`
-    );
-  }
-  const payload = remaining.trim();
-  if (!payload) {
-    throw new Error(
-      `line ${lineNumber}: ${keyword} must include source and destination`
-    );
-  }
-  let parts;
-  if (payload.startsWith("[")) {
-    let parsed;
-    try {
-      parsed = JSON.parse(payload);
-    } catch (error) {
-      throw new Error(
-        `line ${lineNumber}: invalid JSON array syntax for ${keyword}: ${error.message}`
-      );
-    }
-    if (!Array.isArray(parsed) || parsed.length < 2 || parsed.some((item) => typeof item !== "string")) {
-      throw new Error(
-        `line ${lineNumber}: ${keyword} JSON array form requires at least two string values`
-      );
-    }
-    parts = parsed;
-  } else {
-    parts = shellSplit(payload);
-    if (parts.length < 2) {
-      throw new Error(
-        `line ${lineNumber}: ${keyword} must include at least one source and one destination`
-      );
-    }
-  }
-  return {
-    flags,
-    sources: parts.slice(0, -1),
-    destination: parts[parts.length - 1]
-  };
-}
-function parseEnvPairs(value, lineNumber) {
-  const tokens = shellSplit(value);
-  if (tokens.length === 0) {
-    throw new Error(`line ${lineNumber}: ENV must include a key and value`);
-  }
-  if (tokens.every((token) => token.includes("="))) {
-    return tokens.map((token) => {
-      const [key, envValue] = token.split(/=(.*)/s, 2);
-      if (!key) {
-        throw new Error(`line ${lineNumber}: invalid ENV token '${token}'`);
-      }
-      return [key, envValue];
-    });
-  }
-  if (tokens.length < 2) {
-    throw new Error(`line ${lineNumber}: ENV must include a key and value`);
-  }
-  return [[tokens[0], tokens.slice(1).join(" ")]];
-}
-function resolveContainerPath(containerPath, workingDir) {
-  if (!containerPath) {
-    return workingDir;
-  }
-  const normalized = containerPath.startsWith("/") ? path.posix.normalize(containerPath) : path.posix.normalize(path.posix.join(workingDir, containerPath));
-  return normalized.startsWith("/") ? normalized : `/${normalized}`;
-}
 function buildPlanFromDockerfileText(dockerfileText, dockerfilePath, contextDir, registeredName) {
   let baseImage;
   const instructions = [];
@@ -4635,14 +4571,292 @@ function buildContextFromEnv() {
   };
 }
 function createDefaultClient(context) {
+  const useScopeHeaders = context.personalAccessToken != null && context.apiKey == null;
   return new SandboxClient({
     apiUrl: context.apiUrl,
     apiKey: context.apiKey ?? context.personalAccessToken,
-    organizationId: context.organizationId,
-    projectId: context.projectId,
+    organizationId: useScopeHeaders ? context.organizationId : void 0,
+    projectId: useScopeHeaders ? context.projectId : void 0,
     namespace: context.namespace
   });
 }
+function baseApiUrl(context) {
+  return context.apiUrl.replace(/\/+$/, "");
+}
+function scopedBuildsPath(context) {
+  return `/platform/v1/organizations/${encodeURIComponent(context.organizationId)}/projects/${encodeURIComponent(context.projectId)}/sandbox-template-builds`;
+}
+function platformHeaders(context) {
+  const headers = {
+    Authorization: `Bearer ${context.bearerToken}`,
+    "Content-Type": "application/json"
+  };
+  if (context.useScopeHeaders) {
+    headers["X-Forwarded-Organization-Id"] = context.organizationId;
+    headers["X-Forwarded-Project-Id"] = context.projectId;
+  }
+  return headers;
+}
+async function requestJson(url, init, errorPrefix) {
+  const response = await fetch(url, init);
+  if (!response.ok) {
+    throw new Error(
+      `${errorPrefix} (HTTP ${response.status}): ${await response.text()}`
+    );
+  }
+  const text = await response.text();
+  return text ? JSON.parse(text) : {};
+}
+async function resolveBuildContext(context) {
+  const bearerToken = context.apiKey ?? context.personalAccessToken;
+  if (!bearerToken) {
+    throw new Error("Missing TENSORLAKE_API_KEY or TENSORLAKE_PAT.");
+  }
+  if (context.apiKey) {
+    const scope = await requestJson(
+      `${baseApiUrl(context)}/platform/v1/keys/introspect`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${bearerToken}`,
+          "Content-Type": "application/json"
+        }
+      },
+      "API key introspection failed"
+    );
+    if (!scope.organizationId || !scope.projectId) {
+      throw new Error("API key introspection response is missing organizationId or projectId");
+    }
+    return {
+      ...context,
+      bearerToken,
+      organizationId: scope.organizationId,
+      projectId: scope.projectId,
+      useScopeHeaders: false
+    };
+  }
+  if (!context.organizationId || !context.projectId) {
+    throw new Error(
+      "Personal Access Token authentication requires TENSORLAKE_ORGANIZATION_ID and TENSORLAKE_PROJECT_ID to be set (e.g. via 'tl login && tl init'). To skip this requirement, authenticate with TENSORLAKE_API_KEY instead \u2014 API keys are bound to a single project at creation."
+    );
+  }
+  return {
+    ...context,
+    bearerToken,
+    organizationId: context.organizationId,
+    projectId: context.projectId,
+    useScopeHeaders: true
+  };
+}
+async function prepareRootfsBuild(context, plan, isPublic) {
+  if (!plan.baseImage) {
+    throw new Error("Sandbox image builds require a Dockerfile FROM image or Image baseImage");
+  }
+  const spec = await requestJson(
+    `${baseApiUrl(context)}${scopedBuildsPath(context)}`,
+    {
+      method: "POST",
+      headers: platformHeaders(context),
+      body: JSON.stringify({
+        name: plan.registeredName,
+        dockerfile: plan.dockerfileText,
+        baseImage: plan.baseImage,
+        public: isPublic
+      })
+    },
+    "failed to prepare sandbox image build"
+  );
+  return { prepared: parsePreparedBuild(spec), spec };
+}
+function parsePreparedBuild(raw) {
+  const builder = raw.builder;
+  if (!builder) {
+    throw new Error("platform API response is missing rootfs builder configuration");
+  }
+  const prepared = {
+    ...raw,
+    buildId: requiredString(raw, "buildId"),
+    snapshotId: requiredString(raw, "snapshotId"),
+    snapshotUri: requiredString(raw, "snapshotUri"),
+    rootfsNodeKind: requiredString(raw, "rootfsNodeKind"),
+    builder: {
+      image: requiredString(builder, "image"),
+      command: requiredString(builder, "command"),
+      cpus: requiredNumber(builder, "cpus"),
+      memoryMb: requiredNumber(builder, "memoryMb"),
+      diskMb: requiredNumber(builder, "diskMb")
+    }
+  };
+  const parent = raw.parent;
+  if (parent != null) {
+    prepared.parent = {
+      parentManifestUri: requiredString(parent, "parentManifestUri"),
+      rootfsDiskBytes: optionalNumber(parent, "rootfsDiskBytes")
+    };
+  }
+  return prepared;
+}
+async function completeRootfsBuild(context, buildId, request) {
+  return requestJson(
+    `${baseApiUrl(context)}${scopedBuildsPath(context)}/${encodeURIComponent(buildId)}/complete`,
+    {
+      method: "POST",
+      headers: platformHeaders(context),
+      body: JSON.stringify(request)
+    },
+    "failed to complete sandbox image build"
+  );
+}
+async function resolvedDockerConfigJson() {
+  const configDir = process.env.DOCKER_CONFIG ?? path.join(homedir(), ".docker");
+  const configPath = path.join(configDir, "config.json");
+  try {
+    const content = await readFile(configPath, "utf8");
+    const parsed = JSON.parse(content);
+    const auths = parsed.auths;
+    if (auths != null && Object.keys(auths).length > 0) {
+      return JSON.stringify({ auths });
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+  return void 0;
+}
+function rootfsDiskBytes(diskMb, prepared) {
+  if (diskMb != null) {
+    return diskMb * 1024 * 1024;
+  }
+  if (prepared.parent != null) {
+    if (prepared.parent.rootfsDiskBytes == null) {
+      throw new Error(
+        "platform API did not return parent rootfsDiskBytes for diff build; pass diskMb explicitly or update Platform API"
+      );
+    }
+    return prepared.parent.rootfsDiskBytes;
+  }
+  return DEFAULT_ROOTFS_DISK_MB * 1024 * 1024;
+}
+function rootfsDiskBytesToMb(bytes) {
+  return Math.ceil(bytes / (1024 * 1024));
+}
+async function buildRootfsSpec(preparedSpec, prepared, plan, diskMb) {
+  const spec = {
+    ...preparedSpec,
+    dockerfile: plan.dockerfileText,
+    contextDir: REMOTE_CONTEXT_DIR,
+    baseImage: plan.baseImage,
+    rootfsDiskBytes: rootfsDiskBytes(diskMb, prepared)
+  };
+  const dockerConfigJson = await resolvedDockerConfigJson();
+  if (dockerConfigJson != null) {
+    spec.dockerConfigJson = dockerConfigJson;
+  }
+  return spec;
+}
+function rootfsBuilderExecutable(executable) {
+  return executable === ROOTFS_BUILDER_COMMAND ? `${ROOTFS_BUILDER_BIN_DIR}/${ROOTFS_BUILDER_COMMAND}` : executable;
+}
+function rootfsBuilderEnv() {
+  return { PATH: ROOTFS_BUILDER_PATH };
+}
+async function runRootfsBuilder(sandbox, command, emit, sleep3) {
+  const parts = shellSplit(command);
+  const [executable, ...commandArgs] = parts;
+  if (!executable) {
+    throw new Error("empty rootfs builder command returned by platform API");
+  }
+  await runStreaming(
+    sandbox,
+    emit,
+    sleep3,
+    rootfsBuilderExecutable(executable),
+    [...commandArgs, "--spec", REMOTE_SPEC_PATH, "--metadata-out", REMOTE_METADATA_PATH],
+    rootfsBuilderEnv(),
+    REMOTE_BUILD_DIR
+  );
+}
+function metadataString(metadata, snakeKey, camelKey) {
+  const value = metadata[snakeKey] ?? metadata[camelKey];
+  return typeof value === "string" ? value : void 0;
+}
+function metadataNumber(metadata, snakeKey, camelKey) {
+  const value = metadata[snakeKey] ?? metadata[camelKey];
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : void 0;
+  }
+  return void 0;
+}
+function completeRequestFromMetadata(prepared, metadata) {
+  const rootfsNodeKind = metadataString(metadata, "rootfs_node_kind", "rootfsNodeKind") ?? prepared.rootfsNodeKind;
+  const parentManifestUri = metadataString(metadata, "parent_manifest_uri", "parentManifestUri") ?? (rootfsNodeKind === "diff" ? prepared.parent?.parentManifestUri : void 0);
+  if (rootfsNodeKind === "diff" && parentManifestUri == null) {
+    throw new Error("rootfs diff build completed without parent_manifest_uri");
+  }
+  const snapshotFormatVersion = metadataString(
+    metadata,
+    "snapshot_format_version",
+    "snapshotFormatVersion"
+  );
+  const snapshotSizeBytes = metadataNumber(
+    metadata,
+    "snapshot_size_bytes",
+    "snapshotSizeBytes"
+  );
+  const rootfsDiskBytesValue = metadataNumber(
+    metadata,
+    "rootfs_disk_bytes",
+    "rootfsDiskBytes"
+  );
+  if (!snapshotFormatVersion) {
+    throw new Error("rootfs builder metadata is missing snapshot_format_version");
+  }
+  if (snapshotSizeBytes == null) {
+    throw new Error("rootfs builder metadata is missing numeric snapshot_size_bytes");
+  }
+  if (rootfsDiskBytesValue == null) {
+    throw new Error("rootfs builder metadata is missing numeric rootfs_disk_bytes");
+  }
+  return {
+    snapshotId: metadataString(metadata, "snapshot_id", "snapshotId") ?? prepared.snapshotId,
+    snapshotUri: metadataString(metadata, "snapshot_uri", "snapshotUri") ?? prepared.snapshotUri,
+    snapshotFormatVersion,
+    snapshotSizeBytes,
+    rootfsDiskBytes: rootfsDiskBytesValue,
+    rootfsNodeKind,
+    ...parentManifestUri ? { parentManifestUri } : {}
+  };
+}
+function requiredString(object, key) {
+  const value = object[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`expected '${key}' to be a non-empty string`);
+  }
+  return value;
+}
+function requiredNumber(object, key) {
+  const value = object[key];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`expected '${key}' to be a finite number`);
+  }
+  return value;
+}
+function optionalNumber(object, key) {
+  const value = object[key];
+  if (value == null) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`expected '${key}' to be a finite number`);
+  }
+  return value;
+}
 async function runChecked(sandbox, command, args, env, workingDir) {
   const result = await sandbox.run(command, {
     args,
@@ -4702,18 +4916,6 @@ function emitOutputLines(emit, stream, response, seen) {
     emit({ type: "build_log", stream, message: line });
   }
 }
-function isPathWithinContext(contextDir, localPath) {
-  const relative = path.relative(contextDir, localPath);
-  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
-}
-function resolveContextSourcePath(contextDir, source) {
-  const resolvedContextDir = path.resolve(contextDir);
-  const resolvedSource = path.resolve(resolvedContextDir, source);
-  if (!isPathWithinContext(resolvedContextDir, resolvedSource)) {
-    throw new Error(`Local path escapes the build context: ${source}`);
-  }
-  return resolvedSource;
-}
 async function copyLocalPathToSandbox(sandbox, localPath, remotePath) {
   const fileStats = await stat(localPath).catch(() => null);
   if (!fileStats) {
@@ -4744,184 +4946,26 @@ async function copyLocalPathToSandbox(sandbox, localPath, remotePath) {
     }
   }
 }
-async function persistEnvVar(sandbox, processEnv, key, value) {
-  const exportLine = `export ${key}=${shellQuote(value)}`;
-  await runChecked(
-    sandbox,
-    "sh",
-    ["-c", `printf '%s\\n' ${shellQuote(exportLine)} >> /etc/environment`],
-    processEnv
-  );
-}
-async function copyFromContext(sandbox, emit, contextDir, sources, destination, workingDir, keyword) {
-  const destinationPath = resolveContainerPath(destination, workingDir);
-  if (sources.length > 1 && !destinationPath.endsWith("/")) {
-    throw new Error(
-      `${keyword} with multiple sources requires a directory destination ending in '/'`
-    );
-  }
-  for (const source of sources) {
-    const localSource = resolveContextSourcePath(contextDir, source);
-    const localStats = await stat(localSource).catch(() => null);
-    if (!localStats) {
-      throw new Error(`Local path not found: ${localSource}`);
-    }
-    let remoteDestination = destinationPath;
-    if (sources.length > 1) {
-      remoteDestination = path.posix.join(
-        destinationPath.replace(/\/$/, ""),
-        path.posix.basename(source.replace(/\/$/, ""))
-      );
-    } else if (localStats.isFile() && destinationPath.endsWith("/")) {
-      remoteDestination = path.posix.join(
-        destinationPath.replace(/\/$/, ""),
-        path.basename(source)
-      );
-    }
-    emit({
-      type: "status",
-      message: `${keyword} ${source} -> ${remoteDestination}`
-    });
-    await copyLocalPathToSandbox(sandbox, localSource, remoteDestination);
-  }
-}
-async function addUrlToSandbox(sandbox, emit, url, destination, workingDir, processEnv, sleep3) {
-  let destinationPath = resolveContainerPath(destination, workingDir);
-  const parsedUrl = new URL(url);
-  const fileName = path.posix.basename(parsedUrl.pathname.replace(/\/$/, "")) || "downloaded";
-  if (destinationPath.endsWith("/")) {
-    destinationPath = path.posix.join(destinationPath.replace(/\/$/, ""), fileName);
-  }
-  const parentDir = path.posix.dirname(destinationPath) || "/";
-  emit({
-    type: "status",
-    message: `ADD ${url} -> ${destinationPath}`
-  });
-  await runChecked(sandbox, "mkdir", ["-p", parentDir], processEnv);
-  await runStreaming(
-    sandbox,
-    emit,
-    sleep3,
-    "sh",
-    [
-      "-c",
-      `curl -fsSL --location ${shellQuote(url)} -o ${shellQuote(destinationPath)}`
-    ],
-    processEnv,
-    workingDir
-  );
-}
-async function executeDockerfilePlan(sandbox, plan, emit, sleep3) {
-  const processEnv = { ...BUILD_SANDBOX_PIP_ENV };
-  let workingDir = "/";
-  for (const instruction of plan.instructions) {
-    const { keyword, value, lineNumber } = instruction;
-    if (keyword === "RUN") {
-      emit({ type: "status", message: `RUN ${value}` });
-      await runStreaming(
-        sandbox,
-        emit,
-        sleep3,
-        "sh",
-        ["-c", value],
-        processEnv,
-        workingDir
-      );
-      continue;
-    }
-    if (keyword === "WORKDIR") {
-      const tokens = shellSplit(value);
-      if (tokens.length !== 1) {
-        throw new Error(`line ${lineNumber}: WORKDIR must include exactly one path`);
-      }
-      workingDir = resolveContainerPath(tokens[0], workingDir);
-      emit({ type: "status", message: `WORKDIR ${workingDir}` });
-      await runChecked(sandbox, "mkdir", ["-p", workingDir], processEnv);
-      continue;
-    }
-    if (keyword === "ENV") {
-      for (const [key, envValue] of parseEnvPairs(value, lineNumber)) {
-        emit({ type: "status", message: `ENV ${key}=${envValue}` });
-        processEnv[key] = envValue;
-        await persistEnvVar(sandbox, processEnv, key, envValue);
-      }
-      continue;
-    }
-    if (keyword === "COPY") {
-      const { sources, destination } = parseCopyLikeValues(
-        value,
-        lineNumber,
-        keyword
-      );
-      await copyFromContext(
-        sandbox,
-        emit,
-        plan.contextDir,
-        sources,
-        destination,
-        workingDir,
-        keyword
-      );
-      continue;
-    }
-    if (keyword === "ADD") {
-      const { sources, destination } = parseCopyLikeValues(
-        value,
-        lineNumber,
-        keyword
-      );
-      if (sources.length === 1 && /^https?:\/\//.test(sources[0])) {
-        await addUrlToSandbox(
-          sandbox,
-          emit,
-          sources[0],
-          destination,
-          workingDir,
-          processEnv,
-          sleep3
-        );
-      } else {
-        await copyFromContext(
-          sandbox,
-          emit,
-          plan.contextDir,
-          sources,
-          destination,
-          workingDir,
-          keyword
-        );
-      }
-      continue;
-    }
-    if (IGNORED_DOCKERFILE_INSTRUCTIONS.has(keyword)) {
-      emit({
-        type: "warning",
-        message: `Skipping Dockerfile instruction '${keyword}' during snapshot materialization. It is still preserved in the registered Dockerfile.`
-      });
-      continue;
-    }
-    throw new Error(
-      `line ${lineNumber}: Dockerfile instruction '${keyword}' is not supported for sandbox image creation`
-    );
-  }
-}
-async function registerImage(context, name, dockerfile, snapshotId, snapshotSandboxId, snapshotUri, snapshotSizeBytes, rootfsDiskBytes, isPublic) {
-  if (!context.organizationId || !context.projectId) {
-    throw new Error(
-      "Organization ID and Project ID are required. Run 'tl login' and 'tl init'."
-    );
-  }
+async function registerImage(context, name, dockerfile, snapshotId, snapshotSandboxId, snapshotUri, snapshotSizeBytes, rootfsDiskBytes2, isPublic, snapshotFormatVersion) {
   const bearerToken = context.apiKey ?? context.personalAccessToken;
   if (!bearerToken) {
     throw new Error("Missing TENSORLAKE_API_KEY or TENSORLAKE_PAT.");
   }
   const baseUrl = context.apiUrl.replace(/\/+$/, "");
-  const url = `${baseUrl}/platform/v1/organizations/${encodeURIComponent(context.organizationId)}/projects/${encodeURIComponent(context.projectId)}/sandbox-templates`;
   const headers = {
     Authorization: `Bearer ${bearerToken}`,
     "Content-Type": "application/json"
   };
-  if (context.personalAccessToken && !context.apiKey) {
+  let url;
+  if (context.apiKey) {
+    url = `${baseUrl}/platform/v1/sandbox-templates`;
+  } else {
+    if (!context.organizationId || !context.projectId) {
+      throw new Error(
+        "Personal Access Token authentication requires TENSORLAKE_ORGANIZATION_ID and TENSORLAKE_PROJECT_ID to be set (e.g. via 'tl login && tl init'). To skip this requirement, authenticate with TENSORLAKE_API_KEY instead \u2014 API keys are bound to a single project at creation."
+      );
+    }
+    url = `${baseUrl}/platform/v1/organizations/${encodeURIComponent(context.organizationId)}/projects/${encodeURIComponent(context.projectId)}/sandbox-templates`;
     headers["X-Forwarded-Organization-Id"] = context.organizationId;
     headers["X-Forwarded-Project-Id"] = context.projectId;
   }
@@ -4934,8 +4978,9 @@ async function registerImage(context, name, dockerfile, snapshotId, snapshotSand
       snapshotId,
       snapshotSandboxId,
       snapshotUri,
+      ...snapshotFormatVersion ? { snapshotFormatVersion } : {},
       snapshotSizeBytes,
-      rootfsDiskBytes,
+      rootfsDiskBytes: rootfsDiskBytes2,
       public: isPublic
     })
   });
@@ -4952,65 +4997,71 @@ async function createSandboxImage(source, options = {}, deps = {}) {
   const sleep3 = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const context = buildContextFromEnv();
   const clientFactory = deps.createClient ?? createDefaultClient;
-  const register = deps.registerImage ?? ((...args) => registerImage(...args));
   const sourceLabel = typeof source === "string" ? source : `Image(${source.name})`;
   emit({ type: "status", message: `Loading ${sourceLabel}...` });
   const plan = typeof source === "string" ? await loadDockerfilePlan(source, options.registeredName) : loadImagePlan(source, options);
   emit({
     type: "status",
-    message: plan.baseImage == null ? "Starting build sandbox with the default server image..." : `Starting build sandbox from ${plan.baseImage}...`
+    message: `Selected image name: ${plan.registeredName}`
+  });
+  emit({ type: "status", message: "Preparing rootfs build..." });
+  const resolvedContext = await resolveBuildContext(context);
+  const { prepared, spec: preparedSpec } = await prepareRootfsBuild(
+    resolvedContext,
+    plan,
+    options.isPublic ?? false
+  );
+  emit({
+    type: "status",
+    message: prepared.rootfsNodeKind === "diff" ? "Build mode: RootfsDiff" : "Build mode: RootfsBase"
   });
   const client = clientFactory(context);
   let sandbox;
   try {
-    sandbox = await client.createAndConnect({
-      ...plan.baseImage == null ? {} : { image: plan.baseImage },
-      cpus: options.cpus ?? 2,
-      memoryMb: options.memoryMb ?? 4096,
-      ...options.diskMb != null ? { diskMb: options.diskMb } : {}
-    });
+    const outputRootfsDiskBytes = rootfsDiskBytes(options.diskMb, prepared);
+    const builderDiskMb = Math.max(
+      rootfsDiskBytesToMb(outputRootfsDiskBytes),
+      options.builderDiskMb ?? prepared.builder.diskMb
+    );
     emit({
       type: "status",
-      message: `Materializing image in sandbox ${sandbox.sandboxId}...`
+      message: `Creating rootfs builder sandbox from ${prepared.builder.image}...`
     });
-    await executeDockerfilePlan(sandbox, plan, emit, sleep3);
-    emit({ type: "status", message: "Creating snapshot..." });
-    const snapshot = await client.snapshotAndWait(sandbox.sandboxId, {
-      snapshotType: "filesystem"
-    });
-    emit({
-      type: "snapshot_created",
-      snapshot_id: snapshot.snapshotId
+    sandbox = await client.createAndConnect({
+      image: prepared.builder.image,
+      cpus: options.cpus ?? prepared.builder.cpus,
+      memoryMb: options.memoryMb ?? prepared.builder.memoryMb,
+      diskMb: builderDiskMb
     });
-    if (!snapshot.snapshotUri) {
-      throw new Error(
-        `Snapshot ${snapshot.snapshotId} is missing snapshotUri and cannot be registered as a sandbox image.`
-      );
-    }
-    if (snapshot.sizeBytes == null) {
-      throw new Error(
-        `Snapshot ${snapshot.snapshotId} is missing sizeBytes and cannot be registered as a sandbox image.`
-      );
-    }
-    if (snapshot.rootfsDiskBytes == null) {
-      throw new Error(
-        `Snapshot ${snapshot.snapshotId} is missing rootfsDiskBytes and cannot be registered as a sandbox image.`
-      );
-    }
     emit({
       type: "status",
-      message: `Registering image '${plan.registeredName}'...`
+      message: `Rootfs builder sandbox ${sandbox.sandboxId} is running`
     });
-    const result = await register(
-      context,
-      plan.registeredName,
-      plan.dockerfileText,
-      snapshot.snapshotId,
-      snapshot.sandboxId,
-      snapshot.snapshotUri,
-      snapshot.sizeBytes,
-      snapshot.rootfsDiskBytes,
-      options.isPublic ?? false
+    emit({ type: "status", message: "Uploading build context..." });
+    await copyLocalPathToSandbox(sandbox, plan.contextDir, REMOTE_CONTEXT_DIR);
+    const spec = await buildRootfsSpec(
+      preparedSpec,
+      prepared,
+      plan,
+      options.diskMb
+    );
+    await runChecked(sandbox, "mkdir", ["-p", path.posix.dirname(REMOTE_SPEC_PATH)]);
+    await sandbox.writeFile(
+      REMOTE_SPEC_PATH,
+      new TextEncoder().encode(JSON.stringify(spec, null, 2))
+    );
+    emit({ type: "status", message: "Running offline rootfs builder..." });
+    await runRootfsBuilder(sandbox, prepared.builder.command, emit, sleep3);
+    const metadataBytes = await sandbox.readFile(REMOTE_METADATA_PATH);
+    const metadata = JSON.parse(
+      new TextDecoder().decode(metadataBytes)
+    );
+    const completeRequest = completeRequestFromMetadata(prepared, metadata);
+    emit({ type: "status", message: "Completing image registration..." });
+    const result = await completeRootfsBuild(
+      resolvedContext,
+      prepared.buildId,
+      completeRequest
     );
     emit({
       type: "image_registered",
@@ -5038,16 +5089,18 @@ async function runCreateSandboxImageCli(argv = process.argv.slice(2)) {
       cpus: { type: "string" },
       memory: { type: "string" },
       disk_mb: { type: "string" },
+      builder_disk_mb: { type: "string" },
       public: { type: "boolean", default: false }
     }
   });
   const dockerfilePath = parsed.positionals[0];
   if (!dockerfilePath) {
-    throw new Error("Usage: tensorlake-create-sandbox-image <dockerfile_path> [--name NAME] [--cpus N] [--memory MB] [--disk_mb MB] [--public]");
+    throw new Error("Usage: tensorlake-create-sandbox-image <dockerfile_path> [--name NAME] [--cpus N] [--memory MB] [--disk_mb MB] [--builder_disk_mb MB] [--public]");
   }
   const cpus = parsed.values.cpus != null ? Number(parsed.values.cpus) : void 0;
   const memoryMb = parsed.values.memory != null ? Number(parsed.values.memory) : void 0;
   const diskMb = parsed.values.disk_mb != null ? Number(parsed.values.disk_mb) : void 0;
+  const builderDiskMb = parsed.values.builder_disk_mb != null ? Number(parsed.values.builder_disk_mb) : void 0;
   if (cpus != null && !Number.isFinite(cpus)) {
     throw new Error(`Invalid --cpus value: ${parsed.values.cpus}`);
   }
@@ -5057,6 +5110,11 @@ async function runCreateSandboxImageCli(argv = process.argv.slice(2)) {
   if (diskMb != null && !Number.isInteger(diskMb)) {
     throw new Error(`Invalid --disk_mb value: ${parsed.values.disk_mb}`);
   }
+  if (builderDiskMb != null && !Number.isInteger(builderDiskMb)) {
+    throw new Error(
+      `Invalid --builder_disk_mb value: ${parsed.values.builder_disk_mb}`
+    );
+  }
   await createSandboxImage(
     dockerfilePath,
     {
@@ -5064,27 +5122,26 @@ async function runCreateSandboxImageCli(argv = process.argv.slice(2)) {
       cpus,
       memoryMb,
       diskMb,
+      builderDiskMb,
       isPublic: parsed.values.public
     },
     { emit: ndjsonStdoutEmit }
   );
 }
-var BUILD_SANDBOX_PIP_ENV, IGNORED_DOCKERFILE_INSTRUCTIONS, UNSUPPORTED_DOCKERFILE_INSTRUCTIONS;
+var DEFAULT_ROOTFS_DISK_MB, REMOTE_BUILD_DIR, REMOTE_CONTEXT_DIR, REMOTE_SPEC_PATH, REMOTE_METADATA_PATH, ROOTFS_BUILDER_BIN_DIR, ROOTFS_BUILDER_PATH, ROOTFS_BUILDER_COMMAND, UNSUPPORTED_DOCKERFILE_INSTRUCTIONS;
 var init_sandbox_image = __esm({
   "src/sandbox-image.ts"() {
     init_models();
     init_client();
     init_image();
-    BUILD_SANDBOX_PIP_ENV = { PIP_BREAK_SYSTEM_PACKAGES: "1" };
-    IGNORED_DOCKERFILE_INSTRUCTIONS = /* @__PURE__ */ new Set([
-      "CMD",
-      "ENTRYPOINT",
-      "EXPOSE",
-      "HEALTHCHECK",
-      "LABEL",
-      "STOPSIGNAL",
-      "VOLUME"
-    ]);
+    DEFAULT_ROOTFS_DISK_MB = 10 * 1024;
+    REMOTE_BUILD_DIR = "/var/lib/tensorlake/rootfs-builder/build";
+    REMOTE_CONTEXT_DIR = "/var/lib/tensorlake/rootfs-builder/build/context";
+    REMOTE_SPEC_PATH = "/var/lib/tensorlake/rootfs-builder/build/spec.json";
+    REMOTE_METADATA_PATH = "/var/lib/tensorlake/rootfs-builder/build/metadata.json";
+    ROOTFS_BUILDER_BIN_DIR = "/usr/local/bin";
+    ROOTFS_BUILDER_PATH = "/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+    ROOTFS_BUILDER_COMMAND = "tl-rootfs-build";
     UNSUPPORTED_DOCKERFILE_INSTRUCTIONS = /* @__PURE__ */ new Set([
       "ARG",
       "ONBUILD",
@@ -5100,6 +5157,7 @@ export {
   loadDockerfilePlan,
   loadImagePlan,
   logicalDockerfileLines,
+  registerImage,
   runCreateSandboxImageCli
 };
 //# sourceMappingURL=sandbox-image.js.map