Document headless Linux server setup by sdhilip200 · Pull Request #6802 · stablyai/orca

sdhilip200 · 2026-06-29T23:51:14Z

Summary

Adds docs/reference/headless-linux-server.md, a headless Linux setup guide for running the Linux AppImage with orca serve.

The new guide documents:

Ubuntu prerequisites: curl, libfuse2, and xvfb
how to download and run the AppImage directly on a server
foreground orca serve commands with --port and --pairing-address
a systemd orca-serve.service example
an optional separate orca-xvfb.service when the operator wants systemd to own the virtual display
troubleshooting for FUSE, Xvfb, software rendering, sandbox, and reachable pairing addresses

The PR also adds a README link beside the Linux AppImage install link and indexes the guide from docs/reference/README.md.

Fixes #6790

Screenshots

No visual change.

Testing

pnpm test was attempted locally, but the run was not usable in this sandboxed environment. It failed broadly in unrelated socket/runtime/daemon suites, including listen EPERM ... relay.sock from src/relay/relay-handshake-roundtrip.test.ts and multiple WebSocket/daemon/relay 30s timeouts.

pnpm build was not run because this PR only changes markdown documentation and README links.

Environment note: local pnpm reported the repo engine warning node 24 wanted; local node was v26.0.0.

AI Review Report

Review checked the guide against:

issue AppImage fails to run on headless Ubuntu 22.04 — missing deps and no documented server install path #6790's requested headless Ubuntu/AppImage setup path
the current orca serve CLI options in src/cli/specs/core.ts
Linux serve display behavior in src/main/startup/ensure-virtual-display.ts
existing open PR scope, to avoid duplicating the separate Linux CLI binary-name docs work

No product code changed. The examples use documented orca serve flags and keep the Linux-only guidance out of macOS/Windows install paths.
Cross-platform compatibility was checked for macOS, Linux, and Windows: the diff only adds Linux-specific markdown and links, so no shortcuts, shell behavior, Electron platform handling, or runtime paths change on macOS or Windows.

Security Audit

Docs-only change; no runtime code, dependencies, IPC, auth, or secret handling changed.

The service examples run Orca as a dedicated non-root orca user, avoid recommending sandbox disablement as the default path, and use a private Tailscale-range pairing address placeholder that readers must replace with their own reachable address.

Notes

The guide documents the current AppImage-based server path. If a future server package removes the Electron/X display requirement, the Xvfb sections should be simplified.
X handle: not provided.

coderabbitai · 2026-06-29T23:53:49Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 6a9abe9d-497b-4c69-ab87-dddbfad8508b

📥 Commits

Reviewing files that changed from the base of the PR and between 2db45ce and c36e4d5.

📒 Files selected for processing (1)

docs/reference/headless-linux-server.md

📝 Walkthrough

Walkthrough

A new reference page, docs/reference/headless-linux-server.md, is added for running orca serve on a headless Linux server. It documents prerequisites, AppImage setup, foreground execution with LIBGL_ALWAYS_SOFTWARE=1, two systemd deployment patterns, a CLI install note, and troubleshooting steps. README.md and docs/reference/README.md each gain a cross-reference to the new guide.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change.
Linked Issues check	✅ Passed	The docs address the headless Linux AppImage path, prerequisites, systemd setup, GUI workaround, and remote pairing guidance from `#6790`.
Out of Scope Changes check	✅ Passed	All changes stay within documentation and reference updates for the headless Linux guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The PR description follows the required template and includes summary, screenshots, testing, AI review, security audit, and notes.

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.}

coderabbitai

🧹 Nitpick comments (1)

docs/reference/headless-linux-server.md (1)
168-181: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider adding --disable-gpu as a fallback for persistent GPU/DRI warnings.

LIBGL_ALWAYS_SOFTWARE=1 usually resolves GPU-less VPS rendering, but some providers still emit DRI warnings that can confuse operators. Adding an optional note that --disable-gpu can be appended to ExecStart when software rendering alone is insufficient would close the loop on the GPU-less setup path described in the PR objectives.
ExecStart=/opt/orca/orca-linux.AppImage serve --port 6768 --pairing-address 100.64.1.20 --disable-gpu

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 6d91b4e8-494f-411c-9b6d-8dfd4debd345

