@shadowob/cloud 1.1.6 → 1.1.8

package/dist/index.d.ts

@@ -1010,6 +1010,7 @@ interface SharedWorkspaceConfig {
     accessMode?: 'ReadWriteOnce' | 'ReadWriteMany' | 'ReadOnlyMany';
 }
 type CloudWorkloadBackend = 'agent-sandbox' | 'deployment';
+type CloudWorkloadBackendPolicy = 'sandbox-required' | 'sandbox-preferred' | 'deployment-only';
 type SandboxBackupDriver = 'volumeSnapshot' | 'restic';
 type SandboxWarmPoolUpdateStrategy = 'OnReplenish' | 'Recreate';
 interface AgentSandboxStateConfig {
@@ -1054,7 +1055,7 @@ interface AgentSandboxWarmPoolConfig {
     updateStrategy?: SandboxWarmPoolUpdateStrategy;
 }
 interface AgentSandboxConfig {
-    /** RuntimeClass used by sandbox pods. Defaults to gvisor. */
+    /** RuntimeClass used by sandbox pods. Defaults to gvisor unless a managed cluster injects one. */
     runtimeClassName?: string;
     /** Per-agent OpenClaw state volume config. */
     state?: AgentSandboxStateConfig;
@@ -1065,6 +1066,14 @@ interface AgentSandboxConfig {
     /** Warm pool config. */
     warmPool?: AgentSandboxWarmPoolConfig;
 }
+interface AgentSchedulingConfig {
+    /** Kubernetes nodeSelector applied to agent pods. */
+    nodeSelector?: Record<string, string>;
+    /** Kubernetes affinity applied to agent pods. */
+    affinity?: Record<string, unknown>;
+    /** Kubernetes tolerations applied to agent pods. */
+    tolerations?: Array<Record<string, unknown>>;
+}
 /**
  * Agent-level configuration that can extend a base config.
  */
@@ -1167,6 +1176,8 @@ interface AgentDeployment {
     networking?: AgentNetworking;
     /** agent-sandbox backend options. */
     sandbox?: AgentSandboxConfig;
+    /** Per-agent scheduling overrides. */
+    scheduling?: AgentSchedulingConfig;
     /**
      * Agent configuration version (semver).
      * Recorded in K8s Deployment annotations for rollback tracking.
@@ -1183,8 +1194,17 @@ interface DeploymentsConfig {
     namespace?: string;
     /** Kubernetes workload backend. Defaults to agent-sandbox for new deployments. */
     backend?: CloudWorkloadBackend;
+    /**
+     * Backend selection policy.
+     * - sandbox-required: fail fast if agent-sandbox is unavailable.
+     * - sandbox-preferred: use agent-sandbox when preflight passes, otherwise fall back to Deployment.
+     * - deployment-only: always use Kubernetes Deployment.
+     */
+    backendPolicy?: CloudWorkloadBackendPolicy;
     /** Default agent-sandbox options inherited by agents. */
     sandbox?: AgentSandboxConfig;
+    /** Default scheduling applied to all agent pods. */
+    scheduling?: AgentSchedulingConfig;
     /** Agent deployments */
     agents: AgentDeployment[];
 }
@@ -1256,6 +1276,39 @@ interface CloudSkillsConfig {
     entries?: CloudSkillEntry[];
 }
 
+/**
+ * Cloud template routines — scheduled agent work. Delivery surfaces are owned
+ * by plugins so template routines stay independent from any one channel system.
+ */
+
+interface CloudRoutineSchedule {
+    /** Cron expression in the deployment timezone, e.g. "0 9 * * *". */
+    cron?: string;
+    /** Human interval supported by runtime syncers, e.g. "15m", "1h", "1d". */
+    interval?: string;
+    /** IANA timezone for cron evaluation. Defaults to deployment runtime context. */
+    timezone?: string;
+    /** Maximum overlapping runs for this routine. Defaults to the runtime's behavior. */
+    maxConcurrentRuns?: number & tags.Type<'uint32'>;
+}
+interface CloudRoutineConfig {
+    /** Stable routine id. Used as the sync key in runtime cron stores. */
+    id: string;
+    /** Agent deployment id that owns the routine. */
+    agentId: string;
+    /** Human-readable label for dashboards/runtime UIs. */
+    title?: string;
+    /** Optional operator-facing description. */
+    description?: string;
+    /** Disable without removing the template definition. */
+    enabled?: boolean;
+    /** Schedule definition. At least one of cron or interval should be set. */
+    schedule: CloudRoutineSchedule;
+    /** Prompt/task sent to the agent when the routine fires. */
+    prompt: string;
+    metadata?: Record<string, unknown>;
+}
+
 /**
  * Top-level CloudConfig — the root shadowob-cloud.json schema.
  */
@@ -1307,6 +1360,12 @@ interface CloudConfig {
      * }
      */
     i18n?: Record<string, Record<string, string>>;
+    /**
+     * Scheduled routines owned by template agents.
+     * Delivery surfaces are contributed by plugins, so this section remains
+     * independent from Shadow, Slack, webhooks, or other channel providers.
+     */
+    routines?: CloudRoutineConfig[];
     /**
      * Team / agent pack definition.
      * Groups agents with shared defaults.
@@ -1439,6 +1498,15 @@ interface PluginMCPServer {
 interface PluginRuntimeDependency {
     id: string;
     kind: 'npm-global' | 'system-package' | 'binary' | 'shell';
+    /**
+     * Install order within the runtime asset init container.
+     *
+     * Defaults to `pre-source`, which preserves the historical behavior where
+     * dependencies are installed before external skill/subagent sources are
+     * copied. Use `post-source` for commands that need files from mounted
+     * skill sources, such as package installs inside a checked-out skill bundle.
+     */
+    phase?: 'pre-source' | 'post-source';
     packages?: string[];
     command?: string[];
     targetPath?: string;
@@ -1580,11 +1648,24 @@ interface PluginShadowobRuntime {
     defaultAccountEnvKey?: string;
     capabilities?: Record<string, unknown>;
 }
+interface PluginRoutineDelivery {
+    /** Cloud routine id this plugin wires to an external delivery surface. */
+    routineId: string;
+    /** Plugin that owns the delivery semantics, e.g. "shadowob". */
+    pluginId: string;
+    /** Plugin-defined delivery kind, e.g. "channel". */
+    kind: string;
+    /** Runtime-readable target metadata. Keep secrets as env keys/placeholders. */
+    target: Record<string, unknown>;
+    /** Optional env placeholders needed by a runtime bridge for this delivery. */
+    env?: Record<string, string>;
+}
 interface PluginRuntimeExtension {
     openclaw?: {
         manifestPatches?: PluginOpenClawManifestPatch[];
     };
     shadowob?: PluginShadowobRuntime;
+    routineDeliveries?: PluginRoutineDelivery[];
     artifacts?: PluginRuntimeArtifact[];
     runtimeDependencies?: PluginRuntimeDependency[];
     skillSources?: PluginRuntimeSource[];
@@ -1850,6 +1931,13 @@ interface VolumeSnapshotReadyStatus {
     ready: boolean;
     error?: string;
 }
+interface AgentSandboxPreflightResult {
+    ok: boolean;
+    missing: string[];
+    warnings: string[];
+    runtimeClassName?: string;
+    runtimeClassNames?: string[];
+}
 declare function resolveSandboxNameAsync(namespace: string, agentName: string, kubeconfig?: string): Promise<string>;
 declare function getAgentSandboxStatusAsync(namespace: string, agentName: string, kubeconfig?: string): Promise<AgentSandboxStatus>;
 declare function scaleAgentSandboxAsync(namespace: string, agentName: string, replicas: 0 | 1, kubeconfig?: string): Promise<void>;
@@ -2012,36 +2100,376 @@ declare const NodeConfigSchema: z.ZodEffects<z.ZodObject<{
     user: z.ZodString;
     /** Path to SSH private key (supports ~) — mutually inclusive with or exclusive of password */
     sshKeyPath: z.ZodOptional<z.ZodString>;
+    /** SSH private key passphrase — use ${env:VAR} to avoid storing plaintext */
+    sshKeyPassphrase: z.ZodOptional<z.ZodString>;
+    /**
+     * 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.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>;
     /** SSH password — use ${env:VAR} to avoid storing plaintext */
     password: z.ZodOptional<z.ZodString>;
+    /** Optional per-node k3s installer overrides for mixed-region clusters. */
+    install: z.ZodOptional<z.ZodObject<{
+        /** k3s release version. Example: v1.35.4+k3s1 */
+        k3sVersion: z.ZodOptional<z.ZodString>;
+        /** k3s release channel used when k3sVersion is omitted. */
+        k3sChannel: z.ZodOptional<z.ZodString>;
+        /** k3s channel endpoint used by the official install script. */
+        k3sChannelUrl: z.ZodOptional<z.ZodString>;
+        /** k3s release artifact URL prefix. */
+        k3sArtifactUrl: z.ZodOptional<z.ZodString>;
+        /** Common mirror shortcut. "cn" maps to Rancher's China mirror. */
+        k3sMirror: z.ZodOptional<z.ZodString>;
+        /** Registry prefix used by k3s for bundled system images. */
+        systemDefaultRegistry: z.ZodOptional<z.ZodString>;
+        /** Sandbox pause image used by k3s/containerd. Useful when Docker Hub is unreachable. */
+        pauseImage: z.ZodOptional<z.ZodString>;
+        /** Optional k3s containerd registry mirrors/auth config for workload images. */
+        registries: z.ZodOptional<z.ZodObject<{
+            /**
+             * k3s containerd mirrors. Written to /etc/rancher/k3s/registries.yaml as JSON/YAML.
+             * Example: { "docker.io": { "endpoint": ["https://registry-1.docker.io"] } }
+             */
+            mirrors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                endpoint: z.ZodArray<z.ZodString, "many">;
+            }, "strip", z.ZodTypeAny, {
+                endpoint: string[];
+            }, {
+                endpoint: string[];
+            }>>>;
+            configs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                auth: z.ZodOptional<z.ZodObject<{
+                    username: z.ZodOptional<z.ZodString>;
+                    password: z.ZodOptional<z.ZodString>;
+                    auth: z.ZodOptional<z.ZodString>;
+                    identityToken: z.ZodOptional<z.ZodString>;
+                }, "strip", z.ZodTypeAny, {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                }, {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                }>>;
+                tls: z.ZodOptional<z.ZodObject<{
+                    caFile: z.ZodOptional<z.ZodString>;
+                    certFile: z.ZodOptional<z.ZodString>;
+                    keyFile: z.ZodOptional<z.ZodString>;
+                    insecureSkipVerify: z.ZodOptional<z.ZodBoolean>;
+                }, "strip", z.ZodTypeAny, {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                }, {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                }>>;
+            }, "strip", z.ZodTypeAny, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }>>>;
+        }, "strip", z.ZodTypeAny, {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        }, {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
+    }, {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
+    }>>;
+    /** Region label applied during cluster init/apply, e.g. cn or us. */
+    region: z.ZodOptional<z.ZodString>;
+    /** Extra Kubernetes node labels applied during cluster init/apply. */
+    labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** Per-node feature flags used for mixed-capability clusters. */
+    features: z.ZodOptional<z.ZodObject<{
+        sandbox: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        sandbox?: boolean | undefined;
+    }, {
+        sandbox?: boolean | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     host: string;
     port: number;
     user: string;
     role: "master" | "worker";
     password?: string | undefined;
+    features?: {
+        sandbox?: boolean | undefined;
+    } | undefined;
+    install?: {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
+    } | undefined;
     sshKeyPath?: string | undefined;
+    sshKeyPassphrase?: string | undefined;
+    sshAgent?: string | boolean | undefined;
+    region?: string | undefined;
+    labels?: Record<string, string> | undefined;
 }, {
     host: string;
     user: string;
     role: "master" | "worker";
     password?: string | undefined;
     port?: number | undefined;
+    features?: {
+        sandbox?: boolean | undefined;
+    } | undefined;
+    install?: {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
+    } | undefined;
     sshKeyPath?: string | undefined;
+    sshKeyPassphrase?: string | undefined;
+    sshAgent?: string | boolean | undefined;
+    region?: string | undefined;
+    labels?: Record<string, string> | undefined;
 }>, {
     host: string;
     port: number;
     user: string;
     role: "master" | "worker";
     password?: string | undefined;
+    features?: {
+        sandbox?: boolean | undefined;
+    } | undefined;
+    install?: {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
+    } | undefined;
     sshKeyPath?: string | undefined;
+    sshKeyPassphrase?: string | undefined;
+    sshAgent?: string | boolean | undefined;
+    region?: string | undefined;
+    labels?: Record<string, string> | undefined;
 }, {
     host: string;
     user: string;
     role: "master" | "worker";
     password?: string | undefined;
     port?: number | undefined;
+    features?: {
+        sandbox?: boolean | undefined;
+    } | undefined;
+    install?: {
+        k3sVersion?: string | undefined;
+        k3sChannel?: string | undefined;
+        k3sChannelUrl?: string | undefined;
+        k3sArtifactUrl?: string | undefined;
+        k3sMirror?: string | undefined;
+        systemDefaultRegistry?: string | undefined;
+        pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
+    } | undefined;
     sshKeyPath?: string | undefined;
+    sshKeyPassphrase?: string | undefined;
+    sshAgent?: string | boolean | undefined;
+    region?: string | undefined;
+    labels?: Record<string, string> | undefined;
 }>;
 type NodeConfig = z.infer<typeof NodeConfigSchema>;
 declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
@@ -2062,36 +2490,376 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         user: z.ZodString;
         /** Path to SSH private key (supports ~) — mutually inclusive with or exclusive of password */
         sshKeyPath: z.ZodOptional<z.ZodString>;
+        /** SSH private key passphrase — use ${env:VAR} to avoid storing plaintext */
+        sshKeyPassphrase: z.ZodOptional<z.ZodString>;
+        /**
+         * 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.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>;
         /** SSH password — use ${env:VAR} to avoid storing plaintext */
         password: z.ZodOptional<z.ZodString>;
+        /** Optional per-node k3s installer overrides for mixed-region clusters. */
+        install: z.ZodOptional<z.ZodObject<{
+            /** k3s release version. Example: v1.35.4+k3s1 */
+            k3sVersion: z.ZodOptional<z.ZodString>;
+            /** k3s release channel used when k3sVersion is omitted. */
+            k3sChannel: z.ZodOptional<z.ZodString>;
+            /** k3s channel endpoint used by the official install script. */
+            k3sChannelUrl: z.ZodOptional<z.ZodString>;
+            /** k3s release artifact URL prefix. */
+            k3sArtifactUrl: z.ZodOptional<z.ZodString>;
+            /** Common mirror shortcut. "cn" maps to Rancher's China mirror. */
+            k3sMirror: z.ZodOptional<z.ZodString>;
+            /** Registry prefix used by k3s for bundled system images. */
+            systemDefaultRegistry: z.ZodOptional<z.ZodString>;
+            /** Sandbox pause image used by k3s/containerd. Useful when Docker Hub is unreachable. */
+            pauseImage: z.ZodOptional<z.ZodString>;
+            /** Optional k3s containerd registry mirrors/auth config for workload images. */
+            registries: z.ZodOptional<z.ZodObject<{
+                /**
+                 * k3s containerd mirrors. Written to /etc/rancher/k3s/registries.yaml as JSON/YAML.
+                 * Example: { "docker.io": { "endpoint": ["https://registry-1.docker.io"] } }
+                 */
+                mirrors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    endpoint: z.ZodArray<z.ZodString, "many">;
+                }, "strip", z.ZodTypeAny, {
+                    endpoint: string[];
+                }, {
+                    endpoint: string[];
+                }>>>;
+                configs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    auth: z.ZodOptional<z.ZodObject<{
+                        username: z.ZodOptional<z.ZodString>;
+                        password: z.ZodOptional<z.ZodString>;
+                        auth: z.ZodOptional<z.ZodString>;
+                        identityToken: z.ZodOptional<z.ZodString>;
+                    }, "strip", z.ZodTypeAny, {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    }, {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    }>>;
+                    tls: z.ZodOptional<z.ZodObject<{
+                        caFile: z.ZodOptional<z.ZodString>;
+                        certFile: z.ZodOptional<z.ZodString>;
+                        keyFile: z.ZodOptional<z.ZodString>;
+                        insecureSkipVerify: z.ZodOptional<z.ZodBoolean>;
+                    }, "strip", z.ZodTypeAny, {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    }, {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    }>>;
+                }, "strip", z.ZodTypeAny, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }>>>;
+            }, "strip", z.ZodTypeAny, {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            }, {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            k3sVersion?: string | undefined;
+            k3sChannel?: string | undefined;
+            k3sChannelUrl?: string | undefined;
+            k3sArtifactUrl?: string | undefined;
+            k3sMirror?: string | undefined;
+            systemDefaultRegistry?: string | undefined;
+            pauseImage?: string | undefined;
+            registries?: {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            } | undefined;
+        }, {
+            k3sVersion?: string | undefined;
+            k3sChannel?: string | undefined;
+            k3sChannelUrl?: string | undefined;
+            k3sArtifactUrl?: string | undefined;
+            k3sMirror?: string | undefined;
+            systemDefaultRegistry?: string | undefined;
+            pauseImage?: string | undefined;
+            registries?: {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            } | undefined;
+        }>>;
+        /** Region label applied during cluster init/apply, e.g. cn or us. */
+        region: z.ZodOptional<z.ZodString>;
+        /** Extra Kubernetes node labels applied during cluster init/apply. */
+        labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** Per-node feature flags used for mixed-capability clusters. */
+        features: z.ZodOptional<z.ZodObject<{
+            sandbox: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            sandbox?: boolean | undefined;
+        }, {
+            sandbox?: boolean | undefined;
+        }>>;
     }, "strip", z.ZodTypeAny, {
         host: string;
         port: number;
         user: string;
         role: "master" | "worker";
         password?: string | undefined;
+        features?: {
+            sandbox?: boolean | undefined;
+        } | undefined;
+        install?: {
+            k3sVersion?: string | undefined;
+            k3sChannel?: string | undefined;
+            k3sChannelUrl?: string | undefined;
+            k3sArtifactUrl?: string | undefined;
+            k3sMirror?: string | undefined;
+            systemDefaultRegistry?: string | undefined;
+            pauseImage?: string | undefined;
+            registries?: {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            } | undefined;
+        } | undefined;
         sshKeyPath?: string | undefined;
+        sshKeyPassphrase?: string | undefined;
+        sshAgent?: string | boolean | undefined;
+        region?: string | undefined;
+        labels?: Record<string, string> | undefined;
     }, {
         host: string;
         user: string;
         role: "master" | "worker";
         password?: string | undefined;
         port?: number | undefined;
+        features?: {
+            sandbox?: boolean | undefined;
+        } | undefined;
+        install?: {
+            k3sVersion?: string | undefined;
+            k3sChannel?: string | undefined;
+            k3sChannelUrl?: string | undefined;
+            k3sArtifactUrl?: string | undefined;
+            k3sMirror?: string | undefined;
+            systemDefaultRegistry?: string | undefined;
+            pauseImage?: string | undefined;
+            registries?: {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            } | undefined;
+        } | undefined;
         sshKeyPath?: string | undefined;
+        sshKeyPassphrase?: string | undefined;
+        sshAgent?: string | boolean | undefined;
+        region?: string | undefined;
+        labels?: Record<string, string> | undefined;
     }>, {
         host: string;
         port: number;
         user: string;
         role: "master" | "worker";
         password?: string | undefined;
+        features?: {
+            sandbox?: boolean | undefined;
+        } | undefined;
+        install?: {
+            k3sVersion?: string | undefined;
+            k3sChannel?: string | undefined;
+            k3sChannelUrl?: string | undefined;
+            k3sArtifactUrl?: string | undefined;
+            k3sMirror?: string | undefined;
+            systemDefaultRegistry?: string | undefined;
+            pauseImage?: string | undefined;
+            registries?: {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            } | undefined;
+        } | undefined;
         sshKeyPath?: string | undefined;
+        sshKeyPassphrase?: string | undefined;
+        sshAgent?: string | boolean | undefined;
+        region?: string | undefined;
+        labels?: Record<string, string> | undefined;
     }, {
         host: string;
         user: string;
         role: "master" | "worker";
         password?: string | undefined;
         port?: number | undefined;
+        features?: {
+            sandbox?: boolean | undefined;
+        } | undefined;
+        install?: {
+            k3sVersion?: string | undefined;
+            k3sChannel?: string | undefined;
+            k3sChannelUrl?: string | undefined;
+            k3sArtifactUrl?: string | undefined;
+            k3sMirror?: string | undefined;
+            systemDefaultRegistry?: string | undefined;
+            pauseImage?: string | undefined;
+            registries?: {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            } | undefined;
+        } | undefined;
         sshKeyPath?: string | undefined;
+        sshKeyPassphrase?: string | undefined;
+        sshAgent?: string | boolean | undefined;
+        region?: string | undefined;
+        labels?: Record<string, string> | undefined;
     }>, "many">;
     /** Optional k3s installer settings for restricted networks or pinned versions. */
     install: z.ZodOptional<z.ZodObject<{
@@ -2109,6 +2877,116 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         systemDefaultRegistry: z.ZodOptional<z.ZodString>;
         /** Sandbox pause image used by k3s/containerd. Useful when Docker Hub is unreachable. */
         pauseImage: z.ZodOptional<z.ZodString>;
+        /** Optional k3s containerd registry mirrors/auth config for workload images. */
+        registries: z.ZodOptional<z.ZodObject<{
+            /**
+             * k3s containerd mirrors. Written to /etc/rancher/k3s/registries.yaml as JSON/YAML.
+             * Example: { "docker.io": { "endpoint": ["https://registry-1.docker.io"] } }
+             */
+            mirrors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                endpoint: z.ZodArray<z.ZodString, "many">;
+            }, "strip", z.ZodTypeAny, {
+                endpoint: string[];
+            }, {
+                endpoint: string[];
+            }>>>;
+            configs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                auth: z.ZodOptional<z.ZodObject<{
+                    username: z.ZodOptional<z.ZodString>;
+                    password: z.ZodOptional<z.ZodString>;
+                    auth: z.ZodOptional<z.ZodString>;
+                    identityToken: z.ZodOptional<z.ZodString>;
+                }, "strip", z.ZodTypeAny, {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                }, {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                }>>;
+                tls: z.ZodOptional<z.ZodObject<{
+                    caFile: z.ZodOptional<z.ZodString>;
+                    certFile: z.ZodOptional<z.ZodString>;
+                    keyFile: z.ZodOptional<z.ZodString>;
+                    insecureSkipVerify: z.ZodOptional<z.ZodBoolean>;
+                }, "strip", z.ZodTypeAny, {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                }, {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                }>>;
+            }, "strip", z.ZodTypeAny, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }>>>;
+        }, "strip", z.ZodTypeAny, {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        }, {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        }>>;
     }, "strip", z.ZodTypeAny, {
         k3sVersion?: string | undefined;
         k3sChannel?: string | undefined;
@@ -2117,6 +2995,25 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         k3sMirror?: string | undefined;
         systemDefaultRegistry?: string | undefined;
         pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
     }, {
         k3sVersion?: string | undefined;
         k3sChannel?: string | undefined;
@@ -2125,6 +3022,148 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         k3sMirror?: string | undefined;
         systemDefaultRegistry?: string | undefined;
         pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
+    }>>;
+    /** Optional cluster capabilities managed by cluster init/apply. */
+    features: z.ZodOptional<z.ZodObject<{
+        /** agent-sandbox CRDs/controller/runtime-class management. */
+        sandbox: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodObject<{
+            /** Enable agent-sandbox as a cluster capability. */
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            /** Install/upgrade the upstream CRDs and controller during cluster init/apply. */
+            install: z.ZodDefault<z.ZodBoolean>;
+            /** Pinned upstream agent-sandbox release used to build default manifest URLs. */
+            version: z.ZodDefault<z.ZodString>;
+            /**
+             * Optional manifest URLs. Defaults to the upstream release manifest.yaml and extensions.yaml.
+             * Use mirrored URLs for restricted networks.
+             */
+            manifestUrls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            /** Optional controller image override, useful for domestic/private registries. */
+            controllerImage: z.ZodOptional<z.ZodString>;
+            /** RuntimeClass injected into generated Cloud SaaS sandbox configs. */
+            runtimeClassName: z.ZodDefault<z.ZodString>;
+            /** Create RuntimeClass automatically. Disable when the cluster already provides gvisor/runsc. */
+            createRuntimeClass: z.ZodDefault<z.ZodBoolean>;
+            /** RuntimeClass handler used when createRuntimeClass is true. */
+            runtimeClassHandler: z.ZodDefault<z.ZodString>;
+            /** Wait timeout for CRDs/controller readiness. */
+            waitTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+            /** Fail cluster init/apply when sandbox cannot be verified. */
+            required: z.ZodDefault<z.ZodBoolean>;
+            /** Label selector injected into sandbox workloads unless templates override it. */
+            nodeSelector: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            /** Run a real SandboxTemplate/SandboxClaim smoke after install/verify. */
+            smokeTest: z.ZodDefault<z.ZodBoolean>;
+            /** Image used by the optional smoke test. Mirror this for restricted networks. */
+            smokeImage: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            version: string;
+            enabled: boolean;
+            required: boolean;
+            install: boolean;
+            runtimeClassName: string;
+            createRuntimeClass: boolean;
+            runtimeClassHandler: string;
+            waitTimeoutSeconds: number;
+            nodeSelector: Record<string, string>;
+            smokeTest: boolean;
+            smokeImage: string;
+            manifestUrls?: string[] | undefined;
+            controllerImage?: string | undefined;
+        }, {
+            version?: string | undefined;
+            enabled?: boolean | undefined;
+            required?: boolean | undefined;
+            install?: boolean | undefined;
+            manifestUrls?: string[] | undefined;
+            controllerImage?: string | undefined;
+            runtimeClassName?: string | undefined;
+            createRuntimeClass?: boolean | undefined;
+            runtimeClassHandler?: string | undefined;
+            waitTimeoutSeconds?: number | undefined;
+            nodeSelector?: Record<string, string> | undefined;
+            smokeTest?: boolean | undefined;
+            smokeImage?: string | undefined;
+        }>, {
+            version: string;
+            enabled: boolean;
+            required: boolean;
+            install: boolean;
+            runtimeClassName: string;
+            createRuntimeClass: boolean;
+            runtimeClassHandler: string;
+            waitTimeoutSeconds: number;
+            nodeSelector: Record<string, string>;
+            smokeTest: boolean;
+            smokeImage: string;
+            manifestUrls?: string[] | undefined;
+            controllerImage?: string | undefined;
+        }, {
+            version?: string | undefined;
+            enabled?: boolean | undefined;
+            required?: boolean | undefined;
+            install?: boolean | undefined;
+            manifestUrls?: string[] | undefined;
+            controllerImage?: string | undefined;
+            runtimeClassName?: string | undefined;
+            createRuntimeClass?: boolean | undefined;
+            runtimeClassHandler?: string | undefined;
+            waitTimeoutSeconds?: number | undefined;
+            nodeSelector?: Record<string, string> | undefined;
+            smokeTest?: boolean | undefined;
+            smokeImage?: string | undefined;
+        }>]>>;
+    }, "strip", z.ZodTypeAny, {
+        sandbox?: boolean | {
+            version: string;
+            enabled: boolean;
+            required: boolean;
+            install: boolean;
+            runtimeClassName: string;
+            createRuntimeClass: boolean;
+            runtimeClassHandler: string;
+            waitTimeoutSeconds: number;
+            nodeSelector: Record<string, string>;
+            smokeTest: boolean;
+            smokeImage: string;
+            manifestUrls?: string[] | undefined;
+            controllerImage?: string | undefined;
+        } | undefined;
+    }, {
+        sandbox?: boolean | {
+            version?: string | undefined;
+            enabled?: boolean | undefined;
+            required?: boolean | undefined;
+            install?: boolean | undefined;
+            manifestUrls?: string[] | undefined;
+            controllerImage?: string | undefined;
+            runtimeClassName?: string | undefined;
+            createRuntimeClass?: boolean | undefined;
+            runtimeClassHandler?: string | undefined;
+            waitTimeoutSeconds?: number | undefined;
+            nodeSelector?: Record<string, string> | undefined;
+            smokeTest?: boolean | undefined;
+            smokeImage?: string | undefined;
+        } | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
@@ -2135,8 +3174,60 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         user: string;
         role: "master" | "worker";
         password?: string | undefined;
+        features?: {
+            sandbox?: boolean | undefined;
+        } | undefined;
+        install?: {
+            k3sVersion?: string | undefined;
+            k3sChannel?: string | undefined;
+            k3sChannelUrl?: string | undefined;
+            k3sArtifactUrl?: string | undefined;
+            k3sMirror?: string | undefined;
+            systemDefaultRegistry?: string | undefined;
+            pauseImage?: string | undefined;
+            registries?: {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            } | undefined;
+        } | undefined;
         sshKeyPath?: string | undefined;
+        sshKeyPassphrase?: string | undefined;
+        sshAgent?: string | boolean | undefined;
+        region?: string | undefined;
+        labels?: Record<string, string> | undefined;
     }[];
