@shadowob/cloud 1.1.7 → 1.1.8

package/dist/cli.js

@@ -1,23 +1,17 @@
 #!/usr/bin/env node
-import {
-  createConsoleCommand
-} from "./chunk-KODMGZUC.js";
-import {
-  createInitCommand
-} from "./chunk-SAP2DBHO.js";
-import {
-  formatProvisionState,
-  loadProvisionState,
-  mergeProvisionState,
-  saveProvisionState
-} from "./chunk-RTPBU5HF.js";
 import {
   createServeCommand,
   detectInlineKey,
   resolveCloudPackageAssetDir,
   toProviderSecretEnvKey,
   withLegacyEnvAliases
-} from "./chunk-LXJBQBGL.js";
+} from "./chunk-X5VOIA72.js";
+import {
+  createConsoleCommand
+} from "./chunk-4YO3NA26.js";
+import {
+  createInitCommand
+} from "./chunk-Y6BKVDG7.js";
 import {
   RUNNER_AGENTS_VOLUME_NAME,
   RUNNER_CONFIG_MOUNT_PATH,
@@ -29,6 +23,7 @@ import {
   SHADOW_SLASH_COMMANDS_PATH,
   buildOpenClawConfig,
   collectPluginBuildEnvVars,
+  collectPluginRuntimeEnvOmitKeys,
   collectPluginRuntimeExtensions,
   collectRuntimeEnvRefPolicy,
   collectTemplateRefs,
@@ -43,11 +38,17 @@ import {
   resolveConfig,
   runtimeContextEnv,
   runtimeStatePvcName
-} from "./chunk-35LJYCQF.js";
+} from "./chunk-3CT6RQNM.js";
 import {
   deepMerge,
   getPluginRegistry
-} from "./chunk-6P2K6QZR.js";
+} from "./chunk-ZGMWSSCC.js";
+import {
+  formatProvisionState,
+  loadProvisionState,
+  mergeProvisionState,
+  saveProvisionState
+} from "./chunk-RTPBU5HF.js";
 import {
   log
 } from "./chunk-BF6CV2Y4.js";
@@ -89,6 +90,45 @@ import { join, resolve as resolve2 } from "path";
 import { Command } from "commander";
 
 // src/infra/plugin-k8s.ts
