mlclaw 0.2.3 → 0.3.1

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

@@ -9,7 +9,9 @@ description: Use when setting up, operating, migrating, repairing, or explaining
 
 Use the `mlclaw` CLI as the source of truth. Do not hand-create Hugging Face
 Spaces, buckets, secrets, or Docker containers unless debugging a failed
-`mlclaw` operation. Keep credentials local to the user's machine.
+`mlclaw` operation. Keep bootstrap credentials local to the user's machine.
+Space OAuth credentials may be stored only through ML Claw's encrypted,
+process-isolated integration store.
 
 Default to the browser Space gateway unless the user explicitly asks for local
 gateway mode.
@@ -20,24 +22,36 @@ An ML Claw deployment has:
 
 - a private Hugging Face Storage Bucket for durable OpenClaw state snapshots;
 - a private Hugging Face Docker Space for the default browser gateway;
+- no explicit Space hardware request by default; Hugging Face assigns the
+  default free CPU hardware unless `--hardware` or a feature requiring paid
+  hardware is used;
 - a prebuilt `ghcr.io/osolmaz/mlclaw` runtime image by default;
 - Hugging Face OAuth enabled on the Space;
+- automatic Hugging Face MCP and Research Agent integrations authorized by an
+  admin-only OAuth step after ordinary Hugging Face sign-in;
 - a local deployment manifest under `~/.config/mlclaw/deployments/`;
 - local secrets under `~/.config/mlclaw/secrets/`;
+- app Spaces mount the private Storage Bucket read-write at
+  `/data/mlclaw-state` for snapshot storage without storing the user's broad
+  Hub token in the Space;
 - preinstalled Hugging Face tooling in the OpenClaw workspace, including
   `hf`, `hf-discover`, `uv`, HF Python libraries, and baseline Hugging Face
   Agent Skills mirrored into both `.agents/skills` and `skills`;
 - optional local Docker gateway mode for users who want the gateway on their
   own machine;
-- Hugging Face Router model configuration for OpenClaw inference.
+- Hugging Face Router model configuration through an isolated HF Broker.
 
 The bucket is the durable state source. The live gateway is disposable. Do not
-mount a bucket as the live OpenClaw database filesystem.
+mount a bucket as the live OpenClaw database filesystem. Space gateway mode
+uses the mounted bucket only for verified snapshots; live SQLite and workspace
+state stay on local container disk under
+`/home/node/.local/share/mlclaw/live`.
 
-ML Claw seeds a managed Hugging Face tooling note into workspace `AGENTS.md` so
-new OpenClaw sessions see the available Hugging Face skills directly in
-context. If a long-running session predates the seed, start a new OpenClaw
-session so its skill snapshot is rebuilt.
+ML Claw waits for OpenClaw's native first-run identity bootstrap to finish,
+then seeds a managed Hugging Face tooling note into workspace `AGENTS.md` so
+new sessions see the available Hugging Face skills directly in context. If a
+long-running session predates the seed, start a new OpenClaw session so its
+skill snapshot is rebuilt.
 
 ## Required Inputs
 
@@ -45,6 +59,8 @@ 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.
 - Agent name, unless a Telegram bot token is supplied and the user wants the
   name derived from the bot username.
 - Gateway mode:
@@ -185,6 +201,11 @@ Known useful router-compatible choices:
 - `huggingface/deepseek-ai/DeepSeek-V4-Pro:deepinfra`: higher-quality long-context DeepSeek V4 option.
 - `huggingface/MiniMaxAI/MiniMax-M3:together`: long-context MiniMax option with tool and structured-output support.
 
+Fireworks alternatives using the `:fireworks-ai` suffix are curated for GLM
+5.2, Kimi K2.7 Code, GPT-OSS 120B and 20B, DeepSeek V4 Flash and Pro, and
+MiniMax M3. The Router catalog does not currently expose the Gemma 4 or Qwen
+3.6 presets through Fireworks.
+
 Do not assume every Hub model is a Router chat model. If exact current model
 availability matters, check the Hugging Face Router catalog or run a direct
 chat-completions probe.
@@ -224,14 +245,30 @@ mlclaw gateway start <agent>
 
 After signing into the Space, use the ML Claw control UI:
 
