Edge Agent Documentation

I was "nerd-sniped" into asking: Why can't an agent in the browser just write dynamic code and execute it?

Edge Agent is the answer. Instead of relying on full cloud VMs (high latency, not yours) or tedious local installs (complex maintenance), Edge Agent is primed out of the box. A fully browser-native AI coding assistant with a real WASM sandbox.

Quick Start

The fastest way to try Edge Agent is the hosted terminal:

Go to agent.edge-agent.dev
Run /provider to configure your AI provider
Enter your API key when prompted
Start chatting with the agent!

🔒

Privacy Note: Your configuration (including API keys) is stored locally in your browser's OPFS. Nothing is ever sent to our servers.

Supported Providers

Edge Agent works with multiple AI providers:

Anthropic

Claude Opus 4.5, Sonnet 4.5, Haiku 4.5

api.anthropic.com

OpenAI

GPT-5, o3, o4-mini

api.openai.com

Google Gemini

Gemini 3 Pro, Gemini 3 Flash

generativelanguage.googleapis.com

OpenAI-Compatible

Any API with OpenAI format

your-api.example.com

Installation

🚧

Note: Edge Agent packages are not yet published to npm. You currently need to build from source.

To embed Edge Agent, clone the repository and link the package:

Terminal

git clone https://github.com/tjfontaine/agent-in-a-browser.git
cd agent-in-a-browser
npm install
npm run build

Basic Usage

Import and initialize the agent:

TypeScript

import { WebAgent } from '@tjfontaine/web-agent-core';

// Create agent instance
const agent = new WebAgent({
  provider: 'anthropic',
  model: 'claude-sonnet-4-20250514',
  apiKey: 'your-api-key',
  maxTurns: 25,  // optional: limit tool call turns
});

// Initialize (loads WASM sandbox)
await agent.initialize();

// Streaming mode
for await (const event of agent.send('Write a hello world in TypeScript')) {
  if (event.type === 'chunk') {
    console.log(event.text);
  }
}

// One-shot mode (waits for complete response)
const response = await agent.prompt('Summarize this file');
console.log(response);

// Clean up when done
agent.destroy();

Configuration Options

Option	Type	Description
`provider`	string	AI provider: 'anthropic', 'openai', 'gemini'
`model`	string	Model name (e.g., 'claude-sonnet-4-20250514')
`apiKey`	string	API key for the provider
`baseUrl`	string?	Custom API endpoint URL
`preamble`	string?	Additional text appended to built-in system prompt
`preambleOverride`	string?	Complete replacement for built-in system prompt
`mcpServers`	Array?	List of MCP servers: [{url, name?}]
`maxTurns`	number?	Max tool call turns before stopping (default: 25)

Streaming Events

The send() method returns an AsyncGenerator that yields events:

Event Type	Description
`stream-start`	Stream has begun
`chunk`	Streaming text content from the model
`tool-call`	Agent is invoking a tool (shell, file, etc.)
`tool-result`	Result from tool execution
`plan-generated`	Agent generated a task plan
`task-start`	Agent started a subtask (id, name, description)
`task-update`	Progress update for a task (id, status, progress%)
`task-complete`	Task finished (id, success, output)
`complete`	Response finished with final text
`ready`	Agent ready for next message
`error`	Error occurred

API Methods

Method	Description
`initialize()`	Load WASM module and prepare agent
`send(message)`	Stream events via AsyncGenerator
`prompt(message)`	One-shot: returns complete response string
`cancel()`	Cancel current streaming request
`getHistory()`	Get conversation history as Message[]
`clearHistory()`	Clear conversation history
`destroy()`	Release resources and clean up

Shell Commands

The agent has access to 50+ Unix-like commands running in a WASM sandbox:

File Operations

ls cat cp mv rm mkdir touch

Text Processing

grep sed awk sort uniq wc head tail

Development

tsx tsc git sqlite3 vim

Utilities

curl jq find xargs diff echo

Filesystem

Files are stored using the browser's Origin Private File System (OPFS) . This provides:

Persistent storage across sessions
Sandboxed from your real filesystem
Works offline once loaded
No size limits beyond browser storage quotas

MCP Integration

Edge Agent uses the Model Context Protocol for tool integration. You can connect to external MCP servers like:

Stripe - Access Stripe API through MCP
GitHub Copilot - Use GitHub's MCP endpoints
Custom servers - Add your own MCP-compatible tools

Configure MCP servers using the /mcp command in the terminal.

Technology Stack

Edge Agent is built with modern, proven technologies:

WASM Toolchain

@bytecodealliance/jco ^1.15 @bytecodealliance/preview2-shim ^0.17

Runtime

Rust + wasm32-wasip2 Ratatui TUI

Frontend

Vite ^7.3 TypeScript ^5.7 ghostty-web ^0.4

Deployment

Cloudflare Workers Cloudflare Pages

MCP Bridge

The MCP Bridge allows external agents (like Claude Code) to use the browser sandbox as their tool provider. This means you can run any MCP-compatible agent locally while executing all commands in the browser's secure WASM sandbox.

How It Works

External Agent → stdio → MCP Bridge → WebSocket → Browser Sandbox

Quick Start

Terminal

# Clone and start the bridge
cd tools/mcp-bridge
npm install
npm start

# Bridge listens on ws://localhost:9999

Then open agent.edge-agent.dev/mcp-bridge.html in your browser and connect to the bridge.

Claude Code Integration

You can run Claude Code with all built-in tools disabled, forcing it to use the browser sandbox via MCP.

One-Liner Execution

You don't need a config file. Run Claude Code directly with the bridge (ensure the bridge is running first):

Terminal

claude --tools "" \
--mcp-config '{"mcpServers": {"browser-sandbox": {"type": "http", "url": "http://localhost:3050/mcp"}}}'

This disables all default tools (--tools "") and injects the browser sandbox as the sole tool provider.

💡

Pro Tip: This setup lets you use any MCP-compatible agent with the browser sandbox—not just Claude Code.