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

# Quickstart

> Give your AI agent web access in 5 minutes

Follow this quickstart to connect your agent to the web through Grasp's cloud browser, capture a live view, and print fresh Hacker News headlines with Playwright.

## Prerequisites

* Node.js 18+ (for JavaScript/TypeScript users) or Python 3.8+ (for Python users) installed.
* Get your API key from the [Grasp Dashboard](https://getgrasp.ai/dashboard).

## Step 1: Initialize Your Project

Create a new project directory.

<CodeGroup>
  ```bash JavaScript/TypeScript theme={null}
  mkdir grasp-quickstart && cd grasp-quickstart
  npm init -y
  ```

  ```bash Python theme={null}
  mkdir grasp-quickstart && cd grasp-quickstart
  python -m venv venv
  source venv/bin/activate
  ```
</CodeGroup>

Install the Grasp SDK, Playwright, and `dotenv`.

<CodeGroup>
  ```bash JavaScript/TypeScript theme={null}
  # Using npm
  npm install @getgrasp/sdk playwright dotenv
  npx playwright install chromium

  # Using pnpm
  pnpm add @getgrasp/sdk playwright dotenv
  pnpm exec playwright install chromium

  # Using yarn
  yarn add @getgrasp/sdk playwright dotenv
  yarn playwright install chromium
  ```

  ```bash Python theme={null}
  pip install grasp-sdk playwright python-dotenv
  playwright install chromium
  ```
</CodeGroup>

Create a `.env` file to store your API key. The Grasp SDK will automatically load this key.

```bash theme={null}
echo "GRASP_API_KEY=YOUR_API_KEY" > .env
```

## Step 2: Launch a Cloud Browser

Create a file to get started. This script will initialize the Grasp SDK and create a new container, which is your isolated cloud browser environment.

<CodeGroup>
  ```javascript JavaScript/TypeScript theme={null}
  import 'dotenv/config';
  import { Grasp } from '@getgrasp/sdk';

  async function main() {
    const grasp = new Grasp();

    const container = await grasp.create();
    console.log('Cloud browser is ready!');
    console.log('CDP endpoint:', container.browser.wsEndpoint);
    console.log('Live view:', container.browser.liveURL);

    // We will add Playwright automation here

    await container.shutdown();
    console.log('Container has been shut down.');
  }

  main().catch(err => {
    console.error(err);
    process.exit(1);
  });
  ```

  ```python Python theme={null}
  import os
  from dotenv import load_dotenv
  from grasp import Grasp

  load_dotenv()

  def main():
    grasp = Grasp()

    container = grasp.create()
    print('Cloud browser is ready!')
    print('CDP endpoint:', container.browser.ws_endpoint)
    print('Live view:', container.browser.live_url)

    # We will add Playwright automation here

    container.shutdown()
    print('Container has been shut down.')

  if __name__ == '__main__':
    main()
  ```
</CodeGroup>

## Step 3: Automate with Playwright

Now, let's use Playwright to connect to the cloud browser and automate a task. We'll scrape the top 5 headlines from Hacker News.

<CodeGroup>
  ```javascript JavaScript/TypeScript highlight={3,14-21} theme={null}
  import 'dotenv/config';
  import { Grasp } from '@getgrasp/sdk';
  import { chromium } from 'playwright';

  async function main() {
    const grasp = new Grasp();

    const container = await grasp.create();
    console.log('Cloud browser is ready!');
    console.log('CDP endpoint:', container.browser.wsEndpoint);
    console.log('Live view:', container.browser.liveURL);

    // Connect to the browser and scrape Hacker News
    const browser = await chromium.connectOverCDP(container.browser.wsEndpoint);
    const page = await browser.newPage();
    await page.goto('https://news.ycombinator.com');
    const headlines = await page.$$eval('.titleline > a', (links) =>
      links.slice(0, 5).map((link) => link.textContent?.trim())
    );
    console.log('Top stories:', headlines);
    await browser.close();

    await container.shutdown();
    console.log('Container has been shut down.');
  }

  main().catch(err => {
    console.error(err);
    process.exit(1);
  });
  ```

  ```python Python highlight={4,16-26} theme={null}
  import os
  from dotenv import load_dotenv
  from grasp import Grasp
  from playwright.sync_api import sync_playwright

  load_dotenv()

  def main():
    grasp = Grasp()

    container = grasp.create()
    print('Cloud browser is ready!')
    print('CDP endpoint:', container.browser.ws_endpoint)
    print('Live view:', container.browser.live_url)

    # Connect to the browser and scrape Hacker News
    with sync_playwright() as p:
      browser = p.chromium.connect_over_cdp(container.browser.ws_endpoint)
      page = browser.new_page()
      page.goto('https://news.ycombinator.com')
      headlines = [
          link.text_content().strip()
          for link in page.query_selector_all('.titleline > a')[:5]
      ]
      print('Top stories:', headlines)
      browser.close()

    container.shutdown()
    print('Container has been shut down.')

  if __name__ == '__main__':
    main()
  ```
</CodeGroup>

## Step 4: Use a Proxy

To route the browser's traffic through a specific country, you can enable the proxy feature when creating the container.

<CodeGroup>
  ```javascript JavaScript/TypeScript highlight={9-13} theme={null}
  import 'dotenv/config';
  import { Grasp } from '@getgrasp/sdk';
  import { chromium } from 'playwright';

  async function main() {
    const grasp = new Grasp();

    const container = await grasp.create({
      proxy: {
        enabled: true,
        type: 'residential',
        country: 'US',
      },
    });

    // ... rest of the script
  }

  // ... main call
  ```

  ```python Python highlight={6-12} theme={null}
  # ... imports

  def main():
    grasp = Grasp()

    container = grasp.create(
      proxy={
        "enabled": True,
        "type": "residential",
        "country": "US",
      },
    )

    # ... rest of the script
  ```
</CodeGroup>

## Step 5: Run Your Agent

Now, run the complete script from your terminal.

<CodeGroup>
  ```bash JavaScript/TypeScript theme={null}
  node quickstart.mjs
  ```

  ```bash Python theme={null}
  python quickstart.py
  ```
</CodeGroup>

You should see the following output:

```bash theme={null}
Cloud browser is ready!
CDP endpoint: wss://...
Live view: https://...
Top stories: [ 'Story 1', 'Story 2', 'Story 3', 'Story 4', 'Story 5' ]
Container has been shut down.
```