Nstbrowser AI Agent

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.

# 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:
  ```bash
  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)**
```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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.

```bash
# 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.

```bash
# 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`:

```bash
# 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:

```bash
# 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**
```bash
# 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**
```bash
# Show by name or ID
nstbrowser-ai-agent prof