How to use Lightpanda in 2026

Chrome headless is draining your server resources and killing your automation performance. If you've been running scraping operations at scale, you already know the pain: memory bloat, slow startup times, and infrastructure costs that spiral out of control.

Lightpanda is the AI-native headless browser that changes everything. Built from scratch in Zig for machines—not retrofitted from desktop browsers—it delivers 11x faster execution and uses 9x less memory than Chrome.

In this updated 2026 guide, you'll learn how to install, configure, and deploy Lightpanda for production-ready web automation. We'll cover hidden tricks, advanced proxy configurations, MCP integration for AI agents, and scaling strategies that most tutorials skip.

What is Lightpanda?

Lightpanda is an open-source headless browser purpose-built for automation and AI workloads. Unlike Chrome headless—which is essentially a full desktop browser with the display turned off—Lightpanda skips graphical rendering entirely.

The result? A browser that builds only what automation actually needs: the DOM tree and JavaScript execution environment.

Here's how Lightpanda compares to Chrome headless on AWS EC2 m5.large instances:

These numbers translate directly to infrastructure savings. Running 1,000 Chrome instances for data extraction costs roughly $6,000/month on AWS. The same workload on Lightpanda? Around $600/month.

Step 1: Install Lightpanda on Your System

Lightpanda provides nightly builds for Linux (x86_64) and macOS (Apple Silicon). Choose your platform and follow these commands.

Linux Installation

Download the binary and make it executable:

curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux
chmod a+x ./lightpanda

The first command downloads the latest nightly build from GitHub. The second makes it executable so you can run it directly.

Verify the installation:

./lightpanda -h

You should see the help output showing available commands and options.

macOS Installation (Apple Silicon)

Apple Silicon users get a native ARM64 build:

curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos
chmod a+x ./lightpanda
./lightpanda -h

Important: There's currently no Intel Mac build. If you're on an Intel Mac, you'll need to use Docker or build from source.

Windows Installation (via WSL2)

Windows users must run Lightpanda inside WSL2. First, ensure WSL2 is installed, then follow the Linux instructions from within your WSL terminal.

Pro tip: Install Puppeteer on the Windows host (not inside WSL) for better performance when connecting to Lightpanda's CDP server.

Global Installation

Want to run Lightpanda from anywhere? Move it to your PATH:

sudo mv ./lightpanda /usr/local/bin/

Now you can call lightpanda from any directory.

Step 2: Configure the CDP Server

Lightpanda includes a built-in Chrome DevTools Protocol (CDP) server. This is what lets you control it with Puppeteer, Playwright, or any CDP-compatible tool.

Starting the CDP Server

Launch the server with default settings:

./lightpanda serve --host 127.0.0.1 --port 9222

You'll see output confirming the server is listening:

info(websocket): starting blocking worker to listen on 127.0.0.1:9222
info(server): accepting new conn...

Keep this terminal open. Your automation scripts will connect to this endpoint.

CDP Server Options

Customize the server behavior with these flags:

./lightpanda serve --host 0.0.0.0 --port 8080 --timeout 60

Here's what each option does:

• --host: The IP address to bind (use 0.0.0.0 for external access)
• --port: The port number (default: 9222)
• --timeout: Connection timeout in seconds (default: 10)

Security Warning: Never expose --host 0.0.0.0 on production servers without proper firewall rules or authentication.

Quick Test with Fetch Mode

Before setting up automation, test that Lightpanda works with a simple fetch:

./lightpanda fetch --dump https://example.com

This command fetches the page, executes JavaScript, and dumps the rendered HTML to stdout. Think of it as cURL with JavaScript support.

Step 3: Connect Puppeteer or Playwright

The magic of Lightpanda is CDP compatibility. Your existing Puppeteer scripts need only one change: replace puppeteer.launch() with puppeteer.connect().

Basic Puppeteer Connection

First, install puppeteer-core (not full puppeteer—you don't need Chrome):

npm install puppeteer-core

Connect to Lightpanda:

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9222',
});

const context = await browser.createBrowserContext();
const page = await context.newPage();

await page.goto('https://example.com');
console.log(await page.title());

// Always clean up
await page.close();
await context.close();
await browser.disconnect();

The key difference: connect() instead of launch(), and disconnect() instead of close(). Lightpanda manages its own process—you're just connecting to it.