+    features?: {
+        sandbox?: boolean | {
+            version: string;
+            enabled: boolean;
+            required: boolean;
+            install: boolean;
+            runtimeClassName: string;
+            createRuntimeClass: boolean;
+            runtimeClassHandler: string;
+            waitTimeoutSeconds: number;
+            nodeSelector: Record<string, string>;
+            smokeTest: boolean;
+            smokeImage: string;
+            manifestUrls?: string[] | undefined;
+            controllerImage?: string | undefined;
+        } | undefined;
+    } | undefined;
     install?: {
         k3sVersion?: string | undefined;
         k3sChannel?: string | undefined;
@@ -2145,6 +3236,25 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         k3sMirror?: string | undefined;
         systemDefaultRegistry?: string | undefined;
         pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
     } | undefined;
     $schema?: string | undefined;
 }, {
@@ -2155,9 +3265,61 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         role: "master" | "worker";
         password?: string | undefined;
         port?: number | undefined;
+        features?: {
+            sandbox?: boolean | undefined;
+        } | undefined;
+        install?: {
+            k3sVersion?: string | undefined;
+            k3sChannel?: string | undefined;
+            k3sChannelUrl?: string | undefined;
+            k3sArtifactUrl?: string | undefined;
+            k3sMirror?: string | undefined;
+            systemDefaultRegistry?: string | undefined;
+            pauseImage?: string | undefined;
+            registries?: {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            } | undefined;
+        } | undefined;
         sshKeyPath?: string | undefined;
+        sshKeyPassphrase?: string | undefined;
+        sshAgent?: string | boolean | undefined;
+        region?: string | undefined;
+        labels?: Record<string, string> | undefined;
     }[];
     provider?: "ssh" | undefined;
