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.13.0</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://raw.githubusercontent.com/B4N1-com/b4n1-web/master/scripts/install.sh | 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.13.0

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.13.0</version>
</dependency>

Gradle

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

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.13.0 requires binary v0.13.0, 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.13.0 requires binary v0.13.0, 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.13.0 requires binary v0.13.0, 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.13.0</version>
</dependency>

Gradle

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

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.13.0 requires binary v0.13.0, 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.13.0</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.13.0

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.13.0 requires binary v0.13.0, 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.13.0

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.13.0 requires binary v0.13.0, 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

CHANGELOG — b4n1-web

v0.13.0 — 2026-09-02

Security

• Binary hardening protocol: strip=true, lto=fat, codegen-units=1, panic=abort, overflow-checks=false, incremental=false en ambos Cargo.toml (engine + outer) — B4N1-BINARY-SECURITY.md §1.
• String obfuscation: obfstr para URLs sensibles (api.github.com, raw.githubusercontent, github.com/.../download) y product identifiers en engine/cli-core/src/main.rs — §3.
• Post-build verification: scripts/verify-binary-security.sh (strip, nm symbols ≤5, no raw URLs, size) + CI gate — §4/§5.

v0.12.3 — 2026-07-08

Fixed

• Python SDK screenshot parsing: _parse_output now correctly parses Screenshot: field from binary output.
• E2E test suite: Comprehensive test suite covering all 4 registries, all 3 modes, MCP server, error handling.

Added

• Comprehensive E2E tests: scripts/e2e-full-test.sh (15 tests) + scripts/pipeline-test.sh (28 tests).
• Pipeline integration test: Validates version consistency, file structure, binary matching, SDK test suites.

v0.12.2 — 2026-07-08

Added

• Musl static binary: Linux binary compiled with x86_64-unknown-linux-musl for zero-dependency deployment.
• All 4 SDKs updated: Python, JavaScript, C#, Java with bundled musl binary.

Changed

• All components bumped to v0.12.2.

v0.12.0 — 2026-07-03

Added

• Auto-update check on startup: b4n1web now checks for newer versions in background after every command. Non-blocking, fast, prints warning if upgrade available.
• Stratlogos vision spec: Distributed community training network registered in projects.

Removed

