From d883fb6b06578ab789178fca384418d1cd176c2a Mon Sep 17 00:00:00 2001 From: Atlas Date: Tue, 27 Jan 2026 14:24:31 -0800 Subject: [PATCH] feat(browser): add chromeFlags support for browser profiles Adds support for custom Chrome command-line flags via browser profile configuration. This enables users to: - Bypass automation detection when using browser extensions - Enable experimental Chrome features - Adjust performance/security settings - Work around site compatibility issues Usage: { "browser": { "profiles": { "stealth": { "chromeFlags": [ "--disable-blink-features=AutomationControlled", "--disable-features=IsolateOrigins,site-per-process" ] } } } } Changes: - Add chromeFlags?: string[] to BrowserProfileConfig type - Pass chromeFlags through config resolution - Apply flags in launchClawdChrome() - Add comprehensive documentation with examples Fixes compatibility issues with password managers, SSO extensions, web wallets, and other browser extensions that fail when Chrome detects automation. --- docs/browser-chrome-flags-example.md | 268 +++++++++++++++++++++++++++ src/browser/chrome.ts | 5 + src/browser/config.ts | 2 + src/config/types.browser.ts | 2 + 4 files changed, 277 insertions(+) create mode 100644 docs/browser-chrome-flags-example.md diff --git a/docs/browser-chrome-flags-example.md b/docs/browser-chrome-flags-example.md new file mode 100644 index 000000000..40b9d5fa5 --- /dev/null +++ b/docs/browser-chrome-flags-example.md @@ -0,0 +1,268 @@ +# Browser Chrome Flags Configuration + +## Overview + +You can add custom Chrome command-line flags to browser profiles via the `chromeFlags` configuration option. This is useful for: + +- Bypassing automation detection when using browser extensions +- Enabling experimental Chrome features +- Adjusting performance or security settings +- Working around specific site compatibility issues + +## Configuration + +Add `chromeFlags` to any browser profile in your `moltbot.json`: + +```json +{ + "browser": { + "enabled": true, + "profiles": { + "stealth": { + "chromeFlags": [ + "--disable-blink-features=AutomationControlled", + "--disable-features=IsolateOrigins,site-per-process", + "--disable-site-isolation-trials" + ] + } + } + } +} +``` + +## Common Use Cases + +### 1. Stealth Mode (Bypass Automation Detection) + +**Problem:** Some websites detect browser automation and block functionality or show CAPTCHAs. + +**Solution:** +```json +{ + "browser": { + "profiles": { + "stealth": { + "chromeFlags": [ + "--disable-blink-features=AutomationControlled", + "--disable-features=IsolateOrigins,site-per-process", + "--disable-site-isolation-trials" + ] + } + } + } +} +``` + +**Use with:** Sites that require browser extensions (password managers, auth extensions, web wallets) + +### 2. Working with Browser Extensions + +**Problem:** Browser extensions (password managers, SSO, etc.) may be blocked when Chrome detects automation. + +**Solution:** +```json +{ + "browser": { + "profiles": { + "extensions": { + "chromeFlags": [ + "--disable-blink-features=AutomationControlled" + ] + } + } + } +} +``` + +**Examples:** +- 1Password browser extension + automation +- Okta/Azure AD SSO extensions +- VPN browser extensions +- Development tools (React DevTools, Vue DevTools) + +### 3. Performance Tuning + +**Problem:** Chrome uses too much memory or CPU during automation. + +**Solution:** +```json +{ + "browser": { + "profiles": { + "lightweight": { + "chromeFlags": [ + "--disable-gpu", + "--disable-software-rasterizer", + "--disable-dev-shm-usage", + "--disable-extensions" + ] + } + } + } +} +``` + +### 4. Development & Debugging + +**Problem:** Need to enable Chrome flags for testing or development. + +**Solution:** +```json +{ + "browser": { + "profiles": { + "dev": { + "chromeFlags": [ + "--auto-open-devtools-for-tabs", + "--enable-logging", + "--v=1" + ] + } + } + } +} +``` + +## Security Considerations + +⚠️ **Important:** Some Chrome flags reduce browser security protections. + +**Flags that reduce security:** +- `--disable-blink-features=AutomationControlled` - Disables automation detection (makes browser more vulnerable to automated attacks) +- `--disable-features=IsolateOrigins,site-per-process` - Disables site isolation (reduces protection against malicious sites) +- `--disable-web-security` - **NEVER USE** - Completely disables web security +- `--no-sandbox` - **DANGEROUS** - Disables Chrome's security sandbox + +**Best Practices:** +1. Only use flags you understand +2. Only enable stealth mode when necessary (e.g., when extensions are required) +3. Use separate profiles for sensitive work +4. Document why each flag is needed +5. Regularly review your configuration + +## Complete Example + +```json +{ + "browser": { + "enabled": true, + "defaultProfile": "normal", + "profiles": { + "normal": { + "cdpPort": 9222, + "color": "#FF4500" + }, + "stealth": { + "cdpPort": 9223, + "color": "#00AA00", + "chromeFlags": [ + "--disable-blink-features=AutomationControlled", + "--disable-features=IsolateOrigins,site-per-process" + ] + }, + "dev": { + "cdpPort": 9224, + "color": "#0000FF", + "chromeFlags": [ + "--auto-open-devtools-for-tabs", + "--enable-logging" + ] + } + } + } +} +``` + +**Usage:** +```bash +# Use normal profile (default) +moltbot browser open https://example.com + +# Use stealth profile for sites requiring extensions +moltbot browser open https://example.com --profile stealth + +# Use dev profile for debugging +moltbot browser open https://example.com --profile dev +``` + +## Available Chrome Flags + +Chrome supports hundreds of command-line flags. Here are some commonly useful ones: + +### Automation & Detection +- `--disable-blink-features=AutomationControlled` - Hide automation detection +- `--disable-infobars` - Hide "Chrome is being controlled" banner + +### Performance +- `--disable-gpu` - Disable GPU acceleration (useful in headless/containers) +- `--disable-dev-shm-usage` - Reduce shared memory usage (Linux containers) +- `--disk-cache-size=0` - Disable disk cache +- `--media-cache-size=0` - Disable media cache + +### Features +- `--disable-features=Translate` - Disable Google Translate +- `--enable-features=NetworkService` - Enable network service +- `--disable-extensions` - Disable all extensions + +### Debugging +- `--auto-open-devtools-for-tabs` - Auto-open DevTools +- `--enable-logging` - Enable Chrome logging +- `--v=1` - Verbose logging level + +### Display +- `--window-size=1920,1080` - Set window size +- `--start-maximized` - Start maximized +- `--start-fullscreen` - Start in fullscreen + +**Full list:** Run `chrome --help` or see [Chromium Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches/) + +## Troubleshooting + +### Flags not working? +1. Check flag spelling (flags are case-sensitive) +2. Verify Chrome version supports the flag (some flags are version-specific) +3. Check logs for errors: `moltbot browser serve --verbose` +4. Try flags individually to isolate issues + +### Chrome won't start? +1. Check for conflicting flags +2. Remove flags one by one to find the problematic one +3. Check Chrome version compatibility +4. Verify you're not using deprecated flags + +### Still seeing "Chrome is being controlled"? +This is normal behavior. The `--disable-blink-features=AutomationControlled` flag prevents JavaScript detection, but the Chrome UI banner may still appear. Most sites only check JavaScript, so this is usually fine. + +## Migration from Manual Chrome Launch + +If you were previously launching Chrome manually with flags, you can now move them to the config: + +**Before:** +```bash +/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \ + --disable-blink-features=AutomationControlled \ + --user-data-dir="/path/to/profile" +``` + +**After:** +```json +{ + "browser": { + "profiles": { + "myprofile": { + "chromeFlags": [ + "--disable-blink-features=AutomationControlled" + ] + } + } + } +} +``` + +Then use: `moltbot browser open --profile myprofile` + +## Related Documentation + +- [Browser Tool Documentation](https://docs.molt.bot/tools/browser) +- [Browser Configuration Reference](https://docs.molt.bot/gateway/configuration#browser) +- [Security Best Practices](https://docs.molt.bot/gateway/security) diff --git a/src/browser/chrome.ts b/src/browser/chrome.ts index 6f610bcc4..f504697a2 100644 --- a/src/browser/chrome.ts +++ b/src/browser/chrome.ts @@ -204,6 +204,11 @@ export async function launchClawdChrome( args.push("--disable-dev-shm-usage"); } + // Add custom Chrome flags from profile config (e.g., for stealth mode, experimental features) + if (profile.chromeFlags && profile.chromeFlags.length > 0) { + args.push(...profile.chromeFlags); + } + // Always open a blank tab to ensure a target exists. args.push("about:blank"); diff --git a/src/browser/config.ts b/src/browser/config.ts index c5dd0673d..fd90108a4 100644 --- a/src/browser/config.ts +++ b/src/browser/config.ts @@ -40,6 +40,7 @@ export type ResolvedBrowserProfile = { cdpIsLoopback: boolean; color: string; driver: "clawd" | "extension"; + chromeFlags?: string[]; }; function isLoopbackHost(host: string) { @@ -253,6 +254,7 @@ export function resolveProfile( cdpIsLoopback: isLoopbackHost(cdpHost), color: profile.color, driver, + chromeFlags: profile.chromeFlags, }; } diff --git a/src/config/types.browser.ts b/src/config/types.browser.ts index d8678b80b..8e8004243 100644 --- a/src/config/types.browser.ts +++ b/src/config/types.browser.ts @@ -7,6 +7,8 @@ export type BrowserProfileConfig = { driver?: "clawd" | "extension"; /** Profile color (hex). Auto-assigned at creation. */ color: string; + /** Additional Chrome command-line flags for this profile. Use to bypass automation detection or enable experimental features. */ + chromeFlags?: string[]; }; export type BrowserSnapshotDefaults = { /** Default snapshot mode (applies when mode is not provided). */