Extension Setup

The Chrome extension enables browser automation — clicking, typing, scrolling, and extracting data from web pages.

Installation

Install from Chrome Web Store

After installing, pin the extension:

1. Click the puzzle piece icon in Chrome's toolbar
2. Find "SideButton" and click the pin icon
3. The extension icon should now be visible in your toolbar

Connect a Tab

1. Navigate to any website (e.g., wikipedia.org)
2. Click the extension icon in your toolbar
3. Click "Connect This Tab"

The popup should show "Connected" status.

Verify Connection

Check the connection status in the dashboard:

1. Open http://localhost:9876
2. Look for the green "Browser Connected" indicator in the sidebar

Or use the health endpoint:

curl http://localhost:9876/health

Expected response with extension connected:

{
  "status": "ok",
  "browser_connected": true,
  "tab_id": 123456
}

How It Works

┌──────────────┐     WebSocket      ┌──────────────┐
│   Server     │◄──────────────────►│  Extension   │
│  (port 9876) │                    │  (Chrome)    │
└──────────────┘                    └──────────────┘

The extension:

• Connects via WebSocket to the local server
• Executes browser commands (click, type, scroll, extract)
• Captures recordings when you record actions
• Injects embed buttons into pages based on workflow config

Extension Permissions

The extension requests these permissions:

Permission	Why It's Needed
activeTab	Access current tab for automation
scripting	Inject content scripts for DOM operations
tabs	Navigate and manage tabs
debugger	Use Chrome DevTools Protocol for reliable automation
storage	Save connection state
<all_urls>	Work on any website

Privacy Note

All automation runs locally on your computer. The extension only communicates with your local server (localhost:9876), never with external servers.

Troubleshooting

Extension not connecting

1. Is the server running? Check http://localhost:9876
2. Refresh the page and click "Connect This Tab" again
3. Check the console — Right-click extension icon → "Inspect popup" → Console

"Connect This Tab" button doesn't appear

Make sure:

• You're on a regular webpage (not a restricted page — see below)
• The extension is enabled in chrome://extensions/
• Developer mode is on

Restricted Pages

Chrome blocks all extensions from operating on certain URLs. SideButton cannot connect, inject content scripts, or automate these pages:

URL Pattern	Description
chrome://*	Chrome internal pages
chrome-extension://*	Other extensions' pages
devtools://*	Chrome DevTools
chrome-search://*	New Tab Page
chrome-untrusted://*	Sandboxed Chrome content
chrome-distiller://*	Reader mode pages
view-source:*	View source pages
chromewebstore.google.com/*	Chrome Web Store
about:*	About pages
edge://*	Edge internal pages

file:// URLs require opt-in: enable "Allow access to file URLs" in chrome://extensions/ for SideButton.

For the full list and workarounds, see Troubleshooting > Restricted Pages.

Automation not working on specific site

Some sites block automation. Check:

• The site's Content Security Policy
• If you're logged in (some actions require auth)
• The selector is correct (use capture_page to find selectors)

Next Steps

1. Run Your First Workflow — See browser automation in action
2. Recording Mode — Create workflows by clicking
3. Embed Buttons — Add automation buttons to pages