mlclaw 0.2.2 → 0.3.0

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:
@@ -64,7 +80,7 @@ Space names from that.
 With Node.js:
 
 ```bash
-npx mlclaw bootstrap --name mlclaw
+npx mlclaw@latest bootstrap --name mlclaw
 ```
 
 Without Node.js on macOS/Linux:
@@ -92,13 +108,13 @@ node dist/mlclaw.mjs --help
 Interactive:
 
 ```bash
-npx mlclaw bootstrap --name mlclaw
+npx mlclaw@latest bootstrap --name mlclaw
 ```
 
 Automation:
 
 ```bash
-npx mlclaw bootstrap \
+npx mlclaw@latest bootstrap \
   --name mlclaw \
   --model huggingface/google/gemma-4-26B-A4B-it:deepinfra \
   --yes
@@ -118,7 +134,7 @@ Create a public Space only when the user explicitly asks for a public demo or
 template-style deployment:
 
 ```bash
-npx mlclaw bootstrap --name mlclaw --public-space
+npx mlclaw@latest bootstrap --name mlclaw --public-space
 ```
 
 ## Optional Telegram
@@ -126,7 +142,7 @@ npx mlclaw bootstrap --name mlclaw --public-space
 Telegram is optional and should not be required for the default setup.
 
 ```bash
-npx mlclaw bootstrap \
+npx mlclaw@latest bootstrap \
   --telegram-token-file ~/secrets/mlclaw_bot.env \
   --telegram-user-id 1234567890 \
   --hardware cpu-upgrade \
@@ -143,13 +159,13 @@ restriction because messaging traffic originates from the user's machine.
 Use local gateway mode when the user wants the gateway on their machine:
 
 ```bash
-npx mlclaw bootstrap --gateway local --name mlclaw
+npx mlclaw@latest bootstrap --gateway local --name mlclaw
 ```
 
 If the user has multiple Docker engines, pin the intended context:
 
 ```bash
-npx mlclaw bootstrap \
+npx mlclaw@latest bootstrap \
   --gateway local \
   --name mlclaw \
   --docker-context desktop-linux
@@ -167,7 +183,7 @@ models, use the `huggingface/` prefix.
 Default/recommended:
 
 ```bash
-npx mlclaw bootstrap \
+npx mlclaw@latest bootstrap \
   --name mlclaw \
   --model huggingface/google/gemma-4-26B-A4B-it:deepinfra
 ```
@@ -175,6 +191,7 @@ npx mlclaw bootstrap \
 Known useful router-compatible choices:
 
 - `huggingface/google/gemma-4-26B-A4B-it:deepinfra`: default quality target.
+- `huggingface/Qwen/Qwen3.6-35B-A3B:deepinfra`: strong Qwen 3.6 option with tool and structured-output support.
 - `huggingface/Qwen/Qwen3.6-27B:deepinfra`: live Qwen 3.6 option with tool and structured-output support.
 - `huggingface/zai-org/GLM-5.2:deepinfra`: long-context GLM option with tool and structured-output support.
 - `huggingface/moonshotai/Kimi-K2.7-Code:deepinfra`: coding-focused Kimi option with tool and structured-output support.
@@ -183,7 +200,11 @@ Known useful router-compatible choices:
 - `huggingface/deepseek-ai/DeepSeek-V4-Flash:deepinfra`: low-cost long-context DeepSeek V4 option.
 - `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.
-- `huggingface/Qwen/Qwen3-8B:nscale`: cheaper small-model option.
+
+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
@@ -224,22 +245,39 @@ 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
 
 ML Claw white-labels the browser gateway at the proxy layer. App Spaces default
-the browser title, PWA manifest, assistant fallback avatar, login heading, and
-ML Claw control link to the agent name. The ML Claw logo is reserved for the
-control UI brand mark. The gateway shortcut, login logo, and default browser
-icons use the Hugging Face logo.
+the browser title, PWA manifest, login heading, and ML Claw control link to the
+agent name. The ML Claw logo is reserved for the control UI brand mark. The
+gateway shortcut, login logo, and default browser icons use the Hugging Face
+logo. The OpenClaw assistant fallback avatar defaults to a neutral assistant
+icon.
 
 Use Space variables for explicit branding:
 
@@ -251,7 +289,8 @@ MLCLAW_BRAND_LOGO="mlclaw.svg"
 MLCLAW_BRAND_FAVICON="hf-logo.svg"
 MLCLAW_BRAND_FAVICON_32="hf-logo.svg"
 MLCLAW_BRAND_FAVICON_ICO="hf-logo.svg"
-MLCLAW_BRAND_APPLE_TOUCH_ICON="hf-logo.svg"
+MLCLAW_BRAND_APPLE_TOUCH_ICON="assistant-avatar.svg"
+MLCLAW_BRAND_ASSISTANT_AVATAR="assistant-avatar.svg"
 ```
 
 Brand asset paths are relative to the Space `assets/` directory. ML Claw serves
@@ -260,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,33 @@
-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.2-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.0-openclaw-2026.7.1-beta.5
+ARG HF_BROKER_VERSION=bb65192b4dca845289427e63e1d5fa72f64914d8
+
+FROM golang:1.26.5-bookworm AS hf-broker-build
+ARG HF_BROKER_VERSION
+RUN git init /src \
+  && git -C /src fetch --depth=1 https://github.com/osolmaz/hf-broker.git "$HF_BROKER_VERSION" \
+  && git -C /src checkout --detach FETCH_HEAD \
+  && test "$(git -C /src rev-parse HEAD)" = "$HF_BROKER_VERSION" \
+  && cd /src \
+  && GOWORK=off go build -trimpath -o /out/hf-broker ./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 +44,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 +59,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 +79,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,12 +12,18 @@ 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:
 
 ```bash
