---

name: nstbrowser-ai-agent description: Browser automation CLI with Nstbrowser integration for AI agents. Use when the user needs advanced browser fingerprinting, profile management, proxy configuration, batch operations on multiple browser profiles, or cursor-based pagination for large datasets. Triggers include requests to "use NST profile", "configure proxy for profile", "manage browser profiles", "batch update profiles", "start multiple browsers", "list profiles with pagination", or any task requiring Nstbrowser's anti-detection features. allowed-tools: Bash(npx nstbrowser-ai-agent:), Bash(nstbrowser-ai-agent:)

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: http://127.0.0.1:8848
• 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)

nstbrowser-ai-agent config set key YOUR_API_KEY

Method 2: Environment Variable

Set the NST_API_KEY environment variable in your shell configuration file.

4. CLI Tool Installation

Install the nstbrowser-ai-agent CLI:

# Using npx (no installation required)
npx nstbrowser-ai-agent --help

# Or install globally
npm install -g nstbrowser-ai-agent

5. Verify Installation

Test your setup:

# Check CLI version
nstbrowser-ai-agent --version

# List profiles (verifies API connection)
nstbrowser-ai-agent profile list

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:

# 1. Start temporary browser
nstbrowser-ai-agent browser start-once

# 2. Open a website
nstbrowser-ai-agent open https://example.com

# 3. Take a snapshot
nstbrowser-ai-agent snapshot -i

# 4. Close browser (auto-cleanup)
nstbrowser-ai-agent close

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:

# 1. List available profiles
nstbrowser-ai-agent profile list

# 2. Create a new profile (if needed)
nstbrowser-ai-agent profile create my-profile

# 3. Open browser with profile (auto-starts if not running)
nstbrowser-ai-agent open https://example.com

# 4. Interact with page
nstbrowser-ai-agent snapshot -i
nstbrowser-ai-agent click @e1

# 5. Close browser (session saved to profile)
nstbrowser-ai-agent close

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, production-bot
• Use when: Working interactively or in scripts with descriptive names

Profile ID:

• UUID format, guaranteed uniqueness
• Example: 86581051-fb0d-4c4a-b1e3-ebc1abd17174
• 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. --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. 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.

# First command: link session to profile
nstbrowser-ai-agent --profile my-profile open https://example.com

# Subsequent commands: Stays in 'my-profile' automatically
nstbrowser-ai-agent snapshot -i
nstbrowser-ai-agent click @e1
nstbrowser-ai-agent fill @e2 "data"

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.

# Get snapshot with refs
nstbrowser-ai-agent snapshot -i

# Output shows elements with refs:
# @e1 button "Submit"
# @e2 textbox "Email"
# @e3 textbox "Password"

# Use refs to interact
nstbrowser-ai-agent fill @e2 "user@example.com"
nstbrowser-ai-agent fill @e3 "password"
nstbrowser-ai-agent click @e1

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:

# Set API key (required)
nstbrowser-ai-agent config set key YOUR_API_KEY

# Optional: Set custom host
nstbrowser-ai-agent config set host api.example.com

# Optional: Set custom port
nstbrowser-ai-agent config set port 9000

# View all configuration
nstbrowser-ai-agent config show

# Get specific value
nstbrowser-ai-agent config get key

Configuration persists across sessions and takes priority over environment variables.

Environment Variables

Alternative to config file:

# Nstbrowser API credentials (required if not using config)
# Set NST_API_KEY in your environment

# Optional: Nstbrowser API endpoint
# Set NST_HOST and NST_PORT if using custom endpoint

# Optional: Specify profile for each command
# nstbrowser-ai-agent open https://example.com --profile "my-profile"

Priority: Config file > Environment variables > Defaults

Common Commands

Profile Management

List Profiles

# List all profiles
nstbrowser-ai-agent profile list

# List with JSON output
nstbrowser-ai-agent profile list --json

# List with pagination (for large datasets)
nstbrowser-ai-agent profile list-cursor --page-size 50

Show Profile Details

# Show by name or ID
nstbrowser-ai-agent profile show my-profile --json
nstbrowser-ai-agent profile show 86581051-fb0d-4c4a-b1e3-ebc1abd17174 --json

Create Profile

