Browser Automation with nstbrowser-ai-agent

Overview

This skill enables AI agents to control browsers using nstbrowser-ai-agent CLI with Nstbrowser integration. Nstbrowser provides advanced browser fingerprinting, profile management, and anti-detection capabilities for professional browser automation.

This tool requires Nstbrowser service to function. All browser operations are performed through Nstbrowser profiles, which provide:

• - Advanced browser fingerprinting and anti-detection
• Profile management with persistent sessions
• Proxy configuration per profile
• Batch operations on multiple profiles
• Tag and group organization for profile management

Prerequisites

Before using this tool, ensure you have the following:

1. Nstbrowser Client Installation

Nstbrowser client must be installed and running on your system.

• - Download from: https://www.nstbrowser.io/
• Install the client application
• Launch the Nstbrowser client

2. Nstbrowser Service Running

The Nstbrowser API service must be accessible:

• - Default endpoint: INLINECODE0
• Verify service is running using the CLI:

  nstbrowser-ai-agent profile list
  

• - Expected response: List of profiles or empty list

3. API Key Configuration

Obtain your API key from the Nstbrowser dashboard and configure it:

Method 1: Config File (Recommended)
CODEBLOCK1

Method 2: Environment Variable

Set the NSTAPIKEY environment variable in your shell configuration file.

4. CLI Tool Installation

Install the nstbrowser-ai-agent CLI:

CODEBLOCK2

5. Verify Installation

Test your setup:

CODEBLOCK3

If you see your profiles or an empty list, your environment is configured correctly.

Quick Start

Get started in 5 minutes with these examples:

Option 1: Using Temporary Browser (Fastest)

For quick tests or one-time tasks:

CODEBLOCK4

Note: Temporary browsers don't save session state and are cleaned up after use.

Option 2: Using Profile (Recommended for Persistent Sessions)

For tasks that require saved sessions, cookies, or login state:

CODEBLOCK5

Expected Output:

• - Profile list shows your profiles with IDs and names
• Browser opens in headless mode
• Snapshot shows page structure with element refs (@e1, @e2, etc.)
• Session state persists across browser restarts

Core Concepts

Profiles

Profiles are the foundation of Nstbrowser automation. Each profile is an isolated browser environment that stores:

• - Browser Fingerprints: Canvas, WebGL, fonts, screen resolution, timezone
• Session Data: Cookies, localStorage, sessionStorage
• Login State: Persistent authentication across sessions
• Proxy Settings: Per-profile proxy configuration
• Browser Configuration: User agent, platform, language settings

Why use profiles?

• - Maintain separate identities for different tasks
• Preserve login sessions between automation runs
• Isolate cookies and data between different websites
• Configure different proxies for different regions

Profile Name vs ID

All profile commands support both profile NAME and profile ID:

Profile Name:

• - User-friendly, easier to remember
• Example: my-profile, test-account, INLINECODE3
• Use when: Working interactively or in scripts with descriptive names

Profile ID:

• - UUID format, guaranteed uniqueness
• Example: INLINECODE4
• Use when: Scripting with multiple profiles or ensuring exact profile match

UUID Format Auto-Detection:

• - The system automatically detects UUID format in profile names
• If you provide a UUID-formatted string to --profile, it's treated as a profile ID
• This prevents accidental profile creation when you meant to use an ID
• Example: --profile "86581051-fb0d-4c4a-b1e3-ebc1abd17174" is treated as profile ID

Resolution Priority:

1. 1. --profile flag (profile name or UUID auto-detected as ID)
2. Use once browser if no profile specified

Profile Resolution Logic:
When you specify a profile for a browser action:

1. 1. Check running browsers - Uses existing browser if already running (earliest if multiple)
2. Start browser - Starts the profile if it exists but isn't running
3. Create profile - If profile NAME doesn't exist, creates it automatically
4. Error - If profile ID doesn't exist, returns an error
5. Once browser - If no profile specified, uses or creates temporary browser

Important: If multiple profiles have the same name, the earliest started browser will be used.

Sticky Sessions

Once you start a session with a profile, that session "locks" to that browser instance. Subsequent commands automatically reuse the same browser without repeating the --profile flag.

CODEBLOCK6

This makes automation scripts cleaner and reduces the need to specify the profile repeatedly.

