Browser Secure

Secure browser automation with vault-backed credentials, approval gates, and audit trails.

Philosophy

"Never trust, always verify, encrypt everything, audit all actions"

Quick Start

CODEBLOCK0

Auto-Vault Credential Discovery

The --auto-vault flag enables interactive credential discovery from your password manager:

CODEBLOCK1

This will:

1. 1. Extract the domain from the URL (app.neilpatel.com → neilpatel)
2. Search Bitwarden first (free, default), then 1Password if available
3. Present matching items interactively:

CODEBLOCK2

After saving, you can use the simpler command next time:
CODEBLOCK3

Profile Management

Create isolated Chrome profiles for secure automation with automatic welcome page setup:

CODEBLOCK4

What the Welcome Page Includes

When you create a new profile, it opens with a custom welcome page that guides you through:

1. 1. 📖 Why This Profile Exists - Explains the isolated automation concept
2. 🔌 Required Extensions - Direct links to install:

- Bitwarden password manager - OpenClaw Browser Relay

1. 3. 🗝️ Vault Setup - Step-by-step for Bitwarden or 1Password
2. ✅ Setup Checklist - Interactive checklist to track progress
3. 🛡️ Security Info - "Your vault is secure" messaging with key features

Why Separate Profiles?

Aspect	Personal Profile	Automation Profile
Extensions	Your personal ones	Only automation extensions
Cookies

Personal logins | Isolated session state | | Security | Shared with daily browsing | Locked down, audited | | Cleanup | Manual | Automatic session timeout |

Chrome Profile Support

Browser Secure can use your existing Chrome profiles, giving you access to saved cookies, session state, and existing website logins.

List Available Profiles

CODEBLOCK5

Output:
CODEBLOCK6

Use a Specific Profile

CODEBLOCK7

Profile vs Incognito Mode

Mode	Cookies	Logins	Extensions	Use Case
Incognito (default)	❌ None	❌ None	❌ None	Secure, isolated testing
Chrome Profile

✅ Yes | ✅ Yes | ✅ Yes | Access existing sessions |

Security Note: Browser Secure creates isolated profiles for automation without modifying your existing Chrome profiles. When using --profile, it reads from (but does not write to) existing profiles.

Setup

Option 1: Install via Clawdbot (Recommended)

The easiest way—just ask Clawdbot:

CODEBLOCK8

Clawdbot will handle everything: check prerequisites, auto-install dependencies, build, and configure.

Option 2: Install from GitHub

CODEBLOCK9

Option 3: Manual Setup (Advanced)

If you prefer full control or are developing on the tool:

CODEBLOCK10

This will:

1. 1. ✅ Check prerequisites (Node.js 18+, Chrome)
2. 📦 Auto-install missing dependencies (Playwright browsers, optional vault CLIs)
3. 🔨 Build and link the CLI globally
4. 📝 Create default configuration

What Gets Auto-Installed

The setup automatically handles:

• - Playwright Chromium - Required browser binary (~50MB)
• Bitwarden CLI - If brew is available (recommended vault)
• 1Password CLI - If brew is available (optional)

Configure Vault (Optional)

After setup, configure your preferred vault using environment variables (recommended) or direct CLI login:

Option A: .env File (Convenience for Automation)

⚠️ Security Note: .env files store credentials in plaintext. Only use this on trusted, private machines. Vault integration (Bitwarden/1Password) is the recommended secure approach.

CODEBLOCK11

Full Automation (API Key + Password):
CODEBLOCK12

How it works:

1. 1. BW_CLIENTID/BW_CLIENTSECRET → Authenticates with Bitwarden (replaces username/password)
2. INLINECODE8 → Decrypts your vault (required for automated access)

Alternative: Session Token
CODEBLOCK13

Option B: Direct CLI Login

CODEBLOCK14

Verify Installation

CODEBLOCK15

Vault Providers

Bitwarden (Default, Free) ⭐

Recommended — free for personal use, open source, cross-platform.

CODEBLOCK16

Authentication vs Unlock:

• - API Key (BW_CLIENTID/BW_CLIENTSECRET) → Logs you into Bitwarden
• Master Password (BW_PASSWORD) → Decrypts your vault contents
• Both are needed for fully automated workflows

Get API Key: https://vault.bitwarden.com/#/settings/security/keys

1Password (Paid)

Alternative — if you already have a 1Password subscription.

CODEBLOCK17

macOS Keychain (Local)

Fallback — store credentials in macOS Keychain (no cloud sync).

Environment Variables

Emergency fallback — set credentials via env vars:

CODEBLOCK18

Commands

Command	Description
INLINECODE11	Open welcome page (default when no URL provided)
INLINECODE12