+var COLON_SEPARATED_ENV_KEYS = /* @__PURE__ */ new Set(["PATH", "PYTHONPATH", "NODE_PATH"]);
+var DEFAULT_CONTAINER_PATH_PARTS = [
+  "/usr/local/sbin",
+  "/usr/local/bin",
+  "/usr/sbin",
+  "/usr/bin",
+  "/sbin",
+  "/bin"
+];
+function uniquePathParts(parts) {
+  const out = [];
+  for (const part of parts) {
+    if (!part || out.includes(part)) continue;
+    out.push(part);
+  }
+  return out;
+}
+function mergeColonSeparatedEnvValue(key, current, next) {
+  const parts = [...current.split(":"), ...next.split(":")];
+  if (key !== "PATH") return uniquePathParts(parts).join(":");
+  const defaults = new Set(DEFAULT_CONTAINER_PATH_PARTS);
+  const pluginParts = parts.filter((part) => part && !defaults.has(part));
+  const defaultParts = parts.filter((part) => defaults.has(part));
+  return uniquePathParts([...pluginParts, ...defaultParts]).join(":");
+}
+function mergePluginEnvVars(target, incoming) {
+  for (const envVar of incoming) {
+    if (typeof envVar.name === "string" && typeof envVar.value === "string" && COLON_SEPARATED_ENV_KEYS.has(envVar.name)) {
+      const existing = target.find(
+        (candidate) => candidate.name === envVar.name && typeof candidate.value === "string"
+      );
+      if (existing && typeof existing.value === "string") {
+        existing.value = mergeColonSeparatedEnvValue(envVar.name, existing.value, envVar.value);
+        continue;
+      }
+    }
+    target.push(envVar);
+  }
+}
 function collectPluginK8sArtifacts(agent, config, namespace) {
   const result = {
     initContainers: [],
@@ -126,9 +166,7 @@ function collectPluginK8sArtifacts(agent, config, namespace) {
     if (artifacts.volumeMounts?.length) {
       result.volumeMounts.push(...artifacts.volumeMounts);
     }
-    if (artifacts.envVars?.length) {
-      result.envVars.push(...artifacts.envVars);
-    }
+    if (artifacts.envVars?.length) mergePluginEnvVars(result.envVars, artifacts.envVars);
     if (artifacts.labels) {
       Object.assign(result.labels, artifacts.labels);
     }
@@ -259,7 +297,7 @@ function getKubeconfigPath(clusterName) {
 function getMetaPath(clusterName) {
   return join2(getClustersDir(), `${clusterName}.json`);
 }
-function storeKubeconfig(clusterName, rawKubeconfig, masterPublicIp, nodeCount) {
+function storeKubeconfig(clusterName, rawKubeconfig, masterPublicIp, nodeCount, options) {
   const dir = getClustersDir();
   mkdirSync(dir, { recursive: true });
   const kubeconfig = rawKubeconfig.replace(/https?:\/\/127\.0\.0\.1/g, `https://${masterPublicIp}`);
@@ -270,7 +308,9 @@ function storeKubeconfig(clusterName, rawKubeconfig, masterPublicIp, nodeCount)
     masterHost: masterPublicIp,
     nodeCount,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    kubeconfigPath
+    kubeconfigPath,
+    ...options?.configHash ? { configHash: options.configHash } : {},
+    ...options?.features ? { features: options.features } : {}
   };
   writeFileSync2(getMetaPath(clusterName), JSON.stringify(meta, null, 2), { mode: 384 });
   return meta;
@@ -285,6 +325,15 @@ Run: shadowob-cloud cluster init --config cluster.json`
   }
   return path;
 }
+function loadClusterMeta(clusterName) {
+  const path = getMetaPath(clusterName);
+  if (!existsSync3(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
 function listRegisteredClusters() {
   const dir = getClustersDir();
   if (!existsSync3(dir)) return [];
@@ -330,22 +379,41 @@ import { resolve as resolve4 } from "path";
 
 // src/cluster/schema.ts
 import { z } from "zod";
-var NodeRoleSchema = z.enum(["master", "worker"]);
-var NodeConfigSchema = z.object({
-  /** Node role in the cluster */
-  role: NodeRoleSchema,
-  /** Public IP or hostname */
-  host: z.string().min(1),
-  /** SSH port (default: 22) */
-  port: z.number().int().min(1).max(65535).default(22),
-  /** SSH username */
-  user: z.string().min(1),
-  /** Path to SSH private key (supports ~) — mutually inclusive with or exclusive of password */
-  sshKeyPath: z.string().optional(),
-  /** SSH password — use ${env:VAR} to avoid storing plaintext */
-  password: z.string().optional()
-}).refine((n) => n.sshKeyPath !== void 0 || n.password !== void 0, {
-  message: "Each node must have either sshKeyPath or password"
+var K8S_LABEL_KEY_RE = /^([A-Za-z0-9][-A-Za-z0-9_.]*[A-Za-z0-9]\/)?[A-Za-z0-9]([-A-Za-z0-9_.]*[A-Za-z0-9])?$/;
+var K8S_LABEL_VALUE_RE = /^(([A-Za-z0-9][-A-Za-z0-9_.]*[A-Za-z0-9])?)$/;
+var KubernetesLabelMapSchema = z.record(
+  z.string().min(1).regex(K8S_LABEL_KEY_RE, "Invalid Kubernetes label key"),
+  z.string().max(63).regex(K8S_LABEL_VALUE_RE, "Invalid Kubernetes label value")
+);
+var ImageReferenceSchema = z.string().min(1).regex(/^\S+$/, "image must not contain whitespace");
+var ClusterContainerdRegistriesSchema = z.object({
+  /**
+   * k3s containerd mirrors. Written to /etc/rancher/k3s/registries.yaml as JSON/YAML.
+   * Example: { "docker.io": { "endpoint": ["https://registry-1.docker.io"] } }
+   */
+  mirrors: z.record(
+    z.string().min(1),
+    z.object({
+      endpoint: z.array(z.string().url()).min(1)
+    })
+  ).optional(),
+  configs: z.record(
+    z.string().min(1),
+    z.object({
+      auth: z.object({
+        username: z.string().optional(),
+        password: z.string().optional(),
+        auth: z.string().optional(),
+        identityToken: z.string().optional()
+      }).optional(),
+      tls: z.object({
+        caFile: z.string().optional(),
+        certFile: z.string().optional(),
+        keyFile: z.string().optional(),
+        insecureSkipVerify: z.boolean().optional()
+      }).optional()
+    })
+  ).optional()
 });
 var ClusterInstallConfigSchema = z.object({
   /** k3s release version. Example: v1.35.4+k3s1 */
@@ -361,7 +429,86 @@ var ClusterInstallConfigSchema = z.object({
   /** Registry prefix used by k3s for bundled system images. */
   systemDefaultRegistry: z.string().min(1).regex(/^\S+$/, "systemDefaultRegistry must not contain whitespace").optional(),
   /** Sandbox pause image used by k3s/containerd. Useful when Docker Hub is unreachable. */
-  pauseImage: z.string().min(1).regex(/^\S+$/, "pauseImage must not contain whitespace").optional()
+  pauseImage: z.string().min(1).regex(/^\S+$/, "pauseImage must not contain whitespace").optional(),
+  /** Optional k3s containerd registry mirrors/auth config for workload images. */
+  registries: ClusterContainerdRegistriesSchema.optional()
+});
+var AGENT_SANDBOX_DEFAULT_VERSION = "v0.4.5";
+var AGENT_SANDBOX_DEFAULT_RUNTIME_CLASS = "shadow-runc";
+var AGENT_SANDBOX_DEFAULT_RUNTIME_HANDLER = "runc";
+var RuntimeClassNameSchema = z.string().min(1).regex(/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/, "runtimeClassName must be a Kubernetes DNS label");
+var ClusterSandboxFeatureConfigSchema = z.object({
+  /** Enable agent-sandbox as a cluster capability. */
+  enabled: z.boolean().default(true),
+  /** Install/upgrade the upstream CRDs and controller during cluster init/apply. */
+  install: z.boolean().default(true),
+  /** Pinned upstream agent-sandbox release used to build default manifest URLs. */
+  version: z.string().min(1).regex(/^v\d+\.\d+\.\d+(?:[-+][A-Za-z0-9._-]+)?$/, "version must look like v0.4.5").default(AGENT_SANDBOX_DEFAULT_VERSION),
+  /**
+   * Optional manifest URLs. Defaults to the upstream release manifest.yaml and extensions.yaml.
+   * Use mirrored URLs for restricted networks.
+   */
+  manifestUrls: z.array(z.string().url()).min(1).optional(),
+  /** Optional controller image override, useful for domestic/private registries. */
+  controllerImage: ImageReferenceSchema.optional(),
+  /** RuntimeClass injected into generated Cloud SaaS sandbox configs. */
+  runtimeClassName: RuntimeClassNameSchema.default(AGENT_SANDBOX_DEFAULT_RUNTIME_CLASS),
+  /** Create RuntimeClass automatically. Disable when the cluster already provides gvisor/runsc. */
+  createRuntimeClass: z.boolean().default(true),
+  /** RuntimeClass handler used when createRuntimeClass is true. */
+  runtimeClassHandler: z.string().min(1).regex(/^\S+$/, "runtimeClassHandler must not contain whitespace").default(AGENT_SANDBOX_DEFAULT_RUNTIME_HANDLER),
+  /** Wait timeout for CRDs/controller readiness. */
+  waitTimeoutSeconds: z.number().int().min(30).max(1200).default(300),
+  /** Fail cluster init/apply when sandbox cannot be verified. */
+  required: z.boolean().default(true),
+  /** Label selector injected into sandbox workloads unless templates override it. */
+  nodeSelector: KubernetesLabelMapSchema.default({ "shadowob.com/sandbox-ready": "true" }),
+  /** Run a real SandboxTemplate/SandboxClaim smoke after install/verify. */
+  smokeTest: z.boolean().default(false),
+  /** Image used by the optional smoke test. Mirror this for restricted networks. */
+  smokeImage: ImageReferenceSchema.default("busybox:1.36")
+}).refine((sandbox) => !sandbox.createRuntimeClass || Boolean(sandbox.runtimeClassHandler), {
+  path: ["runtimeClassHandler"],
+  message: "runtimeClassHandler is required when createRuntimeClass is true"
+});
+var ClusterSandboxFeatureSchema = z.union([z.boolean(), ClusterSandboxFeatureConfigSchema]);
+var ClusterFeaturesSchema = z.object({
+  /** agent-sandbox CRDs/controller/runtime-class management. */
+  sandbox: ClusterSandboxFeatureSchema.optional()
+});
+var NodeRoleSchema = z.enum(["master", "worker"]);
+var NodeConfigSchema = z.object({
+  /** Node role in the cluster */
+  role: NodeRoleSchema,
+  /** Public IP or hostname */
+  host: z.string().min(1),
+  /** SSH port (default: 22) */
+  port: z.number().int().min(1).max(65535).default(22),
+  /** SSH username */
+  user: z.string().min(1),
+  /** Path to SSH private key (supports ~) — mutually inclusive with or exclusive of password */
+  sshKeyPath: z.string().optional(),
+  /** SSH private key passphrase — use ${env:VAR} to avoid storing plaintext */
+  sshKeyPassphrase: z.string().optional(),
+  /**
+   * SSH agent socket. Use true for SSH_AUTH_SOCK, or a socket path/template.
+   * Useful for encrypted private keys already loaded into an agent.
+   */
+  sshAgent: z.union([z.boolean(), z.string().min(1)]).optional(),
+  /** SSH password — use ${env:VAR} to avoid storing plaintext */
+  password: z.string().optional(),
+  /** Optional per-node k3s installer overrides for mixed-region clusters. */
+  install: ClusterInstallConfigSchema.optional(),
+  /** Region label applied during cluster init/apply, e.g. cn or us. */
+  region: z.string().min(1).max(63).regex(K8S_LABEL_VALUE_RE).optional(),
+  /** Extra Kubernetes node labels applied during cluster init/apply. */
+  labels: KubernetesLabelMapSchema.optional(),
+  /** Per-node feature flags used for mixed-capability clusters. */
+  features: z.object({
+    sandbox: z.boolean().optional()
+  }).optional()
+}).refine((n) => n.sshKeyPath !== void 0 || n.password !== void 0 || n.sshAgent, {
+  message: "Each node must have either sshKeyPath, password, or sshAgent"
 });
 var ClusterProviderSchema = z.enum(["ssh"]);
 var ClusterConfigSchema = z.object({
@@ -373,7 +520,9 @@ var ClusterConfigSchema = z.object({
   /** List of nodes */
   nodes: z.array(NodeConfigSchema).min(1),
   /** Optional k3s installer settings for restricted networks or pinned versions. */
-  install: ClusterInstallConfigSchema.optional()
+  install: ClusterInstallConfigSchema.optional(),
+  /** Optional cluster capabilities managed by cluster init/apply. */
+  features: ClusterFeaturesSchema.optional()
 }).refine((c) => c.nodes.filter((n) => n.role === "master").length === 1, {
   message: "Cluster must have exactly one master node"
 });
@@ -409,14 +558,57 @@ ${issues.join("\n")}`);
   return result.data;
 }
 function resolveNodeCredentials(node) {
+  let sshAgent;
+  if (node.sshAgent === true) {
+    sshAgent = process.env.SSH_AUTH_SOCK;
+    if (!sshAgent) {
+      throw new Error("SSH_AUTH_SOCK is not set (required by cluster.json sshAgent=true)");
+    }
+  } else if (typeof node.sshAgent === "string") {
+    sshAgent = resolveEnvTemplate(node.sshAgent);
+  }
   return {
     host: node.host,
     port: node.port,
     user: node.user,
     sshKeyPath: node.sshKeyPath ? expandHome(node.sshKeyPath) : void 0,
+    sshKeyPassphrase: node.sshKeyPassphrase ? resolveEnvTemplate(node.sshKeyPassphrase) : void 0,
+    sshAgent,
     password: node.password ? resolveEnvTemplate(node.password) : void 0
   };
 }
+function resolveNodeInstallConfig(clusterInstall, node) {
+  const merged = { ...clusterInstall, ...node.install };
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function defaultAgentSandboxManifestUrls(version = AGENT_SANDBOX_DEFAULT_VERSION) {
+  return [
+    `https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${version}/manifest.yaml`,
+    `https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${version}/extensions.yaml`
+  ];
+}
+function resolveClusterSandboxConfig(config) {
+  const sandbox = config.features?.sandbox;
+  if (sandbox === void 0 || sandbox === false) return null;
+  const normalized = sandbox === true ? {
+    enabled: true,
+    install: true,
+    version: AGENT_SANDBOX_DEFAULT_VERSION,
+    runtimeClassName: AGENT_SANDBOX_DEFAULT_RUNTIME_CLASS,
+    createRuntimeClass: true,
+    runtimeClassHandler: AGENT_SANDBOX_DEFAULT_RUNTIME_HANDLER,
+    waitTimeoutSeconds: 300,
+    required: true,
+    nodeSelector: { "shadowob.com/sandbox-ready": "true" },
+    smokeTest: false,
+    smokeImage: "busybox:1.36"
+  } : sandbox;
+  if (!normalized.enabled) return null;
+  return {
+    ...normalized,
+    manifestUrls: normalized.manifestUrls && normalized.manifestUrls.length > 0 ? normalized.manifestUrls : defaultAgentSandboxManifestUrls(normalized.version)
+  };
+}
 function getMasterNode(config) {
   const master = config.nodes.find((n) => n.role === "master");
   if (!master) throw new Error("No master node found in cluster config");
@@ -429,21 +621,35 @@ function getWorkerNodes(config) {
 // src/interfaces/cli/cluster.command.ts
 function createClusterCommand(container2) {
   const cluster = new Command2("cluster").description(
-    "Manage bare-server k3s clusters (init, status, list, destroy)"
+    "Manage bare-server k3s clusters (init, apply, status, list, destroy)"
   );
-  cluster.command("init").description("Bootstrap a k3s cluster on bare servers").option("-c, --config <path>", "Path to cluster.json", "cluster.json").option("--force", "Reinstall k3s even if already installed on nodes").action(async (options) => {
+  async function applyClusterConfig(options) {
+    const config = readClusterConfig(options.config);
+    container2.logger.info(`Applying cluster "${config.name}" from ${options.config}...`);
+    const meta = await container2.cluster.init(
+      config,
+      (msg) => {
+        container2.logger.dim(msg);
+      },
+      options.force
+    );
+    container2.logger.success(`Cluster "${meta.name}" ready! Kubeconfig: ${meta.kubeconfigPath}`);
+    container2.logger.info(
+      `Edit ${options.config} and run this command again to add newly listed nodes.`
+    );
+    container2.logger.info(`Deploy agents: shadowob-cloud up --cluster ${meta.name}`);
+  }
+  cluster.command("init").description("Bootstrap or update a k3s cluster on bare servers").option("-c, --config <path>", "Path to cluster.json", "cluster.json").option("--force", "Reinstall k3s even if already installed on nodes").action(async (options) => {
     try {
-      const config = readClusterConfig(options.config);
-      container2.logger.info(`Initializing cluster "${config.name}"...`);
-      const meta = await container2.cluster.init(
-        config,
-        (msg) => {
-          container2.logger.dim(msg);
-        },
-        options.force
-      );
-      container2.logger.success(`Cluster "${meta.name}" ready! Kubeconfig: ${meta.kubeconfigPath}`);
-      container2.logger.info(`Deploy agents: shadowob-cloud up --cluster ${meta.name}`);
+      await applyClusterConfig(options);
+    } catch (err) {
+      container2.logger.error(err.message);
+      process.exit(1);
+    }
+  });
+  cluster.command("apply").description("Apply cluster.json idempotently and add newly listed nodes").option("-c, --config <path>", "Path to cluster.json", "cluster.json").option("--force", "Reinstall k3s even if already installed on nodes").action(async (options) => {
+    try {
+      await applyClusterConfig(options);
     } catch (err) {
       container2.logger.error(err.message);
       process.exit(1);
@@ -973,7 +1179,7 @@ function createGenerateCommand(container2) {
         container2.logger.error(`Config file not found: ${filePath}`);
         process.exit(1);
       }
-      const { loadAllPlugins, getPluginRegistry: getPluginRegistry2 } = await import("./plugins-I4GD5SZX.js");
+      const { loadAllPlugins, getPluginRegistry: getPluginRegistry2 } = await import("./plugins-UK2QWD6G.js");
       await loadAllPlugins(getPluginRegistry2());
       const outputPath = options.output ? resolve7(options.output) : void 0;
       const configCwd = dirname(filePath);
@@ -1381,7 +1587,7 @@ function createOnboardCommand(container2) {
     } else {
       const answer = await ask(`  No ${configPath} found. Create one from template? [Y/n] `);
       if (!answer || answer.toLowerCase() !== "n") {
-        const { createInitCommand: createInitCommand2 } = await import("./init.command-YVG4X6II.js");
+        const { createInitCommand: createInitCommand2 } = await import("./init.command-C7UKPK2Y.js");
         const init = createInitCommand2(container2);
         await init.parseAsync(["--quick"], { from: "user" });
       } else {
@@ -1398,7 +1604,7 @@ function createOnboardCommand(container2) {
     }
     container2.logger.success("Onboarding complete! Starting console...");
     console.log();
-    const { createConsoleCommand: createConsoleCommand2 } = await import("./dashboard.command-ZMQFKLNQ.js");
+    const { createConsoleCommand: createConsoleCommand2 } = await import("./dashboard.command-BRPZCZER.js");
     const console_ = createConsoleCommand2(container2);
     await console_.parseAsync([], { from: "user" });
   });
@@ -1436,14 +1642,14 @@ function createProvisionCommand(container2) {
         process.exit(1);
       }
       try {
-        const { executePluginProvisions, loadAllPlugins, getPluginRegistry: getPluginRegistry2 } = await import("./plugins-I4GD5SZX.js");
+        const { executePluginProvisions, loadAllPlugins, getPluginRegistry: getPluginRegistry2 } = await import("./plugins-UK2QWD6G.js");
         try {
           await loadAllPlugins(getPluginRegistry2());
         } catch {
         }
         const agents = resolved.deployments?.agents ?? [];
         const namespace = resolved.deployments?.namespace ?? "shadowob-cloud";
-        const existing = loadProvisionState(filePath, options.stateDir);
+        const existing = options.force ? null : loadProvisionState(filePath, options.stateDir);
         const extraSecrets = {
           SHADOW_SERVER_URL: shadowUrl,
           SHADOW_USER_TOKEN: shadowToken
@@ -2150,7 +2356,7 @@ var SSHClient = class {
       host: opts.host,
       port: opts.port,
       username: opts.user,
-      ...opts.sshKeyPath ? { privateKey: readFileSync5(opts.sshKeyPath, "utf8") } : { password: opts.password },
+      ...opts.sshAgent ? { agent: opts.sshAgent } : opts.sshKeyPath ? { privateKey: readFileSync5(opts.sshKeyPath, "utf8"), passphrase: opts.sshKeyPassphrase } : { password: opts.password },
       // Reasonable timeout for WAN SSH
       readyTimeout: 3e4
     });
@@ -2236,9 +2442,14 @@ async function destroyCluster(options) {
 }
 
 // src/cluster/init.ts
-var K3S_INSTALL_URL = "https://get.k3s.io";
-var CN_PAUSE_IMAGE = "registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.6";
-var CN_SYSTEM_DEFAULT_REGISTRY = "registry.cn-hangzhou.aliyuncs.com";
+import { createHash } from "crypto";
+
+// src/cluster/sandbox.ts
+var REQUIRED_AGENT_SANDBOX_CRDS = [
+  "sandboxes.agents.x-k8s.io",
+  "sandboxtemplates.extensions.agents.x-k8s.io",
+  "sandboxclaims.extensions.agents.x-k8s.io"
+];
 function log2(onLog, msg) {
   onLog?.(msg);
 }
@@ -2249,6 +2460,291 @@ function asRoot2(shellCommand) {
   const quoted = shellQuote2(shellCommand);
   return `if [ "$(id -u)" -eq 0 ]; then sh -c ${quoted}; else sudo -n sh -c ${quoted}; fi`;
 }
+async function hasAgentSandboxCrds(client) {
+  const result = await client.exec(
+    asRoot2(
+      `k3s kubectl get crd ${REQUIRED_AGENT_SANDBOX_CRDS.map(shellQuote2).join(" ")} >/dev/null`
+    )
+  );
+  return result.code === 0;
+}
+async function applyManifestUrl(client, url, onLog) {
+  log2(onLog, `[sandbox] Applying ${url}`);
+  await client.execOrThrow(asRoot2(`k3s kubectl apply -f ${shellQuote2(url)}`), {
+    onStdout: (chunk) => log2(onLog, `[sandbox] ${chunk.trimEnd()}`),
+    onStderr: (chunk) => log2(onLog, `[sandbox] ${chunk.trimEnd()}`),
+    errorMessage: `Failed to apply agent-sandbox manifest ${url}. If this node cannot reach GitHub, set features.sandbox.manifestUrls to mirrored URLs.`
+  });
+}
+async function createOrVerifyRuntimeClass(client, options) {
+  if (options.create) {
+    const yaml = [
+      "apiVersion: node.k8s.io/v1",
+      "kind: RuntimeClass",
+      "metadata:",
+      `  name: ${options.name}`,
+      `handler: ${options.handler}`,
+      ""
+    ].join("\n");
+    log2(
+      options.onLog,
+      `[sandbox] Ensuring RuntimeClass ${options.name} uses handler ${options.handler}`
+    );
+    await client.execOrThrow(asRoot2(`cat <<'EOF' | k3s kubectl apply -f -
+${yaml}EOF`), {
+      errorMessage: `Failed to create RuntimeClass ${options.name}`
+    });
+    return;
+  }
+  log2(options.onLog, `[sandbox] Verifying RuntimeClass ${options.name}`);
+  await client.execOrThrow(asRoot2(`k3s kubectl get runtimeclass ${shellQuote2(options.name)}`), {
+    errorMessage: `RuntimeClass ${options.name} was not found. Install the runtime handler first, or set features.sandbox.createRuntimeClass=true with an explicit runtimeClassHandler.`
+  });
+}
+async function waitForAgentSandboxReady(client, timeoutSeconds, onLog) {
+  const crdNames = REQUIRED_AGENT_SANDBOX_CRDS.map((name) => `crd/${name}`).join(" ");
+  log2(onLog, "[sandbox] Waiting for agent-sandbox CRDs to become Established");
+  await client.execOrThrow(
+    asRoot2(`k3s kubectl wait --for=condition=Established ${crdNames} --timeout=${timeoutSeconds}s`),
+    { errorMessage: "agent-sandbox CRDs did not become Established" }
+  );
+  log2(onLog, "[sandbox] Waiting for agent-sandbox controller rollout");
+  await client.execOrThrow(
+    asRoot2(
+      `k3s kubectl -n agent-sandbox-system rollout status deployment/agent-sandbox-controller --timeout=${timeoutSeconds}s`
+    ),
+    { errorMessage: "agent-sandbox controller did not become Ready" }
+  );
+}
+function nodeLabelArgs(labels) {
+  return Object.entries(labels).map(([key, value]) => `${key}=${value}`).map(shellQuote2).join(" ");
+}
+function kubeNodeMatchesConfigNode(kubeNode, node) {
+  const metadata = kubeNode.metadata ?? {};
+  const status = kubeNode.status ?? {};
+  const addresses = Array.isArray(status.addresses) ? status.addresses : [];
+  const candidates = /* @__PURE__ */ new Set([
+    typeof metadata.name === "string" ? metadata.name : "",
+    ...addresses.map((address) => address.address).filter((address) => typeof address === "string")
+  ]);
+  return candidates.has(node.host);
+}
+async function labelConfiguredNodes(client, config, sandboxReady, onLog) {
+  const output2 = await client.execOrThrow(asRoot2("k3s kubectl get nodes -o json"), {
+    errorMessage: "Failed to list Kubernetes nodes for labeling"
+  });
+  const kubeNodes = JSON.parse(output2.stdout).items ?? [];
+  for (const node of config.nodes) {
+    const kubeNode = kubeNodes.find((candidate) => kubeNodeMatchesConfigNode(candidate, node));
+    if (!kubeNode) {
+      log2(onLog, `[sandbox] Could not match cluster.json node ${node.host} to a Kubernetes node`);
+      continue;
+    }
+    const metadata = kubeNode.metadata;
+    const nodeName = metadata.name;
+    if (typeof nodeName !== "string" || !nodeName) continue;
+    const nodeSandboxReady = sandboxReady && (node.features?.sandbox ?? true);
+    const labels = {
+      "shadowob.com/sandbox-ready": nodeSandboxReady ? "true" : "false",
+      ...node.region ? { "shadowob.com/region": node.region } : {},
+      ...node.labels ?? {}
+    };
+    log2(onLog, `[sandbox] Labeling node ${nodeName}`);
+    await client.execOrThrow(
+      asRoot2(`k3s kubectl label node ${shellQuote2(nodeName)} ${nodeLabelArgs(labels)} --overwrite`),
+      { errorMessage: `Failed to label Kubernetes node ${nodeName}` }
+    );
+  }
+}
+async function runAgentSandboxSmoke(client, options) {
+  const namespace = `shadow-sandbox-smoke-${Date.now().toString(36)}`;
+  const manifest = [
+    {
+      apiVersion: "v1",
+      kind: "Namespace",
+      metadata: { name: namespace }
+    },
+    {
+      apiVersion: "extensions.agents.x-k8s.io/v1alpha1",
+      kind: "SandboxTemplate",
+      metadata: { name: "smoke-template", namespace },
+      spec: {
+        networkPolicyManagement: "Unmanaged",
+        envVarsInjectionPolicy: "Disallowed",
+        podTemplate: {
+          metadata: { labels: { app: "shadow-sandbox-smoke" } },
+          spec: {
+            runtimeClassName: options.runtimeClassName,
+            containers: [
+              {
+                name: "smoke",
+                image: options.image,
+                command: ["sh", "-c", "echo shadow-sandbox-smoke && sleep 30"]
+              }
+            ],
+            restartPolicy: "Always"
+          }
+        },
+        volumeClaimTemplates: []
+      }
+    },
+    {
+      apiVersion: "extensions.agents.x-k8s.io/v1alpha1",
+      kind: "SandboxClaim",
+      metadata: { name: "smoke", namespace },
+      spec: {
+        sandboxTemplateRef: { name: "smoke-template" },
+        warmpool: "none",
+        lifecycle: { shutdownPolicy: "Delete" }
+      }
+    }
+  ];
+  const yaml = JSON.stringify({ apiVersion: "v1", kind: "List", items: manifest }, null, 2);
+  log2(options.onLog, `[sandbox] Running smoke test in namespace ${namespace}`);
+  try {
+    await client.execOrThrow(asRoot2(`cat <<'EOF' | k3s kubectl apply -f -
+${yaml}
+EOF`), {
+      errorMessage: "Failed to create agent-sandbox smoke resources"
+    });
+    await client.execOrThrow(
+      asRoot2(
+        `timeout ${options.timeoutSeconds} sh -c ` + shellQuote2(
+          'until [ "$(k3s kubectl -n ' + namespace + ' get sandboxclaim smoke -o jsonpath="{.status.conditions[?(@.type==\\"Ready\\")].status}" 2>/dev/null)" = "True" ]; do sleep 3; done'
+        )
+      ),
+      { errorMessage: "agent-sandbox smoke SandboxClaim did not become Ready" }
+    );
+    log2(options.onLog, "[sandbox] Smoke test passed");
+  } finally {
+    await client.exec(
+      asRoot2(`k3s kubectl delete namespace ${shellQuote2(namespace)} --ignore-not-found=true`)
+    );
+  }
+}
+async function installClusterSandbox(options) {
+  const sandbox = resolveClusterSandboxConfig(options.config);
+  if (!sandbox) return false;
+  const master = getMasterNode(options.config);
+  const creds = resolveNodeCredentials(master);
+  const client = new SSHClient();
+  log2(options.onLog, `[sandbox ${creds.host}] Connecting via SSH...`);
+  await client.connect(creds);
+  try {
+    const alreadyInstalled = await hasAgentSandboxCrds(client);
+    if (!sandbox.install && !alreadyInstalled) {
+      const message = "features.sandbox.enabled=true but the required agent-sandbox CRDs are not installed. Set features.sandbox.install=true or apply the CRDs/controller before using sandbox.";
+      if (sandbox.required) throw new Error(message);
+      log2(options.onLog, `[sandbox] ${message}`);
+      return false;
+    }
+    if (sandbox.install) {
+      log2(options.onLog, `[sandbox] Installing agent-sandbox ${sandbox.version}`);
+      for (const url of sandbox.manifestUrls) {
+        await applyManifestUrl(client, url, options.onLog);
+      }
+      if (sandbox.controllerImage) {
+        log2(options.onLog, `[sandbox] Setting controller image ${sandbox.controllerImage}`);
+        await client.execOrThrow(
+          asRoot2(
+            `k3s kubectl -n agent-sandbox-system set image deployment/agent-sandbox-controller agent-sandbox-controller=${shellQuote2(sandbox.controllerImage)}`
+          ),
+          { errorMessage: "Failed to set agent-sandbox controller image" }
+        );
+      }
+    }
+    await createOrVerifyRuntimeClass(client, {
+      name: sandbox.runtimeClassName,
+      handler: sandbox.runtimeClassHandler,
+      create: sandbox.createRuntimeClass,
+      onLog: options.onLog
+    });
+    await waitForAgentSandboxReady(client, sandbox.waitTimeoutSeconds, options.onLog);
+    await labelConfiguredNodes(client, options.config, true, options.onLog);
+    if (sandbox.smokeTest) {
+      await runAgentSandboxSmoke(client, {
+        runtimeClassName: sandbox.runtimeClassName,
+        image: sandbox.smokeImage,
+        timeoutSeconds: sandbox.waitTimeoutSeconds,
+        onLog: options.onLog
+      });
+    }
+    log2(
+      options.onLog,
+      `[sandbox] Ready with RuntimeClass ${sandbox.runtimeClassName}; new deployments can use agent-sandbox`
+    );
+    return true;
+  } catch (err) {
+    if (sandbox.required) throw err;
+    log2(
+      options.onLog,
+      `[sandbox] Not ready; deployment fallback remains available: ${err.message}`
+    );
+    return false;
+  } finally {
+    await client.dispose();
+  }
+}
+
+// src/cluster/init.ts
+var K3S_INSTALL_URL = "https://get.k3s.io";
+var CN_PAUSE_IMAGE = "registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.6";
+var CN_SYSTEM_DEFAULT_REGISTRY = "registry.cn-hangzhou.aliyuncs.com";
+function log3(onLog, msg) {
+  onLog?.(msg);
+}
+function shellQuote3(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function asRoot3(shellCommand) {
+  const quoted = shellQuote3(shellCommand);
+  return `if [ "$(id -u)" -eq 0 ]; then sh -c ${quoted}; else sudo -n sh -c ${quoted}; fi`;
+}
+function resolveEnvTemplates(value) {
+  if (typeof value === "string") {
+    return value.replace(/\$\{env:([^}]+)\}/g, (_match, envKey) => {
+      const envVal = process.env[envKey];
+      if (envVal === void 0) {
+        throw new Error(`Environment variable "${envKey}" is not set (required by cluster.json)`);
+      }
+      return envVal;
+    });
+  }
+  if (Array.isArray(value)) return value.map(resolveEnvTemplates);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, child]) => [key, resolveEnvTemplates(child)])
+    );
+  }
+  return value;
+}
+function clusterConfigHash(config) {
+  return createHash("sha256").update(stableStringify(config)).digest("hex");
+}
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => `${JSON.stringify(key)}:${stableStringify(child)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+async function ensureK3sRegistriesConfig(client, install2, serviceName, onLog) {
+  if (!install2?.registries) return;
+  const registries = JSON.stringify(resolveEnvTemplates(install2.registries), null, 2);
+  log3(onLog, `[${serviceName}] Writing k3s containerd registries.yaml`);
+  await client.execOrThrow(
+    asRoot3(
+      [
+        "mkdir -p /etc/rancher/k3s",
+        `cat > /etc/rancher/k3s/registries.yaml <<'EOF'
+${registries}
+EOF`,
+        `if command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet ${serviceName}; then systemctl restart ${serviceName}; fi`
+      ].join("\n")
+    ),
+    { errorMessage: `Failed to write k3s registries.yaml for ${serviceName}` }
+  );
+}
 function resolveK3sMirror(install2) {
   return process.env.INSTALL_K3S_MIRROR ?? process.env.K3S_INSTALL_MIRROR ?? install2?.k3sMirror;
 }
@@ -2317,7 +2813,7 @@ function k3sInstallEnv(extra, install2) {
     INSTALL_K3S_VERSION: version,
     ...extra
   };
-  return Object.entries(env).filter((entry) => Boolean(entry[1])).map(([key, value]) => `${key}=${shellQuote2(value)}`).join(" ");
+  return Object.entries(env).filter((entry) => Boolean(entry[1])).map(([key, value]) => `${key}=${shellQuote3(value)}`).join(" ");
 }
 async function isK3sInstalled(client) {
   const result = await client.exec("which k3s");
@@ -2326,25 +2822,26 @@ async function isK3sInstalled(client) {
 async function installMaster(master, install2, force, onLog) {
   const creds = resolveNodeCredentials(master);
   const client = new SSHClient();
-  log2(onLog, `[master ${creds.host}] Connecting via SSH...`);
+  log3(onLog, `[master ${creds.host}] Connecting via SSH...`);
   await client.connect(creds);
   try {
+    await ensureK3sRegistriesConfig(client, install2, "k3s", onLog);
     const alreadyInstalled = await isK3sInstalled(client);
     if (alreadyInstalled && !force) {
-      log2(
+      log3(
         onLog,
         `[master ${creds.host}] k3s already installed \u2014 skipping install (use --force to reinstall)`
       );
-      log2(onLog, `[master ${creds.host}] Reading existing token and kubeconfig...`);
+      log3(onLog, `[master ${creds.host}] Reading existing token and kubeconfig...`);
     } else {
       if (alreadyInstalled && force) {
-        log2(onLog, `[master ${creds.host}] k3s already installed \u2014 reinstalling (--force)`);
-        await client.exec(asRoot2("/usr/local/bin/k3s-uninstall.sh 2>/dev/null || true"));
+        log3(onLog, `[master ${creds.host}] k3s already installed \u2014 reinstalling (--force)`);
+        await client.exec(asRoot3("/usr/local/bin/k3s-uninstall.sh 2>/dev/null || true"));
       }
-      log2(onLog, `[master ${creds.host}] Installing k3s server...`);
+      log3(onLog, `[master ${creds.host}] Installing k3s server...`);
       await client.execOrThrow(
-        asRoot2(
-          `curl -sfL ${shellQuote2(K3S_INSTALL_URL)} | ${k3sInstallEnv(
+        asRoot3(
+          `curl -sfL ${shellQuote3(K3S_INSTALL_URL)} | ${k3sInstallEnv(
             {
               INSTALL_K3S_EXEC: k3sExec(["server", "--tls-san", creds.host], install2)
             },
@@ -2352,28 +2849,28 @@ async function installMaster(master, install2, force, onLog) {
           )} sh -`
         ),
         {
-          onStdout: (c) => log2(onLog, `[master] ${c.trimEnd()}`),
-          onStderr: (c) => log2(onLog, `[master] ${c.trimEnd()}`),
+          onStdout: (c) => log3(onLog, `[master] ${c.trimEnd()}`),
+          onStderr: (c) => log3(onLog, `[master] ${c.trimEnd()}`),
           errorMessage: `Failed to install k3s on master ${creds.host}`
         }
       );
     }
-    log2(onLog, `[master ${creds.host}] Waiting for k3s to be ready...`);
+    log3(onLog, `[master ${creds.host}] Waiting for k3s to be ready...`);
     await client.execOrThrow(
-      asRoot2(`timeout 120 sh -c 'until k3s kubectl get nodes > /dev/null 2>&1; do sleep 3; done'`),
+      asRoot3(`timeout 120 sh -c 'until k3s kubectl get nodes > /dev/null 2>&1; do sleep 3; done'`),
       { errorMessage: "k3s master did not become ready within 120s" }
     );
-    log2(onLog, `[master ${creds.host}] Reading node token...`);
+    log3(onLog, `[master ${creds.host}] Reading node token...`);
     const tokenResult = await client.execOrThrow(
-      asRoot2("cat /var/lib/rancher/k3s/server/node-token"),
+      asRoot3("cat /var/lib/rancher/k3s/server/node-token"),
       {
         errorMessage: "Failed to read k3s node token"
       }
     );
     const token = tokenResult.stdout.trim();
     if (!token) throw new Error("k3s node token is empty");
-    log2(onLog, `[master ${creds.host}] Reading kubeconfig...`);
-    const kubeconfigResult = await client.execOrThrow(asRoot2("cat /etc/rancher/k3s/k3s.yaml"), {
+    log3(onLog, `[master ${creds.host}] Reading kubeconfig...`);
+    const kubeconfigResult = await client.execOrThrow(asRoot3("cat /etc/rancher/k3s/k3s.yaml"), {
       errorMessage: "Failed to read k3s kubeconfig"
     });
     return { token, kubeconfig: kubeconfigResult.stdout };
@@ -2384,25 +2881,26 @@ async function installMaster(master, install2, force, onLog) {
 async function installWorker(worker, masterHost, token, install2, force, onLog) {
   const creds = resolveNodeCredentials(worker);
   const client = new SSHClient();
-  log2(onLog, `[worker ${creds.host}] Connecting via SSH...`);
+  log3(onLog, `[worker ${creds.host}] Connecting via SSH...`);
   await client.connect(creds);
   try {
+    await ensureK3sRegistriesConfig(client, install2, "k3s-agent", onLog);
     const alreadyInstalled = await isK3sInstalled(client);
     if (alreadyInstalled && !force) {
-      log2(
+      log3(
         onLog,
         `[worker ${creds.host}] k3s already installed \u2014 skipping install (use --force to reinstall)`
       );
       return;
     }
     if (alreadyInstalled && force) {
-      log2(onLog, `[worker ${creds.host}] k3s already installed \u2014 reinstalling (--force)`);
-      await client.exec(asRoot2("/usr/local/bin/k3s-agent-uninstall.sh 2>/dev/null || true"));
+      log3(onLog, `[worker ${creds.host}] k3s already installed \u2014 reinstalling (--force)`);
+      await client.exec(asRoot3("/usr/local/bin/k3s-agent-uninstall.sh 2>/dev/null || true"));
     }
-    log2(onLog, `[worker ${creds.host}] Installing k3s agent and joining cluster...`);
+    log3(onLog, `[worker ${creds.host}] Installing k3s agent and joining cluster...`);
     await client.execOrThrow(
-      asRoot2(
-        `curl -sfL ${shellQuote2(K3S_INSTALL_URL)} | ${k3sInstallEnv(
+      asRoot3(
+        `curl -sfL ${shellQuote3(K3S_INSTALL_URL)} | ${k3sInstallEnv(
           {
             K3S_URL: `https://${masterHost}:6443`,
             K3S_TOKEN: token,
@@ -2412,12 +2910,12 @@ async function installWorker(worker, masterHost, token, install2, force, onLog)
         )} sh -`
       ),
       {
-        onStdout: (c) => log2(onLog, `[worker ${creds.host}] ${c.trimEnd()}`),
-        onStderr: (c) => log2(onLog, `[worker ${creds.host}] ${c.trimEnd()}`),
+        onStdout: (c) => log3(onLog, `[worker ${creds.host}] ${c.trimEnd()}`),
+        onStderr: (c) => log3(onLog, `[worker ${creds.host}] ${c.trimEnd()}`),
         errorMessage: `Failed to install k3s agent on worker ${creds.host}`
       }
     );
-    log2(onLog, `[worker ${creds.host}] Agent joined cluster \u2713`);
+    log3(onLog, `[worker ${creds.host}] Agent joined cluster \u2713`);
   } finally {
     await client.dispose();
   }
@@ -2426,17 +2924,39 @@ async function initCluster(options) {
   const { config, force = false, onLog } = options;
   const master = getMasterNode(config);
   const workers = getWorkerNodes(config);
-  log2(onLog, `Initializing cluster "${config.name}" with ${config.nodes.length} nodes...`);
-  const { token, kubeconfig } = await installMaster(master, config.install, force, onLog);
+  log3(onLog, `Initializing cluster "${config.name}" with ${config.nodes.length} nodes...`);
+  const masterInstall = resolveNodeInstallConfig(config.install, master);
+  const { token, kubeconfig } = await installMaster(master, masterInstall, force, onLog);
   if (workers.length > 0) {
-    log2(onLog, `Installing ${workers.length} worker(s) in parallel...`);
+    log3(onLog, `Installing ${workers.length} worker(s) in parallel...`);
     await Promise.all(
-      workers.map((w) => installWorker(w, master.host, token, config.install, force, onLog))
+      workers.map(
+        (worker) => installWorker(
+          worker,
+          master.host,
+          token,
+          resolveNodeInstallConfig(config.install, worker),
+          force,
+          onLog
+        )
+      )
     );
   }
-  const meta = storeKubeconfig(config.name, kubeconfig, master.host, config.nodes.length);
-  log2(onLog, `Kubeconfig stored at ${meta.kubeconfigPath}`);
-  log2(onLog, `Cluster "${config.name}" is ready. Use: shadowob-cloud up --cluster ${config.name}`);
+  const sandboxConfig = resolveClusterSandboxConfig(config);
+  const sandboxEnabled = await installClusterSandbox({ config, onLog });
+  const meta = storeKubeconfig(config.name, kubeconfig, master.host, config.nodes.length, {
+    configHash: clusterConfigHash(config),
+    features: {
+      sandbox: sandboxConfig ? {
+        enabled: sandboxEnabled,
+        version: sandboxConfig.version,
+        runtimeClassName: sandboxConfig.runtimeClassName,
+        nodeSelector: sandboxConfig.nodeSelector
+      } : { enabled: false }
+    }
+  });
+  log3(onLog, `Kubeconfig stored at ${meta.kubeconfigPath}`);
+  log3(onLog, `Cluster "${config.name}" is ready. Use: shadowob-cloud up --cluster ${config.name}`);
   return meta;
 }
 
@@ -2587,8 +3107,68 @@ var ConfigService = class {
 };
 
 // src/services/deploy.service.ts
-import { existsSync as existsSync16, mkdirSync as mkdirSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
 import { dirname as dirname3, resolve as resolve16 } from "path";
+
+// src/utils/kubeconfig-file.ts
+import { existsSync as existsSync16, readFileSync as readFileSync6, statSync } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join4 } from "path";
+function defaultKubeconfigPath() {
+  return join4(homedir3(), ".kube", "config");
+}
+function kubeconfigSetupHint() {
+  return "Configure KUBECONFIG_HOST_PATH or CLOUD_SAAS_CLUSTER_KUBECONFIG_HOST_PATH to an existing host kubeconfig file, or initialize/import a cluster before deploying.";
+}
+function assertReadableKubeconfigFile(kubeconfigPath, label = "Kubernetes kubeconfig") {
+  if (!existsSync16(kubeconfigPath)) {
+    throw new Error(`${label} not found at ${kubeconfigPath}. ${kubeconfigSetupHint()}`);
+  }
+  let stat3;
+  try {
+    stat3 = statSync(kubeconfigPath);
+  } catch (err) {
+    throw new Error(
+      `Failed to inspect ${label} at ${kubeconfigPath}: ${err.message}. ` + kubeconfigSetupHint()
+    );
+  }
+  if (stat3.isDirectory()) {
+    throw new Error(
+      `${label} path ${kubeconfigPath} is a directory, not a file. This usually means Docker created the bind-mount target because the host kubeconfig file is missing. ` + kubeconfigSetupHint()
+    );
+  }
+  if (!stat3.isFile()) {
+    throw new Error(
+      `${label} path ${kubeconfigPath} is not a regular file. ${kubeconfigSetupHint()}`
+    );
+  }
+  if (stat3.size === 0) {
+    throw new Error(`${label} at ${kubeconfigPath} is empty. ${kubeconfigSetupHint()}`);
+  }
+}
+function readKubeconfigFile(kubeconfigPath, label = "Kubernetes kubeconfig") {
+  assertReadableKubeconfigFile(kubeconfigPath, label);
+  try {
+    return readFileSync6(kubeconfigPath, "utf8");
+  } catch (err) {
+    throw new Error(
+      `Failed to read ${label} at ${kubeconfigPath}: ${err.message}. ` + kubeconfigSetupHint()
+    );
+  }
+}
+function findReadableKubeconfigPath(candidates, label = "Kubernetes kubeconfig") {
+  const uniqueCandidates = [
+    ...new Set(candidates.filter((candidate) => Boolean(candidate)))
+  ];
+  for (const candidate of uniqueCandidates) {
+    if (!existsSync16(candidate)) continue;
+    assertReadableKubeconfigFile(candidate, label);
+    return candidate;
+  }
+  return void 0;
+}
+
+// src/services/deploy.service.ts
 function deploymentReadyTimeoutMs() {
   const raw = Number(process.env.CLOUD_DEPLOYMENT_READY_TIMEOUT_MS);
   return Number.isFinite(raw) && raw > 0 ? raw : 20 * 6e4;
@@ -2596,13 +3176,22 @@ function deploymentReadyTimeoutMs() {
 function isAgentSandboxBackend(config) {
   return (config.deployments?.backend ?? "agent-sandbox") === "agent-sandbox";
 }
+function workloadBackendPolicy(config) {
+  if (config.deployments?.backendPolicy) return config.deployments.backendPolicy;
+  return isAgentSandboxBackend(config) ? "sandbox-required" : "deployment-only";
+}
+function sandboxRuntimeClassNames(config) {
+  const deployments = config.deployments;
+  if (!deployments) return [];
+  const defaultRuntimeClassName = deployments.sandbox?.runtimeClassName ?? "gvisor";
+  const names = deployments.agents.map(
+    (agent) => agent.sandbox?.runtimeClassName ?? defaultRuntimeClassName
+  );
+  return [...new Set(names)];
+}
 function readKubeconfigForRuntimeWait(kubeConfigPath) {
   if (!kubeConfigPath) return void 0;
-  try {
-    return readFileSync6(kubeConfigPath, "utf8");
-  } catch {
-    return void 0;
-  }
+  return readKubeconfigFile(kubeConfigPath);
 }
 function resolveStackName(namespace, stack) {
   return stack ?? `dev-${namespace}`;
@@ -2644,7 +3233,7 @@ function configUsesPlugins(value, depth = 0) {
 }
 async function ensureBuiltInPluginsLoaded() {
   try {
-    const { loadAllPlugins, getPluginRegistry: getPluginRegistry2 } = await import("./plugins-I4GD5SZX.js");
+    const { loadAllPlugins, getPluginRegistry: getPluginRegistry2 } = await import("./plugins-UK2QWD6G.js");
     const registry = getPluginRegistry2();
     if (registry.size === 0) await loadAllPlugins(registry);
   } catch {
@@ -2653,7 +3242,7 @@ async function ensureBuiltInPluginsLoaded() {
 function readKubeconfigCurrentContext(kubeConfigPath) {
   if (!kubeConfigPath) return void 0;
   try {
-    return readFileSync6(kubeConfigPath, "utf8").match(/current-context:\s*(\S+)/)?.[1];
+    return readKubeconfigFile(kubeConfigPath).match(/current-context:\s*(\S+)/)?.[1];
   } catch {
     return void 0;
   }
@@ -2666,6 +3255,39 @@ function summarizeK8sTarget(options, kubeConfigPath) {
   const kubeconfig = kubeConfigPath ?? process.env.KUBECONFIG ?? "~/.kube/config";
   return `Kubernetes target: cluster=${cluster} context=${context} kubeconfig=${kubeconfig}`;
 }
+function applyManagedClusterDefaults(config, clusterName) {
+  if (!clusterName || !config.deployments) return;
+  const sandbox = loadClusterMeta(clusterName)?.features?.sandbox;
+  if (!config.deployments.backendPolicy) {
+    config.deployments.backendPolicy = sandbox?.enabled ? "sandbox-preferred" : config.deployments.backend === "agent-sandbox" ? "sandbox-required" : "deployment-only";
+  }
+  if (!config.deployments.backend) {
+    config.deployments.backend = config.deployments.backendPolicy === "deployment-only" ? "deployment" : sandbox?.enabled ? "agent-sandbox" : "deployment";
+  }
+  if (config.deployments.backend === "agent-sandbox" && sandbox?.enabled && sandbox.runtimeClassName) {
+    config.deployments.sandbox = {
+      ...config.deployments.sandbox ?? {},
+      runtimeClassName: config.deployments.sandbox?.runtimeClassName ?? sandbox.runtimeClassName
+    };
+  }
+  if (config.deployments.backend === "agent-sandbox" && sandbox?.enabled && sandbox.nodeSelector) {
+    config.deployments.scheduling = {
+      ...config.deployments.scheduling ?? {},
+      nodeSelector: {
+        ...sandbox.nodeSelector,
+        ...config.deployments.scheduling?.nodeSelector ?? {}
+      }
+    };
+  }
+}
+function describeSandboxPreflightFailure(missing, warnings) {
+  return [
+    "agent-sandbox preflight failed.",
+    missing.length > 0 ? `Missing: ${missing.join(", ")}.` : "",
+    warnings.length > 0 ? `Warnings: ${warnings.join(", ")}.` : "",
+    'Run "shadowob-cloud cluster apply --config cluster.json" to install/verify sandbox, or set deployments.backendPolicy="deployment-only" for fallback.'
+  ].filter(Boolean).join(" ");
+}
 var DeployService = class {
   constructor(configService, manifestService, k8s6, logger) {
     this.configService = configService;
@@ -2685,10 +3307,13 @@ var DeployService = class {
     });
     const runtimeContext = normalizeDeploymentRuntimeContext(options.runtimeContext);
     const effectiveEnv = buildEffectiveEnv(options.runtimeEnvVars, runtimeContext);
-    if (!existsSync16(filePath)) {
+    if (!existsSync17(filePath)) {
       throw new Error(`Config file not found: ${filePath}`);
     }
     const kubeConfigPath = options.kubeConfigPath ?? (options.cluster ? loadKubeconfigPath(options.cluster) : void 0);
+    if (kubeConfigPath) {
+      assertReadableKubeconfigFile(kubeConfigPath);
+    }
     const k8sTargetSummary = summarizeK8sTarget(options, kubeConfigPath);
     this.logger.info(k8sTargetSummary);
     emit(`${k8sTargetSummary}
@@ -2701,6 +3326,7 @@ var DeployService = class {
       await this.configService.parseFile(filePath),
       runtimeContext
     );
+    applyManagedClusterDefaults(config, options.cluster);
     const namespace = options.namespace ?? config.deployments?.namespace ?? "shadowob-cloud";
     const stackName = resolveStackName(namespace, options.stack);
     const agents = config.deployments?.agents ?? [];
@@ -2745,10 +3371,31 @@ var DeployService = class {
     const usesPlugins = configUsesPlugins(config);
     if (usesPlugins) await ensureBuiltInPluginsLoaded();
     const resolved = await this.configService.resolve(config, configCwd, { env: effectiveEnv });
+    if (resolved.deployments && isAgentSandboxBackend(resolved)) {
+      const policy = workloadBackendPolicy(resolved);
+      const preflight = this.k8s.checkAgentSandboxPreflight({
+        kubeconfig: readKubeconfigForRuntimeWait(kubeConfigPath),
+        runtimeClassNames: sandboxRuntimeClassNames(resolved)
+      });
+      if (!preflight.ok) {
+        const message = describeSandboxPreflightFailure(preflight.missing, preflight.warnings);
+        if (policy === "sandbox-preferred") {
+          this.logger.warn(`${message} Falling back to Kubernetes Deployment.`);
+          emit(`${message} Falling back to Kubernetes Deployment.
+`);
+          resolved.deployments.backend = "deployment";
+          resolved.deployments.backendPolicy = "deployment-only";
+        } else {
+          throw new Error(message);
+        }
+      } else if (preflight.warnings.length > 0) {
+        this.logger.warn(`agent-sandbox preflight warnings: ${preflight.warnings.join(", ")}`);
+      }
+    }
     if (usesPlugins) await ensureBuiltInPluginsLoaded();
     if (!options.skipProvision) {
       try {
-        const { executePluginProvisions, getPluginRegistry: getPluginRegistry2 } = await import("./plugins-I4GD5SZX.js");
+        const { executePluginProvisions, getPluginRegistry: getPluginRegistry2 } = await import("./plugins-UK2QWD6G.js");
         for (const agent of agents) {
           const provisionResults = await executePluginProvisions(
             agent,
@@ -2763,6 +3410,9 @@ var DeployService = class {
             for (const e of provisionResults.errors) {
               this.logger.warn(`Plugin provision error (${e.pluginId}): ${e.error}`);
             }
+            throw new Error(
+              `Plugin provisioning failed: ${provisionResults.errors.map((e) => `${e.pluginId}: ${e.error}`).join("; ")}`
+            );
           }
           if (Object.keys(provisionResults.secrets).length > 0) {
             agent.env = { ...agent.env ?? {}, ...provisionResults.secrets };
@@ -2786,7 +3436,10 @@ var DeployService = class {
             await options.onProvisionState?.(merged);
           }
         }
-      } catch {
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.logger.warn(`Plugin provisioning failed; aborting deploy: ${message}`);
+        throw err;
       }
     }
     const k8sShadowUrl = options.k8sShadowUrl ?? effectiveEnv.SHADOW_AGENT_SERVER_URL ?? options.shadowUrl ?? effectiveEnv.K8S_SHADOW_URL ?? effectiveEnv.SHADOW_SERVER_URL;
@@ -2859,11 +3512,11 @@ var DeployService = class {
             emit("Lock canceled, retrying...\n");
           }
         } catch {
-          const { join: join7 } = await import("path");
+          const { join: join8 } = await import("path");
           const { homedir: homedir6 } = await import("os");
-          const { rmSync: rmSync4, existsSync: existsSync19 } = await import("fs");
-          const lockDir = join7(homedir6(), ".shadowob", "pulumi", ".pulumi", "locks");
-          if (existsSync19(lockDir)) {
+          const { rmSync: rmSync4, existsSync: existsSync20 } = await import("fs");
+          const lockDir = join8(homedir6(), ".shadowob", "pulumi", ".pulumi", "locks");
+          if (existsSync20(lockDir)) {
             try {
               rmSync4(lockDir, { recursive: true });
               this.logger.info("Lock files removed, retrying...");
@@ -2963,6 +3616,9 @@ var DeployService = class {
         `Cannot destroy namespace "${namespace}" without a Pulumi config snapshot. Destroy must run through the deployment stack state.`
       );
     }
+    if (options.kubeConfigPath) {
+      assertReadableKubeconfigFile(options.kubeConfigPath);
+    }
     const stack = await this.k8s.getOrCreateStack({
       stackName,
       config: options.config,
@@ -2990,10 +3646,10 @@ var DeployService = class {
 };
 
 // src/services/deployment-runtime.service.ts
-import { createHash } from "crypto";
-import { existsSync as existsSync17, mkdirSync as mkdirSync4, mkdtempSync as mkdtempSync2, readFileSync as readFileSync7, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "fs";
-import { homedir as homedir3, tmpdir as tmpdir2 } from "os";
-import { delimiter, join as join4 } from "path";
+import { createHash as createHash2 } from "crypto";
+import { existsSync as existsSync18, mkdirSync as mkdirSync4, mkdtempSync as mkdtempSync2, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "fs";
+import { homedir as homedir4, tmpdir as tmpdir2 } from "os";
+import { delimiter, join as join5 } from "path";
 function extractKubeContext(kubeconfigYaml) {
   const match = kubeconfigYaml.match(/current-context:\s*(\S+)/);
   return match?.[1];
@@ -3030,24 +3686,24 @@ function normalizeRuntimeEnvVars2(envVars) {
   return normalized;
 }
 function getStableRuntimeKubeconfigPath(kubeconfigYaml) {
-  const runtimeDir = join4(homedir3(), ".shadowob", "kubeconfigs");
+  const runtimeDir = join5(homedir4(), ".shadowob", "kubeconfigs");
   mkdirSync4(runtimeDir, { recursive: true });
-  const hash = createHash("sha256").update(kubeconfigYaml).digest("hex");
-  const kubeconfigPath = join4(runtimeDir, `${hash}.yaml`);
-  if (!existsSync17(kubeconfigPath)) {
+  const hash = createHash2("sha256").update(kubeconfigYaml).digest("hex");
+  const kubeconfigPath = join5(runtimeDir, `${hash}.yaml`);
+  if (!existsSync18(kubeconfigPath)) {
     writeFileSync5(kubeconfigPath, kubeconfigYaml, { mode: 384 });
   }
   return kubeconfigPath;
 }
 function isContainerizedRuntime() {
-  return process.env.SHADOW_CONTAINERIZED === "1" || existsSync17("/.dockerenv");
+  return process.env.SHADOW_CONTAINERIZED === "1" || existsSync18("/.dockerenv");
 }
 function getHostLocalRuntimeKubeconfigPaths() {
   const candidates = [process.env.KUBECONFIG_HOST_PATH?.trim()];
   if (!isContainerizedRuntime()) {
     candidates.push(
       ...process.env.KUBECONFIG?.split(delimiter).map((candidate) => candidate.trim()).filter((candidate) => candidate.length > 0) ?? [],
-      join4(homedir3(), ".kube", "config")
+      defaultKubeconfigPath()
     );
   }
   return [...new Set(candidates.filter((candidate) => Boolean(candidate)))];
@@ -3060,17 +3716,17 @@ function resolveAmbientRuntimeKubeconfigPath() {
   const candidates = [
     ...process.env.KUBECONFIG?.split(delimiter).map((candidate) => candidate.trim()).filter((candidate) => candidate.length > 0) ?? [],
     process.env.KUBECONFIG_HOST_PATH?.trim(),
-    join4(homedir3(), ".kube", "config")
+    defaultKubeconfigPath()
   ].filter((candidate) => Boolean(candidate));
-  return candidates.find((candidate) => existsSync17(candidate));
+  return findReadableKubeconfigPath(candidates, "Cloud SaaS Kubernetes kubeconfig");
 }
 var DeploymentRuntimeService = class {
   constructor(deployService) {
     this.deployService = deployService;
   }
   async deployFromSnapshot(options) {
-    const configDir = mkdtempSync2(join4(tmpdir2(), "sc-cfg-"));
-    const configPath = join4(configDir, "shadowob-cloud.json");
+    const configDir = mkdtempSync2(join5(tmpdir2(), "sc-cfg-"));
+    const configPath = join5(configDir, "shadowob-cloud.json");
     writeFileSync5(configPath, JSON.stringify(options.configSnapshot, null, 2), "utf-8");
     const {
       configSnapshot: _configSnapshot,
@@ -3123,7 +3779,7 @@ var DeploymentRuntimeService = class {
     let k8sContext;
     let kubeConfigPath;
     const activeKubeconfigPath = resolveAmbientRuntimeKubeconfigPath();
-    const activeKubeconfig = cluster?.kubeconfig ? cluster.kubeconfig : activeKubeconfigPath ? readFileSync7(activeKubeconfigPath, "utf8") : void 0;
+    const activeKubeconfig = cluster?.kubeconfig ? cluster.kubeconfig : activeKubeconfigPath ? readKubeconfigFile(activeKubeconfigPath, "Cloud SaaS Kubernetes kubeconfig") : void 0;
     if (activeKubeconfig) {
       const shouldRewriteLoopback = Boolean(
         cluster?.kubeconfig || activeKubeconfigPath && !isHostLocalRuntimeKubeconfigPath(activeKubeconfigPath)
@@ -3454,23 +4110,23 @@ function rolloutUndoAll(namespace) {
 
 // src/clients/kubectl-runtime.ts
 import { execFileSync as execFileSync2, spawn as spawn4, spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync18, mkdtempSync as mkdtempSync3, readFileSync as readFileSync8, rmSync as rmSync3, writeFileSync as writeFileSync6 } from "fs";
-import { homedir as homedir4, tmpdir as tmpdir3 } from "os";
-import { delimiter as delimiter2, join as join5 } from "path";
+import { existsSync as existsSync19, mkdtempSync as mkdtempSync3, rmSync as rmSync3, writeFileSync as writeFileSync6 } from "fs";
+import { tmpdir as tmpdir3 } from "os";
+import { delimiter as delimiter2, join as join6 } from "path";
 function volumeSnapshotApiAvailableFromOutput2(output2) {
   return output2.split(/\s+/).map((item) => item.trim()).some(
     (resource) => resource === "volumesnapshots" || resource === "volumesnapshots.snapshot.storage.k8s.io"
   );
 }
 function isContainerizedRuntime2() {
-  return process.env.SHADOW_CONTAINERIZED === "1" || existsSync18("/.dockerenv");
+  return process.env.SHADOW_CONTAINERIZED === "1" || existsSync19("/.dockerenv");
 }
 function getHostLocalKubeconfigPaths() {
   const candidates = [process.env.KUBECONFIG_HOST_PATH?.trim()];
   if (!isContainerizedRuntime2()) {
     candidates.push(
       ...process.env.KUBECONFIG?.split(delimiter2).map((candidate) => candidate.trim()).filter((candidate) => candidate.length > 0) ?? [],
-      join5(homedir4(), ".kube", "config")
+      defaultKubeconfigPath()
     );
   }
   return [...new Set(candidates.filter((candidate) => Boolean(candidate)))];
@@ -3484,22 +4140,23 @@ function extractCurrentContext(kubeconfigYaml) {
 }
 function resolveAmbientKubeconfig() {
   const envCandidates = process.env.KUBECONFIG?.split(delimiter2).map((candidate) => candidate.trim()).filter((candidate) => candidate.length > 0) ?? [];
-  const kubeconfigPath = [
+  const candidates = [
     ...envCandidates,
     process.env.KUBECONFIG_HOST_PATH?.trim(),
-    join5(homedir4(), ".kube", "config")
-  ].filter((candidate) => Boolean(candidate)).find((candidate) => existsSync18(candidate));
+    defaultKubeconfigPath()
+  ].filter((candidate) => Boolean(candidate));
+  const kubeconfigPath = findReadableKubeconfigPath(candidates, "Kubernetes kubectl kubeconfig");
   if (!kubeconfigPath) {
     return void 0;
   }
   return {
-    kubeconfig: readFileSync8(kubeconfigPath, "utf-8"),
+    kubeconfig: readKubeconfigFile(kubeconfigPath, "Kubernetes kubectl kubeconfig"),
     shouldRewriteLoopback: !isHostLocalKubeconfigPath(kubeconfigPath)
   };
 }
 function createTempKubeconfig(kubeconfig, includeAmbientContext = false, rewriteLoopback = true) {
-  const dir = mkdtempSync3(join5(tmpdir3(), "sc-saas-kube-"));
-  const path = join5(dir, "kubeconfig");
+  const dir = mkdtempSync3(join6(tmpdir3(), "sc-saas-kube-"));
+  const path = join6(dir, "kubeconfig");
   const rewritten = rewriteLoopback ? rewriteLoopbackKubeconfig(kubeconfig, process.env.KUBECONFIG_LOOPBACK_HOST) : kubeconfig;
   writeFileSync6(path, rewritten, { mode: 384 });
   const args = ["--kubeconfig", path];
@@ -3552,6 +4209,93 @@ async function withKubeconfigAsync(kubeconfig, fn) {
     cleanup();
   }
 }
+function execKubectl(args, kubeconfig, timeout = 3e3) {
+  return withKubeconfig(
+    kubeconfig,
+    (kubeArgs) => execFileSync2("kubectl", [...kubeArgs, ...args], {
+      encoding: "utf-8",
+      timeout,
+      stdio: ["ignore", "pipe", "pipe"]
+    })
+  );
+}
+function tryExecKubectl(args, kubeconfig, timeout = 5e3) {
+  try {
+    return execKubectl(args, kubeconfig, timeout);
+  } catch {
+    return null;
+  }
+}
+function resourceOutputHas(output2, resourceName) {
+  return Boolean(
+    output2?.split(/\s+/).map((item) => item.trim()).some((item) => item === resourceName)
+  );
+}
+function checkAgentSandboxPreflight(options) {
+  const missing = [];
+  const warnings = [];
+  const kubeconfig = options?.kubeconfig;
+  const extensionResources = tryExecKubectl(
+    ["api-resources", "--api-group", "extensions.agents.x-k8s.io", "-o", "name"],
+    kubeconfig
+  );
+  if (!resourceOutputHas(extensionResources, "sandboxtemplates")) {
+    missing.push("CRD sandboxtemplates.extensions.agents.x-k8s.io");
+  }
+  if (!resourceOutputHas(extensionResources, "sandboxclaims")) {
+    missing.push("CRD sandboxclaims.extensions.agents.x-k8s.io");
+  }
+  const coreResources = tryExecKubectl(
+    ["api-resources", "--api-group", "agents.x-k8s.io", "-o", "name"],
+    kubeconfig
+  );
+  if (!resourceOutputHas(coreResources, "sandboxes")) {
+    missing.push("CRD sandboxes.agents.x-k8s.io");
+  }
+  const controllerOutput = tryExecKubectl(
+    ["-n", "agent-sandbox-system", "get", "deployment", "agent-sandbox-controller", "-o", "json"],
+    kubeconfig,
+    1e4
+  );
+  if (!controllerOutput) {
+    missing.push("deployment/agent-sandbox-controller in namespace agent-sandbox-system");
+  } else {
+    try {
+      const controller = JSON.parse(controllerOutput);
+      const status = controller.status ?? {};
+      if ((status.availableReplicas ?? 0) < 1) {
+        missing.push("Ready agent-sandbox controller");
+      }
+    } catch {
+      missing.push("Readable agent-sandbox controller status");
+    }
+  }
+  const runtimeClassNames = [
+    ...new Set(
+      [options?.runtimeClassName, ...options?.runtimeClassNames ?? []].map((name) => name?.trim()).filter((name) => Boolean(name))
+    )
+  ];
+  for (const runtimeClassName of runtimeClassNames) {
+    const runtimeClass = tryExecKubectl(["get", "runtimeclass", runtimeClassName], kubeconfig);
+    if (!runtimeClass) {
+      missing.push(`RuntimeClass ${runtimeClassName}`);
+    }
+  }
+  const sandboxNodes = tryExecKubectl(
+    ["get", "nodes", "-l", "shadowob.com/sandbox-ready=true", "-o", "name"],
+    kubeconfig
+  );
+  if (!sandboxNodes?.trim()) {
+    warnings.push("No nodes are labeled shadowob.com/sandbox-ready=true");
+  }
+  return {
+    ok: missing.length === 0,
+    missing,
+    warnings,
+    runtimeClassName: runtimeClassNames[0],
+    runtimeClassNames
+  };
+}
 function execKubectlAsync(args, kubeconfig, timeout = 3e3) {
   return withKubeconfigAsync(
     kubeconfig,
@@ -3669,7 +4413,7 @@ async function getPodReadyState(namespace, podName, kubeconfig) {
     throw error;
   }
 }
-async function waitForAgentSandboxReady(options) {
+async function waitForAgentSandboxReady2(options) {
   const timeoutMs = options.timeoutMs ?? 18e4;
   const intervalMs = options.intervalMs ?? 2e3;
   const startedAt = Date.now();
@@ -3875,7 +4619,7 @@ async function restorePvcFromVolumeSnapshot(options) {
 import { execFileSync as execFileSync3 } from "child_process";
 import { mkdir as mkdir3 } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import { delimiter as delimiter3, join as join6 } from "path";
+import { delimiter as delimiter3, join as join7 } from "path";
 import * as automation from "@pulumi/pulumi/automation/index.js";
 import { PulumiCommand } from "@pulumi/pulumi/automation/index.js";
 
@@ -4143,6 +4887,29 @@ function baseVolumes(configMapName) {
     { name: RUNNER_AGENTS_VOLUME_NAME, emptyDir: {} }
   ];
 }
+function isAgentSandboxBackend2(config) {
+  return (config.deployments?.backend ?? "agent-sandbox") === "agent-sandbox";
+}
+function hasKeys(value) {
+  return Boolean(value && typeof value === "object" && Object.keys(value).length > 0);
+}
+function resolveSchedulingConfig(config, agent) {
+  const defaults = isAgentSandboxBackend2(config) ? { nodeSelector: { "shadowob.com/sandbox-ready": "true" } } : {};
+  const globalScheduling = config.deployments?.scheduling ?? {};
+  const agentScheduling = agent.scheduling ?? {};
+  const nodeSelector = {
+    ...defaults.nodeSelector ?? {},
+    ...globalScheduling.nodeSelector ?? {},
+    ...agentScheduling.nodeSelector ?? {}
+  };
+  const affinity = agentScheduling.affinity ?? globalScheduling.affinity;
+  const tolerations = agentScheduling.tolerations ?? globalScheduling.tolerations;
+  return {
+    ...Object.keys(nodeSelector).length > 0 ? { nodeSelector } : {},
+    ...hasKeys(affinity) ? { affinity } : {},
+    ...tolerations && tolerations.length > 0 ? { tolerations } : {}
+  };
+}
 function buildAgentPodSpec(options) {
   const runtime = getRuntime(options.agent.runtime);
   const image = options.agent.image ?? runtime.defaultImage;
@@ -4237,6 +5004,7 @@ function buildAgentPodSpec(options) {
     initContainers,
     containers,
     volumes,
+    scheduling: resolveSchedulingConfig(options.config, options.agent),
     pluginArtifacts
   };
 }
@@ -4334,6 +5102,9 @@ function createAgentDeployment(options) {
             securityContext: buildSecurityContext(),
             containers: pod.containers,
             volumes: pod.volumes,
+            nodeSelector: pod.scheduling.nodeSelector,
+            affinity: pod.scheduling.affinity,
+            tolerations: pod.scheduling.tolerations,
             restartPolicy: "Always"
           }
         }
@@ -4539,6 +5310,9 @@ function buildAgentSandboxTemplateManifest(options) {
           securityContext: buildSecurityContext(),
           containers: options.pod.containers,
           volumes: options.pod.volumes,
+          nodeSelector: options.pod.scheduling.nodeSelector,
+          affinity: options.pod.scheduling.affinity,
+          tolerations: options.pod.scheduling.tolerations,
           restartPolicy: "Always"
         }
       },
@@ -4626,18 +5400,18 @@ function createConfigResources(options) {
 }
 
 // src/infra/hash.ts
-import { createHash as createHash2 } from "crypto";
-function stableStringify(value) {
+import { createHash as createHash3 } from "crypto";
+function stableStringify2(value) {
   if (Array.isArray(value)) {
-    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    return `[${value.map((item) => stableStringify2(item)).join(",")}]`;
   }
   if (value && typeof value === "object") {
-    return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
+    return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stableStringify2(item)}`).join(",")}}`;
   }
   return JSON.stringify(value);
 }
 function stableHash(value) {
-  return createHash2("sha256").update(stableStringify(value)).digest("hex");
+  return createHash3("sha256").update(stableStringify2(value)).digest("hex");
 }
 
 // src/infra/networking.ts
@@ -4737,6 +5511,9 @@ function classifyEnv(registrySecretEnv, mergedEnv) {
   }
   return { plainEnv, secretData };
 }
+function omitEnvKeys(env, keys) {
+  for (const key of keys) delete env[key];
+}
 function runtimePackageEnvDefaults(options) {
   const env = {};
   if (!options.currentEnv.SHADOW_SLASH_COMMANDS_PATH) {
@@ -4759,6 +5536,7 @@ function buildAgentRuntimePackage(options) {
     ...agent.env ?? {},
     ...extraEnv ?? {}
   };
+  const runtimeEnvOmitKeys = collectPluginRuntimeEnvOmitKeys(agent, config, cwd, runtimeEnv);
   const runtimeExtensions = collectPluginRuntimeExtensions(agent, config, cwd, runtimeEnv);
   const mergedEnv = {
     ...collectPluginBuildEnvVars(agent, config, cwd, runtimeEnv),
@@ -4784,6 +5562,7 @@ function buildAgentRuntimePackage(options) {
   if (runtimeArtifacts.provisionSecrets) {
     Object.assign(mergedEnv, runtimeArtifacts.provisionSecrets);
   }
+  omitEnvKeys(mergedEnv, runtimeEnvOmitKeys);
   const { plainEnv, secretData } = classifyEnv(registrySecretEnv, mergedEnv);
   return {
     runtimeKind: runtime.runtimeKind,
@@ -4796,10 +5575,9 @@ function buildAgentRuntimePackage(options) {
 }
 
 // src/infra/shared.ts
-import { readFileSync as readFileSync9 } from "fs";
 import * as k8s5 from "@pulumi/kubernetes";
 function createSharedResources(options) {
-  const providerConfig = options.kubeConfigPath ? { kubeconfig: readFileSync9(options.kubeConfigPath, "utf8") } : {
+  const providerConfig = options.kubeConfigPath ? { kubeconfig: readKubeconfigFile(options.kubeConfigPath) } : {
     context: options.kubeContext ?? process.env.KUBECONFIG_CONTEXT ?? process.env.K8S_CONTEXT ?? "rancher-desktop"
   };
   const provider = new k8s5.Provider("k8s-provider", providerConfig);
@@ -5191,13 +5969,13 @@ function getNonEmptyEnv(name) {
   return trimmed.length > 0 ? trimmed : void 0;
 }
 function getDefaultStateDir() {
-  return getNonEmptyEnv("PULUMI_BACKEND_URL") ? "" : join6(homedir5(), ".shadowob", "pulumi");
+  return getNonEmptyEnv("PULUMI_BACKEND_URL") ? "" : join7(homedir5(), ".shadowob", "pulumi");
 }
 function resolvePulumiBackendUrl(stateDir) {
   return getNonEmptyEnv("PULUMI_BACKEND_URL") ?? (stateDir ? `file://${stateDir}` : void 0);
 }
 function ensurePulumiCliOnPath(cliRoot) {
-  const binDir = join6(cliRoot, "bin");
+  const binDir = join7(cliRoot, "bin");
   const currentPath = process.env.PATH ?? "";
   const parts = currentPath.split(delimiter3).filter(Boolean);
   if (!parts.includes(binDir)) {
@@ -5227,8 +6005,8 @@ ${stderr}` : ""}`
   }
 }
 async function getOrCreateStack(options) {
-  const cliRoot = join6(homedir5(), ".shadowob", "pulumi", "cli");
-  const pulumiHome = join6(homedir5(), ".shadowob", "pulumi", "home");
+  const cliRoot = join7(homedir5(), ".shadowob", "pulumi", "cli");
+  const pulumiHome = join7(homedir5(), ".shadowob", "pulumi", "home");
   const infraOpts = {
     config: options.config,
     namespace: options.namespace,
@@ -5419,11 +6197,14 @@ var K8sService = class {
     });
   }
   async waitForAgentSandboxReady(options) {
-    return waitForAgentSandboxReady(options);
+    return waitForAgentSandboxReady2(options);
   }
   async waitForAgentSandboxPaused(options) {
     return waitForAgentSandboxPaused(options);
   }
+  checkAgentSandboxPreflight(options) {
+    return checkAgentSandboxPreflight(options);
+  }
   async restorePvcFromVolumeSnapshot(options) {
     await restorePvcFromVolumeSnapshot(options);
   }