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 <device-name>.

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

npm install @monitoro/herd
# or
yarn add @monitoro/herd

Quick Start

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.

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.

HerdClient

The main client for interacting with the Herd platform.

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

Device

Represents a connected device (browser or headless).

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

Page

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

// 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:

// 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:

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:

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.

Using Trails

Search and discover available trails using the CLI:

# 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

Creating Trails

Create and publish your own trails:

# 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

Trail API

You can also use trails programmatically:

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

0.1.48

• Support for specifying a device when running trail servers herd trail server -d <device-name>.

0.1.47

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

0.1.46

• Fix missing dependencies for the herd CLI.

0.1.45

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

0.1.44

• 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.