Browser Mode
Run clawft in the browser via WebAssembly, including build instructions, API reference, and deployment.
Overview
The clawft-wasm crate provides a browser-compatible entrypoint for clawft. It compiles to WebAssembly and exposes a JavaScript API for initializing the framework, sending messages, and managing configuration from within a web page.
With the browser feature, clawft-wasm pulls in clawft-core, clawft-llm, clawft-tools and clawft-platform so the whole agent pipeline runs in the tab. The Platform trait is designed for this target -- process() returns None, HTTP uses the fetch API, and storage can be in-memory or OPFS (browser-opfs feature). The full API is in the browser API reference.
Architecture
Browser JavaScript
|
v
clawft-wasm (wasm-bindgen exports)
|
+-- init(config_json, env_json?) -- Initialize the framework
+-- send_message(text) -- Send a message to the agent
+-- send_message_to(text, group) -- Send into a named group session
+-- stream_chat(text, on_chunk) -- Stream a response chunk by chunk
+-- set_env / get_env -- Environment variables
+-- get_history / clear_history -- Session history
+-- tool_list / tool_schema -- Tool introspection
|
v
clawft-core pipeline + clawft-llm + clawft-tools (browser feature)The WASM module is loaded via wasm-bindgen. init must be called before the agent functions.
Build the WASM Module
cd crates/clawft-wasm
wasm-pack build --target web --no-default-features --features browser \
-- --no-default-features --features browserThis produces pkg/clawft_wasm.js and pkg/clawft_wasm_bg.wasm.
The build script wraps this and the wasm-bindgen step (output under crates/clawft-wasm/www/pkg/):
scripts/build.sh browserFor WASI targets:
scripts/build.sh wasiQuickstart
Create a Minimal HTML Page
Create test.html alongside the pkg/ directory:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>clawft-wasm test</title>
</head>
<body>
<pre id="output">Loading...</pre>
<script type="module">
import init_wasm, { init, send_message, set_env }
from "./pkg/clawft_wasm.js";
const output = document.getElementById("output");
async function run() {
await init_wasm();
output.textContent = "WASM loaded.\n";
const config = {
providers: {
anthropic: {
apiKey: "YOUR_API_KEY_HERE",
browserDirect: true
}
},
agents: {
defaults: {
model: "anthropic/claude-sonnet-4-20250514",
maxTokens: 4096
}
}
};
await init(JSON.stringify(config));
output.textContent += "Initialized.\n";
set_env("ANTHROPIC_API_KEY", "YOUR_API_KEY_HERE");
const response = await send_message("Hello from the browser!");
output.textContent += "Response: " + response + "\n";
}
run().catch(err => {
output.textContent = "Error: " + err;
});
</script>
</body>
</html>Serve and Open
npx serve crates/clawft-wasm/ --listen 8080Open http://localhost:8080/test.html in a browser.
Configuration
The config JSON mirrors the native config.json structure. Key fields for browser use:
{
"providers": {
"anthropic": {
"apiKey": "sk-ant-...",
"browserDirect": true
}
},
"agents": {
"defaults": {
"model": "anthropic/claude-sonnet-4-20250514",
"maxTokens": 4096,
"temperature": 0.7
}
}
}browserDirect-- Set totruefor providers whose APIs support browser CORS. For others, configure a CORS proxy viacorsProxy.apiKey-- In production, inject this at runtime rather than hardcoding.
Test Harness
The built-in test harness at www/index.html provides:
- A JSON config editor
- An "Initialize" button
- Message display with user/assistant/error/system styling
- Console timing for load, init, and message latency
npx serve crates/clawft-wasm/www --listen 8080WASM Size Budget
The CI pipeline enforces size constraints:
| Metric | Limit |
|---|---|
| Raw WASM binary | < 300 KB |
| Gzipped WASM binary | < 120 KB |
The release-wasm profile uses opt-level = "z" for aggressive size optimization. The CI job installs binaryen for wasm-opt post-processing.
Platform Limitations
The WASM target has several constraints compared to native:
- No process spawning --
Platform::process()returnsNone - No filesystem (unless WASI) -- File tools use in-memory backends
- HTTP via fetch API -- Subject to browser CORS policies
- No tokio runtime -- Uses browser event loop via
wasm-bindgen-futures
Deployment
Static Hosting
The WASM module and JavaScript wrapper can be served from any static file host (S3, CloudFront, Vercel, Netlify, GitHub Pages).
Required files:
clawft_wasm.js-- JavaScript bindingsclawft_wasm_bg.wasm-- WebAssembly binary
CDN Considerations
Set appropriate Content-Type headers:
.wasmfiles:application/wasm.jsfiles:application/javascript
Enable gzip or brotli compression for the WASM binary.
Security
Never embed API keys in client-side JavaScript for production deployments. Use a backend proxy to inject credentials server-side, or require users to provide their own keys at runtime.
Live Sandbox (/clawft/)
The WeftOS documentation site hosts an interactive browser sandbox at weftos.weavelogic.ai/clawft/.
Modes
| Mode | API Key Required | How It Works |
|---|---|---|
| Local | No | Pure keyword/semantic retrieval from the RVF knowledge base (Fumadocs MDX plus ADRs, guides, research, architecture, brain, and weftos specs — rebuilt by scripts/build-kb.sh) |
| LLM | Yes | RAG-powered answers: retrieves relevant KB segments, sends them as context to an LLM provider |
Supported Providers
Any OpenAI-compatible provider works. Use the model prefix to select:
anthropic/-- Anthropic (Claude)openai/-- OpenAI (GPT)openrouter/-- OpenRouter (aggregated models)deepseek/-- DeepSeekgroq/-- Groqgemini/-- Google Geminixai/-- xAI (Grok)
Models without a prefix fall back to OpenRouter.
ExoChain Log Panel
The right panel displays a real-time audit trail of every operation:
- Boot phases: INIT, CONFIG, SERVICES, NETWORK, READY -- mirrors the native kernel boot sequence
- KB operations: fetch, search, retrieval with segment counts and embedder info
- LLM transport: request/response logging with provider and model details
- Chain linking: each entry includes a linked hash for tamper-evident sequencing
Guided Tour
Four categories of starter prompts help new users explore:
| Category | Example Prompts |
|---|---|
| Getting Started | "What is WeftOS?", "How do I install it?" |
| Architecture | "Show me the boot sequence", "How does the ECC work?" |
| Assessment | "How does weft assess work?", "What analyzers are available?" |
| Security | "How does governance work?", "What is the ExoChain?" |
Document Preview
Clicking internal documentation links (e.g., /docs/weftos/ecc) opens a side panel with the referenced page, keeping the chat context visible.
Streaming Responses
In LLM mode, responses stream progressively via SSE-style delivery from the WASM runtime, giving real-time feedback as the model generates output.
Configuration
Complete configuration reference for clawft including file location, all config keys with types and defaults, and environment variables.
Deployment
How to run clawft and the WeftOS node daemon in production: Docker, the per-user daemon, per-project kernels, WASM targets, and recommended configuration.