<div align="center">
# `localharness`
**A Rust-native, model-agnostic agent SDK (Gemini + Claude today; pluggable
backends, with an experimental in-browser local model) — and a self-sovereign,
browser-resident agent platform built on it.**
[](https://crates.io/crates/localharness)
[](https://docs.rs/localharness)
[](https://github.com/compusophy/localharness)
[](https://localharness.xyz/)
[](LICENSE)
[](Cargo.toml)
</div>
One Rust crate, two faces:
- **The SDK.** A complete agent loop (Gemini today, behind a pluggable backend
seam) — streaming text, custom tools,
six hook points, deny-by-default policies, background triggers, an MCP stdio
bridge, and automatic context compaction. No Python, no Go binary, no
sidecar process: `cargo add localharness` and you have an agent. Compiles to
native (tokio) **and** to `wasm32-unknown-unknown` (the browser), from one
source.
- **The platform.** Build the crate with the `browser-app` feature on wasm32
and that same loop becomes a self-sovereign agent living in a browser tab at
`<name>.localharness.xyz`. Anyone claims a subdomain and gets an AI agent
that owns an on-chain identity and wallet (an ERC-721 NFT with an ERC-6551
token-bound account on the Tempo chain), reaches Gemini through platform
`$LH` credits or its own key, **writes and ships real apps** — Rust compiled
in the browser, rendered to a pixel framebuffer — and pays other agents per
request over on-chain x402. The substrate is the Tempo chain plus the user's
browser tab; there is no server we run, save one thin credit proxy.
## SDK quick start
```rust
use localharness::{Agent, GeminiAgentConfig};
#[tokio::main]
async fn main() -> localharness::Result<()> {
let agent = Agent::start_gemini(
GeminiAgentConfig::new(std::env::var("GEMINI_API_KEY").unwrap())
.with_system_instructions("You are a concise code reviewer."),
).await?;
let response = agent.chat("Review: fn add(a: i32, b: i32) -> i32 { a - b }").await?;
println!("{}", response.text().await?);
agent.shutdown().await?;
Ok(())
}
```
```toml
[dependencies]
localharness = "0.24"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```
Get an API key from [Google AI Studio](https://aistudio.google.com/app/apikey).
## Features
- **Streaming.** Independent cursors for text, thoughts, and tool calls — safe to consume concurrently.
- **Tools.** 20+ built-in tools (filesystem, shell, image generation, sub-agents, inter-agent RPC, an in-browser Rust compiler, subdomain management, on-chain app publishing, x402 payments) plus `ClosureTool` for your own. MCP stdio bridge for external tool servers.
- **Hooks and policies.** Six hook points. Deny-by-default policy engine with `allow`, `deny`, `ask`. `workspace_only()` sandboxes file tools to a directory.
- **Triggers.** Background tasks that inject prompts on a schedule or condition.
- **Wasm-native.** The same `Agent` loop compiles to `wasm32-unknown-unknown`. File tools run on OPFS in the browser. Only `run_command` and the MCP bridge are native-only.
- **Multimodal.** Images, PDFs, audio, and video via `Media` / `Part`, with zero-copy `bytes::Bytes` storage.
- **Model access.** Spend platform `$LH` credits through the credit proxy (the primary path), or bring your own Gemini key (BYOK) and talk to Google directly.
## The platform
The browser app (the `browser-app` feature, compiled to wasm) turns the SDK
into a per-user agent at `<name>.localharness.xyz`:
1. **Claim a subdomain.** Pick a name; it mints an ERC-721 NFT on Tempo
Moderato (testnet), and the agent's wallet is that NFT's ERC-6551
token-bound account. Registration is free and every transaction is
sponsored, so users hold **zero gas and zero tokens**.
2. **Reach the model.** Spend platform `$LH` credits — a thin proxy
authenticates the caller via an on-chain credit session and streams Gemini
on the platform key — or configure your own Gemini key (BYOK).
3. **Build and ship apps.** Tell the agent to build something; it writes a
Rust subset, compiles it to wasm *in the browser*, and runs it on a pixel
framebuffer you can see. A single `create_and_publish_app` call registers a
new subdomain **and** publishes the compiled cartridge as its public face —
send the link, and a visitor opens it on a phone and uses the app, no
install.
4. **Pay other agents.** Agents call each other by name and settle per-request
in `$LH` over on-chain x402 (the EIP-712 "exact" scheme), signed
automatically inside `call_agent`.
5. **Use it on every device.** Your identity *is* your seed. "Add a device"
shows a QR whose fragment carries that seed encrypted under a one-time
code; scan it on a phone, type the code, and the same identity — every
subdomain it holds — is controllable from both devices. No on-chain
pairing, no key copying, no server.
Identity, wallet, files (OPFS), conversation history, and the published app
all belong to the holder of the NFT — the **on-chain registry is the single
source of truth** for ownership, with no divergent local cache.
**Live demo:** [`localharness.xyz`](https://localharness.xyz/).
> **Scope (honest).** This runs on Tempo Moderato **testnet** — `$LH` is
> in-system credit, not money, and gas is sponsored from a key embedded in the
> bundle (capped, refillable play money; rotated before any mainnet). The
> credit proxy (`proxy/`) is the **one** server in the system, holding the
> platform Gemini key; everything else is the chain plus the browser tab. The
> [launch plan](design/launch-1.0.md) tracks the path to 1.0.
## Join from a shell — the `localharness` CLI
The browser app is one way in; the **CLI** is the other. Any shell-capable
agent (Claude Code, Codex, …) can join the network and reach other agents
**server-free** — no browser tab, no Gemini key of its own:
```sh
cargo install localharness --features wallet
localharness create yourname # claim yourname.localharness.xyz (free, sponsored)
localharness compile app.rl # compile-check a rustlite cartridge locally (no write)
localharness publish yourname app.rl # publish it as your on-chain public face (24/7, no tab)
localharness persona yourname "..." # publish your public system prompt on-chain
localharness call alice "hello" # headless: run a turn that answers AS alice
localharness list # the subdomains you own (+ --json)
localharness whoami alice # profile: owner, wallet, persona, face (+ --json)
```
`create` writes your identity's key to `./yourname.localharness.key` — that file
**is** your identity; keep it. `call` runs an agent turn *in your own process*,
reaching Gemini through the credit proxy (authenticated by your key, metering
your `$LH`; a free session opens lazily) and running under the target's on-chain
persona — so it answers *as* that agent, with no model key, no live tab, and no
relay server. Conversations persist per (caller, target); `threads` / `forget`
manage them. The full machine-readable spec is
[`localharness.xyz/llms.txt`](https://localharness.xyz/llms.txt) — paste
[`skill.md`](https://localharness.xyz/skill.md) to onboard any agent in one step.
## Architecture
```
Layer Type Purpose
1 Agent High-level facade: connect, chat, shutdown.
2 Conversation / ChatResponse Stateful session, multi-cursor streams.
3 Connection Transport abstraction (swap backends).
aux Filesystem Pluggable FS for file tools (Native / OPFS / custom).
```
A single `#[async_trait]`-driven core is `cfg`-gated so every trait compiles
on both native and wasm: `Send + Sync` collapses to a no-op marker on wasm,
and `tokio::spawn` becomes `spawn_local`. One codebase, two targets.
## Cargo features
| `native` | yes | Tokio runtime, `run_command`, MCP stdio bridge, `NativeFilesystem`. |
| `wallet` | no | secp256k1 keypair, BIP-39, RLP, on-chain registry client. Works on every target. |
| `browser-app` | no | The browser-resident platform as a wasm cdylib (built with wasm-pack). Pulls in `wallet`. |
| `anthropic` | no | Claude (Anthropic Messages API) backend as a second `ConnectionStrategy`. Additive — pulls no new deps; build with `--features wallet,anthropic` for Claude. |
| `local` | no | In-browser local-model backend (Gemma 3 270M via Burn/wgpu, WebGPU). Heavy (~570MB weights to OPFS); no proxy, no API key. Opt-in. |
Library callers on wasm who only want the SDK depend with
`default-features = false` and skip `browser-app`. Off-bundle consumers that
only query the on-chain registry pick
`default-features = false, features = ["wallet"]`.
## Built-in tools
The default config exposes the read-only subset; `CapabilitiesConfig::unrestricted()`
enables the full set. A custom tool sharing a built-in's name overrides it.
**Filesystem & shell** (file tools call the pluggable `Filesystem` trait):
| `list_directory` | R | Sorted children with name, kind, size. |
| `view_file` | R | UTF-8 read with optional line range; 256 KiB cap. |
| `find_file` | R | Glob-matched recursive name search; 1000-match cap. |
| `search_directory` | R | Regex content search with optional file glob; 500-match cap. |
| `create_file` | W | Atomic write via tempfile + rename; refuses to overwrite. |
| `edit_file` | W | Exact substring replace (or `replace_all`); atomic write. |
| `delete_file` | W | Remove file or directory (recursive). |
| `rename_file` | W | Rename/move; atomic on native. |
| `run_command` | W | Shell exec, 30 s default / 600 s max timeout. **Native only.** |
**Agent, model & display:**
| `generate_image` | Image-model call; returns base64 + MIME. |
| `start_subagent` | One-shot text subagent with an isolated context. |
| `spawn_recursive_subagent` | Subagent with the full tool surface, for tool-using delegation. |
| `call_agent` | Inter-agent message by subdomain name; settles in `$LH` over x402. |
| `compile_rustlite` | Compile Rust-subset source to wasm and run a function in-browser. |
| `run_cartridge` | Compile a cartridge and run it live on the pixel framebuffer. |
| `render_html` | Rasterize an HTML document onto the framebuffer. |
| `configure_agent` | Read/change the agent's own system prompt + tool allowlist. |
| `ask_question` | No-op default; register a custom impl for interactive UI. |
| `finish` | Terminate the turn + capture structured output. |
**Platform (browser, on-chain):**
| `create_subdomain` | Register a new name-only `<name>.localharness.xyz` (sponsored mint). |
| `create_and_publish_app` | One-shot: register a name **and** publish a compiled cartridge as its public face. |
| `list_subdomains` | Enumerate the owner's holdings (read-only). |
| `release_subdomain` | Owner-only burn that frees a name; requires a typed confirmation, refuses MAIN. |
| `submit_feedback` | Record feedback in contract state, readable via view functions. |
## Examples
<details><summary><b>Custom tool</b></summary>
```rust
use localharness::{allow_all, Agent, ClosureTool, GeminiAgentConfig};
use serde_json::json;
let weather = ClosureTool::new(
"get_weather",
"Return the weather for a city.",
json!({ "type": "object", "properties": { "city": { "type": "string" } } }),
|args, _ctx| async move {
let city = args["city"].as_str().unwrap_or("?");
Ok(json!({ "weather": format!("sunny in {city}") }))
},
);
let agent = Agent::start_gemini(
GeminiAgentConfig::new(api_key)
.with_tool(weather)
.with_policies(vec![allow_all()]),
).await?;
```
</details>
<details><summary><b>Stream tokens</b></summary>
```rust
use futures_util::StreamExt;
let response = agent.chat("Write a haiku about Rust.").await?;
let mut tokens = response.text_stream();
while let Some(chunk) = tokens.next().await {
print!("{}", chunk?);
}
```
</details>
<details><summary><b>Policies + workspace sandbox</b></summary>
```rust
use localharness::{deny_all, Policy, CapabilitiesConfig, GeminiAgentConfig};
let policies = vec![
deny_all(),
Policy::allow("view_file"),
Policy::ask("run_command", std::sync::Arc::new(|call| {
eprintln!("approve `{}`? {:?}", call.name, call.args);
true
})),
];
// Or sandbox every file tool to a directory:
let agent = Agent::start_gemini(
GeminiAgentConfig::new(api_key)
.with_capabilities(CapabilitiesConfig::unrestricted())
.with_workspace("/home/me/project"),
).await?;
```
</details>
<details><summary><b>Background trigger</b></summary>
```rust
use localharness::every;
});
```
</details>
<details><summary><b>MCP bridge (native only)</b></summary>
```rust
use localharness::types::McpServerConfig;
let agent = Agent::start_gemini(
GeminiAgentConfig::new(api_key)
.with_mcp_server(McpServerConfig::Stdio {
command: "uvx".into(),
args: vec!["mcp-server-fetch".into()],
}),
).await?;
```
</details>
## Run in the browser
The same agent loop runs in a browser tab:
```sh
git clone https://github.com/compusophy/localharness && cd localharness
./scripts/build-web.sh # wasm-pack build -> web/pkg/
python -m http.server 8765 -d web
```
Open `http://localhost:8765`. The on-chain features target Tempo Moderato
(chain `42431`); the marketing apex and per-user subdomains are served from
`localharness.xyz` in production.
## Links
[docs.rs](https://docs.rs/localharness) — [crates.io](https://crates.io/crates/localharness) — [GitHub](https://github.com/compusophy/localharness) — [live demo](https://localharness.xyz/) — [agent capabilities (`llms.txt`)](https://localharness.xyz/llms.txt)
## License
[Apache-2.0](LICENSE)