Advanced Scraping Example

Here's a real-world example that extracts product data:

import puppeteer from 'puppeteer-core';

async function scrapeProducts(url) {
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'ws://127.0.0.1:9222',
  });

  try {
    const page = await browser.newPage();
    await page.goto(url, { waitUntil: 'networkidle0' });

    const products = await page.evaluate(() => {
      return Array.from(document.querySelectorAll('.product-card')).map(card => ({
        title: card.querySelector('.title')?.textContent?.trim(),
        price: card.querySelector('.price')?.textContent?.trim(),
        link: card.querySelector('a')?.href,
      }));
    });

    return products;
  } finally {
    await browser.disconnect();
  }
}

The try/finally block ensures cleanup even if scraping fails. This pattern prevents memory leaks in long-running automation.

Playwright Connection

Playwright also works, though with some caveats:

import { chromium } from 'playwright-core';

const browser = await chromium.connectOverCDP('ws://127.0.0.1:9222');
const context = await browser.newContext();
const page = await context.newPage();

await page.goto('https://example.com');
console.log(await page.title());

await page.close();
await context.close();
await browser.close();

Playwright Stability Note: Playwright's behavior can change between Lightpanda versions. The framework uses an intermediate JavaScript layer that selects execution strategies based on available browser features. When Lightpanda adds new Web APIs, Playwright might choose different code paths that use unimplemented features.

For maximum stability in production, stick with Puppeteer.

Step 4: Set Up Proxy Support

Running automation at scale requires proxies. Without them, you'll hit rate limits and IP bans within minutes.

Lightpanda supports HTTP/HTTPS proxies with basic and bearer authentication.

CLI Proxy Configuration

Configure a proxy when starting the CDP server:

./lightpanda serve --http_proxy http://proxy.example.com:8080

All requests through this server instance will route through the proxy.

Authenticated Proxy (Basic Auth)

Use the username:password format for basic authentication:

./lightpanda serve --http_proxy 'http://user:password@proxy.example.com:8080'

Bearer Token Authentication

Some proxy providers use bearer tokens instead of basic auth:

./lightpanda serve --http_proxy 'http://proxy.example.com:8080' --proxy_bearer_token 'YOUR_TOKEN'

This adds a Proxy-Authorization header to all outgoing requests.

Proxy Rotation Strategy

Lightpanda doesn't have built-in proxy rotation yet (it's on the roadmap). For now, implement rotation at the application level.

Here's a pattern that works well:

import puppeteer from 'puppeteer-core';

const proxies = [
  'http://user:pass@proxy1.example.com:8080',
  'http://user:pass@proxy2.example.com:8080',
  'http://user:pass@proxy3.example.com:8080',
];

async function getRandomProxy() {
  return proxies[Math.floor(Math.random() * proxies.length)];
}

// Start multiple Lightpanda instances with different proxies
async function createProxiedInstance(proxy) {
  // In production, spawn separate Lightpanda processes
  // each configured with a different proxy
  const port = 9222 + Math.floor(Math.random() * 1000);
  
  // Spawn: ./lightpanda serve --port ${port} --http_proxy ${proxy}
  
  return puppeteer.connect({
    browserWSEndpoint: `ws://127.0.0.1:${port}`,
  });
}

For serious scraping operations, consider a residential proxy provider like Roundproxies.com. Residential proxies use real IP addresses assigned to households, making them much harder to detect than datacenter proxies.

Step 5: Use the Official npm Package

The @lightpanda/browser npm package simplifies Lightpanda management in Node.js projects. It handles binary downloads and process lifecycle automatically.

Installation

npm install @lightpanda/browser puppeteer-core

The package downloads the correct binary for your platform during installation.

Basic Usage

const { lightpanda } = require('@lightpanda/browser');
const puppeteer = require('puppeteer-core');

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

