mlclaw 0.3.8 → 0.4.1

package/.agents/skills/mlclaw/SKILL.md

@@ -59,8 +59,9 @@ Collect or confirm:
 
 - Hugging Face token access: `HF_TOKEN`, `HF_TOKEN_PATH`, `$HF_HOME/token`, or
   `hf auth login`.
-- The active Hugging Face token is installed as the broker-owned
-  `MLCLAW_BROKER_HF_TOKEN`; legacy dedicated Router tokens remain supported.
+- A separate fine-grained Hugging Face token is installed as the broker-owned
+  `MLCLAW_BROKER_HF_TOKEN`; the active CLI login is used only to provision
+  resources. Legacy dedicated Router tokens remain supported for inference.
 - Agent name, unless a Telegram bot token is supplied and the user wants the
   name derived from the bot username.
 - Gateway mode:
@@ -162,6 +163,25 @@ Use local gateway mode when the user wants the gateway on their machine:
 npx mlclaw@latest bootstrap --gateway local --name mlclaw
 ```
 
+After the first setup, `mlclaw bootstrap` and `mlclaw configure` automatically
+select the only local deployment. Use the same command to reconfigure or resume
+it. If local configuration is missing, interactive bootstrap can recover a
+validated deployment marker from an owned Storage Bucket; credentials and
+machine-specific container bindings must be supplied again.
+
+Tailnet access is explicit:
+
+```bash
+npx mlclaw@latest bootstrap --gateway local --tailscale=direct
+npx mlclaw@latest bootstrap --gateway local --tailscale=serve
+npx mlclaw@latest bootstrap --gateway local --tailscale=off
+```
+
+Direct mode binds loopback and the exact Tailscale IPv4 address. Serve mode
+keeps the gateway on loopback and creates one HTTPS Serve mapping. A Serve
+administrator approval prompt is resumable: approve the printed URL, then run
+bootstrap again.
+
 If the user has multiple Docker engines, pin the intended context:
 
 ```bash
@@ -185,7 +205,7 @@ Default/recommended:
 ```bash
 npx mlclaw@latest bootstrap \
   --name mlclaw \
-  --model huggingface/google/gemma-4-26B-A4B-it:deepinfra
+  --model huggingface/zai-org/GLM-5.2:fireworks-ai
 ```
 
 Known useful router-compatible choices:

package/Dockerfile

@@ -1,8 +1,8 @@
 ARG OPENCLAW_VERSION=2026.7.1
 ARG OPENCLAW_BASE_IMAGE=ghcr.io/openclaw/openclaw:${OPENCLAW_VERSION}
 ARG BROKERKIT_PLUGIN_VERSION=0.2.1
-ARG BROKERKIT_VERSION=hf-broker/v0.1.0
-ARG MLCLAW_RUNTIME_IMAGE=ghcr.io/osolmaz/mlclaw:0.3.8-openclaw-2026.7.1
+ARG BROKERKIT_VERSION=hf-broker/v0.2.0
+ARG MLCLAW_RUNTIME_IMAGE=ghcr.io/osolmaz/mlclaw:0.4.1-openclaw-2026.7.1
 
 FROM golang:1.26.5-bookworm AS hf-broker-build
 ARG BROKERKIT_VERSION

package/README.md

@@ -47,12 +47,23 @@ flow, and resumes after sign-in. Non-interactive runs never install software and
 still require a token up front. You never paste that token into someone else's
 app; the bootstrapper runs locally.
 