-npx mlclaw bootstrap
+npx mlclaw@latest bootstrap
 ```
 
 Without Node.js, the launcher fetches a pinned Node runtime into your user
@@ -37,19 +43,32 @@ 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
-npx mlclaw bootstrap --name mlclaw
+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 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
@@ -59,13 +78,13 @@ for settings, status, credentials, and sign out.
 Create a public Space only when you explicitly want a public demo or template:
 
 ```bash
-npx mlclaw bootstrap --name mlclaw --public-space
+npx mlclaw@latest bootstrap --name mlclaw --public-space
 ```
 
 Choose a Hugging Face Router model with `--model`:
 
 ```bash
-npx mlclaw bootstrap \
+npx mlclaw@latest bootstrap \
   --name mlclaw \
   --model huggingface/google/gemma-4-26B-A4B-it:deepinfra
 ```
@@ -73,6 +92,7 @@ npx mlclaw bootstrap \
 Recommended router-compatible options:
 
 - `huggingface/google/gemma-4-26B-A4B-it:deepinfra`: default quality target.
+- `huggingface/Qwen/Qwen3.6-35B-A3B:deepinfra`: strong Qwen 3.6 option with tool and structured-output support.
 - `huggingface/Qwen/Qwen3.6-27B:deepinfra`: live Qwen 3.6 option with tool and structured-output support.
 - `huggingface/zai-org/GLM-5.2:deepinfra`: long-context GLM option with tool and structured-output support.
 - `huggingface/moonshotai/Kimi-K2.7-Code:deepinfra`: coding-focused Kimi option with tool and structured-output support.
@@ -81,7 +101,11 @@ Recommended router-compatible options:
 - `huggingface/deepseek-ai/DeepSeek-V4-Flash:deepinfra`: low-cost long-context DeepSeek V4 option.
 - `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.
-- `huggingface/Qwen/Qwen3-8B:nscale`: cheaper small-model option.
+
+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
 
@@ -90,7 +114,7 @@ Telegram `getMe`, removes a trailing `_bot` from the username, and can derive
 the Space and bucket names from the bot username.
 
 ```bash
-npx mlclaw bootstrap \
+npx mlclaw@latest bootstrap \
   --telegram-token-file ~/secrets/mlclaw_bot.env \
   --telegram-user-id 1234567890 \
   --hardware cpu-upgrade \
@@ -107,7 +131,7 @@ only for automation.
 You can run the gateway locally instead of inside a Space:
 
 ```bash
-npx mlclaw bootstrap --gateway local --name mlclaw
+npx mlclaw@latest bootstrap --gateway local --name mlclaw
 ```
 
 Local mode uses Docker on your machine and the same private Storage Bucket.
@@ -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
@@ -182,10 +225,11 @@ mutate only the current Space, inferred from `SPACE_ID`.
 ## Branding
 
 ML Claw white-labels the browser-facing gateway by default. App Spaces use the
-agent name as the browser title, PWA name, login heading, assistant fallback
-avatar, and ML Claw control link label. The ML Claw logo is reserved for the
-control UI brand mark. The gateway shortcut, login logo, and default browser
-icons use the Hugging Face logo.
+agent name as the browser title, PWA name, login heading, and ML Claw control
+link label. The ML Claw logo is reserved for the control UI brand mark. The
+gateway shortcut, login logo, and default browser icons use the Hugging Face
+logo. The OpenClaw assistant fallback avatar defaults to a neutral assistant
+icon.
 
 Override branding with Space variables:
 
@@ -197,7 +241,8 @@ MLCLAW_BRAND_LOGO=mlclaw.svg
 MLCLAW_BRAND_FAVICON=hf-logo.svg
 MLCLAW_BRAND_FAVICON_32=hf-logo.svg
 MLCLAW_BRAND_FAVICON_ICO=hf-logo.svg
-MLCLAW_BRAND_APPLE_TOUCH_ICON=hf-logo.svg
+MLCLAW_BRAND_APPLE_TOUCH_ICON=assistant-avatar.svg
+MLCLAW_BRAND_ASSISTANT_AVATAR=assistant-avatar.svg
 ```
 
 Brand asset paths are relative to the Space `assets/` directory. ML Claw serves
@@ -213,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
 

package/assets/assistant-avatar.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-label="Assistant">
+  <rect width="256" height="256" rx="64" fill="#111827"/>
+  <path fill="#f9fafb" d="M128 52 146 107h58l-47 34 18 55-47-34-47 34 18-55-47-34h58z"/>
+  <circle cx="128" cy="128" r="92" fill="none" stroke="#f9fafb" stroke-width="10" opacity=".22"/>
+</svg>