mlclaw 0.1.0

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

@@ -0,0 +1,214 @@
+---
+name: mlclaw
+description: Use when setting up, operating, migrating, repairing, or explaining an OpenClaw deployment on Hugging Face with the ML Claw `mlclaw` CLI. Covers the browser Space gateway, Hugging Face OAuth, local gateway mode, private Storage Buckets, Telegram as an optional connector, Docker context pinning, model selection through the Hugging Face Router, OpenAI API key setup, costs, diagnostics, and state safety.
+---
+
+# ML Claw
+
+## Core Rule
+
+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.
+
+Default to the browser Space gateway unless the user explicitly asks for local
+gateway mode.
+
+## What ML Claw Creates
+
+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;
+- Hugging Face OAuth enabled on the Space;
+- a local deployment manifest under `~/.config/mlclaw/deployments/`;
+- local secrets under `~/.config/mlclaw/secrets/`;
+- optional local Docker gateway mode for users who want the gateway on their
+  own machine;
+- Hugging Face Router model configuration for OpenClaw inference.
+
+The bucket is the durable state source. The live gateway is disposable. Do not
+mount a bucket as the live OpenClaw database filesystem.
+
+## Required Inputs
+
+Collect or confirm:
+
+- Hugging Face token access: `HF_TOKEN`, `HF_TOKEN_PATH`, `$HF_HOME/token`, or
+  `hf auth login`.
+- Agent name, unless a Telegram bot token is supplied and the user wants the
+  name derived from the bot username.
+- Gateway mode:
+  - `space`: default browser gateway, private Space, HF OAuth protected.
+  - `local`: Docker gateway on the user's machine.
+- Optional model override.
+- Optional Docker context for local mode.
+- Optional Telegram bot token and allowed user ID.
+- Optional explicit owner, name, or bucket only when the user needs them.
+
+If a Telegram token is provided, ML Claw calls Telegram `getMe`, removes a
+trailing `_bot` from the bot username, and can derive the agent, bucket, and
+Space names from that.
+
+## Install And Run
+
+With Node.js:
+
+```bash
+npx mlclaw bootstrap --name research
+```
+
+Without Node.js on macOS/Linux:
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/osolmaz/mlclaw/main/mlclaw.sh) --name research
+```
+
+On Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/osolmaz/mlclaw/main/mlclaw.ps1 | iex
+```
+
+For repo-local development, use:
+
+```bash
+npm install
+npm run build
+node dist/mlclaw.mjs --help
+```
+
+## Recommended First Setup: Browser Space Gateway
+
+Interactive:
+
+```bash
+npx mlclaw bootstrap --name research
+```
+
+Automation:
+
+```bash
+npx mlclaw bootstrap \
+  --name research \
+  --model huggingface/google/gemma-4-26B-A4B-it \
+  --yes
+```
+
+After the Space builds, open it in the browser and sign in with the user's
+Hugging Face account. The Space server proxies authenticated browser traffic to
+OpenClaw on loopback using trusted-proxy auth. Do not ask the user for an
+OpenClaw gateway token for the browser Space path.
+
+Create a public Space only when the user explicitly asks for a public demo or
+template-style deployment:
+
+```bash
+npx mlclaw bootstrap --name research --public-space
+```
+
+## Optional Telegram
+
+Telegram is optional and should not be required for the default setup.
+
+```bash
+npx mlclaw bootstrap \
+  --telegram-token-file ~/secrets/research_bot.env \
+  --telegram-user-id 1234567890 \
+  --hardware cpu-upgrade \
+  --sleep-time -1
+```
+
+Free Hugging Face Spaces intentionally block outbound TLS to some messaging
+APIs for anti-abuse reasons. Telegram/Discord connectivity from a Space
+requires upgraded paid Space hardware today. Local gateway mode avoids that
+restriction because messaging traffic originates from the user's machine.
+
+## Local Gateway Mode
+
+Use local gateway mode when the user wants the gateway on their machine:
+
+```bash
+npx mlclaw bootstrap --gateway local --name research
+```
+
+If the user has multiple Docker engines, pin the intended context:
+
+```bash
+npx mlclaw bootstrap \
+  --gateway local \
+  --name research \
+  --docker-context desktop-linux
+```
+
+Common Docker contexts on macOS are `desktop-linux`, `colima`, and `orbstack`.
+After bootstrap, local gateway commands use the pinned context from the
+manifest even if the shell's current Docker context changes.
+
+## Model Selection
+
+The `--model` value is the OpenClaw model identifier. For Hugging Face Router
+models, use the `huggingface/` prefix.
+
+Default/recommended:
+
+```bash
+npx mlclaw bootstrap \
+  --name research \
+  --model huggingface/google/gemma-4-26B-A4B-it
+```
+
+Known useful router-compatible choices:
+
+- `huggingface/google/gemma-4-26B-A4B-it`: default quality target.
+- `huggingface/Qwen/Qwen3.6-35B-A3B`: stronger Qwen option with tool support.
+- `huggingface/Qwen/Qwen3-8B`: cheaper small-model option.
+
+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.
+
+## Operating A Deployment
+
+Check status:
+
+```bash
+mlclaw gateway status <agent>
+mlclaw doctor <owner/space>
+```
+
+Update a Space:
+
+```bash
+mlclaw update <owner/space>
+mlclaw doctor <owner/space> --fix
+```
+
+Move gateway location without losing state:
+
+```bash
+mlclaw gateway migrate <agent> --to local
+mlclaw gateway migrate <agent> --to space
+```
+
+Local gateway lifecycle:
+
+```bash
+mlclaw gateway logs <agent>
+mlclaw gateway stop <agent>
+mlclaw gateway start <agent>
+```
+
+## OpenAI Credentials
+
+After signing into the Space, use `/mlclaw/openai` to submit an OpenAI API key.
+The 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.
+
+## 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.

