> ## 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.

# Quickstart

> Start automating with Hyperbrowser Sessions

In this guide, you'll learn how to scrape Hacker News using scripts and powerful AI agents to automate with Hyperbrowser's cloud based browsers.

## Prerequisites

### Get Your API Key

Sign up and get your API key from the [Hyperbrowser Dashboard](https://app.hyperbrowser.ai/quickstart).

```bash theme={null}
export HYPERBROWSER_API_KEY=<your-api-key>
```

### Install Dependencies

<Tabs>
  <Tab title="Playwright">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @hyperbrowser/sdk playwright-core dotenv
      ```

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

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

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

  <Tab title="Puppeteer">
    <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>
  </Tab>
</Tabs>

## Part 1: Automate with Playwright or Puppeteer Scripts

Let's start by scraping the top story from Hacker News using Playwright or Puppeteer. This shows how you can launch Hyperbrowser sessions and connect to them with automation libraries like Playwright or Puppeteer.

<Tabs>
  <Tab title="Playwright">
    <CodeGroup>
      ```typescript Node.js theme={null}
      import { Hyperbrowser } from "@hyperbrowser/sdk";
      import { chromium } from "playwright-core";
      import { config } from "dotenv";

      config();

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

      async function getTopStory() {
        // Create a cloud browser session
        const session = await client.sessions.create();
        console.log("Session created:", session.id);

        try {
          // Connect Playwright to the cloud browser
          const browser = await chromium.connectOverCDP(session.wsEndpoint);
          const context = browser.contexts()[0];
          const page = context.pages()[0];

          // Navigate to Hacker News
          await page.goto("https://news.ycombinator.com/");

          // Extract the first story title
          const topStory = await page.evaluate(() => {
            const titleElement = document.querySelector(".titleline > a");
            return titleElement ? titleElement.textContent : null;
          });

          console.log("Top Story:", topStory);
          return topStory;
        } catch (err) {
          console.error(`Encountered error: ${err}`);
        } finally {
          // Clean up the session
          await client.sessions.stop(session.id);
        }
      }

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

      ```python Python theme={null}
      import asyncio
      import os
      from playwright.async_api import async_playwright
      from hyperbrowser import AsyncHyperbrowser
      from dotenv import load_dotenv

      load_dotenv()

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


      async def get_top_story():
          # Create a cloud browser session
          session = await client.sessions.create()
          print(f"Session created: {session.id}")

          try:
              # Connect Playwright to the cloud browser
              async with async_playwright() as p:
                  browser = await p.chromium.connect_over_cdp(session.ws_endpoint)
                  context = browser.contexts[0]
                  page = context.pages[0]

                  # Navigate to Hacker News
                  await page.goto("https://news.ycombinator.com/")

                  # Extract the first story title
                  top_story = await page.evaluate("""
                      () => {
                          const titleElement = document.querySelector('.titleline > a');
                          return titleElement ? titleElement.textContent : null;
                      }
                  """)

                  print(f"Top Story: {top_story}")
                  return top_story
          except Exception as e:
              print(f"Error: {e}")
          finally:
              # Clean up the session
              await client.sessions.stop(session.id)


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

  <Tab title="Puppeteer">
    <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 getTopStory() {
        // Create a cloud browser session
        const session = await client.sessions.create();
        console.log("Session created:", session.id);

        try {
          // Connect Playwright to the cloud browser
          const browser = await connect({
            browserWSEndpoint: session.wsEndpoint,
            defaultViewport: null,
          });
          const page = (await browser.pages())[0];

          // Navigate to Hacker News
          await page.goto("https://news.ycombinator.com/");

          // Extract the first story title
          const topStory = await page.evaluate(() => {
            const titleElement = document.querySelector(".titleline > a");
            return titleElement ? titleElement.textContent : null;
          });

          console.log("Top Story:", topStory);
          return topStory;
        } catch (err) {
          console.error(`Encountered error: ${err}`);
        } finally {
          // Clean up the session
          await client.sessions.stop(session.id);
        }
      }

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

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

      load_dotenv()

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


      async def get_top_story():
          # Create a cloud browser session
          session = await client.sessions.create()
          print(f"Session created: {session.id}")

          try:
              # Connect Puppeteer to the cloud browser
              browser = await connect(
                  browserWSEndpoint=session.ws_endpoint, defaultViewport=None
              )
              context = browser._defaultContext
              page = await context.newPage()

              # Navigate to Hacker News
              await page.goto("https://news.ycombinator.com/")

              # Extract the first story title
              top_story = await page.evaluate("""
                  () => {
                      const titleElement = document.querySelector('.titleline > a');
                      return titleElement ? titleElement.textContent : null;
                  }
              """)

              print(f"Top Story: {top_story}")
              return top_story
          except Exception as e:
              print(f"Error: {e}")
          finally:
              # Clean up the session
              await client.sessions.stop(session.id)


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

## Part 2: AI-Powered Automation

Now let's solve the same problem using HyperAgent, our AI-powered browser automation tool. Instead of writing selectors and navigation logic, you simply describe what you want in natural language.

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

  config();

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

  async function getTopStoryWithAgent() {
    const result = await client.agents.hyperAgent.startAndWait({
      task: "Go to Hacker News and get the title of the first post",
    });

    console.log("Top Story:", result.data?.finalResult);
    return result.data?.finalResult;
  }

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

  ```python Python theme={null}
  import os
  from hyperbrowser import Hyperbrowser
  from hyperbrowser.models import StartHyperAgentTaskParams
  from dotenv import load_dotenv

  load_dotenv()

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


  def get_top_story_with_agent():
      result = client.agents.hyper_agent.start_and_wait(
          StartHyperAgentTaskParams(
              task="Go to Hacker News and get the title of the first post"
          )
      )

      print(f"Top Story: {result.data.final_result}")
      return result.data.final_result


  if __name__ == "__main__":
      get_top_story_with_agent()
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/task/hyper-agent \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: <YOUR_API_KEY>' \
    -d '{
      "task": "Go to Hacker News and get the title of the first post"
    }'
  ```
</CodeGroup>

### The Difference

With HyperAgent, you don't need to:

* Write CSS selectors
* Handle page navigation
* Manage browser state
* Debug DOM changes

Just describe what you want, and the AI handles the rest. It's perfect for complex workflows, dynamic sites, and rapid prototyping.

<Note>
  Hyperbrowser also integrates with other popular AI agent frameworks including [BrowserUse](/agents/browser-use), [Claude Computer Use](/agents/claude-computer-use), [Gemini Computer Use](/agents/gemini-computer-use), and [OpenAI CUA](/agents/openai-cua). All agents benefit from Hyperbrowser's cloud infrastructure, stealth capabilities, and proxy support.
</Note>

## Next Steps

Learn more about managing browsers sessions and other capabilities:

<CardGroup cols={2}>
  <Card title="Browser Sessions" icon="browser" href="/sessions/create">
    Learn about managing cloud browser sessions at scale
  </Card>

  <Card title="Web Scraping APIs" icon="globe" href="/web-scraping/scrape">
    Extract data from websites with our scraping APIs
  </Card>

  <Card title="AI Agents" icon="robot" href="/agents/hyperagent">
    Dive deeper into HyperAgent and other AI automation tools
  </Card>

  <Card title="API Reference" icon="square-terminal" href="/api-reference/create-new-session">
    Explore the complete API documentation
  </Card>
</CardGroup>

## Additional Resources

### Browser Integrations

* [Puppeteer Integration](/sessions/puppeteer) - Connect with Puppeteer for automation
* [Playwright Integration](/sessions/playwright) - Connect with Playwright for automation

### SDKs

* [Node.js SDK](/sdks/node) - TypeScript/JavaScript SDK reference
* [Python SDK](/sdks/python) - Python SDK reference

### AI Agent Integrations

* [BrowserUse](/agents/browser-use) - Open-source agent for fast browser automation
* [Claude Computer Use](/agents/claude-computer-use) - Anthropic's Claude with computer capabilities
* [Gemini Computer Use](/agents/gemini-computer-use) - Google's Gemini computer use agent
* [OpenAI CUA](/agents/openai-cua) - OpenAI's computer use agent