Navigate to a URL | | navigate <url> --profile <id> | Use specific Chrome profile | | navigate <url> --profile select | Interactively choose Chrome profile | | navigate <url> --list-profiles | List available Chrome profiles | | navigate <url> --auto-vault | Auto-discover credentials (Bitwarden → 1Password → manual) | | navigate <url> --site=<name> | Use pre-configured site credentials | | profile --create <name> | Create new Chrome profile with welcome page | | profile --create <name> --launch | Create profile and launch Chrome | | profile --list | List all Chrome profiles | | act "<instruction>" | Natural language action | | extract "<instruction>" | Extract data from page | | screenshot | Take screenshot | | close | Close browser and cleanup | | status | Show session status | | audit | View audit logs |

Welcome Page (Default)

When you run browser-secure navigate without a URL, it opens the welcome page located at:

CODEBLOCK19

The welcome page provides:

• - 📖 Onboarding guide — Why browser-secure exists and how it works
• 🔌 Extension links — Direct install for Bitwarden and OpenClaw Browser Relay
• 🗝️ Vault setup — Step-by-step for Bitwarden or 1Password
• ✅ Setup checklist — Interactive checklist to track progress
• 🛡️ Security info — "Your vault is secure" messaging with key features

Pro tip: Use the welcome page as your starting point for new profiles:
CODEBLOCK20

Approval Modes (Hybrid Design)

browser-secure operates in unattended mode by default, making it ideal for agent automation while preserving safety guardrails.

Default Mode: Unattended (Automation-First)

CODEBLOCK21

In this mode:

• - ✅ All non-destructive actions execute immediately
• ✅ Credentials auto-injected from vault
• ✅ Audit trail written automatically
• ⚠️ Destructive actions (delete, purchase) require --skip-approval or INLINECODE29

Interactive Mode (Human-in-the-Loop)

For sensitive operations, use --interactive to enable approval prompts:

CODEBLOCK22

Approval tiers in interactive mode:

Tier	Actions	Approval
Read-only	navigate, screenshot, extract	None
Form fill

type, select, click | Prompt |
| Authentication | fillpassword, submitlogin | Always |
| Destructive | delete, purchase | 2FA required |

Force Override (Emergency)

CODEBLOCK23

⚠️ Warning: --skip-approval bypasses all safety checks. Use only in fully automated, sandboxed environments.

Session Security

• - Time-bounded (30 min default, auto-expiry)
• Isolated work directories (UUID-based)
• Incognito mode (no persistent profile) — default
• Chrome profile support (your cookies, logins, extensions) — opt-in via INLINECODE32
• Secure cleanup (overwrite + delete)
• Network restrictions (block localhost/private IPs)

Audit Trail

CODEBLOCK24

Environment Variables

Variable	Purpose
INLINECODE33	Config file path
INLINECODE34

Bitwarden API key ID (for automation) | | BW_CLIENTSECRET | Bitwarden API key secret (for automation) | | BW_PASSWORD | Bitwarden master password (alternative) | | BW_SESSION | Bitwarden session token (legacy) | | OP_SERVICE_ACCOUNT_TOKEN | 1Password service account | | BROWSER_SECURE_{SITE}_PASSWORD | Env-based credentials |

Comparison with browser-automation

Feature	browser-automation	browser-secure
Credentials	CLI (exposed)	Vault-backed
Chrome Profiles

❌ No | ✅ Yes (with cookies/logins) | | Approval | None | Tiered gates | | Audit | None | Full trail | | Session timeout | None | 30 min default | | Network | Unrestricted | Allow-list | | Best for | Quick tasks | Sensitive/authenticated |

Troubleshooting

Chrome keychain prompt on first run: This is normal! When Playwright launches Chrome for the first time, macOS asks if Chrome can access your keychain. You can click "Deny" since browser-secure manages credentials through your vault, not Chrome's built-in storage.

Vault not found: Install the CLI for your preferred vault:

• - Bitwarden: INLINECODE40
• 1Password: INLINECODE41

Bitwarden "Vault is locked":

• - If using .env file: Check that BW_CLIENTID and BW_CLIENTSECRET are set correctly
• Or run: INLINECODE44

Bitwarden API key not working: Ensure your API key has access to the vault items you need. API keys are created at: https://vault.bitwarden.com/#/settings/security/keys

Site not configured: Use --auto-vault for interactive setup, or add manually to INLINECODE46

Session expired: Default 30-minute TTL, restart with INLINECODE47

Approval required: Use -y for non-interactive (careful!)

Profile not found: Run browser-secure navigate https://example.com --list-profiles to see available profiles

Chrome profile in use: Close Chrome before using --profile option (Chrome locks profile when running)