-ML Claw places the active Hugging Face token behind an in-container HF Broker.
-The broker owns the real token; OpenClaw receives only a separate agent
-credential that can call the broker's typed, policy-checked routes. It cannot
-read the token or use the admin-only operator API. Existing dedicated inference
-tokens remain supported through `MLCLAW_ROUTER_TOKEN`, `HF_ROUTER_TOKEN`, or
-`--router-token-file` during migration.
+The `hf` CLI login is a provisioning credential: ML Claw uses it to create and
+configure resources owned by your account. HF Broker uses a separate, durable
+fine-grained credential whose required permissions are versioned by BrokerKit.
+Interactive bootstrap opens Hugging Face's token form with those fields
+preselected, then accepts the new token through a hidden local prompt. Creating
+or replacing this credential never changes the active `hf` CLI login. For
+automation, pass a `0600` file through `--broker-hf-token-file`; ML Claw does
+not accept the token as a command-line value.
+
+The broker owns the selected credential; OpenClaw receives only a separate
+agent credential that can call the broker's typed, policy-checked routes. It
+cannot read the token or use the admin-only operator API. Rerunning bootstrap
+reuses a healthy saved broker credential without reopening the form. A missing,
+invalid, wrong-account, or under-scoped credential must be repaired before ML
+Claw continues; it never silently substitutes the active CLI login. Existing
+dedicated inference tokens remain supported through `MLCLAW_ROUTER_TOKEN`,
+`HF_ROUTER_TOKEN`, or `--router-token-file` during migration.
 
 ## Default Flow
 
@@ -62,10 +73,9 @@ npx mlclaw@latest bootstrap --name mlclaw
 
 This creates:
 
-- a private Storage Bucket for OpenClaw state;
-- a private Docker Space for the browser gateway;
-- no explicit Space hardware request; Hugging Face uses the default free CPU
-  hardware unless you pass `--hardware`;
+- a private Docker Space for the browser gateway when the account can host it;
+- a private Storage Bucket for OpenClaw state after the Space is accepted;
+- no explicit Space hardware request unless you pass `--hardware`;
 - a Docker Space that starts from the prebuilt `ghcr.io/osolmaz/mlclaw` image;
 - Hugging Face OAuth metadata for browser auth, Hugging Face MCP, and Research
   Agent access in the Space README;
@@ -75,6 +85,19 @@ This creates:
   Broker process;
 - a local deployment manifest under `~/.config/mlclaw`.
 
+Hugging Face currently requires PRO for Docker Space hosting. When creation is
+rejected for that reason, interactive bootstrap checks for a usable local
+Docker or rootless Podman engine and offers to run the same gateway locally.
+No bucket is created before hosted eligibility is known. Bootstrap does not
+install a container engine or change daemon permissions.
+
+Automation fails instead of changing execution location implicitly. Opt in to
+the same fallback with:
+
+```bash
+npx mlclaw@latest bootstrap --yes --allow-local-fallback
+```
+
 Open the Space, sign in with your Hugging Face account, and use the OpenClaw
 browser gateway directly. The gateway includes a small ML Claw control link
 for settings, status, credentials, and sign out.
@@ -139,9 +162,60 @@ You can run the gateway locally instead of inside a Space:
 npx mlclaw@latest bootstrap --gateway local --name mlclaw
 ```
 
-Local mode uses Docker on your machine and the same private Storage Bucket.
-It avoids Hugging Face messaging egress limits because Telegram traffic comes
-from your network.
+Local mode uses a ready Docker-compatible engine or rootless Podman on your
+machine and the same private Storage Bucket. Runtime selection is deterministic:
+the existing manifest binding wins, an explicit choice comes next, and
+`auto` probes Docker before Podman. Select one explicitly when needed:
+
+```bash
+npx mlclaw@latest bootstrap --gateway local --container-runtime docker
+npx mlclaw@latest bootstrap --gateway local --container-runtime podman
+```
+
+Bootstrap is also the reconfiguration command. With one known deployment,
+rerun `mlclaw bootstrap` or `mlclaw configure` without `--name`; ML Claw selects
+it, shows only configuration changes, and verifies no-op runs without restarting
+a healthy gateway. If the local cache is missing, interactive bootstrap can
+recover a deployment from its validated marker in an owned Storage Bucket.
+Recovery never invents a replacement encryption key: restore the deployment's
+existing `MLCLAW_CREDENTIAL_KEY` in the environment for the recovery run. ML
+Claw verifies its stored SHA-256 fingerprint before changing the runtime.
+
+Cross-host reconciliation uses a generated private Hugging Face model repository
+per deployment as its control lock. Parent-commit compare-and-swap prevents two
+controllers from acquiring the same deployment lease concurrently.
+
+The local control plane is published only on loopback. The default URL is
+`http://127.0.0.1:7860`; choose another unprivileged port with `--local-port`
+when needed. On a remote host, use the SSH forwarding command printed by the
+CLI, then open the same loopback URL in your local browser. The CLI prints a
+private fragment-based access link that is exchanged for an HTTP-only browser
+session; rerun `mlclaw gateway status <agent>` to retrieve it.
+
+To reach the gateway from other devices on your private tailnet, choose direct
+HTTP over Tailscale or an HTTPS Tailscale Serve mapping:
+
+```bash
+npx mlclaw@latest bootstrap --gateway local --tailscale=direct
+npx mlclaw@latest bootstrap --gateway local --tailscale=serve
+mlclaw gateway start mlclaw --tailscale=off
+```
+
+Interactive bootstrap offers this option when Tailscale is installed, signed
+in, and online; it remains off by default. Direct mode publishes only loopback
+and the node's exact Tailscale IPv4 address. Traffic is HTTP in the browser but
+encrypted between tailnet peers by Tailscale. Serve mode keeps the container on
+loopback and owns one scoped HTTPS handler. ML Claw keeps its own browser
+session authentication in front of OpenClaw in both modes, never enables
+Funnel, and never resets unrelated Serve handlers. Use `--tailscale-port
+<port>` for a non-default port. If Serve needs tailnet administrator approval,
+the loopback gateway remains running; approve the printed URL and rerun
+`mlclaw bootstrap` to resume.
+
+Docker Desktop, OrbStack, Colima, Rancher Desktop, and other Docker-compatible
+engines are used through Docker contexts. On Windows, Podman machine
+connections are supported through the Podman CLI. Local mode avoids Hugging
+Face messaging egress limits because Telegram traffic comes from your network.
 
 Move between local and Space without losing state:
 
