Skip to main content

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.

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

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

​
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

​
Step 5: Run Your Agent

Now, run the complete script from your terminal. 
node quickstart.mjs
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.