Refs

Elements are identified by refs (e.g., @e1, @e2) from snapshots, making automation more reliable than CSS selectors.

CODEBLOCK7

Note: For modern web frameworks (React, Vue, Angular), CSS selectors may be more reliable than refs.

Configuration

Config File (Recommended)

Store configuration persistently in ~/.nst-ai-agent/config.json:

CODEBLOCK8

Configuration persists across sessions and takes priority over environment variables.

Environment Variables

Alternative to config file:

CODEBLOCK9

Priority: Config file > Environment variables > Defaults

Common Commands

Profile Management

List Profiles
CODEBLOCK10

Show Profile Details
CODEBLOCK11

Create Profile
CODEBLOCK12

Delete Profile
CODEBLOCK13

Browser Control

Start Browser
CODEBLOCK14

Stop Browser
CODEBLOCK15

List Running Browsers
CODEBLOCK16

Page Navigation

Open URL
CODEBLOCK17

Navigate
CODEBLOCK18

Page Inspection

Get Snapshot
CODEBLOCK19

Get Page Info
CODEBLOCK20

Take Screenshot
CODEBLOCK21

Element Interaction

Click
CODEBLOCK22

Fill Input
CODEBLOCK23

Type Text
CODEBLOCK24

Get Element Text
CODEBLOCK25

Wait Commands

Wait for Element
CODEBLOCK26

Wait for Time
CODEBLOCK27

Wait for Page Load
CODEBLOCK28

JavaScript Execution

Execute JavaScript
CODEBLOCK29

Proxy Management

Show Proxy
CODEBLOCK30

Update Proxy
CODEBLOCK31

Reset Proxy
CODEBLOCK32

Batch Proxy Operations
CODEBLOCK33

Workflow Examples

Pattern 1: Profile-based Automation

Use Case: Automate tasks that require persistent login sessions or cookies.

CODEBLOCK34

Pattern 2: Batch Profile Management

Use Case: Manage multiple profiles efficiently (update proxies, add tags, organize).

CODEBLOCK35

Pattern 3: Login and Scrape

Use Case: Log in to a website, navigate to data pages, and extract information.

CODEBLOCK36

Error Handling

Common Errors (by frequency)

1. "NSTAPIKEY is required"

Cause: API key not configured.

Solution:
CODEBLOCK37

Verify:
CODEBLOCK38

2. "Failed to connect to Nstbrowser"

Cause: Nstbrowser service not running or wrong endpoint.

Solution:

1. 1. Check if NST agent is running:

   nstbrowser-ai-agent nst status
   

1. 2. Ensure Nstbrowser client is running
2. If using custom host/port, configure:

Verify:
CODEBLOCK41

3. "Profile not found"

Cause: Specified profile doesn't exist.

Solution:

1. 1. List available profiles:

   nstbrowser-ai-agent profile list
   

1. 2. Create a new profile:

   nstbrowser-ai-agent profile create my-profile
   

1. 3. Or use temporary browser:

Verify:
CODEBLOCK45

4. "Element not found" or "Action timed out"

Cause: Element ref is stale or page structure changed.

Solution:

1. 1. Get fresh snapshot:

   nstbrowser-ai-agent snapshot -i
   

1. 2. Use CSS selectors instead of refs:

   # Instead of: nstbrowser-ai-agent click @e1
   # Use: nstbrowser-ai-agent click 'button[type="submit"]'
   

1. 3. Inspect page elements:

Verify:
CODEBLOCK49

Ref System Limitations

The ref system (@e1, @e2, etc.) may not work reliably with modern web frameworks (Vue.js, React, Angular) due to dynamic DOM updates.

Workaround - Use CSS Selectors:

CODEBLOCK50

Command Reference

Profile Commands

• - profile list - List all profiles
• INLINECODE13 - List profiles with cursor pagination
• INLINECODE14 - Show profile details
• INLINECODE15 - Create new profile
• INLINECODE16 - Delete profile(s)
• INLINECODE17 - List all groups
• INLINECODE18 - Move profile(s) to group
• INLINECODE19 - Batch change group
• INLINECODE20 - Clear profile cache
• INLINECODE21 - Clear profile cookies

Proxy Commands

