Use a proxy

Local

Use a proxy locally

To use a proxy, start Lightpanda from the command line with --http-proxy followed by an HTTP or HTTPS proxy address. All outgoing requests go through the proxy, regardless of the protocol your client uses to connect to Lightpanda.

The examples below use serve, but fetch, mcp, and agent accept these options too.

lightpanda serve --http-proxy http://127.0.0.1:3000

Authenticate with basic auth

Add basic auth  credentials to the proxy address with the username:password@ format.

lightpanda serve --http-proxy 'http://me:my-password@127.0.0.1:3000'

Authenticate with a bearer token

--proxy-bearer-token authenticates with bearer auth . It adds a Proxy-Authorization header to all outgoing requests.

lightpanda serve --http-proxy 'http://127.0.0.1:3000' --proxy-bearer-token 'MY-TOKEN'

Authenticate from your script

You can also pass the proxy credentials from your Puppeteer or Playwright script instead of the command line.

Selenium can’t do this, because Lightpanda does not support proxy authentication over WebDriver BiDi. Put the credentials in the --http-proxy URL instead.

lightpanda serve --http-proxy 'http://127.0.0.1:3000'

const page = await context.newPage();
 
// Set credentials for HTTP Basic Auth
await page.authenticate({
  username: 'my_username',
  password: 'my_password',
});

const context = await browser.newContext({
    baseURL: baseURL,
    proxy: {
      server: 'http://127.0.0.1:3000',
      username: 'my_username',
      password: 'my_password',
    },
});
 
const page = await context.newPage();

Cloud

Use a proxy on Lightpanda Cloud

Add the proxy query parameter to the connection URL to route the session through a proxy. You have two options: use a shared proxy, or add your own.

Use a shared proxy

Every account can use two shared proxies.

• fast_dc: the default. A single shared datacenter IP, optimized for speed. Each region has its own, so the IP depends on the endpoint you connect to.
• datacenter: a pool of shared datacenter IPs with automatic rotation. Accepts an optional country parameter (two-letter country code) to target a specific country.

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

Omit proxy and the session uses fast_dc. Contact us for additional proxy options.

Use your own proxy

Add your proxy on the proxies page  in the console, then pass its identifier as the proxy parameter. The console generates the identifier and shows it on the proxy’s card. It is not the name you gave the proxy.

wss://euwest.cloud.lightpanda.io/ws?proxy=xK4mP2qR&token=TOKEN

The kind you set on the proxy, datacenter or residential, is a label. It does not change how the session connects.