+    features?: {
+        sandbox?: boolean | {
+            version?: string | undefined;
+            enabled?: boolean | undefined;
+            required?: boolean | undefined;
+            install?: boolean | undefined;
+            manifestUrls?: string[] | undefined;
+            controllerImage?: string | undefined;
+            runtimeClassName?: string | undefined;
+            createRuntimeClass?: boolean | undefined;
+            runtimeClassHandler?: string | undefined;
+            waitTimeoutSeconds?: number | undefined;
+            nodeSelector?: Record<string, string> | undefined;
+            smokeTest?: boolean | undefined;
+            smokeImage?: string | undefined;
+        } | undefined;
+    } | undefined;
     install?: {
         k3sVersion?: string | undefined;
         k3sChannel?: string | undefined;
@@ -2166,6 +3328,25 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         k3sMirror?: string | undefined;
         systemDefaultRegistry?: string | undefined;
         pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
     } | undefined;
     $schema?: string | undefined;
 }>, {
@@ -2177,8 +3358,60 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         user: string;
         role: "master" | "worker";
         password?: string | undefined;
+        features?: {
+            sandbox?: boolean | undefined;
+        } | undefined;
+        install?: {
+            k3sVersion?: string | undefined;
+            k3sChannel?: string | undefined;
+            k3sChannelUrl?: string | undefined;
+            k3sArtifactUrl?: string | undefined;
+            k3sMirror?: string | undefined;
+            systemDefaultRegistry?: string | undefined;
+            pauseImage?: string | undefined;
+            registries?: {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            } | undefined;
+        } | undefined;
         sshKeyPath?: string | undefined;
+        sshKeyPassphrase?: string | undefined;
+        sshAgent?: string | boolean | undefined;
+        region?: string | undefined;
+        labels?: Record<string, string> | undefined;
     }[];