-- `/mlclaw/settings` chooses Router model/provider rows and changes the Space
-  `OPENCLAW_MODEL` and `MLCLAW_MODEL_CHOICES`.
-- `/mlclaw/status` shows runtime, bucket, model, and OAuth status.
-- `/mlclaw/credentials` stores an OpenAI API key.
-
-The OpenAI key is stored as a Hugging Face Space Secret when possible and as a
-0600 runtime file for immediate use. The key must never be logged or returned
-to the browser.
+- `/mlclaw/settings` chooses Router model/provider rows. App Spaces without a
+  Hub token save the selection into snapshotted runtime state and restart only
+  OpenClaw; the CLI remains responsible for privileged Space variable changes.
+- `/mlclaw/status` shows runtime, bucket, model, OAuth, and integration status.
+- `/mlclaw/credentials` connects or disconnects Hugging Face MCP and Research
+  Agent access, and stores an OpenAI API key.
+
+The trusted ML Claw wrapper stores Hugging Face OAuth tokens encrypted on the
+mounted private state volume. OpenClaw runs as a separate unprivileged Unix
+user and receives only local MCP server URLs plus an internal capability
+header; never place the OAuth token in OpenClaw config or environment.
+
+After migrating to a local gateway, the MCP proxy uses the local deployment's
+Hugging Face token inside the trusted wrapper instead of requiring the Space's
+OAuth client. Migrating back resumes the encrypted OAuth credential retained
+in the private bucket. OpenClaw receives only a generated HF Broker agent
+credential; it never receives the broader local Hub token or the broker
+operator credential.
+
+The OpenAI key is stored as a 0600 runtime file for immediate use. For
+restart-durable OpenAI credentials, use the local `mlclaw` CLI or Space
+settings to set a Space Secret; do not put the user's broad Hub token into the
+Space just so the browser app can mutate secrets. The key must never be logged
+or returned to the browser.
 
 ## Branding
 
@@ -262,7 +299,9 @@ them through `/assets/brand/logo`, `/favicon.svg`, `/favicon-32.png`,
 
 ## State Safety
 
-OpenClaw uses local disk. The bucket stores verified snapshots only. On boot,
-the runtime restores the newest valid snapshot. During runtime and shutdown,
-`hf-state-sync` uploads new snapshots. Secrets are kept outside the snapshot
-path.
+OpenClaw uses local disk. In Space gateway mode, the private bucket is mounted
+at `/data/mlclaw-state`, but it stores verified snapshots only. On boot, the
+runtime restores the newest valid snapshot into
+`/home/node/.local/share/mlclaw/live`. During runtime and shutdown,
+`hf-state-sync` writes new snapshots back to the mounted bucket. Secrets are
+kept outside the snapshot path.

package/Dockerfile

@@ -1,6 +1,32 @@
-ARG OPENCLAW_VERSION=2026.7.1-beta.2
+ARG OPENCLAW_VERSION=2026.7.1-beta.5
 ARG OPENCLAW_BASE_IMAGE=ghcr.io/openclaw/openclaw:${OPENCLAW_VERSION}
-ARG MLCLAW_RUNTIME_IMAGE=ghcr.io/osolmaz/mlclaw:0.2.3-openclaw-2026.7.1-beta.2
+ARG BROKERKIT_PLUGIN_VERSION=0.1.0
+ARG BROKERKIT_VERSION=fcfc5f2304436d952b18e7c9583bb378d1952776
+ARG MLCLAW_RUNTIME_IMAGE=ghcr.io/osolmaz/mlclaw:0.3.1-openclaw-2026.7.1-beta.5
+
+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
 
 # Stage 1: build the state-sync bundle so the runtime image needs no dev deps.
 FROM node:24-bookworm-slim AS sync-build
@@ -17,7 +43,8 @@ LABEL org.opencontainers.image.description="ML Claw runtime for OpenClaw on Hugg
 USER root
 # zstd: snapshot archives. gosu: drop privileges after preparing mounted volumes.
 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" \
@@ -31,10 +58,18 @@ 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 --from=sync-build /build/dist/hf-state-sync.js /app/hf-state-sync.js
 COPY --from=sync-build /build/dist/hf-tooling-seed.js /app/hf-tooling-seed.js
 COPY --from=sync-build /build/dist/mlclaw-space-runtime.js /app/mlclaw-space-runtime.js
