Clawsembly

Run upstream coding agents browser-locally, behind a host boundary the embedding application controls. Evidence-gated; OpenClaw is the first supported upstream.

日本語: README.ja.md

Clawsembly is an evidence-gated embedding layer that runs upstream coding agents browser-locally, behind a host boundary the embedding application controls. OpenClaw is the first supported upstream: Clawsembly binds the exact published package to public compatibility evidence and refuses 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. 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	Published now	npm install @haya-inc/clawsembly@alpha — the reviewed publication record records status: published with SHA-512 integrity and Sigstore provenance.
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.
Verified BrowserPod boot	Blocked	BrowserPod 2.12.1 provisions Node 22.15.0, below the 22.19 baseline, so the readiness probe fails closed (node_baseline_unsatisfied); reported to the vendor. Owner-authorized runtime evidence remains pending (#6).
Live provider smoke test	Blocked	The gated path exists but has never been executed.
Performance baselines	Blocked	Not yet measured (#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 today against upstream OpenClaw, the first bound upstream, and designed to stay upstream-portable (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.6.11 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-12 snapshot those resolve to 2026.6.11, 2026.6.10, and 2026.7.1-beta.5. 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, preview is classified breaking: protocol 4 remains current, while legacy plugin declarations move from 38 to 0 and the public surface adds 28 core methods and 51 schema exports. This is a static upgrade warning, 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.3.tgz
npm install https://github.com/haya-inc/clawsembly/releases/download/v0.1.0-alpha.3/haya-inc-clawsembly-0.1.0-alpha.3.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.3 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 coding agents rather than maintaining an independent agent rewrite. OpenClaw is the first bound upstream; additional upstreams bind through the documented upstream-binding contract, whose test-only hello-agent reference binding demonstrates that the boundary is upstream-portable and extends an agent through embedder-granted host capabilities (ADR 0005). No second real agent runs today.
• Keep the host boundary — default-deny capability broker, evidence-bound embed manifest, permission prompts, and payload-free audit — embedder- controlled and upstream-portable, as the reusable product across upstreams.
• Make each bound upstream safe to embed through exact artifact identity, evidence-bound launch, and explicit browser-host authority.
• 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
• 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.

License

MIT