Skip to content

Add Linux-first runtime and systemd deployment support - #618

Open
edmen12 wants to merge 3 commits into
wonderwhy-er:mainfrom
edmen12:feat/linux-first-runtime
Open

Add Linux-first runtime and systemd deployment support#618
edmen12 wants to merge 3 commits into
wonderwhy-er:mainfrom
edmen12:feat/linux-first-runtime

Conversation

@edmen12

@edmen12 edmen12 commented Aug 1, 2026

Copy link
Copy Markdown

Summary

Adds Linux-first runtime support for Desktop Commander across local MCP usage and headless remote-device deployments.

What changed

  • Added a shared platform runtime abstraction for Windows, macOS, and Linux shell/browser behavior.
  • Added native Linux/macOS process enumeration using ps, while preserving the Windows CIM implementation.
  • Made list_processes safe by default: command-line arguments are opt-in, paginated, truncated, and sensitive values are redacted.
  • Added a systemd service template and installer for headless Linux deployments.
  • Added root safeguards, service-name validation, absolute executable validation, temporary unit generation, and systemd-analyze verify before installation.
  • Added headless authentication behavior that prints authorization details instead of trying to open a browser.
  • Added Linux documentation and packaged deployment assets.
  • Raised the supported Node.js baseline to Node 20 because locked runtime dependencies require Node 20 or newer.
  • Added Ubuntu 22.04/24.04 and Debian 12 CI coverage for Node 20/22, ripgrep availability, process behavior, installer generation, and systemd validation.

Why

Desktop Commander previously relied on platform assumptions centered on Windows and macOS. Linux servers and VPS environments need native shell selection, safe process inspection, headless authorization, and a supervised service lifecycle without granting root access by default.

User impact

Linux users can run Desktop Commander as a local MCP server or a persistent headless remote device using systemd. Existing Windows and macOS behavior remains supported, while process output is now safer and bounded across all platforms.

Validation

  • npm run build — passed
  • npm run test:linux — passed
  • Bash syntax validation for the installer — passed
  • Windows live process enumeration, pagination, argument opt-in, redaction, and truncation — passed
  • npm package dry run confirmed Linux service assets are included
  • Full test suite: 46/47 passed

The only failing test is the existing test-enhanced-repl.js Windows Python PATH detection test, which reports that neither python3 nor python is available despite Python being installed. No newly added Linux or process-safety tests failed.

Summary by CodeRabbit

  • New Features
    • Added Linux desktop and headless deployment support, including systemd service installation and management.
    • Added cross-platform process listing with pagination, detailed metadata, optional arguments, and sensitive-data redaction.
    • Added automatic headless-environment detection and safer browser-launch behavior.
  • Documentation
    • Added Linux setup, runtime, service security, and remote-device guidance.
  • Bug Fixes
    • Improved default shell detection and process-listing validation.
  • Chores
    • Updated the minimum supported Node.js version to 20.
    • Added automated Linux compatibility and service installation checks.

@coderabbitai

coderabbitai Bot commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0971dade-7629-4de8-b6b5-d4a268cc2aa9

📥 Commits

Reviewing files that changed from the base of the PR and between 05c4267 and 6644477.

📒 Files selected for processing (2)
  • test/test-markdown-editor-edit-diff.js
  • test/test-markdown-editor-roundtrip.js

📝 Walkthrough

Walkthrough

The PR adds Linux runtime detection, cross-platform process inspection, systemd service installation, Linux documentation, and CI coverage. It also adds headless browser handling and raises the Node.js minimum version to 20.

Changes

Linux support

