Skip to main content

​
Overview

The Browser capability lets CORE control browsers on your machine using agent-browser under the hood. Sessions are pre-configured and limited to 5 parallel instances. Login once, and CORE can access authenticated pages without re-authenticating. For the full list of available browser commands, see the agent-browser documentation.

​
Sessions

Sessions must be created before use. Each session automatically persists:
  • Cookies
  • localStorage
  • Authentication state
Maximum 5 sessions allowed.

​
Default Sessions

Three sessions are pre-configured and ready to use immediately after install — no setup required:
SessionPurpose
workWork-related browsing — company tools, work accounts, internal dashboards
personalPersonal browsing — personal accounts, social media, personal email
miscMiscellaneous tasks — one-off automation, testing, anything that doesn’t fit work or personal
You can start using these immediately: 
corebrain browser open https://github.com --session-name work
corebrain browser open https://gmail.com --session-name personal
corebrain browser open https://example.com --session-name misc

# Create an additional session
corebrain browser create-session dev

# List configured sessions
corebrain browser list-sessions

# Delete a session
corebrain browser delete-session dev

​
Commands

​
Create Session

corebrain browser create-session <name>
Session names must be alphanumeric with hyphens/underscores only.

​
Open a URL

# Open with default session (corebrain)
corebrain browser open https://github.com

# Open with specific session
corebrain browser open https://github.com --session-name work

​
Open CORE Dashboard

Quick command to open the CORE dashboard with a session selector (headed mode): 
corebrain browser open-head
This prompts you to select a session and opens https://app.getcore.me in headed mode.

​
Run Commands

Execute browser automation commands on an open session: 
corebrain browser command click "#login-button" --session-name work
corebrain browser command fill "#email" "user@example.com" --session-name work
corebrain browser command screenshot --session-name work
See agent-browser docs for all available commands.

​
Close Browser

# Close a specific session
corebrain browser close --session-name work

# Close all sessions
corebrain browser close --all

​
Manage Sessions

# List configured sessions
corebrain browser list-sessions

# Create a new session
corebrain browser create-session <name>

# Delete a session (closes browser and removes config)
corebrain browser delete-session <name>

# View status
corebrain browser status

​
Set Browser

Configure which browser to use for automation: 
# 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
corebrain browser set-browser default

# Use custom browser path
corebrain browser set-browser custom /path/to/browser
The browser setting is stored in your config and applies to all sessions.

​
Gateway Tools

When the gateway is running, CORE can use these browser tools:
ToolDescription
browser_openOpen a URL with a pre-configured session
browser_closeClose a browser for a session
browser_commandRun a browser command (click, fill, screenshot, etc.)
browser_list_sessionsList all configured sessions
browser_close_allClose all browser sessions
Session management (create-session, delete-session, set-browser) is done via CLI commands only.

​
Use Cases

Authenticated scraping: Create a linkedin session, login once. Now CORE can research leads on LinkedIn anytime without re-authenticating. Form automation: CORE fills out repetitive forms - expense reports, time tracking, support tickets - using stored login sessions. Visual testing: CORE opens your staging site, navigates through flows, takes screenshots, and compares them to baselines. Multi-account management: Create separate sessions for different accounts (work, personal). CORE switches between them seamlessly.

​
Headed Mode (Manual Handoff)

By default, browsers run in headless mode (no visible window). When you need to take manual control or watch what CORE is doing, ask it to open the browser in headed mode. 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 in headed mode, close all sessions first and then ask CORE to open a new headed session:
  1. Ask: “Close all browser sessions”
  2. Then: “Open [URL] in headed mode with session [name]”
This ensures no existing headless session interferes with the headed request.

​
Prerequisites

The browser capability requires agent-browser to be installed: 
corebrain browser install
This installs agent-browser via npm and creates default sessions: work, personal, misc.

​
Verify Before Starting Gateway

Important: Before starting the gateway, verify that agent-browser is accessible in your terminal: 
# Check agent-browser is in PATH
agent-browser --version
If agent-browser is not found, you may need to:
  1. Reload your shell to pick up PATH changes: 
    source ~/.bashrc   # or ~/.zshrc for zsh
  2. Restart the gateway after reloading: 
    corebrain gateway stop && corebrain gateway start
The gateway captures your PATH at startup. If agent-browser is installed after the gateway starts, the gateway won’t have access to it until restarted. We recommend installing Brave as your automation browser. Brave is Chromium-based, so it works seamlessly with agent-browser, and includes built-in ad blocking and privacy features that make automation cleaner and faster. 
# macOS
brew install --cask brave-browser

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

# Windows
winget install Brave.Brave