B4n1Web — Agentic Browser Engine

Ultra-lightweight headless browser for AI agents. Single Rust binary, 4 language SDKs. Navigate URLs, extract structured content (markdown, links, screenshots), and build autonomous agent workflows.

Quick Start

1. Install the binary

# One-liner (Linux/macOS/Windows via WSL)
curl -sL https://b4n1.com/install | bash

Or use your preferred package manager:

# Python
pip install b4n1-web

# JavaScript/TypeScript
npm install b4n1-web

# Java (Maven)
# Add to pom.xml:
# <dependency>
#   <groupId>com.b4n1</groupId>
#   <artifactId>b4n1-web</artifactId>
#   <version>0.9.5</version>
# </dependency>

# C# .NET
dotnet add package B4n1Web

2. Extract content from any URL

from b4n1web import AgentBrowser

browser = AgentBrowser()
page = browser.goto("https://example.com")

print(page.url)       # URL
print(page.markdown)  # Clean markdown content
print(page.links)     # All extracted links
print(page.screenshot) # Base64 PNG (if available)
print(page.js_output)  # JavaScript output (if evaluated)

browser.close()

import { AgentBrowser } from 'b4n1-web';

const browser = new AgentBrowser();
const page = await browser.gotoAsync('https://example.com');

console.log(page.url);
console.log(page.markdown);
console.log(page.links);

await browser.close();

using B4N1Web;

var browser = new AgentBrowser();
var page = browser.Goto("https://example.com");

Console.WriteLine(page.Url);
Console.WriteLine(page.Markdown);
Console.WriteLine(page.Links);

browser.Close();

import com.b4n1.AgentBrowser;
import com.b4n1.Page;

AgentBrowser browser = new AgentBrowser();
Page page = browser.goto("https://example.com");

System.out.println(page.getUrl());
System.out.println(page.getMarkdown());
System.out.println(page.getLinks());

browser.close();

What You Get

Browser Modes

SDK Matrix

All platforms = linux-amd64, linux-arm64, macos-x64, macos-arm64, windows-amd64, windows-arm64

Next Steps

• Installation — Detailed install instructions for each platform
• Browser Modes — Choose the right mode for your use case
• Python SDK — Complete Python API reference
• JavaScript SDK — Complete JS/TS API reference
• C# SDK — Complete C# API reference
• Java SDK — Complete Java API reference
• CLI Reference — Command-line interface
• MCP Integration — Use with AI agents via MCP

Installation

Binary Install

One-liner (Linux/macOS/Windows via WSL)

curl -sL https://b4n1.com/install | bash

This downloads the correct binary for your platform and installs it to ~/.local/bin/b4n1web.

Manual Download

Download from GitHub Releases:

Make executable (Linux/macOS):

chmod +x b4n1web-*
sudo mv b4n1web-* /usr/local/bin/b4n1web

Verify Installation

b4n1web --version
# b4n1web 0.9.5

Python SDK

# From PyPI
pip install b4n1-web

# Or with UV
uv pip install b4n1-web

Requires: Python 3.8+

The wheel includes binaries for all 6 platforms.

JavaScript/TypeScript SDK

# npm
npm install b4n1-web

# pnpm
pnpm add b4n1-web

# yarn
yarn add b4n1-web

Requires: Node.js 18+

The package includes binaries for all 6 platforms.

Java SDK

Maven

<dependency>
    <groupId>com.b4n1</groupId>
    <artifactId>b4n1-web</artifactId>
    <version>0.9.5</version>
</dependency>

Gradle

implementation 'com.b4n1:b4n1-web:0.9.5'

Requires: Java 11+

The JAR includes native binaries for all 6 platforms.

C# .NET SDK

dotnet add package B4n1Web

Requires: .NET 6.0+

The NuGet package includes native binaries for all 6 platforms.

Platform Compatibility

All SDKs bundle binaries for these 6 platforms:

Chromium Dependency

Chromium is downloaded automatically when you use Render mode. No separate installation needed.

Supported platforms for Chromium:

• Linux x86_64 ✅
• Linux ARM64 ✅
• macOS Intel ✅
• macOS Apple Silicon ✅
• Windows x86_64 ✅
• Windows ARM64 ✅

The first Render mode call downloads Chromium (~160MB) to ~/.b4n1web/chromium/. Subsequent calls reuse it.

Troubleshooting Install

Binary not found in PATH

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Permission denied

chmod +x ~/.local/bin/b4n1web

Chromium download fails

Check internet connection. Chromium is downloaded from Google’s storage. For offline environments, pre-download and place in ~/.b4n1web/chromium/.

Architecture mismatch

Ensure you’re using the correct binary for your platform:

uname -m  # x86_64 or aarch64

Browser Modes

B4n1Web offers three browser modes, each with different capabilities and resource usage.

Mode Comparison

Light Mode

Best for: Fast scraping, SEO content, static sites, APIs returning HTML.

browser = AgentBrowser()  # Default is Light
page = browser.goto("https://example.com")

What it does:

• Fetches HTML via HTTP
• Parses HTML to extract text, links, meta tags
• Converts to clean markdown
• No JavaScript execution

Use cases:

• Blog posts, articles, documentation
• Product listings, directories
• Any content rendered server-side

JS Mode

Best for: Sites that load content via JavaScript but don’t need screenshots.