+    features?: {
+        sandbox?: boolean | {
+            version: string;
+            enabled: boolean;
+            required: boolean;
+            install: boolean;
+            runtimeClassName: string;
+            createRuntimeClass: boolean;
+            runtimeClassHandler: string;
+            waitTimeoutSeconds: number;
+            nodeSelector: Record<string, string>;
+            smokeTest: boolean;
+            smokeImage: string;
+            manifestUrls?: string[] | undefined;
+            controllerImage?: string | undefined;
+        } | undefined;
+    } | undefined;
     install?: {
         k3sVersion?: string | undefined;
         k3sChannel?: string | undefined;
@@ -2187,6 +3420,25 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         k3sMirror?: string | undefined;
         systemDefaultRegistry?: string | undefined;
         pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
     } | undefined;
     $schema?: string | undefined;
 }, {
@@ -2197,9 +3449,61 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         role: "master" | "worker";
         password?: string | undefined;
         port?: number | undefined;
+        features?: {
+            sandbox?: boolean | undefined;
+        } | undefined;
+        install?: {
+            k3sVersion?: string | undefined;
+            k3sChannel?: string | undefined;
+            k3sChannelUrl?: string | undefined;
+            k3sArtifactUrl?: string | undefined;
+            k3sMirror?: string | undefined;
+            systemDefaultRegistry?: string | undefined;
+            pauseImage?: string | undefined;
+            registries?: {
+                mirrors?: Record<string, {
+                    endpoint: string[];
+                }> | undefined;
+                configs?: Record<string, {
+                    auth?: {
+                        password?: string | undefined;
+                        auth?: string | undefined;
+                        username?: string | undefined;
+                        identityToken?: string | undefined;
+                    } | undefined;
+                    tls?: {
+                        caFile?: string | undefined;
+                        certFile?: string | undefined;
+                        keyFile?: string | undefined;
+                        insecureSkipVerify?: boolean | undefined;
+                    } | undefined;
+                }> | undefined;
+            } | undefined;
+        } | undefined;
         sshKeyPath?: string | undefined;
+        sshKeyPassphrase?: string | undefined;
+        sshAgent?: string | boolean | undefined;
+        region?: string | undefined;
+        labels?: Record<string, string> | undefined;
     }[];
     provider?: "ssh" | undefined;
