162 lines
3.9 KiB
Markdown
162 lines
3.9 KiB
Markdown
# Browserbase Cloud Setup
|
|
|
|
Configure agent-browser to use Browserbase cloud browsers for CI/CD and headless environments.
|
|
|
|
## Overview
|
|
|
|
Browserbase provides remote browser infrastructure. Use when:
|
|
- Running in CI/CD pipelines
|
|
- Local browser not available
|
|
- Need consistent browser environment
|
|
- Scaling parallel browser sessions
|
|
|
|
## Account Setup
|
|
|
|
1. Sign up at [browserbase.com](https://browserbase.com)
|
|
2. Create a project
|
|
3. Get API key from dashboard
|
|
4. Note your project ID
|
|
|
|
## Environment Variables
|
|
|
|
```bash
|
|
# Required
|
|
export BROWSERBASE_API_KEY="bb_live_xxxxxxxxxxxxx"
|
|
export BROWSERBASE_PROJECT_ID="proj_xxxxxxxxxxxxx"
|
|
|
|
# Optional: set provider default
|
|
export AGENT_BROWSER_PROVIDER="browserbase"
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Explicit Provider Flag
|
|
```bash
|
|
agent-browser -p browserbase open https://example.com
|
|
agent-browser snapshot -i
|
|
agent-browser click @e1
|
|
agent-browser close
|
|
```
|
|
|
|
### With Default Provider (env var)
|
|
```bash
|
|
# After setting AGENT_BROWSER_PROVIDER=browserbase
|
|
agent-browser open https://example.com # Uses Browserbase automatically
|
|
```
|
|
|
|
## CI/CD Integration
|
|
|
|
### GitHub Actions
|
|
```yaml
|
|
name: Browser Tests
|
|
on: [push]
|
|
|
|
jobs:
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
|
|
- name: Setup Node
|
|
uses: actions/setup-node@v4
|
|
with:
|
|
node-version: '20'
|
|
|
|
- name: Install agent-browser
|
|
run: npm install -g agent-browser
|
|
|
|
- name: Run browser tests
|
|
env:
|
|
BROWSERBASE_API_KEY: ${{ secrets.BROWSERBASE_API_KEY }}
|
|
BROWSERBASE_PROJECT_ID: ${{ secrets.BROWSERBASE_PROJECT_ID }}
|
|
AGENT_BROWSER_PROVIDER: browserbase
|
|
run: |
|
|
agent-browser open https://example.com
|
|
agent-browser snapshot -i
|
|
agent-browser screenshot -o screenshot.png
|
|
agent-browser close
|
|
|
|
- name: Upload artifacts
|
|
uses: actions/upload-artifact@v4
|
|
with:
|
|
name: screenshots
|
|
path: screenshot.png
|
|
```
|
|
|
|
### GitLab CI
|
|
```yaml
|
|
browser-test:
|
|
image: node:20
|
|
variables:
|
|
AGENT_BROWSER_PROVIDER: browserbase
|
|
script:
|
|
- npm install -g agent-browser
|
|
- agent-browser open https://example.com
|
|
- agent-browser snapshot -i
|
|
- agent-browser close
|
|
artifacts:
|
|
paths:
|
|
- "*.png"
|
|
```
|
|
|
|
## Session Management
|
|
|
|
Browserbase sessions are managed automatically. Each `open` creates a new session, `close` terminates it.
|
|
|
|
```bash
|
|
# Long-running session
|
|
agent-browser -p browserbase open https://example.com
|
|
# ... many commands ...
|
|
agent-browser close # Terminates Browserbase session
|
|
```
|
|
|
|
## Parallel Sessions
|
|
|
|
Use named sessions for parallel browser instances:
|
|
|
|
```bash
|
|
# Session 1
|
|
agent-browser -p browserbase --session user1 open https://example.com
|
|
|
|
# Session 2 (separate terminal/process)
|
|
agent-browser -p browserbase --session user2 open https://example.com
|
|
```
|
|
|
|
## Debugging
|
|
|
|
### View Session Logs
|
|
Check Browserbase dashboard for:
|
|
- Session recordings
|
|
- Network logs
|
|
- Console output
|
|
- Screenshots
|
|
|
|
### Local Fallback
|
|
If Browserbase unavailable, remove provider flag to use local browser:
|
|
```bash
|
|
agent-browser open https://example.com # Uses local Chromium
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
| Issue | Solution |
|
|
|-------|----------|
|
|
| Authentication failed | Verify API key is correct and not expired |
|
|
| Project not found | Check BROWSERBASE_PROJECT_ID matches dashboard |
|
|
| Connection timeout | Check network/firewall allows outbound connections |
|
|
| Session limit reached | Upgrade Browserbase plan or wait for sessions to expire |
|
|
| Commands hang | Ensure previous session closed properly |
|
|
|
|
## Pricing Considerations
|
|
|
|
- Browserbase charges per session minute
|
|
- Close sessions promptly with `agent-browser close`
|
|
- Use local browser for development, cloud for CI/CD
|
|
- Monitor usage in Browserbase dashboard
|
|
|
|
## Resources
|
|
|
|
- [Browserbase Documentation](https://docs.browserbase.com/)
|
|
- [Browserbase Dashboard](https://browserbase.com/dashboard)
|
|
- [agent-browser GitHub](https://github.com/vercel-labs/agent-browser)
|