from b4n1web import AgentBrowser, BrowserMode

browser = AgentBrowser(mode=BrowserMode.JS)
page = browser.goto("https://example.com")

What it does:

• Same as Light mode
• PLUS: Extracts data from JavaScript variables
• Can evaluate JavaScript expressions
• Returns page.js_output with JS results

Use cases:

• Single Page Applications (SPAs)
• Sites with JSON data embedded in scripts
• Dynamic content loaded via fetch/XHR

Render Mode

Best for: Screenshots, clicking, typing, waiting, full browser automation.

from b4n1web import AgentBrowser, BrowserMode

browser = AgentBrowser(mode=BrowserMode.RENDER)
page = browser.goto("https://example.com", wait_for=".content")

# Screenshot
screenshot_b64 = browser.screenshot(1920, 1080)

# Interact
browser.click(".button")
browser.type_text("#search", "query")
browser.wait_for_selector(".results", 5000)

What it does:

• Full Chromium browser (headless)
• Screenshots (full page or viewport)
• Click, type, hover, scroll
• Wait for selectors
• Full JavaScript execution
• All MCP tools available

Use cases:

• Visual regression testing
• Form automation
• Complex SPAs
• Screenshots for reports
• Any interaction requiring real browser

Choosing the Right Mode

START: Do you need screenshots or interaction (click/type/wait)?
  YES → RENDER MODE
  NO  → Does the site load content via JavaScript?
    YES → JS MODE
    NO  → LIGHT MODE

Mode Switching

# Change mode per request
browser = AgentBrowser(mode=BrowserMode.LIGHT)

# Light request
page = browser.goto("https://example.com")

# Switch to Render for screenshot
browser2 = AgentBrowser(mode=BrowserMode.RENDER)
page2 = browser2.goto("https://example.com")
screenshot = browser2.screenshot(1920, 1080)

Note: Each AgentBrowser instance has one mode. Create separate instances for different modes.

Performance Tips

Memory Comparison

Light:     ████░░░░░░░░░░░░░░░░░░░░  ~15 MB
JS:        ████░░░░░░░░░░░░░░░░░░░░  ~15 MB
Render:    ████████████░░░░░░░░░░░░  ~100 MB

Quick Reference

Python SDK

Complete API reference for the Python SDK.

Installation

pip install b4n1-web

Basic Usage

from b4n1web import AgentBrowser, BrowserOptions, BrowserMode

# Simple usage
browser = AgentBrowser()
page = browser.goto("https://example.com")
print(page.markdown)
browser.close()

# Context manager (auto-close)
with AgentBrowser() as browser:
    page = browser.goto("https://example.com")
    print(page.markdown)

Browser Options

from b4n1web import BrowserOptions, BrowserMode

options = BrowserOptions(
    mode=BrowserMode.LIGHT,      # LIGHT, JS, or RENDER
    timeout=30,                  # seconds
    user_agent="MyBot/1.0"       # custom user agent
)

browser = AgentBrowser(options=options)

Options:

Page Object

page = browser.goto("https://example.com")

# Properties
page.url          # str - Final URL after redirects
page.markdown     # str - Clean markdown content
page.links        # List[str] - All extracted links
page.screenshot   # str | None - Base64 PNG (Render mode only)
page.js_output    # str | None - JavaScript output (JS/Render mode)

# Methods
page.get_main_content()     # str - Content skipping first 2 lines
page.find_links_by_text("click")  # List[str] - Links containing text

Page Methods

# Get main content (skip headers)
content = page.get_main_content()

# Find links containing specific text (case-insensitive)
contact_links = page.find_links_by_text("contact")

Advanced Features (Render Mode Only)

browser = AgentBrowser(options=BrowserOptions(mode=BrowserMode.RENDER))

# Navigate with wait
page = browser.goto("https://example.com", wait_for=".content")

# Screenshot
screenshot_b64 = browser.screenshot(width=1920, height=1080)
# Returns base64 PNG string

# Wait for selector
found = browser.wait_for_selector(".my-element", timeout_ms=5000)
# Returns True/False

# Click element
browser.click(".submit-button")

# Type text
browser.type_text("#search", "query", clear_first=True)

# Get links from last page
links = browser.get_links()

# Execute JavaScript
result = browser.evaluate("document.title")
# Returns JS output as string

Async Usage

import asyncio
from b4n1web import AgentBrowser

async def main():
    browser = AgentBrowser()
    page = await browser.goto_async("https://example.com")
    print(page.markdown)
    await browser.close_async()

asyncio.run(main())

Environment Variables

export B4N1WEB_BINARY=/custom/path/b4n1web
export B4N1WEB_CHROMIUM=/usr/bin/chromium

Error Handling

from b4n1web import AgentBrowser, BrowserOptions

try:
    browser = AgentBrowser()
    page = browser.goto("https://example.com")
except FileNotFoundError:
    print("Binary not found. Install with: pip install b4n1-web")
except Exception as e:
    print(f"Error: {e}")

Version Compatibility

The SDK checks binary version on startup. If mismatched, a warning is printed:

⚠️  Version mismatch: SDK v0.9.5 requires binary v0.9.5, but found v0.9.4

Type Hints

Full type annotations included. Works with mypy, pyright, VS Code IntelliSense.

from b4n1web import AgentBrowser, Page
from typing import List