Layer / File(s) Summary
Runtime environment and platform adapters
src/platform/runtime.ts, src/config-manager.ts, src/utils/open-browser.ts, src/remote-device/device-authenticator.ts
Runtime helpers select shells and detect graphical or headless environments. Configuration and browser authentication use these helpers.
Cross-platform process listing
src/platform/processes.ts, src/tools/process.ts, src/tools/schemas.ts, src/handlers/process-handlers.ts, src/server.ts, test/test-linux-platform.js
Process listing supports normalized platform data, pagination, optional redacted arguments, bounded output, and structured errors.
Linux systemd service installation
deploy/linux/*, scripts/install-linux-service.sh, src/npm-scripts/linux-service.ts, src/index.ts, package.json, test/test-linux-service-installer.js
The CLI runs a validated installer that renders and installs a restricted systemd service with dry-run and startup options.
Linux validation and documentation
.github/workflows/linux-ci.yml, .gitattributes, LINUX.md, README.md, test/test-markdown-editor-edit-diff.js, test/test-markdown-editor-roundtrip.js
Linux CI runs platform and installer tests. Documentation covers setup, headless operation, systemd lifecycle, and security settings. Test bootstrap code initializes navigator when required.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant runLinuxServiceInstaller
  participant installLinuxService
  participant systemd
  CLI->>runLinuxServiceInstaller: Run linux-service command
  runLinuxServiceInstaller->>installLinuxService: Forward installer arguments
  installLinuxService->>systemd: Verify and install service unit
  systemd-->>installLinuxService: Return service status
  installLinuxService-->>runLinuxServiceInstaller: Return exit status
  runLinuxServiceInstaller-->>CLI: Report completion or error
Loading

Possibly related PRs

Suggested labels: size:XL

Suggested reviewers: wonderwhy-er

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 8.33% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main Linux runtime and systemd deployment changes in the pull request.
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.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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

Comment @coderabbitai help to get the list of available commands.

@edmen12
edmen12 marked this pull request as ready for review August 1, 2026 12:57

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Nitpick comments (1)
.github/workflows/linux-ci.yml (1)

26-26: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Disable persisted checkout credentials.

The workflow executes repository build and test code after checkout. Set persist-credentials: false on each checkout step because the workflow only needs read access during checkout.

  • .github/workflows/linux-ci.yml#L26-L26: add with: persist-credentials: false.
  • .github/workflows/linux-ci.yml#L47-L47: add with: persist-credentials: false.
  • .github/workflows/linux-ci.yml#L61-L61: add with: persist-credentials: false.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/linux-ci.yml at line 26, Disable persisted checkout
credentials on all three checkout steps in .github/workflows/linux-ci.yml at
lines 26-26, 47-47, and 61-61 by adding the checkout action’s with configuration
with persist-credentials set to false.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@LINUX.md`:
- Around line 93-98: Update the final journalctl command in the Linux
service-management instructions to invoke journalctl with sudo, while preserving
its existing service unit and time-filter arguments.

In `@src/platform/processes.ts`:
- Around line 93-104: Update the execFileAsync invocation in runPs to provide a
stable POSIX locale through its subprocess environment, using LC_ALL or
LC_NUMERIC set to C while preserving the existing options and output handling.

In `@src/tools/process.ts`:
- Around line 20-23: Extend SENSITIVE_FLAG_PATTERN and the redactProcessArgs
flow to recognize Windows-style sensitive switches using /name:value and /name
value forms, including command lines returned by listPlatformProcesses('win32').
Preserve existing hyphen-prefixed redaction and ensure sensitive values are
removed whenever includeArgs is true.

---

Nitpick comments:
In @.github/workflows/linux-ci.yml:
- Line 26: Disable persisted checkout credentials on all three checkout steps in
.github/workflows/linux-ci.yml at lines 26-26, 47-47, and 61-61 by adding the
checkout action’s with configuration with persist-credentials set to false.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 93ad690e-7b63-423c-bc70-3d46fda3f598

📥 Commits

Reviewing files that changed from the base of the PR and between 1eccc8b and 032cfa3.

⛔ Files ignored due to path filters (1)
  • package-lock.json is excluded by !**/package-lock.json
📒 Files selected for processing (20)
  • .gitattributes
  • .github/workflows/linux-ci.yml
  • LINUX.md
  • README.md
  • deploy/linux/desktop-commander-device.service.template
  • package.json
  • scripts/install-linux-service.sh
  • src/config-manager.ts
  • src/handlers/process-handlers.ts
  • src/index.ts
  • src/npm-scripts/linux-service.ts
  • src/platform/processes.ts
  • src/platform/runtime.ts
  • src/remote-device/device-authenticator.ts
  • src/server.ts
  • src/tools/process.ts
  • src/tools/schemas.ts
  • src/utils/open-browser.ts
  • test/test-linux-platform.js
  • test/test-linux-service-installer.js

Comment thread LINUX.md
Comment thread src/platform/processes.ts
Comment thread src/tools/process.ts
@edmen12

edmen12 commented Aug 1, 2026

Copy link
Copy Markdown
Author

Addressed all actionable CodeRabbit findings in 05c4267:\n\n- Disabled persisted checkout credentials in all Linux CI jobs.\n- Added sudo to the system journal command.\n- Forced LC_ALL=C for POSIX ps subprocesses.\n- Added Windows-style sensitive switch redaction, including /name:value, /name=value, /name value, /p, and /rp forms, with regression coverage.\n\nValidation: npm run test:linux passed; git diff --check passed.

@edmen12

edmen12 commented Aug 1, 2026

Copy link
Copy Markdown
Author

Fixed the failing Full Linux test suite in 6644477.

Root cause: the two jsdom-based Markdown editor tests imported Tiptap/ProseMirror without defining globalThis.navigator. Node 22 provides a global navigator, but the Node 20 Linux runner does not, so prosemirror-view failed during import.

The tests now conditionally install jsdom's navigator before importing Tiptap.

Validation:

  • npm run test:linux passed locally
  • Both affected tests passed with node --no-experimental-global-navigator, reproducing the Node 20 environment
  • Fork Linux CI run 30703137142 passed all 6 jobs, including the complete 47-test Linux suite

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