@@ -163,9 +237,9 @@ mlclaw gateway stop mlclaw
 mlclaw gateway start mlclaw
 ```
 
-Local Docker deployments are pinned to the Docker context used at bootstrap
-time. Rebind explicitly if you move between Docker Desktop, OrbStack, Colima,
-or another Docker engine:
+Local deployments are pinned to their selected engine and connection. Rebind
+Docker deployments explicitly if you move between Docker Desktop, OrbStack,
+Colima, or another Docker engine:
 
 ```bash
 mlclaw gateway rebind mlclaw --docker-context desktop-linux
@@ -191,9 +265,25 @@ It never reads secret values and never modifies bucket contents.
 
 `mlclaw update` also refreshes the generated Space Dockerfile and runtime
 metadata, so older Spaces can move to the current implementation without
-recreating their bucket. For legacy deployments, ML Claw installs the active
-local Hugging Face credential as `MLCLAW_BROKER_HF_TOKEN`, removes stale direct
-token secrets, and restarts the Space with the broker boundary enabled.
+recreating their bucket. It does not promote the active Hugging Face CLI login
+into a runtime secret. Recover or repair the dedicated broker credential first
+when updating a deployment that predates this boundary.
+
+Inspect or replace the dedicated credential with:
+
+```bash
+mlclaw credentials status mlclaw
+mlclaw credentials repair mlclaw
+mlclaw credentials repair mlclaw --broker-hf-token-file ~/secrets/mlclaw-broker.env
+```
+
+`status` performs a read-only verification and prints the account, BrokerKit
+profile, verification time, and a short SHA-256 fingerprint, never the token.
+`repair` validates the replacement before changing anything. Local running
+gateways are replaced transactionally and rolled back on failure; stopped local
+gateways stay stopped. Space repair uses the active CLI login only to install
+the already-validated secret and restart the Space, restoring the previous
+secret and local metadata if the operation fails.
 
 ## Browser Settings
 

package/dist/hf-state-sync.js

@@ -9814,15 +9814,16 @@ async function main(argv) {
     return runStageWorker(liveDir);
   }
   const config = resolveSyncConfig();
+  if (argv[0] === "prepare-restore") {
+    await prepareRestore(config);
+    return 0;
+  }
   const hub = makeHub(config);
   if (!hub) {
     logError("OPENCLAW_HF_STATE_BUCKET is not set; state will NOT survive restarts");
   }
   const mode = argv[0];
   switch (mode) {
-    case "prepare-restore":
-      await prepareRestore(config);
-      return 0;
     case "restore": {
       if (!hub) {
         return 0;