From 1bb329d8d5a113924ed23699e3f5e6ab261b5353 Mon Sep 17 00:00:00 2001 From: bbingz Date: Sun, 9 Aug 2026 04:24:14 +0800 Subject: [PATCH 1/3] docs(headless): expand serve host agent-skills install guide (#11885) Document which skills ship with the CLI, common serve install sets, integration/secret handling for Linear/GitHub/computer-use, and update/verify steps so headless orca serve operators need not use Settings. --- docs/reference/headless-linux-server.md | 93 +++++++++++++++++++++++-- 1 file changed, 86 insertions(+), 7 deletions(-) diff --git a/docs/reference/headless-linux-server.md b/docs/reference/headless-linux-server.md index a6a13489f2cb..182f9da2cd3e 100644 --- a/docs/reference/headless-linux-server.md +++ b/docs/reference/headless-linux-server.md @@ -868,10 +868,38 @@ is resolved. ## Installing Agent Skills Without A Desktop -Orca's agent skills (CLI usage, orchestration, computer use, etc.) are normally -installed from Orca Settings, which pre-fills an `npx skills add ... --global` -command in a terminal for you to run. A headless host has no Settings UI, so -use `orca skills install` instead: +Orca's agent skills (CLI usage, orchestration, computer use, Linear, etc.) are +normally installed from Orca Settings, which pre-fills an +`npx skills add ... --global` command in a terminal for you to run. A headless +`orca serve` host has no Settings UI, so use the CLI on that machine instead. + +### What ships with this Orca CLI + +`orca skills list` prints the version-matched guides bundled with **this** CLI +binary (the same set `orca skills install` can place for agents): + +| Skill | Use when | +| --- | --- | +| `orca-cli` | Worktrees, terminals, browser tabs, artifacts from agents | +| `orchestration` | Multi-agent task runs, dispatch, `worker_done` / ask | +| `computer-use` | Desktop UI automation via `orca computer` | +| `orca-linear` / `linear-tickets` | Linear issues from agents | +| `orca-emulator` / `orca-emulator-android` | Device control from agents | +| `orca-per-workspace-env` | Per-worktree env / recipe runtimes | + +Read a guide without installing it into an agent: + +```bash +orca skills get orca-cli --full +orca skills get orchestration --full +orca skills get computer-use --full +orca skills get orca-linear --full +``` + +Guides are version-matched to the CLI; after an Orca upgrade, re-read or +re-install so agents do not keep an older guide. + +### Install on the serve host ```bash orca skills install # list installable skills @@ -907,6 +935,49 @@ orca skills install --skill orca-cli --agent universal If Orca detects no agent at all, `orca skills install` stops and asks for `--agent` rather than guessing. +### Common serve installs + +```bash +# Core CLI + multi-agent coordination (most orchestration hosts) +orca skills install --skill orca-cli --skill orchestration --agent claude-code,codex + +# Linear issue workflows (needs Linear credentials on the host — see below) +orca skills install --skill orca-linear --skill linear-tickets --agent claude-code,codex + +# Desktop automation on a Linux host that has accessibility permissions +orca skills install --skill computer-use --agent claude-code,codex +``` + +After install, confirm agents can load the guide (exact paths depend on the +agent; Claude Code and Codex use their usual skills directories): + +```bash +orca skills get orchestration --full | head +# From an agent session on this host: "load the orchestration skill" / skills list +``` + +### Integrations and secrets on a serve host + +Skills only document commands; credentials stay on the host, not in the skill +markdown and not in the repo: + +| Integration | Typical host setup | Skill | +| --- | --- | --- | +| GitHub / `gh` | Install `gh`, run `gh auth login` (or set `GH_TOKEN` for non-interactive) as the same user that runs agents | `orca-cli`, `orchestration` | +| Linear | Configure Linear in Orca (desktop once, or host env / secrets that the Linear skill documents); never commit API keys | `orca-linear`, `linear-tickets` | +| Computer use | Linux accessibility / display permissions for the serve user; often needs a real or virtual display (`DISPLAY`, see Xvfb above) | `computer-use` | + +Prefer environment variables or a secret manager owned by the serve user. Do not +put tokens in `orca-data.json` copies you share, in worktree files agents can +read, or in journal logs. Restart agents (or the serve unit) after changing +credentials so they pick up new env. + +SSH workspaces and remote clients use the **host's** installed skills and +integrations: install and authenticate on the machine that runs `orca serve`, +not only on the laptop that pairs. + +### Update and verify + To refresh already-installed skills, `orca skills update` mirrors the same selection flags (`--skill`, `--all`, `--local`, `--dry-run`) and resolves to `npx skills update ` with a matching scope flag — `--global`, or @@ -922,12 +993,20 @@ orca skills update --skill orca-cli --dry-run # print the npx comman generally, a 0 exit means the `skills` CLI ran without erroring, not that it wrote anything; read its output to confirm what changed. +After an Orca package upgrade, re-run `orca skills update --all` (or re-install) +so agent-side skill copies match this CLI's guides. `orca skills list` shows the +CLI's current names; agent skill trees can lag until update runs. + `--json` covers the skill listing and `--dry-run`. A real run streams the `skills` CLI's own non-JSON output and rejects `--json`. -Both commands install onto the machine that runs them. In an Orca SSH workspace -or the WSL bridge the `orca` shim forwards commands to the Orca host, so they -refuse to run there and print the command to run on the machine you want. +### Where the command runs + +Both install and update install onto the machine that runs them. In an Orca SSH +workspace or the WSL bridge the `orca` shim forwards commands to the Orca host, +so they refuse to run there and print the command to run on the machine you want. +For `orca serve`, that is almost always the server itself (the same user as +`ExecStart` / the agent shells). ## Troubleshooting From 830c47c902b5b68937a5c4c2891b7ccd74c432ff Mon Sep 17 00:00:00 2001 From: bbingz Date: Sun, 9 Aug 2026 05:03:07 +0800 Subject: [PATCH 2/3] docs(headless): correct serve skill install verification and Linear/AT-SPI setup Review follow-up for #13262: Linear is runtime-token based (not skill env secrets), skills get is not install proof, and computer-use needs AT-SPI session bus rather than macOS-style accessibility + Xvfb alone. --- docs/reference/headless-linux-server.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/reference/headless-linux-server.md b/docs/reference/headless-linux-server.md index 182f9da2cd3e..4e82617a7d19 100644 --- a/docs/reference/headless-linux-server.md +++ b/docs/reference/headless-linux-server.md @@ -941,19 +941,23 @@ If Orca detects no agent at all, `orca skills install` stops and asks for # Core CLI + multi-agent coordination (most orchestration hosts) orca skills install --skill orca-cli --skill orchestration --agent claude-code,codex -# Linear issue workflows (needs Linear credentials on the host — see below) -orca skills install --skill orca-linear --skill linear-tickets --agent claude-code,codex +# Linear issue workflows (needs Linear connected on this host runtime — see below) +# Prefer orca-linear; install linear-tickets only if an existing agent still +# looks for that legacy skill name. +orca skills install --skill orca-linear --agent claude-code,codex -# Desktop automation on a Linux host that has accessibility permissions +# Desktop automation only on hosts with a real AT-SPI-capable session (see below) orca skills install --skill computer-use --agent claude-code,codex ``` -After install, confirm agents can load the guide (exact paths depend on the -agent; Claude Code and Codex use their usual skills directories): +After install, verify the **agent-side** skill directory (not `orca skills get` — +that only dumps the CLI's bundled guide and succeeds with no install): ```bash +# Install command exit 0 + skill path printed by `npx skills` is the install proof. +# From an agent session on this host: "load the orchestration skill" / skills list. +# Optional: confirm the guide content you will reinstall after upgrades: orca skills get orchestration --full | head -# From an agent session on this host: "load the orchestration skill" / skills list ``` ### Integrations and secrets on a serve host @@ -963,9 +967,9 @@ markdown and not in the repo: | Integration | Typical host setup | Skill | | --- | --- | --- | -| GitHub / `gh` | Install `gh`, run `gh auth login` (or set `GH_TOKEN` for non-interactive) as the same user that runs agents | `orca-cli`, `orchestration` | -| Linear | Configure Linear in Orca (desktop once, or host env / secrets that the Linear skill documents); never commit API keys | `orca-linear`, `linear-tickets` | -| Computer use | Linux accessibility / display permissions for the serve user; often needs a real or virtual display (`DISPLAY`, see Xvfb above) | `computer-use` | +| GitHub / `gh` | Install `gh`, run `gh auth login` (or set `GH_TOKEN` for non-interactive) as the same user that runs agents; verify with `gh auth status` | `orca-cli`, `orchestration` | +| Linear | Connect Linear against **this host's** Orca runtime from a paired desktop/client (tokens live under `~/.orca` via safeStorage — there is no `orca linear connect` CLI and no skill-documented env secret path). Keep tokens out of git/journals. Verify while serve is running: `orca linear team list --workspace all --json` | `orca-linear` (legacy: `linear-tickets`) | +| Computer use | Linux provider is an AT-SPI bridge (`python3-gi` + Atspi), not macOS-style accessibility grants. Needs an active desktop session (`XDG_RUNTIME_DIR`, `DBUS_SESSION_BUS_ADDRESS`) for the serve user — Xvfb for Electron startup alone is not enough, and pure no-desktop VPS hosts often cannot run it. Probe: `orca computer capabilities --json` | `computer-use` | Prefer environment variables or a secret manager owned by the serve user. Do not put tokens in `orca-data.json` copies you share, in worktree files agents can From 72261caa7a3a510afbd2ff5fe455abb5ada68314 Mon Sep 17 00:00:00 2001 From: bbingz Date: Sun, 9 Aug 2026 05:14:19 +0800 Subject: [PATCH 3/3] docs(headless): tighten skill verify, Linear connect, AT-SPI notes Campaign review follow-up for #13262: prove installs via agent skill dirs (not skills get), document linear.connect/UI tokens under ~/.orca, and spell out python3-gi/AT-SPI session-bus requirements for computer-use. --- docs/reference/headless-linux-server.md | 32 +++++++++++++++---------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/reference/headless-linux-server.md b/docs/reference/headless-linux-server.md index 4e82617a7d19..90ca9bb811a5 100644 --- a/docs/reference/headless-linux-server.md +++ b/docs/reference/headless-linux-server.md @@ -896,8 +896,10 @@ orca skills get computer-use --full orca skills get orca-linear --full ``` -Guides are version-matched to the CLI; after an Orca upgrade, re-read or -re-install so agents do not keep an older guide. +Guides are version-matched to the CLI; after an Orca upgrade, run +`orca skills update` (or reinstall) so agent-side copies do not keep an older +guide. `orca skills get` only shows the CLI's bundled text — it does not refresh +installed agent directories. ### Install on the serve host @@ -950,14 +952,19 @@ orca skills install --skill orca-linear --agent claude-code,codex orca skills install --skill computer-use --agent claude-code,codex ``` -After install, verify the **agent-side** skill directory (not `orca skills get` — -that only dumps the CLI's bundled guide and succeeds with no install): +After install, verify the **agent-side** skill directories that `npx skills` +wrote. Do **not** use `orca skills get` as install proof — it only dumps the +CLI's bundled guide and succeeds even when nothing is installed. ```bash -# Install command exit 0 + skill path printed by `npx skills` is the install proof. -# From an agent session on this host: "load the orchestration skill" / skills list. -# Optional: confirm the guide content you will reinstall after upgrades: -orca skills get orchestration --full | head +# Global install targets (exact set depends on --agent): +ls -la ~/.agents/skills # universal / shared (always when universal is a target) +ls -la ~/.claude/skills 2>/dev/null # claude-code +ls -la ~/.codex/skills 2>/dev/null # codex +# Expect a directory per skill (e.g. orchestration/ with SKILL.md inside). +# Project-local (--local): .agents/skills under the project cwd instead of ~/.agents. +# Install exit 0 + paths printed by npx skills is also proof; from an agent session +# on this host: "load the orchestration skill" / the agent's skills list. ``` ### Integrations and secrets on a serve host @@ -967,9 +974,9 @@ markdown and not in the repo: | Integration | Typical host setup | Skill | | --- | --- | --- | -| GitHub / `gh` | Install `gh`, run `gh auth login` (or set `GH_TOKEN` for non-interactive) as the same user that runs agents; verify with `gh auth status` | `orca-cli`, `orchestration` | -| Linear | Connect Linear against **this host's** Orca runtime from a paired desktop/client (tokens live under `~/.orca` via safeStorage — there is no `orca linear connect` CLI and no skill-documented env secret path). Keep tokens out of git/journals. Verify while serve is running: `orca linear team list --workspace all --json` | `orca-linear` (legacy: `linear-tickets`) | -| Computer use | Linux provider is an AT-SPI bridge (`python3-gi` + Atspi), not macOS-style accessibility grants. Needs an active desktop session (`XDG_RUNTIME_DIR`, `DBUS_SESSION_BUS_ADDRESS`) for the serve user — Xvfb for Electron startup alone is not enough, and pure no-desktop VPS hosts often cannot run it. Probe: `orca computer capabilities --json` | `computer-use` | +| GitHub / `gh` | Install `gh`, run `gh auth login` (or set `GH_TOKEN` for non-interactive) as the same user who runs agents; verify with `gh auth status` | `orca-cli`, `orchestration` | +| Linear | Connect Linear on **this host's** Orca runtime (Settings → Linear on a desktop once, or the runtime `linear.connect` RPC/IPC from a paired client). Tokens are stored under `~/.orca` (safeStorage) — there is **no** `orca linear connect` CLI and **no** skill-documented host env/secret path. Keep tokens out of git/journals. Verify while serve is running: `orca linear team list --workspace all --json` | `orca-linear` (legacy: `linear-tickets`) | +| Computer use | Linux provider is an AT-SPI bridge, not macOS-style accessibility grants. Install `python3-gi`, `gir1.2-atspi-2.0`, and `at-spi2-core`. The serve user needs an active session bus (`XDG_RUNTIME_DIR`, `DBUS_SESSION_BUS_ADDRESS`) and a real AT-SPI-capable desktop — the Xvfb used only for Electron/`DISPLAY` startup is not enough. Pure no-desktop VPS hosts often cannot run computer-use. Probe: `orca computer capabilities --json` | `computer-use` | Prefer environment variables or a secret manager owned by the serve user. Do not put tokens in `orca-data.json` copies you share, in worktree files agents can @@ -1006,7 +1013,8 @@ CLI's current names; agent skill trees can lag until update runs. ### Where the command runs -Both install and update install onto the machine that runs them. In an Orca SSH +Both commands operate on the machine that runs them. `install` adds skills; +`update` refreshes only skills that are already installed. In an Orca SSH workspace or the WSL bridge the `orca` shim forwards commands to the Orca host, so they refuse to run there and print the command to run on the machine you want. For `orca serve`, that is almost always the server itself (the same user as