def extract_links(url: str) -> List[str]:
    browser: AgentBrowser = AgentBrowser()
    page: Page = browser.goto(url)
    return page.links

Async Context Manager

async with AgentBrowser() as browser:
    page = await browser.goto_async("https://example.com")
    # Auto-closes on exit

JavaScript/TypeScript SDK

Complete API reference for the JavaScript/TypeScript SDK.

Installation

npm install b4n1-web
# or
pnpm add b4n1-web
# or
yarn add b4n1-web

Basic Usage

import { AgentBrowser, BrowserMode } from 'b4n1-web';

// Simple usage
const browser = new AgentBrowser();
const page = await browser.gotoAsync('https://example.com');
console.log(page.markdown);
await browser.close();

// Async context manager
await using browser = new AgentBrowser();
const page = await browser.gotoAsync('https://example.com');
console.log(page.markdown);

Browser Options

import { AgentBrowser, BrowserMode, BrowserOptions } from 'b4n1-web';

const options: BrowserOptions = {
    mode: BrowserMode.LIGHT,      // LIGHT, JS, or RENDER
    timeout: 30,                  // seconds
    userAgent: 'MyBot/1.0'        // custom user agent
};

const browser = new AgentBrowser(options);

Options:

import { BrowserMode } from 'b4n1-web';

const browser = new AgentBrowser({
    mode: BrowserMode.RENDER,
    timeout: 60,
    userAgent: 'CustomBot/1.0'
});

Page Object

const page = await browser.gotoAsync('https://example.com');

// Properties
page.url           // string - Final URL after redirects
page.markdown      // string - Clean markdown content
page.links         // string[] - All extracted links
page.screenshot    // string | null - Base64 PNG (Render mode only)
page.jsOutput      // string | null - JavaScript output (JS/Render mode)

Page Methods

// Get main content (skip headers)
const content = page.getMainContent();

// Find links containing specific text (case-insensitive)
const contactLinks = page.findLinksByText('contact');

Advanced Features (Render Mode Only)

const browser = new AgentBrowser({ mode: BrowserMode.RENDER });

// Navigate with wait
const page = await browser.gotoAsync('https://example.com', { waitFor: '.content' });

// Screenshot
const screenshotB64 = await browser.screenshot(1920, 1080);
// Returns base64 PNG string

// Wait for selector
const found = await browser.waitForSelector('.my-element', 5000);
// Returns true/false

// Click element
await browser.click('.submit-button');

// Type text
await browser.typeText('#search', 'query', true); // clearFirst = true

// Get links from last page
const links = browser.getLinks();

// Execute JavaScript
const result = await browser.evaluate('document.title');
// Returns JS output as string

Synchronous API

import { AgentBrowser, BrowserMode } from 'b4n1-web';

const browser = new AgentBrowser({ mode: BrowserMode.LIGHT });
const page = browser.goto('https://example.com');  // Blocking
console.log(page.markdown);
browser.close();

Environment Variables

# Custom binary path
export B4N1WEB_BINARY=/custom/path/b4n1web

# Custom Chromium path
export B4N1WEB_CHROMIUM=/usr/bin/chromium

TypeScript Support

Full TypeScript definitions included. Works out of the box with VS Code, tsc, etc.

import { AgentBrowser, BrowserOptions, BrowserMode, Page } from 'b4n1-web';

interface MyPageData {
    url: string;
    markdown: string;
    links: string[];
}

async function extractData(url: string): Promise<MyPageData> {
    const options: BrowserOptions = {
        mode: BrowserMode.LIGHT,
        timeout: 30
    };
    
    const browser = new AgentBrowser(options);
    const page: Page = await browser.gotoAsync(url);
    
    return {
        url: page.url,
        markdown: page.markdown,
        links: page.links
    };
}

Version Compatibility

The SDK checks binary version on startup. If mismatched, a warning is printed to stderr:

⚠️  Version mismatch: SDK v0.9.5 requires binary v0.9.5, but found v0.9.4

Error Handling

import { AgentBrowser, BrowserMode } from 'b4n1-web';

try {
    const browser = new AgentBrowser({ mode: BrowserMode.LIGHT });
    const page = await browser.gotoAsync('https://example.com');
    console.log(page.markdown);
} catch (error) {
    if (error.message.includes('not found')) {
        console.error('Binary not found. Install with: npm install b4n1-web');
    } else {
        console.error('Error:', error);
    }
} finally {
    await browser.close();
}

Static Methods

import { AgentBrowser } from 'b4n1-web';

// Get version without creating browser
const version = AgentBrowser.getVersion();

// Get links from URL without creating browser instance
const links = await AgentBrowser.getLinksFromPage('https://example.com');

Vite/Next.js/Framework Integration

Works with all modern frameworks. Just import and use:

// Next.js API route
export async function GET() {
    const browser = new AgentBrowser({ mode: BrowserMode.LIGHT });
    const page = await browser.gotoAsync('https://example.com');
    return Response.json({ markdown: page.markdown });
}

Async Disposable (using declaration)

// Automatic cleanup with using (Node 20+ / TypeScript 5.2+)
await using browser = new AgentBrowser({ mode: BrowserMode.RENDER });
const page = await browser.gotoAsync('https://example.com');
const screenshot = await browser.screenshot(1920, 1080);
// browser.close() called automatically

C# .NET SDK