nstbrowser-ai-agent profile create my-profile \
  --proxy-host proxy.example.com \
  --proxy-port 8080 \
  --proxy-type http \
  --platform Windows

Delete Profile

# Delete single profile
nstbrowser-ai-agent profile delete <profile-name-or-id>

# Delete multiple profiles
nstbrowser-ai-agent profile delete id-1 id-2 id-3

Browser Control

Start Browser

# Start with profile name
nstbrowser-ai-agent browser start my-profile

# Start with profile ID
nstbrowser-ai-agent browser start 86581051-fb0d-4c4a-b1e3-ebc1abd17174

# Start temporary browser
nstbrowser-ai-agent browser start-once

# Start temporary browser
nstbrowser-ai-agent browser start-once

Stop Browser

# Stop specific browser
nstbrowser-ai-agent browser stop my-profile

# Stop all browsers
nstbrowser-ai-agent browser stop-all

List Running Browsers

nstbrowser-ai-agent browser list

Page Navigation

Open URL

# Auto-launches browser if not running
nstbrowser-ai-agent open https://example.com

Navigate

nstbrowser-ai-agent back
nstbrowser-ai-agent forward
nstbrowser-ai-agent reload

Page Inspection

Get Snapshot

# Accessibility snapshot with refs (best for AI)
nstbrowser-ai-agent snapshot -i

# Compact snapshot
nstbrowser-ai-agent snapshot -c

# Custom depth
nstbrowser-ai-agent snapshot -d 3

Get Page Info

nstbrowser-ai-agent get title
nstbrowser-ai-agent get url

Take Screenshot

nstbrowser-ai-agent screenshot output.png

# Annotated screenshot with element labels
nstbrowser-ai-agent screenshot --annotate output.png

Element Interaction

Click

# Click by ref
nstbrowser-ai-agent click @e1

# Click by CSS selector
nstbrowser-ai-agent click 'button[type="submit"]'

Fill Input

# Fill by ref
nstbrowser-ai-agent fill @e2 "text"

# Fill by CSS selector
nstbrowser-ai-agent fill 'input[name="email"]' "user@example.com"

Type Text

nstbrowser-ai-agent type @e3 "text"

Get Element Text

nstbrowser-ai-agent get text @e4
nstbrowser-ai-agent get text '.product-price'

Wait Commands

Wait for Element

nstbrowser-ai-agent wait 'button.submit'

Wait for Time

# Wait 3 seconds
nstbrowser-ai-agent wait 3000

Wait for Page Load

nstbrowser-ai-agent wait --load networkidle

JavaScript Execution

Execute JavaScript

nstbrowser-ai-agent eval "document.title"
nstbrowser-ai-agent eval "document.querySelectorAll('a').length"

# Execute from stdin
echo "document.body.innerHTML" | nstbrowser-ai-agent eval --stdin

Proxy Management

Show Proxy

nstbrowser-ai-agent profile proxy show my-profile --json

Update Proxy

nstbrowser-ai-agent profile proxy update my-profile \
  --host proxy.example.com \
  --port 8080 \
  --type http \
  --username proxyuser \
  --password proxypass

Reset Proxy

nstbrowser-ai-agent profile proxy reset <profile-name-or-id>

Batch Proxy Operations

# Batch update
nstbrowser-ai-agent profile proxy batch-update id-1 id-2 id-3 \
  --host proxy.example.com \
  --port 8080 \
  --type http

# Batch reset
nstbrowser-ai-agent profile proxy batch-reset id-1 id-2 id-3

Workflow Examples

Pattern 1: Profile-based Automation

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

# 1. List profiles to verify connection
nstbrowser-ai-agent profile list

# 2. Set profile by name
nstbrowser-ai-agent config set profile my-profile

# 3. List profiles to find target
nstbrowser-ai-agent profile list

# 4. Open browser with profile (auto-starts if not running)
nstbrowser-ai-agent open https://example.com --profile "my-profile"
nstbrowser-ai-agent open https://example.com

# 6. Get snapshot
nstbrowser-ai-agent snapshot -i

# 7. Interact with page
nstbrowser-ai-agent click @e1
nstbrowser-ai-agent fill @e2 "data"

# 8. Close (session saved to profile)
nstbrowser-ai-agent close

Pattern 2: Batch Profile Management

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

