mlclaw 0.2.3 → 0.3.1

package/dist/mlclaw.mjs

@@ -14629,6 +14629,20 @@ var HubApi = class {
     const raw = await this.requestJson(`/api/spaces/${repoId}/secrets`);
     return new Map(Object.entries(raw));
   }
+  async deleteSpaceSecret(repoId, key) {
+    try {
+      await this.requestJson(`/api/spaces/${repoId}/secrets`, {
+        method: "DELETE",
+        body: JSON.stringify({ key }),
+        headers: { "Content-Type": "application/json" }
+      });
+    } catch (err) {
+      if (err instanceof HubApiError2 && err.status === 404) {
+        return;
+      }
+      throw err;
+    }
+  }
   async restartSpace(repoId, factoryReboot = false) {
     await this.requestJson(`/api/spaces/${repoId}/restart`, {
       method: "POST",
@@ -14660,7 +14674,25 @@ var HubApi = class {
     });
   }
   async getSpaceRuntime(repoId) {
-    return await this.requestJson(`/api/spaces/${repoId}/runtime`);
+    const runtime = await this.requestJson(`/api/spaces/${repoId}/runtime`);
+    if (Array.isArray(runtime.volumes)) {
+      return runtime;
+    }
+    try {
+      const info = await this.requestJson(`/api/spaces/${repoId}`);
+      if (Array.isArray(info.runtime?.volumes)) {
+        return { ...runtime, volumes: info.runtime.volumes };
+      }
+    } catch {
+    }
+    return runtime;
+  }
+  async setSpaceVolumes(repoId, volumes) {
+    await this.requestJson(`/api/spaces/${repoId}/volumes`, {
+      method: "PUT",
+      body: JSON.stringify({ volumes }),
+      headers: { "Content-Type": "application/json" }
+    });
   }
   async fetchSpaceLogs(repoId, kind = "run") {
     const url = `${this.hubUrl}/api/spaces/${repoId}/logs/${kind}`;
@@ -14804,12 +14836,19 @@ function sseDataToText(raw) {
 import fs11 from "node:fs";
 import path12 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-var DEFAULT_OPENCLAW_VERSION = "2026.7.1-beta.2";
+var DEFAULT_OPENCLAW_VERSION = "2026.7.1-beta.5";
+var DEFAULT_BROKERKIT_PLUGIN_VERSION = "0.1.0";
+var DEFAULT_BROKERKIT_VERSION = "fcfc5f2304436d952b18e7c9583bb378d1952776";
 var DEFAULT_RUNTIME_IMAGE_REPOSITORY = "ghcr.io/osolmaz/mlclaw";
 var PACKAGE_METADATA = readPackageMetadata();
 var PACKAGE_VERSION = packageString("version", "unknown");
 var OPENCLAW_VERSION = packageConfigString("openclawVersion", DEFAULT_OPENCLAW_VERSION);
 var OPENCLAW_BASE_IMAGE = `ghcr.io/openclaw/openclaw:${OPENCLAW_VERSION}`;
+var BROKERKIT_PLUGIN_VERSION = packageConfigString(
+  "brokerkitPluginVersion",
+  DEFAULT_BROKERKIT_PLUGIN_VERSION
+);
+var BROKERKIT_VERSION = packageConfigString("brokerkitVersion", DEFAULT_BROKERKIT_VERSION);
 var RUNTIME_IMAGE_REPOSITORY = packageConfigString("runtimeImageRepository", DEFAULT_RUNTIME_IMAGE_REPOSITORY);
 var DEFAULT_RUNTIME_IMAGE_TAG = `${PACKAGE_VERSION}-openclaw-${OPENCLAW_VERSION}`;
 var DEFAULT_RUNTIME_IMAGE = `${RUNTIME_IMAGE_REPOSITORY}:${DEFAULT_RUNTIME_IMAGE_TAG}`;
@@ -14916,6 +14955,7 @@ async function generateSpaceRepo(sourceDir, outDir, options = {}) {
       ["dist/hf-tooling-seed.js", "runtime/hf-tooling-seed.js"],
       ["dist/mlclaw-space-runtime.js", "runtime/mlclaw-space-runtime.js"],
       ["entrypoint.sh", "runtime/entrypoint.sh"],
+      ["hf-broker.scope.json", "runtime/hf-broker.scope.json"],
       ["openclaw.default.json", "runtime/openclaw.default.json"],
       ["scripts/configure-huggingface-model.mjs", "runtime/scripts/configure-huggingface-model.mjs"],
       ["scripts/configure-telegram.mjs", "runtime/scripts/configure-telegram.mjs"],
@@ -14936,14 +14976,33 @@ function imageDockerfile(runtimeImage) {
 `;
 }
 function bundledDockerfile() {
-  return `FROM ${OPENCLAW_BASE_IMAGE}
+  return `ARG BROKERKIT_PLUGIN_VERSION=${BROKERKIT_PLUGIN_VERSION}
+ARG BROKERKIT_VERSION=${BROKERKIT_VERSION}
+
+FROM golang:1.26.5-bookworm AS hf-broker-build
+ARG BROKERKIT_VERSION
+RUN git init /src \\
+  && git -C /src fetch --depth=1 https://github.com/osolmaz/brokerkit.git "$BROKERKIT_VERSION" \\
+  && git -C /src checkout --detach FETCH_HEAD \\
+  && test "$(git -C /src rev-parse HEAD)" = "$BROKERKIT_VERSION" \\
+  && cd /src \\
+  && GOWORK=off go build -trimpath -o /out/hf-broker ./brokers/huggingface/cmd/hf-broker
+
+FROM node:24-bookworm-slim AS brokerkit-plugin-build
+ARG BROKERKIT_VERSION
+RUN apt-get update   && apt-get install -y --no-install-recommends ca-certificates git   && rm -rf /var/lib/apt/lists/*   && git init /src   && git -C /src fetch --depth=1 https://github.com/osolmaz/brokerkit.git "$BROKERKIT_VERSION"   && git -C /src checkout --detach FETCH_HEAD   && test "$(git -C /src rev-parse HEAD)" = "$BROKERKIT_VERSION"
+WORKDIR /src
+RUN corepack enable   && pnpm install --frozen-lockfile   && pnpm --filter openclaw-brokerkit build   && pnpm --filter openclaw-brokerkit pack --pack-destination /out
+
+FROM ${OPENCLAW_BASE_IMAGE}
 
 LABEL org.opencontainers.image.source="https://github.com/osolmaz/mlclaw"
 LABEL org.opencontainers.image.description="ML Claw runtime for OpenClaw on Hugging Face"
 
 USER root
 RUN apt-get update \\
-  && apt-get install -y --no-install-recommends gosu python3 python3-pip python3-venv zstd \\
+  && apt-get install -y --no-install-recommends ca-certificates gosu python3 python3-pip python3-venv zstd \\
+  && useradd --system --home-dir /var/lib/hf-broker --create-home --shell /usr/sbin/nologin hf-broker \\
   && rm -rf /var/lib/apt/lists/*
 RUN python3 -m pip install --break-system-packages --no-cache-dir \\
   "huggingface_hub==1.19.0" \\
@@ -14957,10 +15016,15 @@ RUN python3 -m pip install --break-system-packages --no-cache-dir \\
   "uvicorn==0.49.0" \\
   "uv==0.11.28" \\
   "hf-discover==1.3.7"
+ARG BROKERKIT_PLUGIN_VERSION
+COPY --from=brokerkit-plugin-build /out/openclaw-brokerkit-\${BROKERKIT_PLUGIN_VERSION}.tgz /tmp/openclaw-brokerkit.tgz
+RUN npm install --omit=dev --omit=peer --no-audit --no-fund --prefix /opt/openclaw-plugins   /tmp/openclaw-brokerkit.tgz   && rm /tmp/openclaw-brokerkit.tgz   && test -f /opt/openclaw-plugins/node_modules/openclaw-brokerkit/openclaw.plugin.json
 
 COPY --chown=node:node runtime/hf-state-sync.js /app/hf-state-sync.js
 COPY --chown=node:node runtime/hf-tooling-seed.js /app/hf-tooling-seed.js
 COPY --chown=node:node runtime/mlclaw-space-runtime.js /app/mlclaw-space-runtime.js
+COPY --from=hf-broker-build /out/hf-broker /usr/local/bin/hf-broker
+COPY runtime/hf-broker.scope.json /app/hf-broker.scope.json
 COPY --chown=node:node runtime/openclaw.default.json /app/openclaw.default.json
 COPY --chown=node:node runtime/entrypoint.sh /app/entrypoint.sh
 COPY --chown=node:node runtime/scripts/ /app/scripts/
@@ -14970,11 +15034,12 @@ RUN chmod +x /app/entrypoint.sh
 ENV PORT=7860
 ENV MLCLAW_OPENCLAW_PORT=7861
 ENV OPENCLAW_GATEWAY_PORT=7861
-ENV OPENCLAW_LIVE_DIR=/tmp/openclaw-live
-ENV OPENCLAW_STATE_DIR=/tmp/openclaw-live/.openclaw
-ENV OPENCLAW_WORKSPACE_DIR=/tmp/openclaw-live/workspace
-ENV OPENCLAW_CONFIG_PATH=/tmp/openclaw-live/.openclaw/openclaw.json
+ENV OPENCLAW_LIVE_DIR=/home/node/.local/share/mlclaw/live
+ENV OPENCLAW_STATE_DIR=/home/node/.local/share/mlclaw/live/.openclaw
+ENV OPENCLAW_WORKSPACE_DIR=/home/node/.local/share/mlclaw/live/workspace
+ENV OPENCLAW_CONFIG_PATH=/home/node/.local/share/mlclaw/live/.openclaw/openclaw.json
 ENV OPENCLAW_DISABLE_BONJOUR=1
+ENV MLCLAW_BROKERKIT_PLUGIN_PATH=/opt/openclaw-plugins/node_modules/openclaw-brokerkit
 
 EXPOSE 7860
 
@@ -15259,6 +15324,8 @@ var DEFAULT_LOCAL_PORT = 7860;
 var DEFAULT_SPACE_OPENCLAW_PORT = 7861;
 var LOCAL_VOLUME_MOUNT_PATH = "/tmp/mlclaw-local";
 var LOCAL_LIVE_DIR = `${LOCAL_VOLUME_MOUNT_PATH}/openclaw-live`;
+var SPACE_STATE_MOUNT_DIR = "/data/mlclaw-state";
+var SPACE_LIVE_DIR = "/home/node/.local/share/mlclaw/live";
 var SPACE_HANDOFF_TIMEOUT_MS = 12e4;
 var SPACE_HANDOFF_POLL_MS = 5e3;
 var STALE_PATH_VARS = ["OPENCLAW_STATE_DIR", "OPENCLAW_WORKSPACE_DIR", "OPENCLAW_CONFIG_PATH"];
@@ -15296,10 +15363,10 @@ function createProgram(runtimeOverrides = {}) {
   program2.name("mlclaw").description("Deploy OpenClaw to a Hugging Face Space and private bucket").showHelpAfterError().exitOverride((err) => {
     throw err;
   });
-  program2.command("bootstrap", { isDefault: true }).description("Create or update a Hugging Face OpenClaw deployment").option("--owner <owner>", "Hugging Face user or organization").option("--name <name>", "Agent and runtime resource base name").option("--bucket <owner/bucket>", "State bucket to create or adopt").option("--gateway <local|space>", "Where the live gateway runs").option("--telegram-token <token>", "Optional Telegram bot token").option("--telegram-token-file <path>", "File containing TELEGRAM_BOT_TOKEN=... or a raw token").option("--telegram-user-id <id>", "Allowed Telegram user ID").option("--telegram-api-root <url>", "Telegram API root override").option("--telegram-proxy <url>", "Telegram proxy URL override").option("--hardware <flavor>", "Hugging Face Space hardware flavor").option("--sleep-time <seconds>", "Space sleep timeout in seconds; -1 means never sleep", parseInteger).option("--model <model>", "OpenClaw model identifier", DEFAULT_MODEL).option("--runtime-image <image>", "ML Claw runtime image").option("--bundled-runtime", "Generate a bundled Space runtime instead of using the prebuilt ML Claw image", false).option("--public-space", "Create the Hugging Face Space as public instead of private", false).addOption(new Option("--gateway-token <token>").hideHelp()).option("--docker-context <name>", "Docker context for local gateway mode").option("--no-pull", "Do not docker pull before starting a local gateway").option("--takeover", "Start even if a stale runtime lease is present", false).option("--yes", "Confirm paid hardware prompts for automation", false).action(async (opts) => {
+  program2.command("bootstrap", { isDefault: true }).description("Create or update a Hugging Face OpenClaw deployment").option("--owner <owner>", "Hugging Face user or organization").option("--name <name>", "Agent and runtime resource base name").option("--bucket <owner/bucket>", "State bucket to create or adopt").option("--gateway <local|space>", "Where the live gateway runs").option("--telegram-token <token>", "Optional Telegram bot token").option("--telegram-token-file <path>", "File containing TELEGRAM_BOT_TOKEN=... or a raw token").option("--telegram-user-id <id>", "Allowed Telegram user ID").option("--telegram-api-root <url>", "Telegram API root override").option("--telegram-proxy <url>", "Telegram proxy URL override").option("--hardware <flavor>", "Hugging Face Space hardware flavor").option("--sleep-time <seconds>", "Space sleep timeout in seconds; -1 means never sleep", parseInteger).option("--model <model>", "OpenClaw model identifier", DEFAULT_MODEL).option("--runtime-image <image>", "ML Claw runtime image").option("--bundled-runtime", "Generate a bundled Space runtime instead of using the prebuilt ML Claw image", false).option("--public-space", "Create the Hugging Face Space as public instead of private", false).addOption(new Option("--gateway-token <token>").hideHelp()).option("--router-token <token>", "Hugging Face Router inference token for Space gateway model calls").option("--router-token-file <path>", "File containing MLCLAW_ROUTER_TOKEN=..., HF_ROUTER_TOKEN=..., or a raw token").option("--docker-context <name>", "Docker context for local gateway mode").option("--no-pull", "Do not docker pull before starting a local gateway").option("--takeover", "Start even if a stale runtime lease is present", false).option("--yes", "Confirm paid hardware prompts for automation", false).action(async (opts) => {
     await bootstrap(opts, runtime);
   });
-  program2.command("update").description("Regenerate and upload current ML Claw Space files").argument("<owner/space>", "Hugging Face Space repo ID").option("--runtime-image <image>", "Runtime image to write into the generated Space Dockerfile").option("--bundled-runtime", "Generate a bundled Space runtime instead of using the prebuilt ML Claw image", false).option("--force", "Update even if the Space does not look like ML Claw", false).action(async (repoId, opts) => {
+  program2.command("update").description("Regenerate and upload current ML Claw Space files").argument("<owner/space>", "Hugging Face Space repo ID").option("--runtime-image <image>", "Runtime image to write into the generated Space Dockerfile").option("--bundled-runtime", "Generate a bundled Space runtime instead of using the prebuilt ML Claw image", false).option("--router-token <token>", "Dedicated Hugging Face Router inference token").option("--router-token-file <path>", "File containing MLCLAW_ROUTER_TOKEN=..., HF_ROUTER_TOKEN=..., or a raw token").option("--force", "Update even if the Space does not look like ML Claw", false).action(async (repoId, opts) => {
     const token = await runtime.readToken(runtime.env);
     const hub = runtime.hubFactory(token);
     await update(repoId, opts, hub, token, runtime);
@@ -15322,8 +15389,7 @@ function createProgram(runtimeOverrides = {}) {
     await gatewayStop(agent, runtime);
   });
   gateway.command("restart").argument("<agent>", "Agent name").option("--no-pull", "Do not docker pull before starting a local gateway").option("--takeover", "Start even if another live runtime lease is present", false).action(async (agent, opts) => {
-    await gatewayStop(agent, runtime);
-    await gatewayStart(agent, opts, runtime);
+    await gatewayRestart(agent, opts, runtime);
   });
   gateway.command("status").argument("<agent>", "Agent name").action(async (agent) => {
     await gatewayStatus(agent, runtime);
@@ -15331,7 +15397,7 @@ function createProgram(runtimeOverrides = {}) {
   gateway.command("logs").argument("<agent>", "Agent name").option("--tail <lines>", "Number of log lines", parseInteger, 200).action(async (agent, opts) => {
     await gatewayLogs(agent, opts, runtime);
   });
-  gateway.command("migrate").argument("<agent>", "Agent name").requiredOption("--to <local|space>", "Target gateway location").option("--hardware <flavor>", "Hugging Face Space hardware flavor").option("--sleep-time <seconds>", "Space sleep timeout in seconds; -1 means never sleep", parseInteger).option("--runtime-image <image>", "ML Claw runtime image").option("--bundled-runtime", "Generate a bundled Space runtime instead of using the prebuilt ML Claw image", false).option("--public-space", "Create the Hugging Face Space as public instead of private", false).option("--docker-context <name>", "Docker context for local gateway startup when migrating to local").option("--no-pull", "Do not docker pull before starting a local gateway").option("--takeover", "Start even if another live runtime lease is present", false).option("--yes", "Confirm paid hardware prompts for automation", false).action(async (agent, opts) => {
+  gateway.command("migrate").argument("<agent>", "Agent name").requiredOption("--to <local|space>", "Target gateway location").option("--hardware <flavor>", "Hugging Face Space hardware flavor").option("--sleep-time <seconds>", "Space sleep timeout in seconds; -1 means never sleep", parseInteger).option("--runtime-image <image>", "ML Claw runtime image").option("--bundled-runtime", "Generate a bundled Space runtime instead of using the prebuilt ML Claw image", false).option("--public-space", "Create the Hugging Face Space as public instead of private", false).option("--router-token <token>", "Hugging Face Router inference token for Space gateway model calls").option("--router-token-file <path>", "File containing MLCLAW_ROUTER_TOKEN=..., HF_ROUTER_TOKEN=..., or a raw token").option("--docker-context <name>", "Docker context for local gateway startup when migrating to local").option("--no-pull", "Do not docker pull before starting a local gateway").option("--takeover", "Start even if another live runtime lease is present", false).option("--yes", "Confirm paid hardware prompts for automation", false).action(async (agent, opts) => {
     await gatewayMigrate(agent, opts, runtime);
   });
   gateway.command("rebind").argument("<agent>", "Agent name").requiredOption("--docker-context <name>", "Target Docker context").option("--no-pull", "Do not docker pull before starting the rebound local gateway").option("--takeover", "Rebind even if the old Docker context is unavailable", false).action(async (agent, opts) => {
@@ -15404,8 +15470,9 @@ async function bootstrap(opts, runtime) {
       throw new Error("internal error: Space plan was not resolved");
     }
     const paidHardware = await resolveHardware({
-      requestedHardware: opts.hardware ?? (telegramToken ? TELEGRAM_HARDWARE : DEFAULT_HARDWARE),
+      ...opts.hardware ? { requestedHardware: opts.hardware } : {},
       ...typeof opts.sleepTime === "number" ? { requestedSleepTime: opts.sleepTime } : telegramToken ? { requestedSleepTime: TELEGRAM_SLEEP_TIME } : {},
+      defaultLabel: spacePlan.exists ? "unchanged Space hardware" : "default free CPU",
       requiresMessagingEgress: Boolean(telegramToken),
       yes: Boolean(opts.yes),
       runtime
@@ -15415,7 +15482,7 @@ async function bootstrap(opts, runtime) {
       bucketPlan,
       spacePlan,
       hasExistingManifest: plan.hasExistingManifest,
-      hardware: paidHardware.hardware,
+      hardware: paidHardware.label,
       ...typeof paidHardware.sleepTime === "number" ? { sleepTime: paidHardware.sleepTime } : {},
       yes: Boolean(opts.yes),
       runtime
@@ -15435,9 +15502,9 @@ async function bootstrap(opts, runtime) {
       manifest,
       secrets,
       allowedUsers: me2.name,
-      hardware: paidHardware.hardware,
       spaceExists: spacePlan.exists,
       publicSpace: Boolean(opts.publicSpace),
+      ...paidHardware.kind === "explicit" ? { hardware: paidHardware.hardware } : {},
       ...typeof paidHardware.sleepTime === "number" ? { sleepTime: paidHardware.sleepTime } : {},
       ...templateRuntimeImage ? { templateRuntimeImage } : {}
     });
@@ -15493,10 +15560,11 @@ function spacePublicUrl(repoId) {
 async function resolveBootstrapPlan(params) {
   const { opts, owner, agentName, requestedGatewayLocation, hfToken, telegramToken, telegramUserId, model, runtimeImage, hub, runtime } = params;
   const names = namesFor(owner, agentName);
-  const sessionSecret = randomBytes(48).toString("base64url");
   const now = runtime.now().toISOString();
   const existingManifest = await readManifest(runtime.configRoot, agentName).catch(() => null);
   const existingSecrets = await readSecretEnv(runtime.configRoot, agentName).catch(() => ({}));
+  const sessionSecret = existingSecrets.MLCLAW_SESSION_SECRET ?? randomBytes(48).toString("base64url");
+  const credentialKey = existingSecrets.MLCLAW_CREDENTIAL_KEY ?? randomBytes(32).toString("base64url");
   const gatewayLocation = requestedGatewayLocation ?? existingManifest?.gatewayLocation ?? DEFAULT_GATEWAY_LOCATION;
   if (opts.dockerContext && gatewayLocation !== "local") {
     throw new Error("--docker-context only applies to local gateway mode");
@@ -15517,6 +15585,12 @@ async function resolveBootstrapPlan(params) {
     hub
   });
   const bucket = bucketPlan.bucket;
+  const routerToken = await resolveRouterToken({
+    opts,
+    runtime,
+    existingSecrets,
+    model
+  });
   const spacePlan = gatewayLocation === "space" ? {
     space: names.space,
     exists: await hub.spaceExists(names.space),
@@ -15541,6 +15615,7 @@ async function resolveBootstrapPlan(params) {
     ...telegramToken ? { telegramToken } : {},
     ...telegramUserId ? { telegramUserId } : {},
     sessionSecret,
+    credentialKey,
     bucket,
     model,
     agentName,
@@ -15549,7 +15624,8 @@ async function resolveBootstrapPlan(params) {
     runtimeId: gatewayLocation === "local" ? manifest.localRuntimeId : spaceRuntimeId(agentName),
     ...bucketPrefix ? { bucketPrefix } : {},
     ...opts.telegramProxy ? { telegramProxy: opts.telegramProxy } : {},
-    ...opts.telegramApiRoot ? { telegramApiRoot: opts.telegramApiRoot } : {}
+    ...opts.telegramApiRoot ? { telegramApiRoot: opts.telegramApiRoot } : {},
+    ...routerToken ? { routerToken } : {}
   });
   return {
     agentName,
@@ -15611,6 +15687,8 @@ async function confirmBootstrapPlan(params) {
   if (params.spacePlan) {
     lines.push(`Space: ${params.spacePlan.space} (${params.spacePlan.exists ? "exists; files, variables, secrets, and runtime will be updated" : `will be created as ${params.spacePlan.visibility}`})`);
     lines.push(`Hardware: ${params.hardware}`);
+    lines.push(`Bucket mount: ${SPACE_STATE_MOUNT_DIR}`);
+    lines.push(`Live state: ${SPACE_LIVE_DIR}`);
     if (typeof params.sleepTime === "number") {
       lines.push(`Sleep time: ${params.sleepTime}`);
     }
@@ -15650,6 +15728,10 @@ async function stateAdopt(agent, opts, runtime) {
   const hub = runtime.hubFactory(token);
   const secrets = await readSecretEnv(runtime.configRoot, agent);
   const bucketPrefix = persistedBucketPrefix(secrets);
+  const bucketChanged = current.bucket !== bucket;
+  if (bucketChanged && current.gatewayLocation === "local") {
+    assertDedicatedRouterToken(current.model, secrets);
+  }
   runtime.stdout.log(`Creating or adopting private bucket ${bucket}`);
   await hub.createBucket(bucket, true);
   await inspectStateBucket(hub, bucket, bucketPrefix);
@@ -15660,7 +15742,6 @@ async function stateAdopt(agent, opts, runtime) {
     runtimeId: runtimeIdFor(current),
     takeover: Boolean(opts.takeover)
   });
-  const bucketChanged = current.bucket !== bucket;
   if (bucketChanged) {
     await confirmBucketChange({
       message: `Adopt state bucket ${bucket} for ${agent}, replacing ${current.bucket}?`,
@@ -15711,9 +15792,16 @@ async function stateAdopt(agent, opts, runtime) {
   } else {
     await setDeploymentVariables(hub, updated.space, {
       OPENCLAW_HF_STATE_BUCKET: bucket,
+      MLCLAW_STATE_MOUNT_DIR: SPACE_STATE_MOUNT_DIR,
+      OPENCLAW_LIVE_DIR: SPACE_LIVE_DIR,
+      MLCLAW_RUNTIME_SETTINGS_FILE: `${SPACE_LIVE_DIR}/.mlclaw/settings.json`,
       MLCLAW_GATEWAY_LOCATION: "space",
       MLCLAW_RUNTIME_ID: spaceRuntimeId(updated.agent)
     });
+    await ensureSpaceStateVolume(hub, updated.space, bucket);
+    if (canDeleteBroadTokenSecrets({ model: updated.model, routerTokenPresent: hasBrokerOrRouterTokenSecretRecord(secrets) })) {
+      await deleteStaleSpaceTokenSecrets(hub, updated.space);
+    }
     await clearSpaceGatewayDisabled(hub, updated.space);
     if (bucketChanged) {
       await hub.restartSpace(updated.space, true);
@@ -15788,8 +15876,8 @@ function parseBucketId(raw) {
 }
 function deploymentSecrets(params) {
   return {
-    HF_TOKEN: params.hfToken,
-    HUGGINGFACE_HUB_TOKEN: params.hfToken,
+    MLCLAW_BROKER_HF_TOKEN: params.hfToken,
+    ...params.routerToken ? { MLCLAW_ROUTER_TOKEN: params.routerToken } : {},
     OPENCLAW_HF_STATE_BUCKET: params.bucket,
     OPENCLAW_MODEL: params.model,
     OPENCLAW_AGENT_NAME: params.agentName,
@@ -15797,6 +15885,7 @@ function deploymentSecrets(params) {
     MLCLAW_RUNTIME_IMAGE: params.runtimeImage,
     MLCLAW_RUNTIME_ID: params.runtimeId,
     MLCLAW_SESSION_SECRET: params.sessionSecret,
+    MLCLAW_CREDENTIAL_KEY: params.credentialKey,
     MLCLAW_OPENCLAW_PORT: String(DEFAULT_SPACE_OPENCLAW_PORT),
     OPENCLAW_GATEWAY_PORT: String(DEFAULT_SPACE_OPENCLAW_PORT),
     ...params.telegramToken ? { TELEGRAM_BOT_TOKEN: params.telegramToken } : {},
@@ -15815,10 +15904,14 @@ async function deploySpaceGateway(params) {
   runtime.stdout.log(params.spaceExists ? `Updating existing Space ${manifest.space}` : `Creating ${params.publicSpace ? "public" : "private"} Space ${manifest.space}`);
   await hub.createDockerSpace(manifest.space, {
     private: !params.publicSpace,
-    hardware: params.hardware,
+    ...params.hardware && !params.spaceExists ? { hardware: params.hardware } : {},
     ...typeof params.sleepTime === "number" ? { sleepTimeSeconds: params.sleepTime } : {}
   });
-  await hub.requestSpaceHardware(manifest.space, params.hardware, params.sleepTime);
+  if (params.hardware && params.spaceExists) {
+    await hub.requestSpaceHardware(manifest.space, params.hardware, params.sleepTime);
+  } else if (!params.hardware && params.spaceExists && typeof params.sleepTime === "number") {
+    await hub.setSpaceSleepTime(manifest.space, params.sleepTime);
+  }
   runtime.stdout.log(params.templateRuntimeImage ? "Generating Space files from prebuilt runtime image" : "Generating bundled Space runtime files");
   const { templateRev } = await runtime.pushTemplateToSpace({
     targetRepo: manifest.space,
@@ -15828,6 +15921,9 @@ async function deploySpaceGateway(params) {
   const spaceRuntimeRef = params.templateRuntimeImage ?? bundledSpaceRuntimeRef(templateRev);
   await setDeploymentVariables(hub, manifest.space, {
     OPENCLAW_HF_STATE_BUCKET: manifest.bucket,
+    MLCLAW_STATE_MOUNT_DIR: SPACE_STATE_MOUNT_DIR,
+    OPENCLAW_LIVE_DIR: SPACE_LIVE_DIR,
+    MLCLAW_RUNTIME_SETTINGS_FILE: `${SPACE_LIVE_DIR}/.mlclaw/settings.json`,
     ...secrets.OPENCLAW_HF_STATE_PREFIX ? { OPENCLAW_HF_STATE_PREFIX: secrets.OPENCLAW_HF_STATE_PREFIX } : {},
     MLCLAW_TEMPLATE_REV: templateRev,
     OPENCLAW_MODEL: manifest.model,
@@ -15841,21 +15937,30 @@ async function deploySpaceGateway(params) {
     MLCLAW_OPENCLAW_PORT: String(DEFAULT_SPACE_OPENCLAW_PORT),
     OPENCLAW_GATEWAY_PORT: String(DEFAULT_SPACE_OPENCLAW_PORT)
   });
+  await ensureSpaceStateVolume(hub, manifest.space, manifest.bucket, { allowMissingVolumes: !params.spaceExists });
   await clearSpaceGatewayDisabled(hub, manifest.space);
   await setDeploymentSecrets(hub, manifest.space, {
-    HF_TOKEN: requiredSecret(secrets, "HF_TOKEN"),
-    HUGGINGFACE_HUB_TOKEN: requiredSecret(secrets, "HF_TOKEN"),
     MLCLAW_SESSION_SECRET: requiredSecret(secrets, "MLCLAW_SESSION_SECRET"),
+    MLCLAW_CREDENTIAL_KEY: requiredSecret(secrets, "MLCLAW_CREDENTIAL_KEY"),
+    MLCLAW_BROKER_HF_TOKEN: hfToken,
+    ...secrets.MLCLAW_ROUTER_TOKEN ? { MLCLAW_ROUTER_TOKEN: secrets.MLCLAW_ROUTER_TOKEN } : {},
     ...secrets.TELEGRAM_BOT_TOKEN ? { TELEGRAM_BOT_TOKEN: secrets.TELEGRAM_BOT_TOKEN } : {},
     ...secrets.TELEGRAM_ALLOWED_USERS ? { TELEGRAM_ALLOWED_USERS: secrets.TELEGRAM_ALLOWED_USERS } : {},
     ...secrets.TELEGRAM_PROXY ? { TELEGRAM_PROXY: secrets.TELEGRAM_PROXY } : {},
     ...secrets.TELEGRAM_API_ROOT ? { TELEGRAM_API_ROOT: secrets.TELEGRAM_API_ROOT } : {}
   });
+  if (canDeleteBroadTokenSecrets({ model: manifest.model, routerTokenPresent: hasBrokerOrRouterTokenSecretRecord(secrets) })) {
+    await deleteStaleSpaceTokenSecrets(hub, manifest.space);
+  } else {
+    runtime.stdout.log("Keeping legacy broad Hub token secrets until an HF Broker or Router credential is configured");
+  }
   await hub.restartSpace(manifest.space, true);
   return { runtimeImage: spaceRuntimeRef };
 }
 async function startLocalGateway(params) {
   const { manifest, runtime } = params;
+  const secrets = await ensureDeploymentCredentialKey(runtime, manifest.agent);
+  assertDedicatedRouterToken(manifest.model, secrets);
   const containerName = containerNameFor(manifest.agent);
   const volumeName = volumeNameFor(manifest.agent);
   const dockerContext = dockerContextFor(manifest);
@@ -15928,6 +16033,17 @@ async function gatewayStart(agent, opts, runtime) {
     runtime.stdout.log(`Space gateway restart requested: ${manifest.space}`);
   }
 }
+async function gatewayRestart(agent, opts, runtime) {
+  const manifest = await readDeploymentManifest(runtime, agent, { requestedDockerContext: opts.dockerContext });
+  if (manifest.gatewayLocation === "local") {
+    assertDedicatedRouterToken(
+      manifest.model,
+      await readSecretEnv(runtime.configRoot, agent).catch(() => ({}))
+    );
+  }
+  await gatewayStop(agent, runtime);
+  await gatewayStart(agent, opts, runtime);
+}
 async function gatewayStop(agent, runtime) {
   const manifest = await readDeploymentManifest(runtime, agent);
   const bucketPrefix = await readDeploymentBucketPrefix(runtime, agent);
@@ -15995,7 +16111,7 @@ async function gatewayMigrate(agent, opts, runtime) {
   }
   const token = await runtime.readToken(runtime.env);
   const hub = runtime.hubFactory(token);
-  const secrets = await readSecretEnv(runtime.configRoot, agent);
+  const secrets = await ensureDeploymentCredentialKey(runtime, agent);
   const bucketPrefix = persistedBucketPrefix(secrets);
   const updated = {
     ...current,
@@ -16003,10 +16119,23 @@ async function gatewayMigrate(agent, opts, runtime) {
     runtimeImage: resolveRuntimeImage(opts.runtimeImage ?? current.runtimeImage, runtime.env),
     updatedAt: runtime.now().toISOString()
   };
+  const routerToken = await resolveRouterToken({
+    opts,
+    runtime,
+    existingSecrets: secrets,
+    model: updated.model
+  });
   if (target === "space") {
+    const deploymentSecrets2 = {
+      ...secrets,
+      MLCLAW_GATEWAY_LOCATION: "space",
+      MLCLAW_RUNTIME_IMAGE: updated.runtimeImage,
+      ...routerToken ? { MLCLAW_ROUTER_TOKEN: routerToken } : {}
+    };
     const paidHardware = await resolveHardware({
-      requestedHardware: opts.hardware ?? (secrets.TELEGRAM_BOT_TOKEN ? TELEGRAM_HARDWARE : DEFAULT_HARDWARE),
+      ...opts.hardware ? { requestedHardware: opts.hardware } : {},
       ...typeof opts.sleepTime === "number" ? { requestedSleepTime: opts.sleepTime } : secrets.TELEGRAM_BOT_TOKEN ? { requestedSleepTime: TELEGRAM_SLEEP_TIME } : {},
+      defaultLabel: "unchanged Space hardware",
       requiresMessagingEgress: Boolean(secrets.TELEGRAM_BOT_TOKEN),
       yes: Boolean(opts.yes),
       runtime
@@ -16021,24 +16150,22 @@ async function gatewayMigrate(agent, opts, runtime) {
     await handoffAndStopLocalGateway({ manifest: current, hub, runtime, bucketPrefix });
     const me2 = await hub.whoami();
     const templateRuntimeImage = resolveSpaceRuntimeImage(opts, runtime.env);
+    const spaceExists = await hub.spaceExists(updated.space);
     await deploySpaceGateway({
       hub,
       runtime,
       hfToken: token,
       manifest: updated,
-      secrets: {
-        ...secrets,
-        MLCLAW_GATEWAY_LOCATION: "space",
-        MLCLAW_RUNTIME_IMAGE: updated.runtimeImage
-      },
+      secrets: deploymentSecrets2,
       allowedUsers: me2.name,
-      hardware: paidHardware.hardware,
       publicSpace: Boolean(opts.publicSpace),
+      spaceExists,
+      ...paidHardware.kind === "explicit" ? { hardware: paidHardware.hardware } : {},
       ...typeof paidHardware.sleepTime === "number" ? { sleepTime: paidHardware.sleepTime } : {},
       ...templateRuntimeImage ? { templateRuntimeImage } : {}
     });
     await writeSecretEnv(runtime.configRoot, agent, {
-      ...secrets,
+      ...deploymentSecrets2,
       MLCLAW_GATEWAY_LOCATION: "space",
       MLCLAW_RUNTIME_IMAGE: updated.runtimeImage,
       MLCLAW_RUNTIME_ID: spaceRuntimeId(agent)
@@ -16070,6 +16197,7 @@ async function gatewayMigrate(agent, opts, runtime) {
     });
     await writeSecretEnv(runtime.configRoot, agent, {
       ...secrets,
+      ...routerToken ? { MLCLAW_ROUTER_TOKEN: routerToken } : {},
       MLCLAW_GATEWAY_LOCATION: "local",
       MLCLAW_RUNTIME_IMAGE: updated.runtimeImage,
       MLCLAW_RUNTIME_ID: updated.localRuntimeId
@@ -16085,6 +16213,10 @@ async function gatewayRebind(agent, opts, runtime) {
   if (current.gatewayLocation !== "local") {
     throw new Error("Docker context rebind only applies to local gateway deployments");
   }
+  assertDedicatedRouterToken(
+    current.model,
+    await readSecretEnv(runtime.configRoot, agent).catch(() => ({}))
+  );
   const targetBinding = await resolveLocalGatewayBinding({
     manifest: void 0,
     requestedContext: targetContext,
@@ -16358,6 +16490,18 @@ function requiredSecret(secrets, key) {
   }
   return value;
 }
+async function ensureDeploymentCredentialKey(runtime, agent, existing) {
+  const secrets = existing ?? await readSecretEnv(runtime.configRoot, agent).catch(() => ({}));
+  if (secrets.MLCLAW_CREDENTIAL_KEY) {
+    return secrets;
+  }
+  const updated = {
+    ...secrets,
+    MLCLAW_CREDENTIAL_KEY: randomBytes(32).toString("base64url")
+  };
+  await writeSecretEnv(runtime.configRoot, agent, updated);
+  return updated;
+}
 function requiredOption(value, label) {
   if (!value) {
     throw new Error(`${label} is required`);
@@ -16375,6 +16519,16 @@ async function update(repoId, opts, hub, hfToken, runtime) {
   }
   const runtimeImage = resolveSpaceRuntimeImage(opts, runtime.env);
   const agentName = variables.get("OPENCLAW_AGENT_NAME")?.value?.trim() || repoId.split("/")[1] || "openclaw";
+  if (!canonicalTemplate) {
+    await ensureUpdateRouterToken({
+      repoId,
+      agentName,
+      model: variables.get("OPENCLAW_MODEL")?.value ?? DEFAULT_MODEL,
+      opts,
+      hub,
+      runtime
+    });
+  }
   runtime.stdout.log(`Generating current Space files into ${repoId}`);
   const { templateRev } = await runtime.pushTemplateToSpace({
     targetRepo: repoId,
@@ -16393,9 +16547,50 @@ async function update(repoId, opts, hub, hfToken, runtime) {
   await hub.addSpaceVariable(repoId, "MLCLAW_RUNTIME_ID", spaceRuntimeId(agentName));
   await hub.addSpaceVariable(repoId, "MLCLAW_OPENCLAW_PORT", String(DEFAULT_SPACE_OPENCLAW_PORT));
   await hub.addSpaceVariable(repoId, "OPENCLAW_GATEWAY_PORT", String(DEFAULT_SPACE_OPENCLAW_PORT));
+  const bucket = variables.get("OPENCLAW_HF_STATE_BUCKET")?.value;
+  if (bucket) {
+    await hub.addSpaceVariable(repoId, "MLCLAW_STATE_MOUNT_DIR", SPACE_STATE_MOUNT_DIR);
+    await hub.addSpaceVariable(repoId, "OPENCLAW_LIVE_DIR", SPACE_LIVE_DIR);
+    await hub.addSpaceVariable(repoId, "MLCLAW_RUNTIME_SETTINGS_FILE", `${SPACE_LIVE_DIR}/.mlclaw/settings.json`);
+    await ensureSpaceStateVolume(hub, repoId, bucket);
+  }
   await doctor(repoId, { fix: true }, hub, runtime);
   await hub.restartSpace(repoId, true);
 }
+async function ensureUpdateRouterToken(params) {
+  if (!isHuggingFaceRouterModel(params.model)) {
+    return;
+  }
+  const spaceSecrets = await params.hub.getSpaceSecrets(params.repoId);
+  const hasExplicitOverride = params.opts.routerToken !== void 0 || params.opts.routerTokenFile !== void 0;
+  if (hasBrokerOrRouterTokenSecretMap(spaceSecrets) && !hasExplicitOverride) {
+    return;
+  }
+  const hasManifest = await manifestExists(params.runtime.configRoot, params.agentName);
+  const localSecrets = hasManifest ? await readSecretEnv(params.runtime.configRoot, params.agentName).catch(() => ({})) : {};
+  const routerToken = hasExplicitOverride ? await resolveRouterToken({
+    opts: params.opts,
+    runtime: params.runtime,
+    existingSecrets: localSecrets,
+    model: params.model
+  }) : void 0;
+  const brokerToken = routerToken ? void 0 : await params.runtime.readToken(params.runtime.env);
+  const credential = routerToken ?? brokerToken;
+  if (!credential) {
+    throw new Error("Hugging Face broker credential is unavailable");
+  }
+  await params.hub.addSpaceSecret(
+    params.repoId,
+    routerToken ? "MLCLAW_ROUTER_TOKEN" : "MLCLAW_BROKER_HF_TOKEN",
+    credential
+  );
+  if (hasManifest) {
+    await writeSecretEnv(params.runtime.configRoot, params.agentName, {
+      ...localSecrets,
+      ...routerToken ? { MLCLAW_ROUTER_TOKEN: routerToken } : { MLCLAW_BROKER_HF_TOKEN: brokerToken }
+    });
+  }
+}
 async function doctor(repoId, opts, hub, runtime) {
   if (!repoId.includes("/") && await manifestExists(runtime.configRoot, repoId)) {
     await gatewayStatus(repoId, runtime);
@@ -16454,6 +16649,31 @@ async function doctor(repoId, opts, hub, runtime) {
     await hub.addSpaceVariable(repoId, "OPENCLAW_HF_STATE_BUCKET", bucket);
     fixed.push("set OPENCLAW_HF_STATE_BUCKET");
   }
+  if ((variables.get("MLCLAW_STATE_MOUNT_DIR")?.value ?? "") !== SPACE_STATE_MOUNT_DIR) {
+    if (fix) {
+      await hub.addSpaceVariable(repoId, "MLCLAW_STATE_MOUNT_DIR", SPACE_STATE_MOUNT_DIR);
+      fixed.push("set MLCLAW_STATE_MOUNT_DIR");
+    } else {
+      issues.push(`MLCLAW_STATE_MOUNT_DIR is not ${SPACE_STATE_MOUNT_DIR}`);
+    }
+  }
+  if ((variables.get("OPENCLAW_LIVE_DIR")?.value ?? "") !== SPACE_LIVE_DIR) {
+    if (fix) {
+      await hub.addSpaceVariable(repoId, "OPENCLAW_LIVE_DIR", SPACE_LIVE_DIR);
+      fixed.push("set OPENCLAW_LIVE_DIR");
+    } else {
+      issues.push(`OPENCLAW_LIVE_DIR is not ${SPACE_LIVE_DIR}`);
+    }
+  }
+  const expectedRuntimeSettingsFile = `${SPACE_LIVE_DIR}/.mlclaw/settings.json`;
+  if ((variables.get("MLCLAW_RUNTIME_SETTINGS_FILE")?.value ?? "") !== expectedRuntimeSettingsFile) {
+    if (fix) {
+      await hub.addSpaceVariable(repoId, "MLCLAW_RUNTIME_SETTINGS_FILE", expectedRuntimeSettingsFile);
+      fixed.push("set MLCLAW_RUNTIME_SETTINGS_FILE");
+    } else {
+      issues.push(`MLCLAW_RUNTIME_SETTINGS_FILE is not ${expectedRuntimeSettingsFile}`);
+    }
+  }
   for (const key of STALE_PATH_VARS) {
     if (variables.has(key)) {
       if (fix) {
@@ -16464,8 +16684,30 @@ async function doctor(repoId, opts, hub, runtime) {
       }
     }
   }
-  if (!secrets.has("HF_TOKEN")) {
-    issues.push("secret HF_TOKEN is missing");
+  if (!secrets.has("MLCLAW_BROKER_HF_TOKEN")) {
+    if (fix) {
+      await hub.addSpaceSecret(repoId, "MLCLAW_BROKER_HF_TOKEN", await runtime.readToken(runtime.env));
+      secrets.set("MLCLAW_BROKER_HF_TOKEN", { key: "MLCLAW_BROKER_HF_TOKEN" });
+      fixed.push("set secret MLCLAW_BROKER_HF_TOKEN");
+    } else {
+      issues.push("secret MLCLAW_BROKER_HF_TOKEN is missing");
+    }
+  }
+  const staleTokenSecrets = ["HF_TOKEN", "HUGGINGFACE_HUB_TOKEN"].filter((key) => secrets.has(key));
+  if (staleTokenSecrets.length > 0) {
+    const model = variables.get("OPENCLAW_MODEL")?.value ?? DEFAULT_MODEL;
+    const canDelete = canDeleteBroadTokenSecrets({
+      model,
+      routerTokenPresent: hasBrokerOrRouterTokenSecretMap(secrets)
+    });
+    if (fix && canDelete) {
+      await deleteStaleSpaceTokenSecrets(hub, repoId);
+      fixed.push(`deleted stale secret${staleTokenSecrets.length === 1 ? "" : "s"} ${staleTokenSecrets.join(", ")}`);
+    } else if (fix) {
+      issues.push(`stale broad Hub token secret${staleTokenSecrets.length === 1 ? "" : "s"} present: ${staleTokenSecrets.join(", ")}; add MLCLAW_BROKER_HF_TOKEN before removing`);
+    } else {
+      issues.push(`stale broad Hub token secret${staleTokenSecrets.length === 1 ? "" : "s"} present: ${staleTokenSecrets.join(", ")}`);
+    }
   }
   if (!secrets.has("MLCLAW_SESSION_SECRET")) {
     if (fix) {
@@ -16475,6 +16717,16 @@ async function doctor(repoId, opts, hub, runtime) {
       issues.push("secret MLCLAW_SESSION_SECRET is missing");
     }
   }
+  if (!secrets.has("MLCLAW_CREDENTIAL_KEY")) {
+    if (fix) {
+      const agent = variables.get("OPENCLAW_AGENT_NAME")?.value?.trim() || repoId.split("/")[1] || "openclaw";
+      const credentialKey = await manifestExists(runtime.configRoot, agent) ? requiredSecret(await ensureDeploymentCredentialKey(runtime, agent), "MLCLAW_CREDENTIAL_KEY") : randomBytes(32).toString("base64url");
+      await hub.addSpaceSecret(repoId, "MLCLAW_CREDENTIAL_KEY", credentialKey);
+      fixed.push("set secret MLCLAW_CREDENTIAL_KEY");
+    } else {
+      issues.push("secret MLCLAW_CREDENTIAL_KEY is missing");
+    }
+  }
   if (!variables.has("MLCLAW_TEMPLATE_REV") && !variables.has("OPENCLAW_HF_TEMPLATE_REV")) {
     issues.push("MLCLAW_TEMPLATE_REV is missing; updates cannot verify template lineage");
   }
@@ -16514,6 +16766,14 @@ async function doctor(repoId, opts, hub, runtime) {
     await hub.assertBucketAccessible(bucket);
   }
   const runtimeInfo = await hub.getSpaceRuntime(repoId);
+  if (bucket && !hasStateVolume(runtimeInfo.volumes, bucket)) {
+    if (fix) {
+      await hub.setSpaceVolumes(repoId, mergeStateVolume(requireRuntimeVolumes(runtimeInfo, repoId), bucket));
+      fixed.push(`mounted bucket ${bucket} at ${SPACE_STATE_MOUNT_DIR}`);
+    } else {
+      issues.push(`bucket ${bucket} is not mounted read-write at ${SPACE_STATE_MOUNT_DIR}`);
+    }
+  }
   let logs = "";
   try {
     logs = await hub.fetchSpaceLogs(repoId, "run");
@@ -16614,6 +16874,79 @@ async function setDeploymentSecrets(hub, repoId, secrets) {
     await hub.addSpaceSecret(repoId, key, value);
   }
 }
+async function deleteStaleSpaceTokenSecrets(hub, repoId) {
+  await Promise.all([
+    hub.deleteSpaceSecret(repoId, "HF_TOKEN"),
+    hub.deleteSpaceSecret(repoId, "HUGGINGFACE_HUB_TOKEN")
+  ]);
+}
+function canDeleteBroadTokenSecrets(params) {
+  return params.routerTokenPresent || !isHuggingFaceRouterModel(params.model);
+}
+function hasRouterTokenSecretRecord(secrets) {
+  return Boolean(secrets.MLCLAW_ROUTER_TOKEN || secrets.HF_ROUTER_TOKEN);
+}
+function hasRouterTokenSecretMap(secrets) {
+  return secrets.has("MLCLAW_ROUTER_TOKEN") || secrets.has("HF_ROUTER_TOKEN");
+}
+function hasBrokerOrRouterTokenSecretRecord(secrets) {
+  return Boolean(secrets.MLCLAW_BROKER_HF_TOKEN) || hasRouterTokenSecretRecord(secrets);
+}
+function hasBrokerOrRouterTokenSecretMap(secrets) {
+  return secrets.has("MLCLAW_BROKER_HF_TOKEN") || hasRouterTokenSecretMap(secrets);
+}
+function assertDedicatedRouterToken(model, secrets) {
+  if (isHuggingFaceRouterModel(model) && !hasBrokerOrRouterTokenSecretRecord(secrets)) {
+    throw new Error(
+      "Hugging Face Router models require MLCLAW_BROKER_HF_TOKEN or a dedicated inference token"
+    );
+  }
+}
+async function ensureSpaceStateVolume(hub, repoId, bucket, opts = {}) {
+  const runtime = await hub.getSpaceRuntime(repoId);
+  const volumes = Array.isArray(runtime.volumes) ? runtime.volumes : opts.allowMissingVolumes ? [] : requireRuntimeVolumes(runtime, repoId);
+  await hub.setSpaceVolumes(repoId, mergeStateVolume(volumes, bucket));
+}
+function requireRuntimeVolumes(runtime, repoId) {
+  if (!Array.isArray(runtime.volumes)) {
+    throw new Error(`Space runtime metadata for ${repoId} did not include volumes; refusing to replace mounts`);
+  }
+  return runtime.volumes;
+}
+function mergeStateVolume(existing, bucket) {
+  return [
+    ...existing.filter((volume) => volumeMountPath(volume) !== SPACE_STATE_MOUNT_DIR).map(normalizeSpaceVolume),
+    {
+      type: "bucket",
+      source: bucket,
+      mountPath: SPACE_STATE_MOUNT_DIR,
+      readOnly: false
+    }
+  ];
+}
+function hasStateVolume(volumes, bucket) {
+  return Boolean(volumes?.some(
+    (volume) => volume.type === "bucket" && volume.source === bucket && volumeMountPath(volume) === SPACE_STATE_MOUNT_DIR && volumeReadOnly(volume) !== true
+  ));
+}
+function normalizeSpaceVolume(volume) {
+  const normalized = { ...volume };
+  const mountPath = volumeMountPath(volume);
+  if (mountPath) {
+    normalized.mountPath = mountPath;
+  }
+  const readOnly = volumeReadOnly(volume);
+  if (typeof readOnly === "boolean") {
+    normalized.readOnly = readOnly;
+  }
+  return normalized;
+}
+function volumeMountPath(volume) {
+  return volume.mountPath ?? volume.mount_path;
+}
+function volumeReadOnly(volume) {
+  return volume.readOnly ?? volume.read_only;
+}
 async function clearSpaceGatewayDisabled(hub, repoId) {
   try {
     await hub.deleteSpaceVariable(repoId, "MLCLAW_GATEWAY_DISABLED");
@@ -16636,6 +16969,29 @@ async function readOptionalTelegramToken(opts, runtime) {
   }
   return void 0;
 }
+async function resolveRouterToken(params) {
+  const explicit = nonEmpty(params.opts.routerToken) ?? await readOptionalRouterTokenFile(params.opts.routerTokenFile);
+  const direct = explicit ?? params.runtime.env.MLCLAW_ROUTER_TOKEN ?? params.runtime.env.HF_ROUTER_TOKEN ?? params.existingSecrets?.MLCLAW_ROUTER_TOKEN ?? params.existingSecrets?.HF_ROUTER_TOKEN;
+  const existing = nonEmpty(direct);
+  if (existing) {
+    return existing;
+  }
+  if (!isHuggingFaceRouterModel(params.model)) {
+    return void 0;
+  }
+  return void 0;
+}
+async function readOptionalRouterTokenFile(file) {
+  if (!file) {
+    return void 0;
+  }
+  const raw = await fs14.readFile(file, "utf8");
+  const parsed = parseSecretEnv(raw);
+  return nonEmpty(parsed.MLCLAW_ROUTER_TOKEN) ?? nonEmpty(parsed.HF_ROUTER_TOKEN) ?? nonEmpty(raw);
+}
+function isHuggingFaceRouterModel(model) {
+  return model.trim().startsWith("huggingface/");
+}
 async function promptAgentName(runtime) {
   if (!runtime.prompt.isInteractive()) {
     return "mlclaw";
@@ -16648,21 +17004,26 @@ async function promptAgentName(runtime) {
   return readPromptValue(value, "Agent name");
 }
 async function resolveHardware(params) {
-  const hardware = params.requestedHardware;
-  const sleepTime = params.requestedSleepTime ?? TELEGRAM_SLEEP_TIME;
+  const hardware = params.requestedHardware ?? (params.requiresMessagingEgress ? TELEGRAM_HARDWARE : void 0);
+  if (!hardware) {
+    const label = params.defaultLabel ?? "default free CPU";
+    return typeof params.requestedSleepTime === "number" ? { kind: "default", label, sleepTime: params.requestedSleepTime } : { kind: "default", label };
+  }
+  const sleepTime = isPaidHardware(hardware) ? params.requestedSleepTime ?? TELEGRAM_SLEEP_TIME : params.requestedSleepTime;
   if (params.requiresMessagingEgress && !isPaidHardware(hardware)) {
     throw new Error(`Telegram requires upgraded paid Space hardware today; use --hardware ${TELEGRAM_HARDWARE} or --gateway local`);
   }
   if (isPaidHardware(hardware)) {
+    const paidSleepTime = params.requestedSleepTime ?? TELEGRAM_SLEEP_TIME;
     await confirmPaidHardware({
       hardware,
-      sleepTime,
+      sleepTime: paidSleepTime,
       yes: params.yes,
       runtime: params.runtime
     });
-    return { hardware, sleepTime };
+    return { kind: "explicit", hardware, label: hardware, sleepTime: paidSleepTime };
   }
-  return typeof params.requestedSleepTime === "number" ? { hardware, sleepTime: params.requestedSleepTime } : { hardware };
+  return typeof sleepTime === "number" ? { kind: "explicit", hardware, label: hardware, sleepTime } : { kind: "explicit", hardware, label: hardware };
 }
 async function confirmPaidHardware(params) {
   if (params.yes) {
@@ -16746,8 +17107,11 @@ export {
   LOCAL_VOLUME_MOUNT_PATH,
   SPACE_HANDOFF_POLL_MS,
   SPACE_HANDOFF_TIMEOUT_MS,
+  SPACE_LIVE_DIR,
+  SPACE_STATE_MOUNT_DIR,
   TELEGRAM_HARDWARE,
   TELEGRAM_SLEEP_TIME,
   createProgram,
-  main
+  main,
+  mergeStateVolume
 };