Complete API reference for the C# .NET SDK.

Installation

dotnet add package B4n1Web

Requires: .NET 6.0+

Basic Usage

using B4N1Web;

// Simple usage
var browser = new AgentBrowser();
var page = browser.Goto("https://example.com");
Console.WriteLine(page.Markdown);
browser.Close();

// Using statement (auto-dispose)
using var browser = new AgentBrowser();
var page = browser.Goto("https://example.com");
Console.WriteLine(page.Markdown);

Browser Options

using B4N1Web;

var options = new BrowserOptions
{
    Mode = BrowserMode.Light,      // Light, JS, or Render
    Timeout = 30,                  // seconds
    UserAgent = "MyBot/1.0"        // custom user agent
};

var browser = new AgentBrowser(options);

Options:

var browser = new AgentBrowser(new BrowserOptions
{
    Mode = BrowserMode.Render,
    Timeout = 60,
    UserAgent = "CustomBot/1.0"
});

BrowserMode Enum

public enum BrowserMode
{
    Light = 0,
    JS = 1,
    Render = 2
}

Page Object

var page = browser.Goto("https://example.com");

// Properties
page.Url           // string - Final URL after redirects
page.Markdown      // string - Clean markdown content
page.Links         // List<string> - All extracted links
page.Screenshot    // string? - Base64 PNG (Render mode only)
page.JsOutput      // string? - JavaScript output (JS/Render mode)

Page Methods

// Get main content (skip headers)
var content = page.GetMainContent();

// Find links containing specific text (case-insensitive)
var contactLinks = page.FindLinksByText("contact");
// Returns List<string>

Advanced Features (Render Mode Only)

var browser = new AgentBrowser(new BrowserOptions { Mode = BrowserMode.Render });

// Navigate with wait
var page = browser.Goto("https://example.com", waitFor: ".content");

// Screenshot
var screenshotB64 = browser.Screenshot(1920, 1080);
// Returns base64 PNG string

// Wait for selector
var found = browser.WaitForSelector(".my-element", 5000);
// Returns true/false

// Click element
browser.Click(".submit-button");

// Type text
browser.TypeText("#search", "query", true);  // clearFirst = true

// Get links from last page
var links = browser.GetLinks();
// Returns string[]

// Execute JavaScript
var result = browser.Evaluate("document.title");
// Returns JS output as string

Async API

var browser = new AgentBrowser(new BrowserOptions { Mode = BrowserMode.Light });

// Navigate async
var page = await browser.GotoAsync("https://example.com");
Console.WriteLine(page.Markdown);

// Screenshot async
var screenshot = await browser.ScreenshotAsync(1920, 1080);

// Wait for selector async
var found = await browser.WaitForSelectorAsync(".my-element", 5000);

// Click async
await browser.ClickAsync(".submit-button");

// Type text async
await browser.TypeTextAsync("#search", "query", true);

// Evaluate JavaScript async
var result = await browser.EvaluateAsync("document.title");

Static Methods

using B4N1Web;

// Get version without creating browser
var version = AgentBrowser.GetVersion();

// Get links from URL without creating browser instance
var links = AgentBrowser.GetLinksFromPage("https://example.com");
// Returns string[]

Environment Variables

# Custom binary path
export B4N1WEB_BINARY=/custom/path/b4n1web

# Custom Chromium path
export B4N1WEB_CHROMIUM=/usr/bin/chromium

Error Handling

using B4N1Web;

try
{
    var browser = new AgentBrowser();
    var page = browser.Goto("https://example.com");
    Console.WriteLine(page.Markdown);
}
catch (BinaryNotFoundException)
{
    Console.WriteLine("Binary not found. Install with: dotnet add package B4n1Web");
}
catch (Exception ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}
finally
{
    browser?.Dispose();
}

BinaryNotFoundException

Thrown when the b4n1web binary cannot be found:

try
{
    var browser = new AgentBrowser();
}
catch (BinaryNotFoundException ex)
{
    Console.WriteLine(ex.Message);
    // "B4n1Web binary not found. Please install it first..."
}

Version Compatibility

The SDK checks binary version on startup. If mismatched, a warning is printed to stderr:

⚠️  Version mismatch: SDK v0.9.5 requires binary v0.9.5, but found v0.9.4

Dependency Injection

// Register in DI container
services.AddSingleton<IAgentBrowser>(provider => 
    new AgentBrowser(new BrowserOptions { Mode = BrowserMode.Light })
);

// Use in controller/service
public class MyService
{
    private readonly IAgentBrowser _browser;
    
    public MyService(IAgentBrowser browser) => _browser = browser;
    
    public async Task<string> ScrapeAsync(string url)
    {
        var page = await _browser.GotoAsync(url);
        return page.Markdown;
    }
}

Platform Compatibility

The NuGet package bundles binaries for all 6 platforms:

• Linux x86_64
• Linux ARM64
• macOS x86_64
• macOS ARM64
• Windows x86_64
• Windows ARM64

The correct binary is selected automatically at runtime.

Async Disposable

// Using declaration (C# 8+)
await using var browser = new AgentBrowser();
var page = await browser.GotoAsync("https://example.com");
// Auto-disposes on scope exit

Testing with FakeProcessRunner

using B4N1Web.Tests;

// For unit testing
var fake = new FakeProcessRunner();
fake.QueueResult(new ProcessResult { ExitCode = 0, StdOut = "test" });

