Skip to main content

​
Installation

Install the SDK using your preferred package manager: 
npm install @getgrasp/sdk

​
Quick Start

import { Grasp } from '@getgrasp/sdk';

const grasp = new Grasp({
  apiKey: 'your-api-key'
});

const container = await grasp.create();
console.log('Browser ready:', container.browser.wsEndpoint);

await container.shutdown();

​
API Reference

​
new Grasp(options)

Create a new Grasp client instance.
​
options
object
Returns: Grasp client instance Example: 
// Using environment variable
const grasp = new Grasp();

// With explicit API key
const grasp = new Grasp({
  apiKey: 'your-api-key'
});

​
grasp.create(options)

Create and start a new container.
​
options
object
Returns: Promise<GraspContainer> Example: 
// Create basic container
const container = await grasp.create();

// With idle timeout
const container = await grasp.create({
  idleTimeout: 60000  // 60 seconds
});

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

​
grasp.connect(containerId)

Connect to an existing container by ID. If the container is sleeping, it will be awakened.
​
containerId
string
required
The ID of the container to connect to
Returns: Promise<GraspContainer> Example: 
const containerId = 'existing-container-id';
const container = await grasp.connect(containerId);

console.log('Connected to:', container.id);

​
GraspContainer

The container object returned by grasp.create() and grasp.connect(). Properties:
​
id
string
Unique container identifier
​
status
string
Container status
​
createdAt
string
ISO timestamp of creation
​
browser
GraspBrowserSession
Browser session details
Methods:

​
container.shutdown()

Shut down and clean up the container. Returns: Promise<void> Example: 
await container.shutdown();

​
GraspBrowserSession

Browser session details associated with a container. Properties:
​
wsEndpoint
string
Chrome DevTools Protocol WebSocket endpoint
​
liveURL
string
Live view URL for observing the browser
Example: 
console.log('CDP endpoint:', container.browser.wsEndpoint);
console.log('Live view:', container.browser.liveURL);

​
Type Definitions

​
TProxySettings

type TProxySettings = {
  enabled: boolean;
  type: 'mobile' | 'residential' | 'isp' | 'datacenter' | 'custom';
  country?: string;  // ISO 3166 country code (e.g., 'US')
  state?: string;    // State code (e.g., 'CA')
  city?: string;     // City name
};

​
TBrowserSettings

type TBrowserSettings = {
  // Browser settings - not yet implemented
};

​
TTerminalSettings

type TTerminalSettings = {
  // Terminal settings - not yet implemented
};

​
TFileSystemSettings

type TFileSystemSettings = {
  // Filesystem settings - not yet implemented
};

​
Environment Variables

  • GRASP_API_KEY - Default API key (recommended)

​
Error Handling

try {
  const container = await grasp.create();
  // Use container
  await container.shutdown();
} catch (error) {
  console.error('Failed to create container:', error.message);
  if (error.status) {
    console.error('HTTP status:', error.status);
  }
}

​
TypeScript Support

The SDK is written in TypeScript and includes full type definitions. 
import { Grasp, type GraspCreateOptions, type GraspContainer } from '@getgrasp/sdk';

const options: GraspCreateOptions = {
  idleTimeout: 60000,
  proxy: {
    enabled: true,
    type: 'residential',
    country: 'US'
  }
};

const grasp = new Grasp({ apiKey: process.env.GRASP_API_KEY });
const container: GraspContainer = await grasp.create(options);

​
Complete Example with Playwright

import { Grasp } from '@getgrasp/sdk';
import { chromium } from 'playwright';

const grasp = new Grasp();

// Create container
const container = await grasp.create({
  idleTimeout: 300000  // 5 minutes
});

// Connect Playwright to cloud browser
const browser = await chromium.connectOverCDP(container.browser.wsEndpoint);
const page = await browser.newPage();

// Perform automation
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);

// Clean up
await browser.close();
await container.shutdown();

​
Reconnecting to Containers

Save the container ID and reconnect later: 
// First session - create and save ID
const container = await grasp.create();
const containerId = container.id;
console.log('Container ID:', containerId);
// Save containerId to database or file

// Later session - reconnect
const grasp = new Grasp();
const container = await grasp.connect(containerId);
console.log('Reconnected to:', container.id);