moli-cdp-server

---
name: moli-cdp-server
description: Start Moli's CDP server and connect Playwright, Puppeteer, or raw CDP clients. Use to run a headless-browser CDP endpoint, replace a Chromium process, attach over CDP, enable real layout and screenshot surfaces, or diagnose CDP discovery, connection, and target startup—even when Moli is not named.
---

# Run Moli's CDP Server

Run one Moli CDP server and connect the requested CDP client to its endpoint.
Preserve the client's existing API where Moli supports it.

## Workflow

1. Resolve `moli` from `PATH`. If it is unavailable, install the latest prebuilt
   release for the current platform:

   Linux or macOS:

   ```bash
   curl --proto '=https' --tlsv1.2 -fsSL \
     https://github.com/lexmount/moli/releases/latest/download/moli-installer.sh | sh
   ```

   On Windows, use PowerShell:

   ```powershell
   powershell -ExecutionPolicy ByPass -c "irm https://github.com/lexmount/moli/releases/latest/download/moli-installer.ps1 | iex"
   ```

   Resolve the installed binary again and run `moli --version`. The default
   location is `~/.local/bin/moli` on Linux/macOS and
   `%LOCALAPPDATA%\Moli\bin\moli.exe` on Windows when it is not yet on `PATH`.
2. Start `moli serve` on the default loopback endpoint
   `http://127.0.0.1:9222`.
3. Add `--layout` when the workflow needs real element geometry, coordinate
   input, screenshots, PDFs, or screencasts. Add `--resource` only when all
   optional visual/media resources are required.
4. Probe `/json/version` before connecting the client.
5. Connect with the client's remote/attach API; do not launch a second bundled
   browser.
6. Close CDP clients cleanly, then stop the Moli server if this workflow
   owns it.

## Playwright over CDP

```js
import { chromium } from "playwright";

const browser = await chromium.connectOverCDP("http://127.0.0.1:9222");
const context = browser.contexts()[0];
const page = context.pages()[0] ?? await context.newPage();

await page.goto("https://example.com");
console.log(await page.locator("body").innerText());

await browser.close();
```

## Integration rules

- Bind to `127.0.0.1` by default. Expose another host only when the user
  explicitly needs remote access and has addressed network access controls.
- Treat Moli as a remote endpoint. Avoid Chrome launch flags and assumptions
  that require a local Chromium executable.
- Expect selected CDP coverage, not complete Chrome protocol parity. Preserve
  explicit unsupported errors.
- Use a unique port for parallel isolated runs.
- Persist state intentionally with `--profile-dir`; otherwise keep runs
  disposable.
- Pass proxy, cookie, resource, user-agent, and private-network policy to the
  Moli server, not to a nonexistent child browser process.

Read [references/protocols.md](references/protocols.md) for CDP discovery
URLs, server options, client selection, and connection troubleshooting.