var browser = new AgentBrowser(new BrowserOptions(), fake);
var page = browser.Goto("https://example.com");

Java SDK

Complete API reference for the Java SDK.

Installation

Maven

<dependency>
    <groupId>com.b4n1</groupId>
    <artifactId>b4n1-web</artifactId>
    <version>0.9.5</version>
</dependency>

Gradle

implementation 'com.b4n1:b4n1-web:0.9.5'

Requires: Java 11+

Basic Usage

import com.b4n1.AgentBrowser;
import com.b4n1.Page;
import com.b4n1.BrowserOptions;
import com.b4n1.BrowserMode;

// Simple usage
AgentBrowser browser = new AgentBrowser();
Page page = browser.goto("https://example.com");
System.out.println(page.getMarkdown());
browser.close();

// Try-with-resources (auto-close)
try (AgentBrowser browser = new AgentBrowser()) {
    Page page = browser.goto("https://example.com");
    System.out.println(page.getMarkdown());
}

Browser Options

import com.b4n1.AgentBrowser;
import com.b4n1.BrowserOptions;
import com.b4n1.BrowserMode;

BrowserOptions options = new BrowserOptions()
    .setMode(BrowserMode.LIGHT)      // LIGHT, JS, or RENDER
    .setTimeout(30)                  // seconds
    .setUserAgent("MyBot/1.0");      // custom user agent

AgentBrowser browser = new AgentBrowser(options);

Options:

AgentBrowser browser = new AgentBrowser(
    new BrowserOptions()
        .setMode(BrowserMode.RENDER)
        .setTimeout(60)
        .setUserAgent("CustomBot/1.0")
);

BrowserMode Enum

public enum BrowserMode {
    LIGHT,
    JS,
    RENDER
}

Page Object

Page page = browser.goto("https://example.com");

// Properties
page.getUrl()           // String - Final URL after redirects
page.getMarkdown()      // String - Clean markdown content
page.getLinks()         // List<String> - All extracted links
page.getScreenshot()    // String - Base64 PNG (Render mode only, or null)
page.getJsOutput()      // String - JavaScript output (JS/Render mode, or null)

Page Methods

// Get main content (skip headers)
String content = page.getMainContent();

// Find links containing specific text (case-insensitive)
List<String> contactLinks = page.findLinksByText("contact");
// Returns List<String>

Advanced Features (Render Mode Only)

AgentBrowser browser = new AgentBrowser(
    new BrowserOptions().setMode(BrowserMode.RENDER)
);

// Navigate with wait
Page page = browser.goto("https://example.com", ".content");

// Screenshot
String screenshotB64 = browser.screenshot(1920, 1080);
// Returns base64 PNG string

// Wait for selector
boolean found = browser.waitForSelector(".my-element", 5000);
// Returns true/false

// Click element
browser.click(".submit-button");

// Type text
browser.typeText("#search", "query", true);  // clearFirst = true

// Get links from last page
String[] links = browser.getLinks();
// Returns String[]

// Execute JavaScript
String result = browser.evaluate("document.title");
// Returns JS output as String

Static Methods

import com.b4n1.AgentBrowser;

// Get version without creating browser
String version = AgentBrowser.getVersion();

// Get links from URL without creating browser instance
String[] links = AgentBrowser.getLinksFromPage("https://example.com");
// Returns String[]

Environment Variables

# Custom binary path
export B4N1WEB_BINARY=/custom/path/b4n1web

# Custom Chromium path
export B4N1WEB_CHROMIUM=/usr/bin/chromium

Error Handling

import com.b4n1.AgentBrowser;
import com.b4n1.BinaryNotFoundException;

try {
    AgentBrowser browser = new AgentBrowser();
    Page page = browser.goto("https://example.com");
    System.out.println(page.getMarkdown());
} catch (BinaryNotFoundException e) {
    System.err.println("Binary not found: " + e.getMessage());
    // "B4n1Web binary not found. Please install it first..."
} catch (Exception e) {
    System.err.println("Error: " + e.getMessage());
}

BinaryNotFoundException

Thrown when the b4n1web binary cannot be found:

try {
    AgentBrowser browser = new AgentBrowser();
} catch (BinaryNotFoundException e) {
    System.err.println(e.getMessage());
    // "B4n1Web binary not found. Please install it first..."
}

Version Compatibility

The SDK checks binary version on startup. If mismatched, a warning is printed to stderr:

⚠️  Version mismatch: SDK v0.9.5 requires binary v0.9.5, but found v0.9.4

Dependency Injection (Spring)

@Configuration
public class BrowserConfig {
    
    @Bean
    public AgentBrowser agentBrowser() {
        return new AgentBrowser(
            new BrowserOptions().setMode(BrowserMode.LIGHT)
        );
    }
}

@Service
public class ScraperService {
    
    private final AgentBrowser browser;
    
    public ScraperService(AgentBrowser browser) {
        this.browser = browser;
    }
    
    public String scrape(String url) {
        Page page = browser.goto(url);
        return page.getMarkdown();
    }
}

Platform Compatibility

The JAR bundles native binaries for all 6 platforms:

• Linux x86_64
• Linux ARM64
• macOS x86_64
• macOS ARM64
• Windows x86_64
• Windows ARM64

The correct binary is selected automatically at runtime via the native/ directory structure.