(async () => {
  // Start Lightpanda in a separate process
  const proc = await lightpanda.serve(lpdopts);

  // Connect Puppeteer
  const browser = await puppeteer.connect({
    browserWSEndpoint: `ws://${lpdopts.host}:${lpdopts.port}`,
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());

  // Cleanup
  await browser.disconnect();
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

The lightpanda.serve() function returns a child process handle. You're responsible for killing it when done.

Fetch Mode with npm Package

For simple HTML extraction without full browser automation:

import { lightpanda } from '@lightpanda/browser';

const options = {
  dump: true,
  httpProxy: 'http://proxy.example.com:8080',
};

const html = await lightpanda.fetch('https://example.com', options);
console.log(html);

This is faster than full CDP automation when you just need rendered HTML.

Custom Binary Path

If you've installed Lightpanda manually or want to use a specific version:

export LIGHTPANDA_EXECUTABLE_PATH=/path/to/your/lightpanda

The npm package checks this environment variable before using its bundled binary.

Step 6: Deploy with Docker

Docker is the cleanest way to deploy Lightpanda in production. Official images are available for both AMD64 and ARM64 architectures.

Quick Start

Pull and run the official image:

docker run -d --name lightpanda -p 9222:9222 lightpanda/browser:nightly

This starts Lightpanda with the CDP server exposed on port 9222.

Docker Compose for Production

Create a docker-compose.yml for more complex deployments:

version: '3.8'

services:
  lightpanda:
    image: lightpanda/browser:nightly
    container_name: lightpanda
    ports:
      - "9222:9222"
    environment:
      - LIGHTPANDA_DISABLE_TELEMETRY=true
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 128M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9222"]
      interval: 30s
      timeout: 10s
      retries: 3

Notice the memory limits. Lightpanda's low memory footprint means you can set tight constraints—something impossible with Chrome containers that need 2GB+ each.

Multiple Instances

Scale horizontally by running multiple containers:

version: '3.8'

services:
  lightpanda-1:
    image: lightpanda/browser:nightly
    ports:
      - "9222:9222"
    environment:
      - LIGHTPANDA_DISABLE_TELEMETRY=true

  lightpanda-2:
    image: lightpanda/browser:nightly
    ports:
      - "9223:9222"
    environment:
      - LIGHTPANDA_DISABLE_TELEMETRY=true

  lightpanda-3:
    image: lightpanda/browser:nightly
    ports:
      - "9224:9222"
    environment:
      - LIGHTPANDA_DISABLE_TELEMETRY=true

Each container gets its own port. Your load balancer distributes scraping tasks across them.

Disabling Telemetry

Lightpanda collects usage telemetry by default. Disable it in production:

docker run -d \
  -e LIGHTPANDA_DISABLE_TELEMETRY=true \
  -p 9222:9222 \
  lightpanda/browser:nightly

Step 7: Integrate with MCP for AI Agents

Model Context Protocol (MCP) is becoming the standard for AI agent tool integration. Lightpanda has an official MCP server that lets AI agents control browser automation.

What is MCP?

MCP is a protocol designed for communication between AI applications and external services. With Lightpanda's MCP server, AI agents can navigate websites, extract data, fill forms, and more—all through natural language commands.

Installing the Go MCP Server

Lightpanda provides a Go-based MCP server called gomcp:

git clone https://github.com/lightpanda-io/gomcp
cd gomcp
go build

On first run, download the Lightpanda binary:

./gomcp download

The binary is stored in ~/.config/lightpanda-gomcp (Linux) or ~/Library/Application Support/lightpanda-gomcp (macOS).

Configuring with Claude Desktop

Add this to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "lightpanda": {
      "command": "/path/to/gomcp",
      "args": ["stdio"]
    }
  }
}

Now Claude can use Lightpanda for web automation tasks.

Running as SSE Server

For non-Claude integrations, run gomcp as an SSE server:

./gomcp sse

The server listens on 127.0.0.1:8081 by default.

Connecting to Remote Lightpanda

Point gomcp at an existing Lightpanda instance:

./gomcp --cdp ws://remote-server:9222

This is useful when Lightpanda runs in Docker or on a different machine.

Step 8: Scale for Production

Scaling Lightpanda requires different strategies than scaling Chrome. The low resource footprint changes the economics completely.

Concurrent Browser Contexts

Instead of launching new browser instances, create isolated contexts:

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9222',
});

// Create multiple isolated contexts
const contexts = await Promise.all([
  browser.createBrowserContext(),
  browser.createBrowserContext(),
  browser.createBrowserContext(),
]);

// Process pages in parallel
const results = await Promise.all(
  contexts.map(async (context, index) => {
    const page = await context.newPage();
    await page.goto(`https://example.com/page${index}`);
    const title = await page.title();
    await page.close();
    await context.close();
    return title;
  })
);