# Get multiple profile IDs
PROFILE_IDS=$(nstbrowser-ai-agent profile list --json | jq -r '.data.profiles[0:3] | map(.profileId) | join(" ")')

# Batch update proxy
nstbrowser-ai-agent profile proxy batch-update $PROFILE_IDS \
  --host proxy.example.com \
  --port 8080 \
  --type http

# Batch add tags
nstbrowser-ai-agent profile tags batch-create $PROFILE_IDS \
  automated:blue batch-updated:green

# Batch move to group
GROUP_ID=$(nstbrowser-ai-agent profile groups list --json | jq -r '.data.groups[0].groupId')
nstbrowser-ai-agent profile groups batch-change $GROUP_ID $PROFILE_IDS

Pattern 3: Login and Scrape

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

# 1. Open login page
nstbrowser-ai-agent --profile my-profile open https://site.com/login

# 2. Wait for page to load
nstbrowser-ai-agent wait --load networkidle

# 3. Fill and submit using CSS selectors
nstbrowser-ai-agent fill 'input[placeholder="Email"]' "user@example.com"
nstbrowser-ai-agent fill 'input[type="password"]' "userpassword"
nstbrowser-ai-agent click 'button[type="submit"]'

# 4. Wait for navigation
nstbrowser-ai-agent wait --load networkidle

# 5. Navigate to target page
nstbrowser-ai-agent open https://site.com/data

# 6. Extract data
nstbrowser-ai-agent snapshot -i > data.txt
nstbrowser-ai-agent eval "document.querySelector('.info')?.textContent"

# 7. Close (session saved to profile)
nstbrowser-ai-agent close

Error Handling

Common Errors (by frequency)

1. "NST_API_KEY is required"

Cause: API key not configured.

Solution:

# Method 1: Config file (recommended)
nstbrowser-ai-agent config set key YOUR_API_KEY

# Method 2: Set environment variable in your shell

Verify:

nstbrowser-ai-agent config get key

2. "Failed to connect to Nstbrowser"

Cause: Nstbrowser service not running or wrong endpoint.

Solution:

1. Check if NST agent is running:

   nstbrowser-ai-agent nst status
   

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

   nstbrowser-ai-agent config set host YOUR_HOST
   nstbrowser-ai-agent config set port YOUR_PORT
   

Verify:

# Should show "NST agent is running and responsive"
nstbrowser-ai-agent nst status

# Should return list of profiles
nstbrowser-ai-agent profile list

3. "Profile not found"

Cause: Specified profile doesn't exist.

Solution:

1. List available profiles:

   nstbrowser-ai-agent profile list
   

2. Create a new profile:

   nstbrowser-ai-agent profile create my-profile
   

3. Or use temporary browser:

   nstbrowser-ai-agent browser start-once
   

Verify:

# Should show your profile
nstbrowser-ai-agent profile show my-profile

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

Cause: Element ref is stale or page structure changed.

Solution:

1. Get fresh snapshot:

   nstbrowser-ai-agent snapshot -i
   

2. Use CSS selectors instead of refs:

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

3. Inspect page elements:

   nstbrowser-ai-agent eval "Array.from(document.querySelectorAll('input')).map(el => ({type: el.type, placeholder: el.placeholder}))"
   

Verify:

# Element should be visible
nstbrowser-ai-agent is visible 'button[type="submit"]'

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:

# 1. Inspect page elements
nstbrowser-ai-agent eval "Array.from(document.querySelectorAll('input')).map(el => ({type: el.type, placeholder: el.placeholder}))"

# 2. Use CSS selectors directly
nstbrowser-ai-agent fill 'input[placeholder="Email"]' "user@example.com"
nstbrowser-ai-agent fill 'input[type="password"]' "password"
nstbrowser-ai-agent click 'button[type="submit"]'

Command Reference

Profile Commands

• profile list - List all profiles
• profile list-cursor - List profiles with cursor pagination
• profile show <name-or-id> - Show profile details
• profile create <name> - Create new profile
• profile delete <name-or-id> [name-or-id...] - Delete profile(s)
• profile groups list - List all groups
• profile groups change <group-id> <profile-name-or-id> [...] - Move profile(s) to group
• profile groups batch-change <group-id> <id> [...] - Batch change group
• profile cache clear <id> [id...] - Clear profile cache
• profile cookies clear <id> [id...] - Clear profile cookies