AutoCloseable

// Try-with-resources (Java 7+)
try (AgentBrowser browser = new AgentBrowser()) {
    Page page = browser.goto("https://example.com");
    System.out.println(page.getMarkdown());
} // browser.close() called automatically

Maven Packaging

The SDK is published as a single JAR with all native binaries included. No additional dependencies needed.

<dependency>
    <groupId>com.b4n1</groupId>
    <artifactId>b4n1-web</artifactId>
    <version>0.9.5</version>
</dependency>

Testing

// The SDK uses ProcessBuilder internally
// For testing, you can mock the binary behavior
// or use the real binary in integration tests

Version Information

import com.b4n1.AgentBrowser;

String sdkVersion = AgentBrowser.getVersion();
// Returns binary version or "unknown" if not found

CLI Reference

Complete command-line interface for the b4n1web binary.

Installation

# One-liner
curl -sL https://b4n1.com/install | bash

# Or download from GitHub Releases

Commands

b4n1web goto <URL>

Navigate to a URL and extract content.

# Basic usage
b4n1web goto https://example.com

# With mode
b4n1web goto https://example.com --mode light
b4n1web goto https://example.com --mode js
b4n1web goto https://example.com --mode render

# Wait for selector
b4n1web goto https://example.com --wait-for ".content"

# Output to file
b4n1web goto https://example.com --output page.md

Options:

b4n1web screenshot

Take a screenshot (requires Render mode).

b4n1web screenshot --url https://example.com --width 1920 --height 1080

Options:

b4n1web click

Click an element (requires Render mode).

b4n1web click ".submit-button" --url https://example.com

b4n1web type-text

Type text into an element (requires Render mode).

b4n1web type-text "#search" "query" --url https://example.com --clear-first

b4n1web wait-for-selector

Wait for an element to appear (requires Render mode).

b4n1web wait-for-selector ".results" --url https://example.com --timeout 5000

b4n1web evaluate

Execute JavaScript (requires Render mode).

b4n1web evaluate "document.title" --url https://example.com

b4n1web scroll

Scroll the page (requires Render mode).

b4n1web scroll --x 0 --y 500 --url https://example.com

b4n1web pdf

Generate PDF (requires Render mode).

b4n1web pdf --url https://example.com --output page.pdf

b4n1web --version

Show version.

b4n1web --version
# b4n1web 0.9.5

b4n1web --help

Show help.

b4n1web --help

MCP Server

b4n1web mcp

Start MCP server for AI agents.

b4n1web mcp

This starts a Model Context Protocol server on stdio with 33 tools.

b4n1web daemon

Start background daemon.

b4n1web daemon start
b4n1web daemon stop
b4n1web daemon status

Environment Variables

export B4N1WEB_BINARY=/custom/path/b4n1web
export B4N1WEB_CHROMIUM=/usr/bin/chromium

Exit Codes

Examples

Scrape a blog post

b4n1web goto https://blog.example.com/post --output post.md

Screenshot a dashboard

b4n1web screenshot --url https://dashboard.example.com --width 1920 --height 1080 --output dashboard.png

Extract links for crawling

b4n1web goto https://example.com --mode light | grep -A 100 "Links:" | jq -r '.[]'

Interactive session

# Start daemon
b4n1web daemon start

# Use MCP tools
# (via MCP client like Claude, Cursor, etc.)

# Stop daemon
b4n1web daemon stop

Configuration File

Create ~/.config/b4n1web/config.toml:

[default]
mode = "light"
timeout = 30
user_agent = "MyBot/1.0"

[chromium]
path = "/usr/bin/chromium"
download_dir = "~/.b4n1web/chromium"

Then run without flags:

b4n1web goto https://example.com

MCP Integration

B4n1Web includes a Model Context Protocol (MCP) server with 33 tools for AI agent workflows.

What is MCP?

MCP (Model Context Protocol) lets AI agents (Claude, Cursor, etc.) use tools through a standardized interface. B4n1Web’s MCP server exposes browser automation as callable tools.

Quick Start

# Start MCP server
b4n1web mcp

This runs on stdio. Configure your AI client to use it:

Claude Desktop Config

{
  "mcpServers": {
    "b4n1web": {
      "command": "b4n1web",
      "args": ["mcp"]
    }
  }
}

Cursor Config

{
  "mcp": {
    "servers": {
      "b4n1web": {
        "command": "b4n1web",
        "args": ["mcp"]
      }
    }
  }
}

Available Tools (33)

Navigation

Content Extraction

Page Interaction

Network

Browser State

Utility

Usage Example (AI Agent)

User: "Go to github.com and get the markdown of the trending page"

AI Agent calls:
1. goto(url="https://github.com/trending", mode="light")
2. Returns: {url, markdown, links, ...}

Daemon Mode

For persistent connections:

# Start daemon
b4n1web daemon start

# Check status
b4n1web daemon status

# Stop daemon
b4n1web daemon stop

The daemon runs the MCP server in background. Useful for long-running agent sessions.

Configuration

Environment Variables

export B4N1WEB_BINARY=/custom/path/b4n1web
export B4N1WEB_CHROMIUM=/usr/bin/chromium

Custom Chromium

The MCP server auto-downloads Chromium for Render mode tools. To use system Chromium:

export B4N1WEB_CHROMIUM=/usr/bin/chromium
b4n1web mcp