+COPY --from=hf-broker-build /out/hf-broker /usr/local/bin/hf-broker
+COPY hf-broker.scope.json /app/hf-broker.scope.json
 COPY --chown=node:node openclaw.default.json /app/openclaw.default.json
 COPY --chown=node:node entrypoint.sh /app/entrypoint.sh
 COPY --chown=node:node assets/ /app/assets/
@@ -43,15 +78,18 @@ RUN chmod +x /app/entrypoint.sh
 
 USER root
 
-# Live state on local disk; the bucket is reached only through the TS client.
+# Live state stays on local disk; Space bucket volumes are mounted separately for snapshots.
 ENV PORT=7860
 ENV MLCLAW_OPENCLAW_PORT=7861
+ENV MLCLAW_OPENCLAW_UID=1000
+ENV MLCLAW_OPENCLAW_GID=1000
 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
 ARG MLCLAW_RUNTIME_IMAGE
 ENV MLCLAW_RUNTIME_IMAGE=$MLCLAW_RUNTIME_IMAGE
 

package/README.md

@@ -12,6 +12,12 @@ The browser never receives an OpenClaw gateway token. ML Claw authenticates the
 signed-in Hugging Face user, then proxies HTTP and WebSocket traffic to
 OpenClaw on loopback using OpenClaw trusted-proxy auth.
 
+After signing in, an administrator can authorize the hosted Hugging Face MCP
+server and Research Agent with the same Hugging Face account. Ordinary users
+grant only identity scopes. Integration credentials stay in the trusted ML
+Claw wrapper; the unprivileged OpenClaw process receives only loopback MCP
+access.
+
 ## Install
 
 With Node.js:
@@ -37,6 +43,13 @@ You need a Hugging Face account and a token available through `HF_TOKEN`,
 `HF_TOKEN_PATH`, `$HF_HOME/token`, or `hf auth login`. 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.
+
 ## Default Flow
 
 ```bash
@@ -47,9 +60,15 @@ 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 Docker Space that starts from the prebuilt `ghcr.io/osolmaz/mlclaw` image;
-- Hugging Face OAuth metadata in the Space README;
-- Space variables and write-only secrets for state sync and session signing;
+- Hugging Face OAuth metadata for browser auth, Hugging Face MCP, and Research
+  Agent access in the Space README;
+- Space variables, a bucket volume mount for state sync, and separate
+  write-only secrets for session signing and OAuth credential encryption;
+- an `MLCLAW_BROKER_HF_TOKEN` Space secret consumed only by the isolated HF
+  Broker process;
 - a local deployment manifest under `~/.config/mlclaw`.
 
 Open the Space, sign in with your Hugging Face account, and use the OpenClaw
@@ -83,6 +102,11 @@ Recommended router-compatible options:
 - `huggingface/deepseek-ai/DeepSeek-V4-Pro:deepinfra`: higher-quality long-context DeepSeek V4 option.
 - `huggingface/MiniMaxAI/MiniMax-M3:together`: long-context MiniMax option with tool and structured-output support.
 
+Fireworks alternatives are also included for GLM 5.2, Kimi K2.7 Code,
+GPT-OSS 120B and 20B, DeepSeek V4 Flash and Pro, and MiniMax M3. Use the
+provider suffix `:fireworks-ai`. The current Router catalog does not expose the
+Gemma 4 or Qwen 3.6 presets through Fireworks.
+
 ## Optional Telegram
 
 Telegram is optional. If you provide a Telegram bot token, ML Claw calls
@@ -121,6 +145,10 @@ mlclaw gateway migrate mlclaw --to local
 mlclaw gateway migrate mlclaw --to space
 ```
 
