nstbrowser-ai-agent

What this skill does

# 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 "[email protected]"
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 pro