All 33 Tools Reference

Each tool returns structured JSON. Example:

{
  "goto": {
    "url": "https://example.com",
    "mode": "light",
    "wait_for": ".content"
  }
}

See CLI Reference for individual tool parameters.

Security

The MCP server runs with your user permissions. It can:

• Access any URL
• Take screenshots
• Download files
• Execute JavaScript

Only run with trusted AI agents.

Troubleshooting

Common issues and solutions.

Chromium Not Found

Error: Chromium not found or Failed to download Chromium

Solutions:

1. Auto-download failed - Check internet connection. Chromium (~160MB) downloads from Google’s storage.

2. Use system Chromium:

   export B4N1WEB_CHROMIUM=/usr/bin/chromium
   # or
   export B4N1WEB_CHROMIUM=/Applications/Chromium.app/Contents/MacOS/Chromium
   

3. Manual download:

   • Download from Chromium Snapshots
   • Place in ~/.b4n1web/chromium/

4. Linux ARM64 (Raspberry Pi):

   sudo apt install chromium-browser
   export B4N1WEB_CHROMIUM=/usr/bin/chromium
   

Permission Errors

Error: Permission denied when running binary

chmod +x b4n1web

Error: Permission denied for Chromium

chmod +x ~/.b4n1web/chromium/chrome

Binary Not Found

Error: Binary not found or b4n1web: command not found

1. Check PATH:

   echo $PATH
   

2. Add to PATH:

   export PATH="$HOME/.local/bin:$PATH"
   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   

3. Use full path:

   /full/path/to/b4n1web goto https://example.com
   

Timeout Issues

Error: Binary timed out after 30s

Increase timeout:

browser = AgentBrowser(options={"timeout": 60})

const browser = new AgentBrowser({ timeout: 60 });

var browser = new AgentBrowser(new BrowserOptions { Timeout = 60 });

AgentBrowser browser = new AgentBrowser(new BrowserOptions().setTimeout(60));

Or CLI:

b4n1web goto https://slow-site.com --timeout 60

Connection Errors

Error: Connection refused or Network error

1. Check internet connection
2. Try different mode (Light mode doesn’t need Chromium)
3. Check firewall/proxy settings
4. For corporate networks, configure proxy:

export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

Version Mismatch

Warning: Version mismatch: SDK v0.9.5 requires binary v0.9.5, but found v0.9.4

Update both SDK and binary to same version:

# Reinstall SDK (gets latest binary)
pip install --upgrade b4n1-web
npm install b4n1-web@latest
dotnet add package B4n1Web --version 0.9.5

Or update binary manually:

curl -sL https://b4n1.com/install | bash

Architecture Mismatch

Error: Binary runs but crashes immediately

Check architecture:

uname -m        # Linux/macOS
# x86_64 = amd64
# aarch64 = arm64

# Windows
echo %PROCESSOR_ARCHITECTURE%

Download correct binary from Releases.

Mode-Specific Issues

Light/JS Mode

• No Chromium needed
• Fastest
• Limited to static content

Render Mode

• Needs Chromium
• Slower startup (~2s first run)
• Full browser features

If Render mode fails, try JS mode first:

browser = AgentBrowser(options={"mode": "js"})

Debug Mode

Enable verbose logging:

RUST_LOG=debug b4n1web goto https://example.com

import logging
logging.basicConfig(level=logging.DEBUG)

Getting Help

1. Check GitHub Issues
2. Search existing issues
3. Create new issue with:
   • OS and version
   • b4n1web version (b4n1web --version)
   • Full error message
   • Minimal reproduction code

FAQ

General

What is b4n1web?