Proxy Commands

• profile proxy show <name-or-id> - Show proxy configuration
• profile proxy update <name-or-id> - Update proxy settings
• profile proxy reset <id> [id...] - Reset proxy settings
• profile proxy batch-update <id> [id...] - Batch update proxy
• profile proxy batch-reset <id> [id...] - Batch reset proxy

Tag Commands

• profile tags list - List all tags
• profile tags create <id> <tag> - Add tag to profile
• profile tags update <id> <tag:color> [...] - Update profile tags
• profile tags clear <id> [id...] - Clear profile tags
• profile tags batch-create <id> [id...] <tag:color> - Batch create tags
• profile tags batch-update <id> [id...] <tag:color> - Batch update tags
• profile tags batch-clear <id> [id...] - Batch clear tags

Browser Commands

• browser list - List running browsers
• browser start <name-or-id> - Start browser with profile
• browser start-once - Start temporary browser
• browser stop <name-or-id> - Stop browser
• browser stop-all - Stop all browsers
• browser pages <name-or-id> - Get browser pages list
• browser debugger <name-or-id> - Get debugger URL
• browser cdp-url <name-or-id> - Get CDP WebSocket URL
• browser cdp-url-once - Get CDP URL for temporary browser
• browser connect <name-or-id> - Connect and get CDP URL
• browser connect-once - Connect to temporary browser and get CDP URL

Navigation Commands

• open <url> - Navigate to URL
• back - Go back
• forward - Go forward
• reload - Reload page

Inspection Commands

• snapshot [-i] [-c] [-d <depth>] - Get page snapshot
• get title - Get page title
• get url - Get current URL
• get text <sel> - Get element text
• screenshot [path] - Take screenshot
• is visible <sel> - Check if element is visible

Interaction Commands

• click <sel> - Click element
• fill <sel> <text> - Fill input
• type <sel> <text> - Type into element
• press <key> - Press key
• wait <sel|ms> - Wait for element or time

Utility Commands

• eval <js> - Execute JavaScript
• close - Close browser
• session list - List active sessions
• update check - Check for available updates
• nst status - Check if NST agent is running
• config set <key> <value> - Set configuration
• config get <key> - Get configuration value
• config show - Show all configuration

JSON Output

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

nstbrowser-ai-agent profile list --json
nstbrowser-ai-agent snapshot -i --json
nstbrowser-ai-agent get text @e1 --json

Best Practices

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:

# Set environment variable
NSTBROWSER_AI_AGENT_NO_UPDATE_CHECK=1

Manual Update Check

# Check for updates
nstbrowser-ai-agent update check

# JSON output
nstbrowser-ai-agent update check --json

Updating to Latest Version

# If installed globally
npm install -g nstbrowser-ai-agent@latest

# If using npx
npx nstbrowser-ai-agent@latest

# If installed locally in project
npm install nstbrowser-ai-agent@latest

Deep-Dive Documentation

For more detailed information, see:

Reference	When to Use
references/nst-api-reference.md	Complete NST API reference with all commands
references/profile-management.md	Profile creation, organization, and lifecycle
references/proxy-configuration.md	Proxy setup, testing, and troubleshooting
references/batch-operations.md	Efficient batch operations on multiple profiles
references/troubleshooting.md	Common issues and diagnostic commands

Ready-to-Use Templates

Template	Description
templates/profile-setup.sh	Profile initialization with proxy and tags
templates/batch-proxy-update.sh	Batch proxy update for multiple profiles
templates/automated-workflow.sh	Complete automation workflow example

./templates/profile-setup.sh my-profile --proxy-host proxy.com --proxy-port 8080
./templates/batch-proxy-update.sh "id1 id2 id3" --proxy-host proxy.com --proxy-port 8080
./templates/automated-workflow.sh my-profile https://example.com

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:

# Get CDP URL for existing browser
nstbrowser-ai-agent browser cdp-url my-profile

# Get CDP URL for temporary browser
nstbrowser-ai-agent browser cdp-url-once

# Connect to browser and get CDP URL (starts if not running)
nstbrowser-ai-agent browser connect my-profile

# Connect to temporary browser and get CDP URL
nstbrowser-ai-agent browser connect-once

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