docs(cef): document Linux shell fallback

[aqilaziz]

Summary

• add a Linux CEF troubleshooting section for startup crashes like X BadWindow
• document the external core + Vite browser fallback for development
• call out which native shell features are bypassed by that workaround

Refs #2094

Testing

• git diff --check

Summary by CodeRabbit

• Documentation
  • Added new troubleshooting documentation for Linux users encountering CEF startup crashes, with detailed information about potential Wayland and NVIDIA graphics compatibility issues that may cause failures
  • Provided clear instructions for alternative deployment using separate core and frontend processes with RPC URL configuration to maintain full functionality while bypassing platform-specific native dependencies

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 26ec9d27-c593-4c25-8ab7-e0e49badfc11

📥 Commits

Reviewing files that changed from the base of the PR and between 369a392 and 3b4b285.

📒 Files selected for processing (1)

• gitbooks/developing/cef.md

---

📝 Walkthrough

Walkthrough

A new documentation section was added to the CEF development guide describing a Linux shell fallback workflow for CEF startup crashes likely caused by Wayland/NVIDIA interactions. The section provides step-by-step instructions to run the core and frontend in separate terminals and configure the frontend to connect to the core's RPC endpoint.

Changes

CEF Linux Fallback Documentation

Layer / File(s)	Summary
Linux shell fallback for CEF startup crashes gitbooks/developing/cef.md	New troubleshooting section with symptoms, a two-terminal development workflow to run core and frontend independently, and instructions to open the Vite URL in advanced/remote core mode pointing to the core RPC URL and bearer token.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 When CEF crashes on Wayland's shore,
Two terminals fix what one can't restore,
Core speaks RPC, frontend listens in,
NVIDIA's woes? This trick will win! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs(cef): document Linux shell fallback' is directly and specifically related to the main change—adding documentation about a Linux shell fallback for CEF startup crashes. It accurately summarizes the primary objective of the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[graycyrus]

Nice docs addition — clean write-up of a real pain point for Linux NVIDIA users. One small accuracy nit below, otherwise LGTM.

File	+/−
gitbooks/developing/cef.md	+20

[graycyrus]

[minor] The actual UI label is "Run on the Cloud (Complex)" (see bootCheck.cloudMode in app/src/lib/i18n/en.ts), not "Advanced / remote core mode." A user following these steps would look for an option that doesn't exist.

Suggestion:

Open the Vite URL in a regular browser, choose **Run on the Cloud (Complex)**, set the RPC URL to `http://127.0.0.1:7788/rpc`, and paste the bearer token written by the core to `~/.openhuman/core.token`.

[graycyrus]

Looks good, nice work!