• - profile proxy show <name-or-id> - Show proxy configuration
• INLINECODE23 - Update proxy settings
• INLINECODE24 - Reset proxy settings
• INLINECODE25 - Batch update proxy
• INLINECODE26 - Batch reset proxy

Tag Commands

• - profile tags list - List all tags
• INLINECODE28 - Add tag to profile
• INLINECODE29 - Update profile tags
• INLINECODE30 - Clear profile tags
• INLINECODE31 - Batch create tags
• INLINECODE32 - Batch update tags
• INLINECODE33 - Batch clear tags

Browser Commands

• - browser list - List running browsers
• INLINECODE35 - Start browser with profile
• INLINECODE36 - Start temporary browser
• INLINECODE37 - Stop browser
• INLINECODE38 - Stop all browsers
• INLINECODE39 - Get browser pages list
• INLINECODE40 - Get debugger URL
• INLINECODE41 - Get CDP WebSocket URL
• INLINECODE42 - Get CDP URL for temporary browser
• INLINECODE43 - Connect and get CDP URL
• INLINECODE44 - Connect to temporary browser and get CDP URL

Navigation Commands

• - open <url> - Navigate to URL
• INLINECODE46 - Go back
• INLINECODE47 - Go forward
• INLINECODE48 - Reload page

Inspection Commands

• - snapshot [-i] [-c] [-d <depth>] - Get page snapshot
• INLINECODE50 - Get page title
• INLINECODE51 - Get current URL
• INLINECODE52 - Get element text
• INLINECODE53 - Take screenshot
• INLINECODE54 - Check if element is visible

Interaction Commands

• - click <sel> - Click element
• INLINECODE56 - Fill input
• INLINECODE57 - Type into element
• INLINECODE58 - Press key
• INLINECODE59 - Wait for element or time

Utility Commands

• - eval <js> - Execute JavaScript
• INLINECODE61 - Close browser
• INLINECODE62 - List active sessions
• INLINECODE63 - Check for available updates
• INLINECODE64 - Check if NST agent is running
• INLINECODE65 - Set configuration
• INLINECODE66 - Get configuration value
• INLINECODE67 - Show all configuration

JSON Output

All commands support --json flag for machine-readable output:

CODEBLOCK51

Best Practices

1. 1. Use Profile Names: More readable than IDs for most use cases
2. Leverage Sticky Sessions: No need to repeat --profile flag once browser is running
3. Use Batch Operations: More efficient for multiple profiles
4. Organize with Groups and Tags: Keep profiles organized
5. Prefer CSS Selectors for Modern Apps: Refs may not work with Vue/React/Angular
6. Wait Appropriately: Use wait --load networkidle after navigation
7. Close Cleanly: Always close browser to save session state
8. Handle Errors: Check command output and retry if needed
9. Use Proxies Per Profile: Configure proxies for geo-targeting or privacy
10. Keep Updated: Run nstbrowser-ai-agent update check periodically

Updates

Automatic Update Checks

The CLI automatically checks for updates once every 24 hours and notifies you when a new version is available.

Disable automatic checks:
CODEBLOCK52

Manual Update Check

CODEBLOCK53

Updating to Latest Version

CODEBLOCK54

Deep-Dive Documentation

For more detailed information, see:

Ready-to-Use Templates

CODEBLOCK55

Notes

• - Nstbrowser is required: This tool only works with Nstbrowser service
• Profile name/ID support: All commands accept both names and IDs
• Auto-start: Browser automatically starts when using profile if not running
• Name resolution: Profile names are resolved to IDs automatically via API
• Sticky sessions: Profile persists across commands in the same session
• Profiles managed by Nstbrowser: Profiles are created and stored by Nstbrowser client
• Daemon auto-starts: Daemon starts on first command and persists between commands
• Session persistence: Session state is automatically saved to profiles when browser closes
• Temporary browsers: Use browser start-once for disposable sessions that don't save state

CDP Integration

Get Chrome DevTools Protocol (CDP) WebSocket URLs to connect external tools:

CODEBLOCK56

Use cases:

• - Connect Puppeteer/Playwright to Nstbrowser-managed browsers
• Attach Chrome DevTools for debugging
• Integrate with custom CDP-based automation tools
• Monitor browser activity with external tools