Larapanda: A Type-Safe Lightpanda Browser SDK for Laravel

Larapanda is a Laravel SDK for Lightpanda, a headless browser written in Zig. The package handles runtime resolution between CLI binary and Docker, profile-based instance management, typed fetch results, and optional adapters for the Laravel AI SDK and MCP server.

#Profile-Based Instance Management

Configuration is organized into named instance profiles. Each profile can override the global defaults for runtime mode, binary path, and Docker settings — making it straightforward to maintain separate profiles for general fetching, crawling, and AI tool sessions.

// config/larapanda.php
'instances' => [
    'default' => [],
    'crawler' => [
        'runtime' => 'cli',
        'binary_path' => '/absolute/path/to/lightpanda',
    ],
    'mcp' => [
        'runtime' => 'docker',
    ],
],

Selecting a profile at call time uses the manager interface:

use Ferdiunal\Larapanda\Contracts\LarapandaManagerInterface;

$manager = app(LarapandaManagerInterface::class);

$defaultClient = $manager->instance('default');
$crawlerClient = $manager->instance('crawler');

#Runtime Resolution

The auto runtime prefers CLI execution when a valid binary_path is configured and the binary is executable, and falls back to Docker otherwise. You can also pin a profile to cli or docker explicitly.

#Typed Fetch Results

fetchRequest() returns a FetchResult with strict accessors tied to the selected dump format. Calling a mismatched accessor throws UnexpectedFetchOutputFormatException rather than silently returning garbage data.

use Ferdiunal\Larapanda\Enums\FetchDumpFormat;

$result = $client->fetchRequest('https://example.com')
    ->withOptions(
        dump: FetchDumpFormat::Markdown,
        obeyRobots: true,
        waitMs: 2000,
    )
    ->run();

$markdown = $result->asMarkdown();

// Semantic tree formats
$treeResult = $client->fetchRequest('https://example.com')
    ->withOptions(dump: FetchDumpFormat::SemanticTree)
    ->run();

$tree = $treeResult->asSemanticTree(); // array<string, mixed>

Proxy support is available per-request:

$result = $client->fetchRequest('https://example.com')
    ->withOptions(
        dump: FetchDumpFormat::Markdown,
        httpProxy: 'http://127.0.0.1:3000',
        proxyBearerToken: 'MY-TOKEN',
    )
    ->run();

#Laravel AI SDK Integration

Larapanda exposes Lightpanda as tools for the Laravel AI SDK. The adapter is session-aware — passing the same session_id across tool calls keeps the browser session open between steps, which matters for multi-step browsing tasks.

composer require laravel/ai laravel/mcp

use Ferdiunal\Larapanda\Integrations\Ai\LarapandaAiTools;
use Illuminate\Support\Facades\AI;

$response = AI::provider('openai')
    ->model('gpt-5-mini')
    ->prompt('Open laravel.com and return the main headings.')
    ->tools(app(LarapandaAiTools::class)->make())
    ->text();

Tool names use the configured prefix (default lightpanda_): lightpanda_markdown, lightpanda_semantic_tree, lightpanda_click, and so on. You can restrict which tools the model sees via config:

'integrations' => [
    'ai' => [
        'exposed_tools' => ['goto', 'markdown', 'semantic_tree'],
    ],
],

#MCP Server Adapter

For applications using the Laravel MCP server, Larapanda provides an adapter that registers Lightpanda tools with Laravel's container, applies profile-based runtime resolution, and shares the session pool and proxy policy with the AI SDK adapter.

// routes/ai.php
use Ferdiunal\Larapanda\Integrations\Mcp\LarapandaMcpServer;

LarapandaMcpServer::registerLocal(name: 'lightpanda');

Session lifetime and pool size are controlled from config:

'integrations' => [
    'mcp' => [
        'session_ttl_seconds' => 300,
        'max_sessions' => 32,
        'obey_robots' => true,
    ],
],

You can find the source and full documentation on GitHub.