An ultra-lightweight headless browser engine with a single Rust binary and 4 language SDKs (Python, JavaScript/TypeScript, Java, C#). Designed for AI agents and web scraping.

How is it different from Selenium/Playwright/Puppeteer?

Which mode should I use?

START: Do you need screenshots or interaction (click/type/wait)?
  YES → RENDER MODE
  NO  → Does the site load content via JavaScript?
    YES → JS MODE
    NO  → LIGHT MODE

Installation

“Binary not found” error

The SDK bundles binaries for all 6 platforms. If you see this:

1. Reinstall: pip install --upgrade b4n1-web
2. Or manually: curl -sL https://b4n1.com/install | bash

Python: “No module named ‘b4n1web’”

pip install b4n1-web
# Note: package name has hyphen, import uses underscore
from b4n1web import AgentBrowser

npm: “Cannot find module ‘b4n1-web’”

npm install b4n1-web
# or
pnpm add b4n1-web

Runtime Issues

“Chromium not found” (Render mode)

Render mode needs Chromium. It auto-downloads (~160MB) on first use.

Solutions:

1. Wait for auto-download (requires internet)
2. Use system Chromium:

   export B4N1WEB_CHROMIUM=/usr/bin/chromium
   

3. Linux ARM64 (Raspberry Pi):

   sudo apt install chromium-browser
   export B4N1WEB_CHROMIUM=/usr/bin/chromium
   

“Permission denied” on binary

chmod +x ~/.local/bin/b4n1web

“Version mismatch” warning

⚠️ Version mismatch: SDK v0.9.5 requires binary v0.9.5, but found v0.9.4

Update both:

pip install --upgrade b4n1-web
curl -sL https://b4n1.com/install | bash

SDK-Specific

Python: Async vs Sync

# Sync (blocking)
browser = AgentBrowser()
page = browser.goto("https://example.com")

# Async (non-blocking)
browser = AgentBrowser()
page = await browser.goto_async("https://example.com")

JavaScript: CommonJS vs ESM

// ESM (recommended)
import { AgentBrowser } from 'b4n1-web';

// CommonJS
const { AgentBrowser } = require('b4n1-web');

C#: Dependency Injection

services.AddSingleton<IAgentBrowser>(provider => 
    new AgentBrowser(new BrowserOptions { Mode = BrowserMode.Light }));

Java: Spring Boot

@Bean
public AgentBrowser agentBrowser() {
    return new AgentBrowser(new BrowserOptions().setMode(BrowserMode.LIGHT));
}

Platform Support

MCP Server

“Connection refused”

# Start daemon first
b4n1web daemon start
b4n1web mcp

“Tool not found”

Update to latest version:

curl -sL https://b4n1.com/install | bash

Performance

Still Stuck?

1. Check GitHub Issues
2. Search existing issues
3. Create new issue with:
   • OS + version
   • b4n1web --version
   • Full error message
   • Minimal reproduction code

Contributing

Thanks for contributing to B4n1Web!

Development Setup

# Clone
git clone https://github.com/B4N1-com/b4n1-web.git
cd b4n1-web

# Rust binary
cd engine/cli-core
cargo build --release

# Python SDK
cd ../../sdks/python
pip install -e ".[dev]"

# JavaScript SDK
cd ../../sdks/javascript
npm install

# Java SDK
cd ../../sdks/java
mvn install -DskipTests

# C# SDK
cd ../../sdks/csharp
dotnet build

Running Tests

# All tests
bash test_all.sh

# Rust
cd engine/cli-core && cargo test --lib

# JavaScript
cd sdks/javascript && npx vitest run

# Python
cd sdks/python && PYTHONPATH=. pytest tests/ -v

# C#
cd sdks/csharp && dotnet test

Code Style

• Rust: cargo fmt + cargo clippy
• TypeScript: npm run lint (ESLint + Prettier)
• Python: black + ruff
• C#: dotnet format
• Java: Google Java Format

Pull Request Process

1. Fork the repo
2. Create feature branch: git checkout -b feat/my-feature
3. Make changes with tests
4. Run all tests: bash test_all.sh
5. Commit: git commit -m "feat: my feature"
6. Push and open PR

Commit Convention

feat: new feature
fix: bug fix
docs: documentation changes
refactor: code restructuring
test: adding tests
chore: maintenance

Example: feat(python): add async context manager support

Adding a New SDK

1. Create sdks/<language>/ directory
2. Implement AgentBrowser class with same API
3. Add tests in sdks/<language>/tests/
4. Add to test_all.sh
5. Update documentation

Releasing

# Bump version
bash scripts/bump-version.sh 0.9.6

# Commit and tag
git add -A && git commit -m "release: v0.9.6"
git tag v0.9.6
git push && git push --tags

# GitHub Actions builds and publishes automatically

Reporting Issues

Use GitHub Issues with:

• OS and version
• b4n1web version
• Full error message
• Minimal reproduction

Security

Report security issues privately via email to security@b4n1.com

Code of Conduct

Be respectful. No harassment, discrimination, or spam.

Changelog

All notable changes to B4n1Web.

[Unreleased]

Added

• Full mdBook documentation site
• Windows ARM64 support
• Linux ARM64 support (Raspberry Pi, ARM servers)
• macOS Intel (x64) support
• Chromium auto-download for all 6 platforms
• MCP server with 33 tools

Changed

• Release pipeline builds 6 platforms
• Bundled binaries in all 4 SDKs

[0.9.5] - 2024-06-27

Added

• Java SDK (Maven Central)
• C# SDK (NuGet)
• Python SDK (PyPI)
• JavaScript/TypeScript SDK (npm)
• Binary bundling in all SDKs
• Browser modes: Light, JS, Render
• MCP server with 33 tools
• CLI with goto, screenshot, click, type, wait, evaluate
• Daemon mode for persistent MCP

Fixed

• Chromium auto-download for Linux ARM64
• Version compatibility checks
• Binary path resolution

[0.9.0] - 2024-01-15

Added

• Initial Rust binary
• Light mode (HTTP + HTML parsing)
• JS mode (JavaScript extraction)
• Python SDK
• JavaScript SDK

Changed

• Single binary architecture
• Cross-platform compilation

Version Format

B4n1Web uses Semantic Versioning:

• Major (X.0.0): Breaking changes
• Minor (0.X.0): New features, backward compatible
• Patch (0.0.X): Bug fixes, backward compatible

Current: 0.9.5 (pre-1.0, API may change)

Release Schedule

• Patch releases: As needed for bug fixes
• Minor releases: Monthly (new features)
• Major releases: When stable API reached (1.0)

Supported Versions

Upgrade Guide

0.9.x → 0.9.x (Patch)

Safe upgrade. Just reinstall:

pip install --upgrade b4n1-web
npm install b4n1-web@latest

Future: 0.x → 1.0 (Major)

Will include breaking changes. Migration guide will be provided.

Deprecation Policy

• Features marked deprecated in minor release
• Removed in next major release
• Minimum 6 months notice