Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 98 additions & 7 deletions docs/reference/headless-linux-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

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 <names...>` with a matching scope flag — `--global`, or
Expand All @@ -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

Expand Down