Herd SDK

A powerful SDK for controlling your own browser and other devices through the Herd platform, whether it's one browser or a fleet of millions. Similar to Puppeteer but with support for multiple devices and real-time events, and no infrastructure to setup.

Learn more at https://herd.garden.

New in 0.1.48

- Support for specifying a device when running trail servers herd trail server -d .

See all release notes

Features

- 🌐 Control multiple browsers and devices from a single client
- ⛏️ Extract data from web pages
- 🔍 Run automations and interact with webpages
- 🤖 Build AI web tools and MCP servers
- 🚀 Familiar automation API similar to Puppeteer
- 🧩 TypeScript support with full type definitions

Installation

``bash
npm install @monitoro/herd


or


yarn add @monitoro/herd
`

Quick Start

`typescript
import { HerdClient } from '@monitoro/herd';

async function example() {
// Create a client
const client = new HerdClient({
token: 'your-auth-token'
});

// List available devices
const devices = await client.devices();
console.log('Available devices:', devices);

// Get a specific device
const device = await client.device('device-id');

// Create a new page
const page = await device.newPage();

// Navigate to a URL
await page.goto('https://example.com');

// Wait for element and click
await page.waitForElement('#login-button');
await page.click('#login-button');

// Fill a form
await page.fill('#username', 'testuser');
await page.fill('#password', 'password');
await page.click('#submit');

// Extract data
const data = await page.extract({
title: 'h1',
description: '.description',
items: {
price: '.item-price',
name: '.item-name'
}
});

console.log('Extracted data:', data);

// Cleanup
await page.close();
await device.close();
}
`

MCP Server

Herd can be used build MCP servers for the website of your choice, using your web accounts without setting up any infrastructure nor sharing your credentials with anyone.

Learn more at https://herd.garden/docs/reference-mcp-server.

`typescript
import { HerdMcpServer } from '@monitoro/herd';

const server = new HerdMcpServer({
info: {
name: "social-assistant",
version: "1.0.0",
description: "Social media automation tools for LLMs"
},
transport: {
type: "sse",
port: 3000
},
herd: {
token: "your-herd-token" // Get from herd.garden
}
});

// Start the server
await server.start();
`

API Reference

Docs available at https://herd.garden/docs.

$3

The main client for interacting with the Herd platform.

`typescript
const client = new HerdClient({
token: 'your-auth-token'
});

// List devices
const devices = await client.devices();

// Get specific device
const device = await client.device('device-id');

// Register new device and get a registration url
const result = await client.registerDevice({
deviceId: 'my-device',
name: 'Laptop Browser',
type: 'browser'
});
`

$3

Represents a connected device (browser or headless).

`typescript
// Create new page
const page = await device.newPage();

// List all pages
const pages = await device.pages();

// Subscribe to device events
device.onEvent((event) => {
console.log('Device event:', event);
});

// Close device
await device.close();
`

$3

Provides browser automation functionality similar to Puppeteer's Page class.

`typescript
// Navigation
await page.goto('https://example.com');
await page.back();
await page.forward();
await page.reload();

// Element interaction
await page.click('#button', { button: 'left', clickCount: 1 });
await page.fill('#input', 'text', { clearFirst: true });

// Finding elements
const options: FindOptions = {
timeout: 5000,
visible: true
};
const element = await page.find('.selector', options);

// Waiting
await page.waitForElement('.selector', { state: 'visible' });
await page.waitForNavigation('networkidle0');

// JavaScript evaluation
const result = await page.evaluate(() => document.title);

// Data extraction
const data = await page.extract({
title: 'h1',
items: '.item'
});

// Event subscription
const unsubscribe = page.onEvent((event) => {
console.log('Page event:', event);
});

// Cleanup
unsubscribe();
await page.close();
`

Events

The SDK provides real-time events for various actions:

- Device status changes
- Page navigation
- DOM mutations
- Network activity
- Console messages
- JavaScript errors

Subscribe to events using the onEvent method:

`typescript
// Device events
device.onEvent((event) => {
console.log('Device event:', event);
});

// Page events
page.onEvent((event) => {
console.log('Page event:', event);
});

// Specific event
device.on('status', (event) => {
console.log('Status changed:', event);
});
`

Error Handling

The SDK uses standard error handling patterns:

`typescript
try {
await page.click('#non-existent');
} catch (error) {
if (error.code === 'ELEMENT_NOT_FOUND') {
console.error('Element not found');
} else {
console.error('Other error:', error);
}
}
`

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

`typescript
import { HerdClient, Device, Page, FindOptions } from '@herd/sdk';

const options: FindOptions = {
timeout: 5000,
visible: true
};

const element = await page.find('.selector', options);
`

Trails

Trails are packaged automations that can be shared, reused, and published to the Herd registry.

$3

Search and discover available trails using the CLI:

`bash


Search for trails in the registry

herd trail search --query "login"

Get detailed information about a specific trail

herd trail info @organization/trail-name

View a trail's manifest

herd trail manifest @organization/trail-name

Run a trail

herd trail run @organization/trail-name -a login

Run a specific version of a trail

herd trail run @organization/trail-name -v 1.2.0 -a login
`

$3

Create and publish your own trails:

`bash


Initialize a new trail in the current directory

herd trail init

Build the trail

herd trail build

Test the trail

herd trail test

Publish the trail to the registry

herd trail publish --organization your-org-id
`

$3

You can also use trails programmatically:

`typescript
import { HerdClient } from '@monitoro/herd';

async function useTrail() {
const client = new HerdClient();
await client.initialize();

// Get the trail engine
const trailEngine = client.trails();

// Load a trail from the registry
const { actions, resources } = await trailEngine.loadTrail('@organization/trail-name');

// Run an action from the trail
const result = await trailEngine.runTrail('@organization/trail-name', {
actionName: 'login',
params: {
username: 'user',
password: 'pass'
}
});

console.log('Action result:', result);
}
`

Release Notes




$3

- Support for specifying a device when running trail servers herd trail server -d .

$3

- Better handling of longer running requests and introducing automated retries.

$3

- Fix missing dependencies for the herd CLI.

$3

- Solved a bug where the version was not being correctly set in the CLI.

$3

- We added a universal HTTP transport with dynamic trail loading. Just run herd trail server -t http` to start a server that will dynamically load trails from the Herd registry. Call the API at http://localhost:3000/api/run/{trail}/{action} to run a trail. Visit http://localhost:3000/api/docs to see the OpenAPI documentation.

License

This project is licensed under a EULA - see the LICENSE file for details.

Copyright

Copyright (c) 2025 Monitoro, Omneity Labs.