• Version mismatch warnings: Removed checkVersionCompatibility() from all 4 SDKs (Python, JS, C#, Java). Since the binary is bundled with the SDK, the warning only confused users.

Changed

• All components bumped to v0.12.0 (engine, 4 SDKs, docs).

v0.11.0 — 2026-07-01

Added

• Cross-platform builds: 8 binary targets (linux amd64/arm64/ia32, macOS x64/arm64, Windows amd64/arm64/ia32).
• 32-bit support: i686 Linux and Windows builds added to release matrix.

Changed

• All SDK native binaries updated to v0.11.0 builds.
• Version bumped across all 15 files (engine, SDKs, docs).

v0.10.0 — 2026-07-01

Fixed

• PDF generation: goto MCP handler now shares session ChromiumBrowser with pdf/screenshot instead of creating a separate ephemeral browser per call. PDFs are no longer blank (848 bytes → real content).
• Hardcoded version: MCP server now uses env!("CARGO_PKG_VERSION") at compile time instead of hardcoded "0.8.0".

Changed

• Version bump automation: bump-version.sh now updates 15 files (was 5). Covers all SDK runtime constants (__init__.py, browser.py, binary.ts, AgentBrowser.java), MANIFEST.md, and docs.
• BREAKING: All components now at v0.10.0 — unified version across Rust engine, Python SDK, JS SDK, C# SDK, Java SDK, MCP server, and docs.
• RELEASE_CHECKLIST.md: Rewritten with complete end-to-end pipeline.

v0.9.11 — 2026-07-01

Fixed

• npm SDK: Removed broken postinstall script (not included in package files → npm install crash). Handled chmod in binary.ts at runtime instead.
• npm SDK: Added import entry to package.json exports for ESM compatibility.
• verify-publish.sh: Fixed ESM import → CJS require() for npm test. Fixed Java List.size() (was .length).

Changed

• Published npm v0.9.9, v0.9.10, v0.9.11 with fixes (postinstall removal + ESM exports).
• All 4 SDKs (Python, npm, C#, Java) smoke-tested E2E.
• Removed stale ~/.npmrc global auth token to prevent accidental publishes.

v0.9.10 — 2026-07-01

Fixed

• Same as v0.9.9. Published to fix ESM exports in package.json.

v0.9.9 — 2026-07-01

Fixed

• Same as v0.9.11 (npm postinstall fix only). Superseded by v0.9.10.

v0.9.8 — 2026-07-01

Added

• Maven Central: b4n1-web Java SDK published to Maven Central (v0.9.8).
• verify-publish.sh: Smoke test script for all 4 SDK registries (pip, npm, NuGet, Maven).
• PIPELINE_GUIDE.md: Complete documentation of the multi-platform build + publish pipeline.

Fixed

• URL web.b4n1.com → b4n1.com: Updated across 29 files (SDK metadata, READMEs, docs, examples, tests, nginx).
• Maven Central credentials: Stale ~/.m2/settings.xml updated with correct Sonatype token.
• C# build artifacts: **/bin/ and **/obj/ removed from git tracking.

v0.9.7 — 2026-07-01

Fixed

• SDK version bump: Published PyPI b4n1-web==0.9.7, npm b4n1-web@0.9.7, NuGet B4n1Web 0.9.7.
• Maven Central: First publish attempt — stalled in PUBLISHING state, auto-published after delay.

v0.9.6 — 2026-06-30

Fixed

• Python SDK (security.py): Fragment handling in _extract_domain — strip #section before parsing.
• Java SDK (AgentBrowser.java): getVersion() returned "b4n1web 0.9.4" instead of "0.9.4" — parse version string correctly.
• C# SDK (AgentBrowser.cs): Same version parsing bug — strip "b4n1web " prefix from version output.

Added

• Rust engine: Full MCP server test suite (322 tests total) — 33 tools with schema validation.
• Python SDK: Comprehensive test suite (130 tests) covering browser, MCP, security, errors, MCP types.
• JavaScript SDK: Comprehensive test suite (50 tests) — vitest with page, types, errors, security, browser, binary.
• Java SDK: Comprehensive test suite (27 tests) — Page, BrowserMode, AgentBrowser, errors.
• C# SDK: Comprehensive test suite (16 tests) — Page, Models, AgentBrowser.
• E2E integration tests: Binary version, help flags, MCP tool listing verification.

Changed

• Updated all SDKs and engine to v0.9.5.

v0.9.3 — 2026-06-08

Refactored

• Core (Rust): Massive modularization of browser.rs, mcp.rs, and session.rs.
• SDKs (Python/JS): Extracted MCP types and separated Page/AgentBrowser classes.
• Portability: Removed all hardcoded absolute paths to /home/b4n1.

Fixed

• MCP Client (Python): Robust non-blocking stdio communication (fixes TypeError and timeout issues).
• Output Parser (JS): Improved line-by-line parsing for structured data and screenshots.

Added

• Unified Test Runner (test_all.sh) covering Core, Python, and JS.
• Support for Symbol.asyncDispose in JS SDK.

v0.7.0 — 2026-05-20

Added

• Full-page screenshot support in Chromium render mode (session.rs improvements)
• evaluate MCP tool for arbitrary JavaScript execution (render mode)
• Chromium compatibility hardening for SDL/libwayland environments
• Visual regression testing framework (visual.rs — compare/encode/decode)
• security and security_schema deferred to V3

Changed

• MCP stdio mode is now the default and primary mode (TCP route was dead-code, now fully removed from main.rs)
• MCP server strip-block bug eliminated
• MCP client cleaned (static list, no eval-in-Python vector)
• b4n1web → b4n1web everywhere in docs and code
• Docs: audience, accomplishment and index names updated (repo renamed to public b4n1-web)
• MCP tests (Python) tripled in focus; 38 tests now cover handshake + goto + links (all edge cases)

Fixed

• MCP stdio mode fix: run_mcp_server_stdio() replaces dead await in main entrypoint
• get_links handler in MCP server now returns live page links
• Visual diff test data schema: prod_data block with md5 / sha256 / size / mime
• Tempfile collision in Rust visual tests (write_test_png now uses atomic counter, not PID)
• MANIFEST.md: b4n1-mcp interface marked ✅activa (was stale ❌no)
• AGENTS.md: b4n1-web-private → b4n1-web, private GitHub URL removed

Security

• Critical: .env removed from git history (contained live API keys: PyPI, NuGet, Sonatype)
• .gitignore hardened: now 101 patterns (Rust target/, Python __pycache__, node_modules, C# obj/bin, Go pkg, IDE files, OS files, etc.)
• All C# internal test build artifacts removed from index (40 files with absolute /home/b4n1/ paths)

Release highlights

• b4n1web binary: 203 tests passing (Rust engine)
• Python MCP test suite: 38/38 passing
• All 5 SDKs (Rust/Python/JS/Java/C#) at v0.7.0