diff --git a/docs/reference/headless-linux-server.md b/docs/reference/headless-linux-server.md index a6a13489f2cb..90ca9bb811a5 100644 --- a/docs/reference/headless-linux-server.md +++ b/docs/reference/headless-linux-server.md @@ -868,10 +868,40 @@ 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, 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 ```bash orca skills install # list installable skills @@ -907,6 +937,58 @@ 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 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 only on hosts with a real AT-SPI-capable session (see below) +orca skills install --skill computer-use --agent claude-code,codex +``` + +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 +# 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 + +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 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 +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 +1004,21 @@ 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 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 +`ExecStart` / the agent shells). ## Troubleshooting