Clawsembly

Run upstream OpenClaw browser-locally, behind a host boundary the embedding application controls. Evidence-gated, and specialized in OpenClaw rather than generic across agents.

日本語: README.ja.md

Clawsembly is an evidence-gated embedding layer specialized in OpenClaw: it runs the upstream package browser-locally, behind a host boundary the embedding application controls, binding the exact published package to public compatibility evidence and refusing to launch it until that evidence verifies. Today every tracked release is probing — meaning the exact artifact has been statically inspected, but no owner-authorized runtime evidence exists yet, so verified launch stays blocked. Wrapping upstream OpenClaw with the conveniences its operators and embedders need — native-Gateway interoperability, release intelligence, extension vetting — is the product direction (ADR 0006); other upstream agents are out of scope for this repository. Clawsembly is an experimental, single-maintainer project and is not affiliated with or endorsed by the OpenClaw project.

What works today, what is blocked

Item	Status	Notes
Zero-install promotion-policy check	Works	node examples/release-policy/check.mjs --observe prints the current promotion decision in a few seconds, no dependencies.
Hosted project page	Works	Live reports plus a permission-prompt demo against an inert local broker: approve, deny, revoke, export a payload-free audit.
npm alpha package	Record-gated	npm install @haya-inc/clawsembly@alpha installs the latest reviewed npm publication. The prepared version's registry status lives in the publication record: pending until its release train completes, published with SHA-512 integrity and Sigstore provenance once reviewed.
Evidence-gated boot demo	Works	The SDK host example verifies the pinned report and shows Provider boot blocked. Refusing an unverified report is the security feature, working.
Boundary chain on real BrowserPod	Works	The hello-agent reference binding's full chain — exact-digest staging, dual readiness, capability-mediated chat with denied and allowed outcomes, in-flight abort, cooperative guest stop — has one owner-authorized record on browserpod@2.12.1 (evidence, capture host). A reference binding, not a real agent; OpenClaw boot stays blocked below.
Verified BrowserPod boot	Blocked	Current stable openclaw@2026.7.1-2 declares the compound engines range >=22.22.3 <23 || >=24.15.0 <25 || >=25.9.0, which the exact-form baseline gate rejects before any token spend (node_baseline_unsupported), and BrowserPod 2.12.1 provisions Node 22.15.0 — below every branch of that range; reported to the vendor. The checked-in openclaw@2026.5.7 report remains the capturable target (#6).
Live provider smoke test	Blocked	The gated path exists but has never been executed.
Performance baselines	Measured	Owner-authorized baseline on browserpod@2.12.1, three samples per pass (baseline): median provider boot under 0.9 s, digest-verified staging under 15 ms, first protocol round trip ≈6.2 s cold / ≈4.7 s with persistent workspace reuse. Boundary-chain numbers on the reference binding — OpenClaw install and Gateway timings stay open (#8).

Try it

Three steps, no API key required:

1. Watch the promotion gate decide (plain Node 22.19+, no install):

   git clone https://github.com/haya-inc/clawsembly
   cd clawsembly
   node examples/release-policy/check.mjs --observe

2. Open the hosted project page at https://haya-inc.github.io/clawsembly/. It tracks the npm latest, previous stable, and beta OpenClaw channels and runs the reusable permission-prompt component against an inert local broker — no runtime boots, no host capability is invoked.

3. Install the published alpha and see evidence-gated boot refuse:

   npm install @haya-inc/clawsembly@alpha

   Then follow the copy-ready SDK host starter or open the deployed copy. It fetches the exact HTTPS compatibility report, verifies its pinned SHA-256 plus artifact and runtime identity, and must show Provider boot blocked without calling BrowserPod while the report remains probing.

Runtime and cost disclosure

Clawsembly's committed browser-local runtime is BrowserPod, which is proprietary and metered. Every downstream deployment needs its own BrowserPod API key; the free tier is limited to non-commercial use with attribution, and a BrowserPod OSS grant program exists for open-source projects. Clawsembly never spends runtime tokens on an unverified release: bootVerifiedEmbed blocks before token consumption while evidence is missing. See the deployment requirements and ADR 0002 for the full licensing analysis.

Deep dive: product boundary

BrowserPod supplies browser-local Node execution. Clawsembly supplies the parts an embedding application still needs in order to trust an upstream agent — implemented against upstream OpenClaw, this repository's specialized upstream (ADR 0006), while the boundary itself stays upstream-portable as an engineering property (ADR 0004):

• exact-version compatibility reports and reproducible failure fixtures;
• a default-deny capability broker for secrets, identity, storage, provider traffic, notifications, and future host APIs;
• an evidence-bound embed manifest that rejects runtime-provider mismatch;
• the generated Gateway client and narrow compatibility adapters.

Clawsembly does not reimplement the agent loop and it is not a generic wrapper around a browser sandbox.

The implemented broker supports exact scopes, call limits, expiry, revocation, cancellation, bounded metadata-only audit, and redacted handler errors. The protected provider smoke-test path now crosses that broker. The embed-manifest core and bootVerifiedEmbed select BrowserPod but correctly block verified launch before token consumption while no owner-authorized BrowserPod runtime evidence exists. The BrowserPod adapter implements documented Node 22 boot, storageKey persistence, long-running output readiness, HTTPS portal discovery, and bounded file I/O. A typed filesystem mailbox now connects the untrusted guest to the exact-scope broker with replay defense, byte limits, generic errors, cancellation, and payload-free audit. Verified boot automatically stages and reads back a generated SHA-256-pinned Node client in the fresh channel, while a release check rejects generated-source drift. Manifest capabilities remain pending until an explicit, expiring user approval; deny, revoke, expiry, current state, and combined broker audit are implemented with stable JSON schemas. The readiness harness installs the exact SHA-512 npm artifact and requires Gateway log, portal, /healthz, /readyz, and a nonce-bound guest-supervisor shutdown. No owner-authorized BrowserPod record has been captured yet. Its public 2.12.1 API has no documented terminal-input, provider-termination, or hard-disposal method, so those features remain explicitly unsupported. See ADR 0003 and the embedding contract. The capture and attachment procedure is documented in BrowserPod evidence. The transport boundary is documented in Capability mailbox, and the authority lifecycle in Capability permissions.

The first generated Gateway-client slice is also implemented. A reproducible contract pins protocol 4 and hashed upstream declarations to the same exact npm integrity. The SDK configures an exact browser-origin allowlist, persists a non-extractable Ed25519 identity, signs connect.challenge, sends the ephemeral token only in the connect frame, and validates a token-free hello-ok summary. Mock contract tests cover pairing-required and secret-redaction paths; this is not yet real BrowserPod handshake evidence. The same client now exposes only bounded chat.send, chat.history, and chat.abort operations after authentication. It forces deliver:false, validates stream events, reports sequence gaps without payloads, rejects pending work on disconnect, and supports an explicit freshly signed reconnect. It does not expose arbitrary Gateway methods. The embedded pairing bridge re-reads the current OpenClaw pending list, refuses changed or broader access, and executes only a one-shot exact-request approve/reject after owner review. Issued device tokens are encrypted in an artifact/device/role/scope-bound IndexedDB vault and used for signed reconnect; rejected stale tokens are cleared without entering results or audit. These paths are provider-free contract evidence, not a claim that BrowserPod pairing has been run.

The source-level ESM entrypoint now exports the same boot functions declared by its .d.mts contract, and an exact runtime export-surface test prevents typed consumer examples from failing only after deployment.

Deep dive: browser runtime direction

Browser-local execution is a product invariant; a remote sandbox is not the replacement path. BrowserPod is the only active embedded provider in the application, public compatibility target, and normal CI path. It is not called supported until it reproduces the full Gateway, broker, tool, recovery, cancellation, persistence, performance, and licensing evidence in ADR 0002. container2wasm is retained as an archived feasibility result after its measured boot failure.

Deep dive: current evidence

The evidence-gate machinery is generic trust infrastructure; the OpenClaw reports below are its first instance. The first implementation is a static compatibility inspector and a public, report-driven project page. For the pinned openclaw@2026.7.1-2 artifact it records package integrity, Node requirements, artifact size, lifecycle scripts, and platform-specific dependency risks without executing install scripts. The same page tracks the npm latest, previous stable, and beta channels as separate reports. At the 2026-07-21 snapshot those resolve to 2026.7.1-2, 2026.6.11, and 2026.7.2-beta.3. All three public reports now target browserpod@2.12.1, contain zero runtime evidence, and remain probing. A scheduled workflow skips unchanged channels and opens or updates a generated report pull request when a channel moves. Each report retains its exact direct dependency specs; the release index and project page expose added, removed, and changed preview dependencies against stable. Added and changed packages are then fetched by their shrinkwrap-resolved version, verified against SHA-512, and scanned without lifecycle execution for install scripts, native/Wasm artifacts, Node built-ins, network signals, and browser-authority risk. These remain static review signals and never promote a runtime check.

The same exact tarballs are inspected for their public Gateway declaration, runtime entrypoint, protocol constants, server-method inventory, and legacy plugin declaration distribution. The release index publishes a stable-relative contract diff with exact added/removed method and schema names. At this snapshot the stable artifact itself ships the new dist/gateway/protocol declaration distribution: protocol 4 remains current and the legacy plugin-declaration tree is gone (38 declarations in 2026.6.x, 0 now), which is why the generated SDK contract is resolved through that distribution. Relative to stable, the previous release 2026.6.11 is classified breaking (its public surface lacks 51 schema exports), and preview 2026.7.2-beta.3 is classified breaking with 237 added and 8 removed schema exports. These are static upgrade warnings, not a claim that those methods run successfully in BrowserPod.

The main branch is BrowserPod-only: it contains no legacy runtime adapter, dependency, fixture, evidence record, report target, fallback, or vendor CSP permission. Browser-host vault, identity, budget, and consent checks remain provider-free and do not boot a guest runtime or contact OpenAI. The superseded implementation remains available through Git history and its decision record, not as executable code in the current tree.

The project page also runs the reusable permission-prompt component against an inert local broker. Reviewers can approve, deny, revoke, and export a schema-valid payload-free audit without booting BrowserPod or invoking a host capability.

Verified embed sessions now expose one manifest-bound OpenClaw installer shared with the evidence probe. It aggregates concurrent calls and returns executable paths only after the installed package version and package-lock SHA-512 match the verified report.

The same session now owns a verified Gateway controller shared with the evidence probe. It performs supervised launch, HTTPS portal and log readiness, guest-local health/readiness checks, exact origin configuration, authenticated protocol-client creation, and cooperative stop without serializing the ephemeral token.

The page provides a credential-and-explicit-consent gate for one fixed-prompt gpt-5.6-luna live smoke test. It enforces store:false, 128 maximum output tokens, a displayed $0.001 upper bound based on the official API pricing, cancel control, and completed plain-text output only. Live network execution has not been performed. Remote approval, token rotation and revocation, general workspace recovery, and the broader BrowserPod matrix remain experimental, so the release is reported as probing rather than production-compatible.

• Project page
• Checked-in compatibility report
• Release-channel history
• Promotion policy
• SDK alpha release manifest
• SDK source prerelease
• npm publication record
• Report schema
• Release-history schema
• Downstream consumption guide
• SDK prerelease recipe
• Copy-ready SDK host starter
• Owner-authorized BrowserPod evidence workflow
• Maintainer release checklist
• Deployment requirements
• Support
• Governance
• Welcome discussion
• Show and tell

Try it in depth

The promotion-policy check from step 1 above is a dependency-free consumer that fetches the public policy over strict HTTPS and prints the exact preview decision. Remove --observe to make HOLD fail CI. See the release-policy example and its copyable zero-install GitHub Action. The current preview is intentionally held; this command is useful before verified BrowserPod support exists.

Requirements for working in the repository: Node.js 22.19 or newer.

npm install
npm run check
npm run dev

The npm alpha installs the same reproducible bytes that were checked into the release. The exact tarball is also available from Pages and from the GitHub prerelease:

npm install @haya-inc/clawsembly@alpha
npm install https://haya-inc.github.io/clawsembly/downloads/haya-inc-clawsembly-0.1.0-alpha.4.tgz
npm install https://github.com/haya-inc/clawsembly/releases/download/v0.1.0-alpha.4/haya-inc-clawsembly-0.1.0-alpha.4.tgz

The GitHub source prerelease carries provider-free browser diagnostics and a provenance record binding the tag, source commit, Pages manifest, and compatibility report. Runtime support remains probing independently of package distribution.

npm run sdk:example installs the tarball into an independent Vite/TypeScript package without workspace aliases and serves a launch inspector on http://127.0.0.1:5174/. The deployed copy is available at the SDK host example.

Generate a fresh static report for an exact upstream release:

npm run compat:inspect -- \
  --package openclaw \
  --version 2026.6.11 \
  --runtime browserpod \
  --runtime-version 2.12.1 \
  --browser-baseline "Desktop Chromium" \
  --output apps/web/public/data/compatibility.json

The inspector downloads and reads the npm tarball in a temporary directory. It does not install the package or execute lifecycle scripts.

Resolve and inspect the current stable, previous stable, and preview channels:

npm run compat:track -- \
  --runtime browserpod \
  --runtime-version 2.12.1

Runtime evidence is attached only when its embedded OpenClaw version exactly matches the inspected artifact. --skip-unchanged leaves every generated file untouched when all three resolved channels are unchanged.

Maintainer release plumbing

The compatibility-lab root intentionally remains a private npm package. A separate publish recipe assembles only the canonical SDK/runtime/broker sources into an installable prerelease artifact:

npm run sdk:check
npm run sdk:lock
npm run sdk:pack
npm run sdk:example
npm run report-pin:check

sdk:check creates the tarball twice and requires byte-identical SHA-256 digests, installs it into an isolated temporary consumer, imports every public ESM subpath, and compiles a strict TypeScript consumer. sdk:lock deliberately updates the copy-ready starter URL and SHA-512 when the SDK version changes; normal checks reject silent drift. sdk:pack writes @haya-inc/clawsembly@0.1.0-alpha.4 plus its checksum under ignored .artifacts/sdk/. The matching GitHub prerelease triggered provenance-backed npm publication under the alpha dist-tag; the reviewed npm publication record now records status: published with matching SHA-512 integrity and Sigstore provenance.

The release manifest is the source of truth for package distribution. It binds the tarball SHA-256 to the exact public compatibility report and admits the npm install path only because the reviewed publication record supplies matching SHA-512 integrity and Sigstore provenance. Runtime support remains independently recorded as status:probing.

The six-hour release tracker regenerates the host pin from the exact stable report in its read-only job and carries both through one validated artifact to the separate PR-publishing job. Pin changes therefore remain explicit review diffs without becoming a handwritten release step.

To regenerate and byte-check the Gateway contract against the exact published npm artifact:

npm run protocol:generate
npm run protocol:verify

The browser lane requires Playwright Chromium and verifies the public page, BrowserPod-only runtime presentation, deployment policy, and provider-free security surfaces:

npx playwright install chromium
npm run test:browser

Maintainers can capture the first real BrowserPod readiness record through the manual, Environment-protected Browser host, page, and evidence workflow. It is opt-in, metered, installs the exact provider SDK from an isolated lock, and uploads evidence for review without committing or promoting it automatically.

Goals

• Run upstream OpenClaw rather than maintaining an independent agent rewrite. This repository specializes in OpenClaw (ADR 0006); other upstreams belong to separate projects. The documented upstream-binding contract and its hello-agent reference binding — test-scoped, and since 2026-07-21 backed by one owner-authorized real-BrowserPod record — remain the test infrastructure that keeps the boundary upstream-portable (ADR 0005). No second real agent runs today, and none is planned here.
• Keep the host boundary — default-deny capability broker, evidence-bound embed manifest, permission prompts, and payload-free audit — embedder- controlled, with upstream portability retained as an engineering property of the boundary rather than a multi-upstream roadmap.
• Make upstream OpenClaw safe to embed through exact artifact identity, evidence-bound launch, and explicit browser-host authority.
• Wrap upstream OpenClaw with the conveniences its operators and embedders need — native-Gateway evidence and interoperability, release intelligence, extension vetting — without reimplementing the agent.
• Keep the useful default browser-local, with an optional native Gateway interoperability mode rather than a remote-sandbox dependency.
• Expose browser limitations as explicit capabilities instead of silently emulating unavailable host features.
• Detect and validate upstream releases automatically, as supporting trust infrastructure rather than the product itself.
• Keep local data and execution inside browser security boundaries where possible.

Documentation

• Documentation index
• Project vision
• Prior-art survey
• Proposed architecture
• Upstream compatibility strategy
• Initial roadmap
• Product and adoption strategy
• OSS success strategy
• Risk register
• Security model
• Commercial browser runtime decision
• Verified OpenClaw embedding decision
• Upstream-portable embedding boundary decision
• Reference-agent growth paths decision
• OpenClaw-specialist refocus decision
• Verified embedding contract
• Upstream binding contract

Contributing

Compatibility work is most useful when it is small and reproducible. Good first contributions include dependency classifications, browser failure fixtures, report-schema improvements, and capability-specific adapters. See CONTRIBUTING.md before opening a pull request. Security issues must follow SECURITY.md.

Status

The first end-to-end compatibility slice is implemented and reproducible from the project page. It is a probe, not a production runtime: the credential vault and OpenClaw broker turn prove the complete secret boundary with mock transport, and a protected fixed-prompt live smoke path is enabled behind credential and explicit-consent gates. No live provider request has been executed in the checked-in evidence yet. Backup/export controls currently apply only to the deterministic mock-state snapshot and deliberately exclude credentials. Browser-owned device signing, exact pending-request review, explicit pairing controls, encrypted token retention, and token reconnect pass provider-free contract tests. They are not yet backed by an owner-authorized BrowserPod/Gateway record. Remote-mode approval, rotation, revocation, and recovery remain future work. The embedding boundary itself now has its first owner-authorized record on the real provider: the hello-agent reference chain — verified staging, readiness, capability-mediated chat with denied and allowed outcomes, in-flight abort, and cooperative stop — executed on browserpod@2.12.1 in a real browser, with the digest-bound evidence checked in under packages/hello-agent-binding/evidence/. That record proves the boundary machinery, not any real upstream: OpenClaw runtime support remains probing and blocked on the vendor gaps above.

License

MIT