---
title: "Deploy lightpanda"
description: "Lightpanda 0.4: fast headless browser for agents over CDP, token-gated."
category: "AI/ML"
url: https://railway.com/deploy/lightpanda-1
---

# Deploy lightpanda

Lightpanda 0.4: fast headless browser for agents over CDP, token-gated.

**[Deploy lightpanda on Railway](https://railway.com/template/lightpanda-1)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/lightpanda-1/manifest.json

- **Creator:** Agaz Self-Host
- **Category:** AI/ML

## Template content

### lightpanda https://cdn.lightpanda.io/assets/images/logo/lpd-logo.png

- **Image:** lightpanda/browser:0.4.1
- **Start command:** `/usr/bin/tini -- /bin/lightpanda serve --host :: --port 9222 --log_level info`

### gateway https://raw.githubusercontent.com/caddyserver/website/5c921006aae4feb2184782ae528c2bb09a07e04f/src/resources/images/favicon.png

- **Image:** caddy:2.11.4-alpine
- **Start command:** `sh -c 'printf "%s\n" "$CADDYFILE" > /tmp/Caddyfile && exec caddy run --config /tmp/Caddyfile --adapter caddyfile'`
- **Health check:** /gateway_health
- **Public domain:** Yes

## Documentation

# Deploy and Host Lightpanda on Railway

Lightpanda is a headless browser written from scratch in Zig for AI agents, scraping and automation. It runs JavaScript and exposes the Chrome DevTools Protocol, so Puppeteer, Playwright and chromedp connect to it like Chrome, while starting instantly and using a fraction of Chrome's memory.

## About Hosting Lightpanda

This template runs two services. `lightpanda` runs the official `lightpanda/browser:0.4.1` image as a CDP server on the private network only. `gateway` is a small Caddy proxy on the public domain that checks a generated token, sent as `?token=` or a `Bearer` header, before passing WebSocket and HTTP traffic through; requests without it get 401. Connect Puppeteer or Playwright to `LIGHTPANDA_WS_URL`. Telemetry is off. The browser keeps no state between sessions, so there is no volume, and both services fit the Hobby plan. Lightpanda does not implement every web API yet, so test your target sites before relying on it.

## Common Use Cases

- A fast headless browser for AI agents and MCP tools
- Scraping JavaScript-heavy pages at lower memory cost than Chrome
- Running Puppeteer or Playwright scripts against a remote browser

## Dependencies for Lightpanda Hosting

- `lightpanda/browser:0.4.1` (official image)
- `caddy:2.11.4-alpine` as the token gateway

### Deployment Dependencies

- [Lightpanda on GitHub](https://github.com/lightpanda-io/browser)
- [Lightpanda 0.4.1 release](https://github.com/lightpanda-io/browser/releases/tag/0.4.1)
- [Puppeteer connect()](https://pptr.dev/api/puppeteer.puppeteer.connect)

### Implementation Details

| Service | Source | Networking | Storage |
| --- | --- | --- | --- |
| lightpanda | `lightpanda/browser:0.4.1` | private only, CDP on 9222 | none |
| gateway | `caddy:2.11.4-alpine` | public domain on 8080 | none |

```js
const browser = await puppeteer.connect({ browserWSEndpoint: process.env.LIGHTPANDA_WS_URL });
const page = await browser.newPage();
await page.goto('https://news.ycombinator.com/');
```

| Variable (gateway) | Default | Purpose |
| --- | --- | --- |
| `LIGHTPANDA_TOKEN` | generated | Required as `?token=` or `Authorization: Bearer` |
| `LIGHTPANDA_WS_URL` | `wss:///?token=...` | Endpoint for CDP clients |
| `CADDYFILE` | gateway config | The Caddy configuration |

Notes:

- The gateway rewrites the Host header because Lightpanda only accepts local WebSocket hosts.
- Keep the service names; the gateway reaches the browser at `lightpanda.railway.internal`.

This is a community-maintained deployment package and does not imply affiliation with or endorsement by Lightpanda.

## Why Deploy Lightpanda on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Lightpanda on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/lightpanda-1