Each context is isolated—separate cookies, storage, and cache. But they share the same browser process, so overhead is minimal.

Performance Monitoring

Track metrics to identify bottlenecks:

async function measurePerformance(url) {
  const startTime = Date.now();
  
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'ws://127.0.0.1:9222',
  });

  const page = await browser.newPage();
  await page.goto(url);

  const metrics = {
    loadTime: Date.now() - startTime,
    memory: process.memoryUsage(),
  };

  console.log(`Page loaded in ${metrics.loadTime}ms`);
  console.log(`Memory: ${Math.round(metrics.memory.rss / 1024 / 1024)}MB`);

  await browser.disconnect();
  return metrics;
}

Kubernetes Deployment

For serious scale, deploy on Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: lightpanda
spec:
  replicas: 10
  selector:
    matchLabels:
      app: lightpanda
  template:
    metadata:
      labels:
        app: lightpanda
    spec:
      containers:
      - name: lightpanda
        image: lightpanda/browser:nightly
        ports:
        - containerPort: 9222
        resources:
          limits:
            memory: "256Mi"
            cpu: "500m"
          requests:
            memory: "128Mi"
            cpu: "250m"
        env:
        - name: LIGHTPANDA_DISABLE_TELEMETRY
          value: "true"
---
apiVersion: v1
kind: Service
metadata:
  name: lightpanda-service
spec:
  selector:
    app: lightpanda
  ports:
  - port: 9222
    targetPort: 9222
  type: ClusterIP

Ten replicas with 256MB each equals just 2.5GB total. The same workload on Chrome would need 20GB+.

Lightpanda Cloud

For managed infrastructure, use Lightpanda Cloud:

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://cloud.lightpanda.io/ws?token=YOUR_TOKEN',
});

Cloud features include:

• Built-in proxy support with datacenter options
• Geographic targeting via country codes
• Auto-scaling based on demand
• Chrome fallback for compatibility

Example with proxy options:

wss://cloud.lightpanda.io/ws?proxy=datacenter&country=de&token=YOUR_TOKEN

Hidden Tricks and Performance Hacks

These tips come from production experience—the stuff that doesn't make it into official documentation.

Trick 1: Instant Page Cleanup

Don't wait for garbage collection. Force cleanup immediately:

async function scrapeWithCleanup(url) {
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'ws://127.0.0.1:9222',
  });

  let page, context;
  
  try {
    context = await browser.createBrowserContext();
    page = await context.newPage();
    await page.goto(url);
    return await page.content();
  } finally {
    // Explicit cleanup in reverse order
    if (page) await page.close().catch(() => {});
    if (context) await context.close().catch(() => {});
    await browser.disconnect();
  }
}

The .catch(() => {}) prevents errors if cleanup already happened.

Trick 2: Network Interception for Speed

Skip unnecessary resources:

const page = await context.newPage();

await page.setRequestInterception(true);
page.on('request', (request) => {
  const resourceType = request.resourceType();
  
  // Block heavy resources Lightpanda won't render anyway
  if (['image', 'stylesheet', 'font', 'media'].includes(resourceType)) {
    request.abort();
  } else {
    request.continue();
  }
});

await page.goto(url);

This reduces bandwidth and speeds up page loads significantly.

Trick 3: Custom Timeouts per Page

Global timeouts don't fit all pages. Set them dynamically:

async function smartNavigate(page, url, options = {}) {
  const timeout = options.timeout || 30000;
  const waitUntil = options.waitUntil || 'domcontentloaded';

  try {
    await page.goto(url, { timeout, waitUntil });
  } catch (error) {
    if (error.name === 'TimeoutError') {
      // Try with just domcontentloaded
      await page.goto(url, { 
        timeout: timeout / 2, 
        waitUntil: 'domcontentloaded' 
      });
    } else {
      throw error;
    }
  }
}

Trick 4: Health Check Endpoint

Monitor Lightpanda instances:

import http from 'http';
import puppeteer from 'puppeteer-core';

async function checkHealth() {
  try {
    const browser = await puppeteer.connect({
      browserWSEndpoint: 'ws://127.0.0.1:9222',
    });
    await browser.disconnect();
    return true;
  } catch {
    return false;
  }
}

