NavFlow Browser Server

A standalone Playwright browser server that enables remote browser automation through secure API key authentication. Perfect for running browser automation workflows from cloud-based frontends.

Quick Start

npx navflow-browser-server

The server will start and display an API key that you can use in the NavFlow frontend at https://buildship-pfw15o.web.app.

Features

✅ Playwright Integration - Full support for Chromium, Firefox, and WebKit browsers
✅ API Key Authentication - Secure device-based authentication with generated API keys
✅ Auto-Installation - Automatically detects and installs Playwright browsers on first run
✅ Node.js v22+ Support - Built for modern Node.js with version validation
✅ Session Management - Persistent browser sessions with cookie/storage support
✅ Flow Execution - Execute complex automation workflows
✅ LLM Discovery Tools - AI-powered flow creation with real-time validation
✅ Real-time Communication - WebSocket support for live updates
✅ Easy Installation - No setup required, works with npx

Usage

Basic Usage

# Start server on default port (3002)
npx navflow-browser-server

# Start server on custom port
npx navflow-browser-server --port=3003

# Show help
npx navflow-browser-server --help

# Show version
npx navflow-browser-server --version

Using with NavFlow Frontend

1. Start the server:

   npx navflow-browser-server

2. Copy the API key from the console output:

   📋 API KEY (Copy this to your NavFlow webapp):
   ────────────────────────────────────────────────────────
   abc123def456789...your-api-key-here
   ────────────────────────────────────────────────────────

3. Configure the frontend:

   • Go to https://buildship-pfw15o.web.app
   • Complete the onboarding flow
   • Paste your API key when prompted
   • The device will connect automatically

4. Start automating! Create and run browser automation flows from the cloud interface.

System Requirements

Automatic Validation

The server automatically checks and validates:

• ✅ Node.js v22+ - Required for optimal performance and security
• ✅ Playwright Browsers - Auto-installs if not detected
• ✅ System Compatibility - Validates environment before starting

Manual Requirements

• Internet connection for Playwright browser downloads
• ~1GB disk space for Playwright browsers
• Modern operating system (Windows 10+, macOS 10.14+, Linux)

API Endpoints

The server exposes several REST endpoints for browser automation (all require API key authentication):

Health Check

GET /health

Returns server status and device information.

Device Information

GET /device

Returns device details including MAC address and configuration.

Session Management

POST /sessions                    # Create browser session
GET /sessions/:id                 # Get session info  
DELETE /sessions/:id              # Close session
POST /sessions/:id/actions        # Execute browser action

Flow Execution

POST /execute-flow               # Execute automation flow

Authentication Sessions

GET /api/sessions                # List saved sessions
POST /api/sessions               # Create new session
DELETE /api/sessions/:name       # Delete session

Discovery Tools (LLM Self-Discovery System)

The browser server includes specialized endpoints for AI-powered flow creation. These tools allow Large Language Models to interact with real browsers to validate and test automation steps in real-time:

POST /discovery/checkSelector     # Validate CSS selectors exist on page
POST /discovery/getHTML          # Extract HTML content from elements  
POST /discovery/screenshot       # Capture page screenshots for AI analysis
POST /discovery/executeStep      # Test automation steps (click, type, navigate)
POST /discovery/getCurrentURL    # Get current page URL and status

Example: Checking if a selector exists

// Request
{
  "sessionId": "my-session",
  "selector": "button[aria-label='Submit']"
}

// Response
{
  "exists": true,
  "count": 1,
  "visible": true
}

Example: Testing an automation step

// Request
{
  "sessionId": "my-session", 
  "action": "click",
  "selector": "button.submit-btn"
}

// Response
{
  "success": true,
  "error": "",
  "newUrl": "https://example.com/success"
}

These tools enable the LLM to:

• Test multiple selector candidates to find reliable ones
• Verify that automation steps actually work before including them in flows
• Understand page context through screenshots and HTML inspection
• Build flows incrementally with real-time validation

All discovery endpoints require API key authentication and operate within isolated browser sessions.

Authentication

All API endpoints (except /health and /device) require API key authentication:

# Include in Authorization header
Authorization: Bearer your-api-key-here

# Or as query parameter
GET /sessions?apiKey=your-api-key-here

Environment Variables

• BROWSER_SERVER_PORT - Port to run server on (default: 3002)

Data Storage

The server creates data directories to store:

• Device Configuration: device-config.json (API key, MAC address)
• Session Data: data/sessions/ (authentication profiles, cookies)
• Temporary Files: Various runtime data

Troubleshooting

Node.js Version Issues

If you see a Node.js version error:

1. Visit https://nodejs.org/
2. Download Node.js v22 or higher
3. Install and restart your terminal
4. Run the command again

Port Already in Use

npx navflow-browser-server --port=3003

Playwright Installation Issues

The server auto-installs Playwright browsers, but if you encounter issues:

npx playwright install

API Key Issues

• API keys are unique per device (MAC address)
• Keys are automatically generated on first run
• If you need a new key, delete device-config.json and restart

Security

• ✅ Device-Based Authentication - Unique API keys per machine
• ✅ Local Data Storage - All browser data stays on your device
• ✅ Secure Communication - API key authentication for all requests
• ✅ No Cloud Dependencies - Direct connection, no proxy servers

Startup Output

When everything is working correctly, you'll see:

🌊 NavFlow Browser Server starting on port 3002...
📍 Health check: http://localhost:3002/health
🔌 WebSocket: ws://localhost:3002

🔍 Checking Playwright browser installation...
✅ Playwright browsers are installed and ready

🖥️  SYSTEM STATUS
──────────────────────────────────────────────────
Node.js: v22.14.0 ✅
Playwright: 1.54.1
Browsers: ✅ Installed

🔧 Initializing device registry...

================================================================================
🔐 NAVFLOW DEVICE REGISTRATION
================================================================================
Device Name: Your-Computer-abc123
MAC Address: 12:34:56:78:90:ab
Port: 3002
Created: 31/07/2025, 10:30:15 am

📋 API KEY (Copy this to your NavFlow webapp):
────────────────────────────────────────────────────────────────────────────────
your-unique-api-key-will-appear-here
────────────────────────────────────────────────────────────────────────────────

📝 To add this device to your workspace:
   1. Open your NavFlow webapp
   2. Go to Workspace Settings → Devices
   3. Click "Add Device" and paste the API key above

✅ Device is ready to receive connections!
================================================================================

🚀 NavFlow Browser Server is ready for API key connections!

Support

• Issues: GitHub Issues
• Frontend: https://buildship-pfw15o.web.app
• Documentation: GitHub Repository

License

MIT License - see LICENSE file for details.

Made with ❤️ by the NavFlow team