From cc575461c9bc79a148c1831ebdb82e1d3bb7c6ab Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sun, 30 Aug 2026 02:14:13 -0700
Subject: [PATCH] docs(linux): make headless AppImage extraction runnable

---
 docs/reference/headless-linux-server.md | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/docs/reference/headless-linux-server.md b/docs/reference/headless-linux-server.md
index beb0220d15b..3d7db834e8e 100644
--- a/docs/reference/headless-linux-server.md
+++ b/docs/reference/headless-linux-server.md
@@ -58,11 +58,23 @@ FUSE. On Ubuntu 24.04 and Debian 13 the package is `libfuse2t64`, though the pla
 `libfuse2` name also resolves there because nothing else provides it. FUSE is
 optional: without it, use the AppImage's supported extraction path. CLI
 registration does this once automatically, so registered commands do not need
-FUSE:
+FUSE.
+
+Download and make the AppImage executable:
+
+```bash
+sudo mkdir -p /opt/orca
+sudo curl -L https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage \
+  -o /opt/orca/orca-linux.AppImage
+sudo chmod +x /opt/orca/orca-linux.AppImage
+```
+
+To extract it without FUSE, run the extraction as root because the installation
+directory is root-owned:
 
 ```bash
 cd /opt/orca
-./orca-linux.AppImage --appimage-extract
+sudo ./orca-linux.AppImage --appimage-extract
 sudo chmod -R a+rX /opt/orca/squashfs-root
 /opt/orca/squashfs-root/AppRun serve --port 6768
 ```
@@ -78,15 +90,6 @@ extract-and-run wrapper can print extracted paths before Orca starts, so
 automation that requires stdout to contain only the ready JSON should extract
 once and invoke `squashfs-root/AppRun`.
 
-Download and make the AppImage executable:
-
-```bash
-sudo mkdir -p /opt/orca
-sudo curl -L https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage \
-  -o /opt/orca/orca-linux.AppImage
-sudo chmod +x /opt/orca/orca-linux.AppImage
-```
-
 If `Xvfb` was installed somewhere other than `/usr/bin`, confirm systemd can
 find it later: