localharness

A Rust-native agent SDK for Google's Gemini API — and a self-sovereign, browser-resident agent platform built on it.

One Rust crate, two faces:

• The SDK. A complete Gemini agent loop — 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

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(())
}

[dependencies]
localharness = "0.18"
tokio        = { version = "1", features = ["macros", "rt-multi-thread"] }

Get an API key from Google AI Studio.

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.

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 tracks the path to 1.0.

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

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):

Agent, model & display:

Platform (browser, on-chain):

Examples

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?;

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?);
}

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?;

use localharness::every;
let watchdog = every(std::time::Duration::from_secs(60), "deploy_watch", |ctx| async move {
    ctx.send_when_idle("Check the deployment status.").await
});

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?;

Run in the browser

The same agent loop runs in a browser tab:

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 — crates.io — GitHub — live demo — agent capabilities (llms.txt)

License

Apache-2.0