+    features?: {
+        sandbox?: boolean | {
+            version?: string | undefined;
+            enabled?: boolean | undefined;
+            required?: boolean | undefined;
+            install?: boolean | undefined;
+            manifestUrls?: string[] | undefined;
+            controllerImage?: string | undefined;
+            runtimeClassName?: string | undefined;
+            createRuntimeClass?: boolean | undefined;
+            runtimeClassHandler?: string | undefined;
+            waitTimeoutSeconds?: number | undefined;
+            nodeSelector?: Record<string, string> | undefined;
+            smokeTest?: boolean | undefined;
+            smokeImage?: string | undefined;
+        } | undefined;
+    } | undefined;
     install?: {
         k3sVersion?: string | undefined;
         k3sChannel?: string | undefined;
@@ -2208,6 +3512,25 @@ declare const ClusterConfigSchema: z.ZodEffects<z.ZodObject<{
         k3sMirror?: string | undefined;
         systemDefaultRegistry?: string | undefined;
         pauseImage?: string | undefined;
+        registries?: {
+            mirrors?: Record<string, {
+                endpoint: string[];
+            }> | undefined;
+            configs?: Record<string, {
+                auth?: {
+                    password?: string | undefined;
+                    auth?: string | undefined;
+                    username?: string | undefined;
+                    identityToken?: string | undefined;
+                } | undefined;
+                tls?: {
+                    caFile?: string | undefined;
+                    certFile?: string | undefined;
+                    keyFile?: string | undefined;
+                    insecureSkipVerify?: boolean | undefined;
+                } | undefined;
+            }> | undefined;
+        } | undefined;
     } | undefined;
     $schema?: string | undefined;
 }>;
@@ -2219,6 +3542,15 @@ interface ClusterMeta {
     nodeCount: number;
     createdAt: string;
     kubeconfigPath: string;
+    configHash?: string;
+    features?: {
+        sandbox?: {
+            enabled: boolean;
+            version?: string;
+            runtimeClassName?: string;
+            nodeSelector?: Record<string, string>;
+        };
+    };
 }
 
 /**
@@ -2572,6 +3904,11 @@ declare class K8sService {
         timeoutMs?: number;
         intervalMs?: number;
     }): Promise<AgentSandboxStatus>;
+    checkAgentSandboxPreflight(options?: {
+        kubeconfig?: string;
+        runtimeClassName?: string;
+        runtimeClassNames?: string[];
+    }): AgentSandboxPreflightResult;
     restorePvcFromVolumeSnapshot(options: {
         namespace: string;
         pvcName: string;