http.createServer(async (req, res) => {
  if (req.url === '/health') {
    const healthy = await checkHealth();
    res.statusCode = healthy ? 200 : 503;
    res.end(healthy ? 'OK' : 'Unhealthy');
  }
}).listen(8080);

Trick 5: Session Reuse Pattern

Reuse browser contexts for related pages:

class SessionManager {
  constructor(browserEndpoint) {
    this.endpoint = browserEndpoint;
    this.browser = null;
    this.contexts = new Map();
  }

  async init() {
    this.browser = await puppeteer.connect({
      browserWSEndpoint: this.endpoint,
    });
  }

  async getContext(sessionId) {
    if (!this.contexts.has(sessionId)) {
      const context = await this.browser.createBrowserContext();
      this.contexts.set(sessionId, context);
    }
    return this.contexts.get(sessionId);
  }

  async closeSession(sessionId) {
    const context = this.contexts.get(sessionId);
    if (context) {
      await context.close();
      this.contexts.delete(sessionId);
    }
  }
}

Troubleshooting Common Issues

Connection Refused

If Puppeteer can't connect:

Error: connect ECONNREFUSED 127.0.0.1:9222

Check that Lightpanda is actually running:

# Check if the process is running
ps aux | grep lightpanda

# Check if port is in use
lsof -i :9222

If something else is using port 9222:

# Use a different port
./lightpanda serve --port 9223

# Or kill existing processes
lsof -ti:9222 | xargs kill -9

Website Crashes or Fails to Load

Lightpanda is still in beta. Not every website works perfectly.

Start with simple sites. Complex React/Vue/Angular SPAs may have issues.

Check the demo pages at Lightpanda's test suite to see what's working.

Report issues on GitHub with full reproduction steps. The team is actively improving compatibility.

Permission Denied

If you get permission errors:

chmod +x ./lightpanda

If still failing, check if the binary downloaded correctly:

file ./lightpanda
# Should show: ELF 64-bit LSB executable (Linux)
# or: Mach-O 64-bit executable arm64 (macOS)

Playwright Breaks After Update

Playwright scripts can break when Lightpanda adds new Web APIs. The framework detects capabilities and changes execution paths.

Solution: Pin your Playwright version and test thoroughly after any Lightpanda update.

{
  "dependencies": {
    "playwright-core": "1.40.0"
  }
}

Intel Mac: No Binary Available

There's no Intel Mac (x86_64) build currently. Your options:

1. Use Docker (recommended)
2. Build from source (requires Zig 0.15.2)
3. Use Lightpanda Cloud

What's Coming in 2026

Lightpanda raised pre-seed funding in mid-2025 to expand browser coverage and ship AI-specific features. Here's what's on the roadmap:

Expanded Web API Coverage

Hundreds of Web APIs still need implementation. The team is prioritizing APIs most used in automation:

• Canvas (partial)
• WebSocket improvements
• More DOM manipulation methods
• Better form handling

Native Proxy Rotation

Per-page proxy rotation is planned, eliminating the need for application-level rotation:

// Future API (not yet available)
await page.goto(url, { proxy: 'http://next-proxy.example.com:8080' });

LLM-Friendly Output Formats

Direct output formatting for AI consumption:

• Structured JSON extraction
• Markdown conversion
• Schema-based data extraction

Enhanced MCP Integration

Deeper MCP server capabilities:

• More browser control tools
• Better error reporting
• Streaming results

Windows Native Support

Native Windows binaries (without WSL) are in development.

Final Thoughts

Lightpanda represents a fundamental shift in how we think about headless browsers. By building for machines from the ground up, it achieves performance numbers that retrofitted desktop browsers can't match.

Key takeaways:

• 11x faster execution, 9x less memory than Chrome
• Direct CDP compatibility with Puppeteer and Playwright
• Official Docker images and npm package for easy deployment
• MCP integration for AI agent workflows
• Active development with regular improvements

Yes, it's still in beta. Some websites won't work perfectly. But for compatible use cases, the performance gains are impossible to ignore.

The infrastructure cost savings alone make Lightpanda worth testing. When you can run 10x more concurrent scrapers on the same hardware, the math becomes obvious.

Next steps:

1. Install Lightpanda and run the basic fetch test
2. Migrate one existing Puppeteer script
3. Measure the performance difference
4. Scale from there

The future of web automation is lighter, faster, and purpose-built. Welcome to the new paradigm.