Skip to content

[codex] improve Linux setup documentation - #2272

Open
Yazington wants to merge 1 commit into
get-bb:mainfrom
Yazington:codex/improve-linux-install-docs
Open

[codex] improve Linux setup documentation#2272
Yazington wants to merge 1 commit into
get-bb:mainfrom
Yazington:codex/improve-linux-install-docs

Conversation

@Yazington

Copy link
Copy Markdown

What was wrong

The top-level documentation identifies Linux as supported, but it does not explain how the AppImage becomes a clickable desktop application or make the boundary between a desktop install, an npx server, and an enrolled execution machine explicit. FUSE, systemd, stale-service, and cleanup guidance is scattered or maintainer-focused, which makes a successful Add machine enrollment easy to mistake for a UI installation.

What changed

  • Added an end-user Linux guide that starts with a setup-selection table.
  • Documented x64 AppImage installation, distro-specific FUSE 2 packages, and a stable per-user application-menu launcher.
  • Documented the requirements and lifecycle of npx bb-app and Add machine installations.
  • Added systemd verification, 203/EXEC diagnosis, headless lingering guidance, browser-app guidance, and safe replacement/removal steps.
  • Linked the guide from the root README, the bb-app package guide, and the desktop maintainer guide.

This is documentation-only; there are no protocol, runtime, or CLI changes.

How you verified

  • corepack pnpm dlx prettier@3.8.3 --check README.md docs/linux.md packages/bb-app/README.md apps/desktop/README.md
  • git diff --check
  • Checked that all relative Markdown links in the four changed files resolve.
  • Parsed the application-launcher shell block with bash -n.
  • Confirmed libfuse2t64 is available on Ubuntu 24.04 and checked the other FUSE package names against their official distro package indexes.

Fixes

No linked issue.

AGENT GENERATED

@Yazington
Yazington marked this pull request as ready for review August 22, 2026 02:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant