Browser

Automate browsers with pre-configured profiles and sessions for authentication and automation

Overview

The Browser capability lets CORE control browsers on your machine using Playwright under the hood. Profiles persist login state on disk; sessions bind a running browser instance to a profile.

Login once per profile, and CORE can access authenticated pages without re-authenticating.

---

Concepts

Concept	Description
Profile	Permanent identity stored on disk (~/.corebrain/browser-profiles/<name>/). Holds cookies, localStorage, and auth state.
Session	Named binding between a task and a profile. Multiple sessions can reference different profiles.

---

Setup

1. Install Playwright Chromium

corebrain browser install

Downloads the Chromium binary and creates default profiles: personal, work, misc.

2. Create a Profile

corebrain browser create-profile personal

Maximum 5 profiles allowed.

3. Create a Session

corebrain browser create-session my_task --profile personal

Maximum 10 sessions allowed.

4. Open (Login)

# Open in headed mode to log in manually
corebrain browser open my_task --headed

# Open at a specific URL
corebrain browser open my_task --url https://github.com --headed

Once logged in, the profile persists auth state. Future opens (headless or headed) will remain authenticated.

---

CLI Reference

Profiles

# Create a profile
corebrain browser create-profile <name>

# Delete a profile (also removes bound sessions and profile directory)
corebrain browser delete-profile <name>

Sessions

# Create a session bound to a profile
corebrain browser create-session <name> --profile <profile>

# List configured sessions
corebrain browser list-sessions

# Delete a session (removes config only; profile data preserved)
corebrain browser delete-session <name>

Open / Close

# Open a session (headless by default)
corebrain browser open <session>

# Open in headed (visible) mode
corebrain browser open <session> --headed

# Open at a specific URL
corebrain browser open <session> --url https://example.com

# Close a running session (profile data preserved)
corebrain browser close-session <session>

# Close all running sessions
corebrain browser close --all

Browser Executable

# Interactive browser selection
corebrain browser set-browser

# Use Brave (auto-detected)
corebrain browser set-browser brave

# Use Chrome (auto-detected)
corebrain browser set-browser chrome

# Use system default (bundled Chromium)
corebrain browser set-browser default

# Use custom browser path
corebrain browser set-browser custom /path/to/browser

Status

corebrain browser status

---

Gateway Tools

When the gateway is running, CORE can control the browser with these tools:

Tool	Description
browser_navigate	Navigate to a URL in a session
browser_snapshot	Get an ARIA accessibility snapshot of the current page
browser_click	Click an element by ref
browser_fill	Fill an input field
browser_type	Type text into a field
browser_press_key	Press a keyboard key
browser_select_option	Select a dropdown option
browser_screenshot	Take a screenshot
browser_scroll	Scroll the page
browser_go_back	Navigate back
browser_go_forward	Navigate forward
browser_wait_for	Wait for a load state
browser_evaluate	Execute JavaScript in the page
browser_close_session	Close a running session
browser_close_all	Close all running sessions
browser_list_sessions	List configured sessions
browser_create_session	Create a session
browser_delete_session	Delete a session

Profile and browser executable management is CLI-only.

---

Agent vs Manual Control

Important: The gateway and CLI maintain separate in-memory session maps (different processes). Do not use corebrain browser open for a session that the agent will also control — it will cause a profile directory lock conflict.

Use case	How to open
Agent-controlled automation	Let the agent call browser_navigate — it launches the browser in-process
Manual login / handoff	Use corebrain browser open <session> --headed

---

Use Cases

Authenticated scraping: Create a linkedin session bound to your personal profile, log in once. CORE can research leads on LinkedIn anytime.

Form automation: CORE fills out repetitive forms — expense reports, time tracking, support tickets — using stored login sessions.

Multi-account management: Create separate profiles (work, personal). CORE switches between them seamlessly via different sessions.

---

Headed Mode (Manual Handoff)

By default, browsers run in headless mode. To take manual control or watch what CORE is doing:

Example prompts:

• “Open LinkedIn in headed mode so I can take over”
• “Start a headed browser session for the checkout flow”
• “I need to intervene — open this in headed mode”

Troubleshooting headed mode: If the browser doesn’t appear, close all sessions first:

1. Ask: “Close all browser sessions”
2. Then: “Open [URL] in headed mode with session [name]“

---

Recommended Browser

We recommend Brave as your automation browser. Brave is Chromium-based, works seamlessly with Playwright, and includes built-in ad blocking that makes automation cleaner and faster.

# macOS
brew install --cask brave-browser

# Linux (Debian/Ubuntu)
sudo apt install brave-browser

# Windows
winget install Brave.Brave

Then configure CORE to use it:

corebrain browser set-browser brave