agent.html is a format for packaging AI agents as single, self-contained HTML files. Share agents as easily as sharing a document—no backend, no installation, no dependencies.
Get started in 10 seconds:
bun install agent-file
agent-html quick
# Open agent.html in your browser - done!Traditional AI agents require complex deployment infrastructure. agent.html packages everything—manifest, code, memory, and UI—into a single HTML file that runs directly in any modern browser.
Key benefits:
- Self-contained: One file contains everything
- Portable: Share via email, download, or file system
- Secure: Built-in integrity checking and permission system
- Universal: Works in any modern browser
- Framework agnostic: Convert from LangChain, TensorFlow Lite RT, vanilla JS, or WASM (incl wasi)
- MCP integration: Built-in Model Context Protocol client for tool calling and resource access
bun install agent-fileCreate a working agent instantly:
agent-html quickThis creates agent.html - open it in your browser and you're done! Set your OpenAI API key in the browser console:
await window.agent.setApiKey("sk-...")
await window.agent.run("Hello!")Create template files to customize:
agent-html init
# Edit manifest.json and agent.js to your needs
agent-html generate --manifest manifest.json --code agent.jsimport { AgentFile } from 'agent-file'
const html = await AgentFile.create({
manifest: {
id: 'my-agent',
name: 'My AI Agent',
version: '1.0.0',
permissions: {
network: ['api.openai.com'],
storage: false,
code: false
}
},
code: `
class Agent {
async run(input) {
// Your agent logic here
return result
}
}
`,
ui: 'full'
})
await Bun.write('my-agent.html', html)Open my-agent.html in a browser and interact via window.agent.run(input).
An agent.html file is a complete HTML document with embedded components:
<!DOCTYPE html>
<html>
<body>
<!-- Agent Manifest -->
<script type="application/json" id="agent-manifest">
{ "id": "my-agent", "permissions": {...}, ... }
</script>
<!-- Agent Code -->
<script type="text/plain" id="agent-code">
class Agent { ... }
</script>
<!-- Integrity Hashes -->
<script type="application/json" id="agent-integrity">
{ "manifestHash": "sha256-...", "codeHash": "sha256-..." }
</script>
<!-- Runtime (loads and executes agent) -->
<script type="module" id="agent-runtime">
// Sandboxed execution environment
</script>
</body>
</html>agent.html enforces security through three mechanisms:
- Integrity Checking: SHA-256 hashes verify the manifest and code haven't been tampered with
- Permission System: Explicit whitelisting of network domains, storage, and code execution
- Sandboxed Execution: Agent runs in an iframe with restricted permissions
permissions: {
network: ['api.openai.com'], // Only these domains
storage: false, // No localStorage/sessionStorage
code: false // No eval() or Function()
}Built-in MCP client for connecting to Model Context Protocol servers. Access tools and resources from MCP servers directly in your browser-based agents.
import { MCPClient, MCPManager } from 'agent-file'
// Use in agents via manifest
const manifest = {
mcp: {
servers: [{ name: 'filesystem', url: 'http://localhost:3000/mcp' }]
}
}
// Access in agent code
async run(input) {
const result = await this.mcp.callTool('read_file', { path: '/etc/hosts' })
return result
}
// Or use directly
const client = new MCPClient('http://localhost:3000/mcp')
await client.connect()
const result = await client.callTool('read_file', { path: '/etc/hosts' })See MCP examples for detailed integration guide.
Create an agent instantly (no files needed):
agent-html quick [--name "Agent Name"] [--output agent.html]Create template files to customize:
agent-html initThis creates manifest.json and agent.js that you can edit.
Generate from custom files:
agent-html generate --manifest manifest.json --code agent.js [options]
Options:
--output <file> Output path (default: agent.html)
--ui <type> UI type: full, minimal, none (default: full)
--styles <file> Custom CSS styles
--memory <file> Initial memory/state JSONValidate an agent file:
agent-html validate agent.html [--verbose]Modify an existing agent:
agent-html modify agent.html --code new-code.js [--output modified.html]Publish to registry (coming soon):
agent-html publish agent.htmlExamples for different frameworks and use cases. Each generates a self-contained .html file you can open in a browser.
bun run example:vanilla # Pure JavaScript
bun run example:langgraph # LangGraph stateful agents
bun run example:litert # TensorFlow Lite RT
bun run example:huggingface # HuggingFace Inference API
bun run example:mcp # Model Context Protocol
bun run example:wasi # WebAssembly (WASI)- Vanilla - Pure JS, no dependencies
- LangGraph - Stateful agent conversion
- TensorFlow Lite RT - CDN model loading
- HuggingFace - Inference API integration
- MCP - Tool calling and resource access
- WASI - WebAssembly embedding
Full TypeScript definitions available in dist/index.d.ts.
import { AgentFile } from 'agent-file'
// Create agent HTML
const html = await AgentFile.create({
manifest: { id, name, version, permissions, capabilities },
code: 'class Agent { ... }',
ui: 'full' | 'minimal' | 'none'
})
// Extract components
const { manifest, code, memory, integrity } = AgentFile.extract(html)import { MCPClient, MCPManager } from 'agent-file'
// Single server
const client = new MCPClient(url, authToken?)
await client.connect()
await client.callTool(name, args)
// Multiple servers
const manager = new MCPManager()
await manager.addServer(name, url, authToken?)
await manager.callTool(toolName, args)import { generateHashes, verifyHashes, checkPermission } from 'agent-file'
const hashes = await generateHashes(manifest, code)
const valid = await verifyHashes(manifest, code, hashes)
const allowed = checkPermission(permissions, 'fetch', url)Your agent code must export a class named Agent:
class Agent {
constructor(manifest) {
this.manifest = manifest
// Your initialization
}
// Required: Main entry point
async run(input) {
// Your logic
return result
}
// Optional: Additional methods
async setApiKey(key) { }
async getState() { }
async clearState() { }
}bun install
bun run build # Compile TypeScript
bun test # Run tests
bun run mcp:server # Start MCP test serverSee examples/ for running example agents.
agent.html/
├── src/
│ ├── agent-file.ts # Main AgentFile class
│ ├── security.ts # Security utilities
│ ├── mcp-client.ts # MCP client for browser
│ ├── mcp-client-inline.ts # Inline MCP client for agents
│ └── index.ts # Public exports
├── examples/
│ ├── vanilla/ # Pure JavaScript examples
│ ├── langchain/ # LangGraph examples
│ ├── litert/ # LiterT examples
│ ├── huggingface/ # HuggingFace examples
│ ├── mcp/ # MCP integration examples
│ └── advanced/
│ └── wasi/ # WebAssembly examples
└── dist/ # Built files
Requires a modern browser with:
- ES2020+ JavaScript
- Fetch API
- Web Crypto API (SHA-256)
- iframe sandboxing
- ES Modules
Tested on Chrome/Edge 90+, Firefox 88+, Safari 14+
agent.html is built on five principles:
- Simplicity: One file, standard technologies, minimal API
- Security: Explicit permissions, integrity verification, sandboxing
- Portability: Works anywhere, no dependencies, no backend
- Transparency: Source code is visible and verifiable
- Extensibility: Platform-agnostic format, easy integration
Contributions welcome. Please:
- Read existing code and follow patterns
- Add tests for new features
- Update documentation
- Submit PR with clear description
MIT License - see LICENSE file
- Examples Guide - Comprehensive examples and patterns
- Model Context Protocol - MCP specification