Support overriding Chrome binary via IBEAM_CHROME_BINARY_PATH (+ --disable-dev-shm-usage)

[Srain021]

Problem

On hosts where Google Chrome is not available (for example aarch64 Linux, which does not have an official Google Chrome build), IBeam cannot start the browser even though a compatible Chromium build is installed. I hit this on a Debian bookworm container running on aarch64 hardware: stock voyz/ibeam:0.5.11 with the default Chrome path crashes during renderer initialization, while the Debian-packaged Chromium binary works correctly from the same image.

There is no existing IBeam env var to point Selenium at an alternative browser binary, so the only workaround today is to vendor IBeam and patch driver.py locally.

Fix

Two related changes in ibeam/src/login/driver.py and ibeam/src/var.py:

1. Add a new optional env var IBEAM_CHROME_BINARY_PATH. When set, it is passed to Selenium as options.binary_location. When unset, Selenium's default Chrome lookup is preserved, so this change is opt-in and does not affect existing deployments.
2. Add --disable-dev-shm-usage to the Chrome options unconditionally. It avoids /dev/shm sizing limits inside containers (a common Selenium-in-Docker recommendation) and is benign otherwise.

The new env var follows the same pattern as the existing IBEAM_CHROME_DRIVER_PATH.

Testing

Tested on aarch64 Linux (Debian bookworm-slim) with apt install chromium chromium-driver:

• IBEAM_CHROME_BINARY_PATH=/usr/bin/chromium + IBEAM_CHROME_DRIVER_PATH=/usr/bin/chromedriver
• Headless login completed successfully
• TOTP auto-entry worked
• Session persisted across container restarts

Without IBEAM_CHROME_BINARY_PATH set, behavior is identical to the pre-patch state.

Open Questions

1. Is the unconditional --disable-dev-shm-usage acceptable, or would you prefer it gated behind a separate env var (e.g. IBEAM_DISABLE_DEV_SHM_USAGE)?
2. The env var name IBEAM_CHROME_BINARY_PATH mirrors IBEAM_CHROME_DRIVER_PATH. Happy to rename if a different convention is preferred.
3. Should this include a README / env.list.example update for discoverability, or would you rather keep the patch minimal and update docs separately?

[Voyz]

Hey @Srain021 - great contribution, I appreciate you spotting this issue and proposing a fix. Also appreciate the details and the questions.

To address them:

1. Is the unconditional --disable-dev-shm-usage acceptable, or would you prefer it gated behind a separate env var (e.g. IBEAM_DISABLE_DEV_SHM_USAGE)?

I think it would be reasonable to add IBEAM_DISABLE_DEV_SHM_USAGE and make it opt-in only.

2. The env var name IBEAM_CHROME_BINARY_PATH mirrors IBEAM_CHROME_DRIVER_PATH. Happy to rename if a different convention is preferred.

Very much in line, fantastic choice 👍

3. Should this include a README / env.list.example update for discoverability, or would you rather keep the patch minimal and update docs separately?

The documentation currently lives in the WiKi, hence if you could write a small section for Troubleshooting we could include it there: https://github.com/Voyz/ibeam/wiki/Troubleshooting

[Srain021]

Apologies for the slow turnaround — this is my first time contributing to an open-source project, so it took me a bit to work through the review carefully. Thanks for your patience!

---

Pushed 6dedd6b addressing all three points:

1. ✅ Added IBEAM_DISABLE_DEV_SHM_USAGE (default False). The --disable-dev-shm-usage flag is now only applied when this is set, so existing users see no behavioural change.
2. ✅ Kept IBEAM_CHROME_BINARY_PATH as is.
3. 📝 Drafted the Wiki snippet below — let me know if you'd like edits before you publish it to the Troubleshooting page.

---

Suggested Wiki addition (Troubleshooting → "Browser fails to start")

Symptom: IBeam fails on startup with errors such as unknown error: cannot find Chrome binary, session not created: This version of ChromeDriver only supports Chrome version X, or DevToolsActivePort file doesn't exist / Chrome crashing immediately.

Two opt-in environment variables can help:

IBEAM_CHROME_BINARY_PATH

Overrides the browser binary location passed to Selenium. Useful when:

• Google Chrome is not available on the host but a compatible Chromium build is — for example on aarch64 Linux, where Debian/Ubuntu ship chromium (/usr/bin/chromium) instead of google-chrome.
• You want to pin to a specific Chromium build for reproducibility.

Example:

IBEAM_CHROME_BINARY_PATH=/usr/bin/chromium

When unset, Selenium's default Chrome lookup is used, so existing setups are unaffected.

IBEAM_DISABLE_DEV_SHM_USAGE

When set to True, IBeam passes --disable-dev-shm-usage to Chrome. This is the standard Selenium-in-Docker workaround for environments where /dev/shm is too small (default 64 MB in many container runtimes), which causes Chrome to crash with errors like DevToolsActivePort file doesn't exist or "session deleted because of page crash".

Common scenarios:

• Running IBeam under Docker / Podman without --shm-size
• Kubernetes pods using the default emptyDir for /dev/shm
• CI runners (GitHub Actions, GitLab CI) with restricted shared memory

Example:

IBEAM_DISABLE_DEV_SHM_USAGE=True

Alternatively, if you prefer not to use this flag, you can size /dev/shm directly when launching the container, e.g. docker run --shm-size=2g ….

[Voyz]

Hey @Srain021 - appreciate you making adjustments. And it's not a slow turnaround at all - you're welcome to take your time with this.

The Troubleshoot wiki addition has been very obviously written by an AI. Please go through it and tidy it up and I'll be happy to add it in.

[Srain021]

Fair point — rewritten. Let me know if this reads better:

---

Chrome binary not found**

On hosts without Google Chrome in the default location (e.g. aarch64 Linux where Debian ships chromium instead of google-chrome), point IBeam at your binary:

IBEAM_CHROME_BINARY_PATH=/usr/bin/chromium

Chrome crashes in a container

DevToolsActivePort file doesn't exist or "session deleted because of page crash" inside Docker/K8s usually means Chrome ran out of shared memory — /dev/shm defaults to 64 MB, which is too small. Either bump it (docker run --shm-size=2g …) or set IBEAM_DISABLE_DEV_SHM_USAGE=True so Chrome falls back to /tmp.