> ## Documentation Index
> Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect with Puppeteer

> Control Hyperbrowser sessions using Puppeteer

Puppeteer is a popular Node.js library for browser automation that integrates seamlessly with Hyperbrowser sessions. This guide shows you how to connect Puppeteer to your cloud browsers. Python has an unofficial library called [pyppeteer](https://github.com/pyppeteer/pyppeteer), however, it is unmaintained and is out of sync with the main Puppeteer library so we recommend using [playwright-python](https://github.com/microsoft/playwright-python) instead.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @hyperbrowser/sdk puppeteer-core dotenv
  ```

  ```bash yarn theme={null}
  yarn add @hyperbrowser/sdk puppeteer-core dotenv
  ```

  ```bash pip theme={null}
  pip install hyperbrowser pyppeteer python-dotenv
  ```

  ```bash uv theme={null}
  uv add hyperbrowser pyppeteer python-dotenv
  ```
</CodeGroup>

<Note>
  For Node.js, use `puppeteer-core` instead of `puppeteer` since Hyperbrowser provides the
  browser. This saves disk space and installation time.
</Note>

## Basic Connection

Connect Puppeteer to a Hyperbrowser session:

<CodeGroup>
  ```typescript Node.js theme={null}
  import { Hyperbrowser } from "@hyperbrowser/sdk";
  import { connect } from "puppeteer-core";
  import { config } from "dotenv";

  config();

  const client = new Hyperbrowser({
    apiKey: process.env.HYPERBROWSER_API_KEY,
  });

  async function main() {
    // Create session
    const session = await client.sessions.create();

    try {
      // Connect Puppeteer
      const browser = await connect({
        browserWSEndpoint: session.wsEndpoint,
        defaultViewport: null,
      });
      const defaultContext = browser.defaultBrowserContext();

      // Get or create a page
      const pages = await defaultContext.pages();
      const page = pages[0];

      // Navigate and interact
      await page.goto("https://example.com");
      console.log("Title:", await page.title());
    } catch (err) {
      console.error("Encountered error:", err);
    } finally {
      // Clean up
      await client.sessions.stop(session.id);
    }
  }

  main().catch(console.error);
  ```

  ```python Python theme={null}
  import asyncio
  import os
  from pyppeteer import connect
  from hyperbrowser import AsyncHyperbrowser
  from hyperbrowser.models import CreateSessionParams
  from dotenv import load_dotenv

  load_dotenv()

  client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


  async def main():
      # Create session
      session = await client.sessions.create(
          CreateSessionParams(
              accept_cookies=True,
          )
      )

      try:
          # Connect Puppeteer
          browser = await connect(
              browserWSEndpoint=session.ws_endpoint, defaultViewport=None
          )

          # Open a new page
          page = await browser.newPage()

          # Navigate and interact
          await page.goto("https://example.com")
          title = await page.title()
          print(f"Title: {title}")

      except Exception as e:
          print(f"Encountered error: {e}")
      finally:
          # Clean up
          await client.sessions.stop(session.id)


  if __name__ == "__main__":
      asyncio.run(main())
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Playwright Integration" icon="code" href="/sessions/playwright">
    Connect with Playwright
  </Card>

  <Card title="Session Lifecycle" icon="rotate" href="/sessions/lifecycle">
    Manage sessions
  </Card>

  <Card title="Stealth Mode" icon="user-secret" href="/sessions/stealth">
    Configure anti-detection
  </Card>

  <Card title="Profiles" icon="user" href="/sessions/profiles">
    Persist browser state
  </Card>
</CardGroup>