fix(#248): ARM64 Linux auto-fallback to Firefox + --browser CLI flag

cli/src/commands.rs

@@ -1544,6 +1544,7 @@ mod tests {
             cli_proxy: false,
             cli_proxy_bypass: false,
             cli_allow_file_access: false,
+            cli_browser: false,
         }
     }
 

cli/src/connection.rs

@@ -220,6 +220,7 @@ pub fn ensure_daemon(
     provider: Option<&str>,
     device: Option<&str>,
     session_name: Option<&str>,
+    browser: Option<&str>,
 ) -> Result<DaemonResult, String> {
     // Check if daemon is running AND responsive
     if is_daemon_running(session) && daemon_ready(session) {
@@ -364,6 +365,10 @@ pub fn ensure_daemon(
             cmd.env("AGENT_BROWSER_SESSION_NAME", sn);
         }
 
+        if let Some(b) = browser {
+            cmd.env("AGENT_BROWSER_BROWSER", b);
+        }
+
         // Create new process group and session to fully detach
         unsafe {
             cmd.pre_exec(|| {
@@ -447,6 +452,10 @@ pub fn ensure_daemon(
             cmd.env("AGENT_BROWSER_SESSION_NAME", sn);
         }
 
+        if let Some(b) = browser {
+            cmd.env("AGENT_BROWSER_BROWSER", b);
+        }
+
         // CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS
         const CREATE_NEW_PROCESS_GROUP: u32 = 0x00000200;
         const DETACHED_PROCESS: u32 = 0x00000008;

cli/src/flags.rs

@@ -17,6 +17,7 @@ pub struct Flags {
     pub args: Option<String>,
     pub user_agent: Option<String>,
     pub provider: Option<String>,
+    pub browser: Option<String>,
     pub ignore_https_errors: bool,
     pub allow_file_access: bool,
     pub device: Option<String>,
@@ -34,6 +35,7 @@ pub struct Flags {
     pub cli_proxy: bool,
     pub cli_proxy_bypass: bool,
     pub cli_allow_file_access: bool,
+    pub cli_browser: bool,
 }
 
 pub fn parse_flags(args: &[String]) -> Flags {
@@ -64,6 +66,7 @@ pub fn parse_flags(args: &[String]) -> Flags {
         args: env::var("AGENT_BROWSER_ARGS").ok(),
         user_agent: env::var("AGENT_BROWSER_USER_AGENT").ok(),
         provider: env::var("AGENT_BROWSER_PROVIDER").ok(),
+        browser: env::var("AGENT_BROWSER_BROWSER").ok(),
         ignore_https_errors: false,
         allow_file_access: env::var("AGENT_BROWSER_ALLOW_FILE_ACCESS").is_ok(),
         device: env::var("AGENT_BROWSER_IOS_DEVICE").ok(),
@@ -79,6 +82,7 @@ pub fn parse_flags(args: &[String]) -> Flags {
         cli_proxy: false,
         cli_proxy_bypass: false,
         cli_allow_file_access: false,
+        cli_browser: false,
     };
 
     let mut i = 0;
@@ -168,6 +172,13 @@ pub fn parse_flags(args: &[String]) -> Flags {
                     i += 1;
                 }
             }
+            "--browser" => {
+                if let Some(b) = args.get(i + 1) {
+                    flags.browser = Some(b.clone());
+                    flags.cli_browser = true;
+                    i += 1;
+                }
+            }
             "--ignore-https-errors" => flags.ignore_https_errors = true,
             "--allow-file-access" => {
                 flags.allow_file_access = true;
@@ -224,6 +235,7 @@ pub fn clean_args(args: &[String]) -> Vec<String> {
         "--provider",
         "--device",
         "--session-name",
+        "--browser",
     ];
 
     for arg in args.iter() {

cli/src/main.rs

@@ -226,6 +226,7 @@ fn main() {
         flags.provider.as_deref(),
         flags.device.as_deref(),
         flags.session_name.as_deref(),
+        flags.browser.as_deref(),
     ) {
         Ok(result) => result,
         Err(e) => {
@@ -281,6 +282,11 @@ fn main() {
             },
             flags.ignore_https_errors.then_some("--ignore-https-errors"),
             flags.cli_allow_file_access.then_some("--allow-file-access"),
+            if flags.cli_browser {
+                Some("--browser")
+            } else {
+                None
+            },
         ]
         .into_iter()
         .flatten()

src/browser.ts

@@ -1144,18 +1144,23 @@ export class BrowserManager {
       return;
     }
 
-    const browserType = options.browser ?? 'chromium';
-    if (hasExtensions && browserType !== 'chromium') {
+    let effectiveBrowser = options.browser ?? 'chromium';
+    // Auto-fallback to Firefox on ARM64 Linux where Chromium is unavailable
+    if (effectiveBrowser === 'chromium' && process.arch === 'arm64' && process.platform === 'linux') {
+      effectiveBrowser = 'firefox';
+      this.launchWarnings.push('Chromium unavailable on ARM64 Linux; using Firefox instead');
+    }
+    if (hasExtensions && effectiveBrowser !== 'chromium') {
       throw new Error('Extensions are only supported in Chromium');
     }
 
     // allowFileAccess is only supported in Chromium
-    if (options.allowFileAccess && browserType !== 'chromium') {
+    if (options.allowFileAccess && effectiveBrowser !== 'chromium') {
       throw new Error('allowFileAccess is only supported in Chromium');
     }
 
     const launcher =
-      browserType === 'firefox' ? firefox : browserType === 'webkit' ? webkit : chromium;
+      effectiveBrowser === 'firefox' ? firefox : effectiveBrowser === 'webkit' ? webkit : chromium;
     const viewport = options.viewport ?? { width: 1280, height: 720 };
 
     // Build base args array with file access flags if enabled

src/daemon.ts

@@ -417,6 +417,7 @@ export async function startDaemon(options?: {
 
               const ignoreHTTPSErrors = process.env.AGENT_BROWSER_IGNORE_HTTPS_ERRORS === '1';
               const allowFileAccess = process.env.AGENT_BROWSER_ALLOW_FILE_ACCESS === '1';
+              const browserType = process.env.AGENT_BROWSER_BROWSER as 'chromium' | 'firefox' | 'webkit' | undefined;
               await manager.launch({
                 id: 'auto',
                 action: 'launch' as const,
@@ -430,6 +431,7 @@ export async function startDaemon(options?: {
                 proxy,
                 ignoreHTTPSErrors: ignoreHTTPSErrors,
                 allowFileAccess: allowFileAccess,
+                browser: browserType,
                 autoStateFilePath: getSessionAutoStatePath(),
               });
             }