+The local MCP proxy uses the Hugging Face token kept in the local deployment
+environment. The trusted wrapper does not need the Space OAuth client, and the
+encrypted Space OAuth credential remains in the bucket for migration back.
+
 Useful operations:
 
 ```bash
@@ -158,7 +186,9 @@ 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.
+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.
 
 ## Browser Settings
 
@@ -172,8 +202,21 @@ Use the browser control UI for:
 
 - `/mlclaw/settings`: choose Router model/provider rows, update `OPENCLAW_MODEL`
   and `MLCLAW_MODEL_CHOICES`, and request a Space restart.
-- `/mlclaw/status`: inspect runtime, bucket, model, and OAuth status.
-- `/mlclaw/credentials`: submit an OpenAI API key.
+- `/mlclaw/status`: inspect runtime, bucket, model, OAuth, and integration status.
+
+OpenClaw's BrokerKit plugin adds an **Approvals** tab to the gateway. The tab
+merges every BrokerKit-compatible backend configured in
+`MLCLAW_OPERATOR_BROKERS_FILE` and lets administrators inspect, approve, deny,
+cancel, or revoke requests. The plugin registers the Gateway tab, while ML Claw
+serves the immutable packaged UI from its trusted HTTP boundary and gives it a
+small launcher inside the Gateway. Decisions open in an unframeable protected
+document with a renewable, short-lived, admin-bound browser token. Broker
+operator tokens remain in backend-only files and are never sent to the browser
+or OpenClaw. See
+[Operator Broker Configuration](docs/operator-brokers-config.md).
+
+- `/mlclaw/credentials`: connect or disconnect Hugging Face MCP and Research
+  Agent access, or submit an OpenAI API key.
 - `/mlclaw/logout`: clear the ML Claw session cookie.
 
 The same control UI is linked from the OpenClaw gateway. Settings changes
@@ -215,21 +258,36 @@ After signing into the Space, open:
 ```
 
 Submit an OpenAI API key there if you want OpenClaw to use OpenAI-compatible
-models. ML Claw stores the key as a Hugging Face Space Secret when possible,
-writes a 0600 runtime file for immediate use, and restarts the internal
-OpenClaw gateway with `OPENAI_API_KEY` set. The key is never returned to the
-browser.
+models. ML Claw writes a `0600` runtime file for immediate use and an encrypted
+durable credential protected by `MLCLAW_CREDENTIAL_KEY`, then restarts the
+internal OpenClaw gateway with `OPENAI_API_KEY` set. When trusted Hub authority
+is available, it also stores the key as a write-only Space secret. The key is
+never returned to the browser, exposed to the agent except as its intended
+OpenAI credential, or stored as plaintext in the state bucket. App Spaces do
+not keep broad Hugging Face authority in the web control process.
 
 ## How State Works
 
-OpenClaw runs against local disk inside the active runtime. The Storage Bucket
-is not mounted as a live filesystem. Instead, `hf-state-sync` restores the
-newest verified snapshot on boot and uploads verified snapshots during runtime
-and shutdown.
-
-That keeps SQLite off network-mounted storage while preserving the agent's
-memory across Space rebuilds, local container replacement, and gateway
-migration.
+OpenClaw runs against local disk inside the active runtime. In Space gateway
+mode, ML Claw mounts the private Storage Bucket at `/data/mlclaw-state` and
+uses that mounted directory only for verified snapshots. The live OpenClaw
+state stays on local container disk at
+`/home/node/.local/share/mlclaw/live`.
+
+That keeps SQLite off bucket-backed storage while preserving the agent's memory
+across Space rebuilds, local container replacement, and gateway migration. The
+Space does not use `HF_TOKEN` or `HUGGINGFACE_HUB_TOKEN` secrets. Its broad
+credential is stored as `MLCLAW_BROKER_HF_TOKEN`, written to a broker-owned
+`0600` file during startup, and removed from child-process environments.
+OpenClaw uses only the generated broker agent credential. Broker grant and
+event state and encrypted control credentials live under the root-owned
+`/var/lib/mlclaw-protected` tree. They are included in the durable snapshot
+through a root-only `.mlclaw-protected` staging step, then restored outside the
+agent-owned live directory before OpenClaw starts. Rebuildable Git mirrors, the
+broad token, and operator credentials are never included in snapshots.
+Local gateways pass the broad credential only to the trusted state-sync
+supervisor for bucket I/O and to the trusted MCP integration proxy through a
+protected token file. Neither path passes it to OpenClaw.
 
 ## Costs