package/.agents/skills/mlclaw/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ML Claw"
+  short_description: "Set up OpenClaw on Hugging Face"
+  default_prompt: "Use $mlclaw to set up an OpenClaw deployment on Hugging Face with mlclaw."

package/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

package/Dockerfile

@@ -0,0 +1,45 @@
+# Stage 1: build the state-sync bundle so the runtime image needs no dev deps.
+FROM node:24-bookworm-slim AS sync-build
+WORKDIR /build
+COPY package.json package-lock.json tsconfig.json ./
+COPY src ./src
+RUN npm ci --no-audit --no-fund && npm run build
+
+FROM ghcr.io/openclaw/openclaw:latest
+
+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
+# zstd: snapshot archives. gosu: drop privileges after preparing mounted volumes.
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends gosu zstd \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY --from=sync-build /build/dist/hf-state-sync.js /app/hf-state-sync.js
+COPY --from=sync-build /build/dist/mlclaw-space-runtime.js /app/mlclaw-space-runtime.js
+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/
+COPY --chown=node:node scripts/ /app/scripts/
+RUN chmod +x /app/entrypoint.sh
+
+USER root
+
+# Live state on local disk; the bucket is reached only through the TS client.
+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_DISABLE_BONJOUR=1
+ARG MLCLAW_RUNTIME_IMAGE=ghcr.io/osolmaz/mlclaw-runtime:latest
+ENV MLCLAW_RUNTIME_IMAGE=$MLCLAW_RUNTIME_IMAGE
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=5 CMD node -e "const port=process.env.PORT||'7860'; fetch('http://127.0.0.1:'+port+'/health').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+CMD ["/app/entrypoint.sh"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Onur Solmaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/osolmaz/mlclaw/main/assets/mlclaw.svg" alt="ML Claw" width="180">
+</p>
+
+# ML Claw
+
+ML Claw deploys an OpenClaw agent on Hugging Face with durable state in a
+private Storage Bucket. The default deployment is a private Hugging Face Space
+with a browser gateway protected by Hugging Face OAuth.
+
+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.
+
+## Install
+
+With Node.js:
+
+```bash
+npx mlclaw bootstrap
+```
+
+Without Node.js, the launcher fetches a pinned Node runtime into your user
+cache and runs the same npm package:
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/osolmaz/mlclaw/main/mlclaw.sh)
+```
+
+On Windows:
+
+```powershell
+irm https://raw.githubusercontent.com/osolmaz/mlclaw/main/mlclaw.ps1 | iex
+```
+
+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.
+
+## Default Flow
+
+```bash
+npx mlclaw bootstrap --name research
+```
+
+This creates:
+
+- a private Storage Bucket for OpenClaw state;
+- a private Docker Space for the browser gateway;
+- a self-contained Space runtime generated from the installed `mlclaw` package;
+- Hugging Face OAuth metadata in the Space README;
+- Space variables and write-only secrets for state sync and session signing;
+- a local deployment manifest under `~/.config/mlclaw`.
+
+Open the Space, sign in with your Hugging Face account, and use the OpenClaw
+browser gateway directly.
+
+Create a public Space only when you explicitly want a public demo or template:
+
+```bash
+npx mlclaw bootstrap --name research --public-space
+```
+
+Choose a Hugging Face Router model with `--model`:
+
+```bash
+npx mlclaw bootstrap \
+  --name research \
+  --model huggingface/google/gemma-4-26B-A4B-it
+```
+
+Recommended router-compatible options:
+
+- `huggingface/google/gemma-4-26B-A4B-it`: default quality target.
+- `huggingface/Qwen/Qwen3.6-35B-A3B`: stronger Qwen option with tool support.
+- `huggingface/Qwen/Qwen3-8B`: cheaper small-model option.
+
+## Optional Telegram
+
+Telegram is optional. If you provide a Telegram bot token, ML Claw calls
+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 \
+  --telegram-token-file ~/secrets/research_bot.env \
+  --telegram-user-id 1234567890 \
+  --hardware cpu-upgrade \
+  --sleep-time -1
+```
+
+Hugging Face free Spaces intentionally block outbound TLS to some messaging
+APIs. Telegram/Discord connectivity therefore requires upgraded paid Space
+hardware today. ML Claw warns before requesting paid hardware; pass `--yes`
+only for automation.
+
+## Local Gateway Mode
+
+You can run the gateway locally instead of inside a Space:
+
+```bash
+npx mlclaw bootstrap --gateway local --name research
+```
+
+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.
+
+Move between local and Space without losing state:
+
+```bash
+mlclaw gateway migrate research --to local
+mlclaw gateway migrate research --to space
+```
+
+Useful operations:
+
+```bash
+mlclaw gateway status research
+mlclaw gateway logs research
+mlclaw gateway stop research
+mlclaw gateway start research
+```
+
+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:
+
+```bash
+mlclaw gateway rebind research --docker-context desktop-linux
+```
+
+## Update and Repair
+
+Update an existing Space to the current ML Claw implementation:
+
+```bash
+mlclaw update your-hf-username/research
+```
+
+Check a deployment and apply safe configuration repairs:
+
+```bash
+mlclaw doctor your-hf-username/research
+mlclaw doctor your-hf-username/research --fix
+```
+
+`doctor --fix` may update Space variables and missing session-secret plumbing.
+It never reads secret values and never modifies bucket contents.
+
+`mlclaw update` also refreshes the generated Space runtime files, so older
+Spaces can move to the current implementation without recreating their bucket.
+
+## OpenAI Credentials
+
+After signing into the Space, open:
+
+```text
+/mlclaw/openai
+```
+
+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.
+
+## 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.
+
+## Costs
+
+- Browser Space gateway: `cpu-basic` is enough for the default browser gateway.
+- Telegram/Discord from a Space: requires paid upgraded Space hardware today.
+- Inference: requests use your Hugging Face Inference Providers credits, then
+  provider pay-as-you-go pricing.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm test
+npm run pack:check
+npm run check:secrets
+```
+
+Core directories:
+
+- `src/mlclaw/`: CLI and Hub orchestration.
+- `src/mlclaw-space-runtime/`: Space OAuth proxy and browser gateway wrapper.
+- `src/hf-state-sync/`: snapshot/restore supervisor.
+- `src/hf-bucket-client/`: TypeScript Storage Bucket client.
+
+## License
+
+[MIT](LICENSE)