mlclaw 0.3.8 → 0.4.0

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

@@ -162,6 +162,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 +204,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

@@ -2,7 +2,7 @@ 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 MLCLAW_RUNTIME_IMAGE=ghcr.io/osolmaz/mlclaw:0.4.0-openclaw-2026.7.1
 
 FROM golang:1.26.5-bookworm AS hf-broker-build
 ARG BROKERKIT_VERSION

package/README.md

@@ -62,10 +62,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 +74,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 +151,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 +226,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

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;