📥 Commits

Reviewing files that changed from the base of the PR and between a27278d and 2db45ce.

📒 Files selected for processing (3)

README.md
docs/reference/README.md
docs/reference/headless-linux-server.md

sdhilip200 · 2026-06-30T01:48:20Z

Updated the PR description to match the markdown-only diff and testing evidence more tightly. @coderabbitai review

coderabbitai · 2026-06-30T01:48:31Z

@sdhilip200: I’ll review the updated PR, including the tightened description against the markdown-only diff and testing evidence.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

sdhilip200 · 2026-06-30T01:50:15Z

Updated the PR description with the explicit macOS/Linux/Windows compatibility review statement requested by the description check. @coderabbitai review

coderabbitai · 2026-06-30T01:50:29Z

@sdhilip200 Got it — I’ll review the updated PR description, including the explicit macOS/Linux/Windows compatibility statement added for the description check.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Salvaged from stablyai#6817 before closing it as a duplicate. Co-authored-by: Orca <help@stably.ai>

Jinwoo-H · 2026-06-30T07:04:42Z

Thanks for this — merging. This is the accurate, comprehensive answer to #6790: it matches the current behavior where orca serve auto-starts Xvfb on :99 when no DISPLAY is set (src/main/startup/ensure-virtual-display.ts, wired in before whenReady), and the prerequisites + systemd templates are correct.

I folded in one debugging tip (--appimage-extract + ldd) salvaged from #6817, which I'm closing as a duplicate in favor of this guide.

croakingtoad · 2026-06-30T14:10:03Z

Thanks everyone for this PR, much appreciated!!

docs: add headless Linux server guide

2db45ce

coderabbitai Bot reviewed Jun 29, 2026

View reviewed changes

docs: add ldd/appimage-extract tip for diagnosing missing libraries

c36e4d5

Salvaged from stablyai#6817 before closing it as a duplicate. Co-authored-by: Orca <help@stably.ai>

Jinwoo-H merged commit 9694830 into stablyai:main Jun 30, 2026

Jinwoo-H mentioned this pull request Jun 30, 2026

docs: add headless AppImage troubleshooting #6817

Closed

LesleyMurfin mentioned this pull request Jul 19, 2026

[Bug]: Headless serve self-spawned Xvfb doesn't reap a stale /tmp/.X99-lock after an unclean exit (reaper is socket-gated) → serve can't get its virtual display and crash-loops LesleyMurfin/orca#23

Open

AmethystLiang added the orca-remote-server Remote Orca Server / orca serve / paired remote runtime label Jul 22, 2026

This was referenced Oct 8, 2026

feat(skills): add headless server setup and recovery guidance LesleyMurfin/orca#60

Open

[Feature / Docs]: Production Headless Server Supervision & Bundled orca-server Skill LesleyMurfin/orca#62

Open

Navigation Menu

Repository navigation

Document headless Linux server setup - #6802

Document headless Linux server setup#6802
Jinwoo-H merged 2 commits into
stablyai:mainfrom
sdhilip200:codex/headless-linux-server-docs

sdhilip200 commented Jun 29, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 29, 2026 •

edited

Loading

Review failed

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Uh oh!

sdhilip200 commented Jun 30, 2026

Uh oh!

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

sdhilip200 commented Jun 30, 2026

Uh oh!

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

Jinwoo-H commented Jun 30, 2026

Uh oh!

croakingtoad commented Jun 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

sdhilip200 commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Screenshots

Testing

AI Review Report

Security Audit

Notes

Uh oh!

coderabbitai Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sdhilip200 commented Jun 30, 2026

Uh oh!

coderabbitai Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sdhilip200 commented Jun 30, 2026

Uh oh!

coderabbitai Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Jinwoo-H commented Jun 30, 2026

Uh oh!

croakingtoad commented Jun 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sdhilip200 commented Jun 29, 2026 •

edited

Loading

coderabbitai Bot commented Jun 29, 2026 •

edited

Loading

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading