Quickstart

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.

Step 1: Initialize Your Project

Create a new project directory.

mkdir grasp-quickstart && cd grasp-quickstart
npm init -y

mkdir grasp-quickstart && cd grasp-quickstart
python -m venv venv
source venv/bin/activate

Install the Grasp SDK, Playwright, and dotenv.

# 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

pip install grasp-sdk playwright python-dotenv
playwright install chromium

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

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.

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);
});

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()

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.

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);
});

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()

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.

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

# ... imports

def main():
  grasp = Grasp()

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

  # ... rest of the script

Step 5: Run Your Agent

Now, run the complete script from your terminal.

node quickstart.mjs

python quickstart.py

You should see the following output:

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.

Getting started

SDKs

Browser

Prerequisites

Step 1: Initialize Your Project

Step 2: Launch a Cloud Browser

Step 3: Automate with Playwright

Step 4: Use a Proxy

Step 5: Run Your Agent

​Prerequisites

​Step 1: Initialize Your Project

​Step 2: Launch a Cloud Browser

​Step 3: Automate with Playwright

​Step 4: Use a Proxy

​Step 5: Run Your Agent

Prerequisites

Step 1: Initialize Your Project

Step 2: Launch a Cloud Browser

Step 3: Automate with Playwright

Step 4: Use a Proxy

Step 5: Run Your Agent