Orca configuration and boundaries

Orca’s Mac application stores project/host settings. The active remote hooks call scripts on Shipyard. The curated snapshot is profiles/shipyard/orca.json; rediscover installation-specific IDs before changing settings.

Inspect on the Mac

ORCA=/Applications/Orca.app/Contents/Resources/bin/orca
"$ORCA" repo list --json
"$ORCA" repo show --help
"$ORCA" repo set-base-ref --help

Choose the repository by both path and execution host. Mac API and Shipyard API have different settings. Do not edit Orca’s private database directly. A sandbox EPERM means CLI access was blocked; it is not evidence Orca needs a restart.

Configured hooks

API setup:

python3 "$HOME/dev-environment/scripts/orca-task.py" setup --root "$ORCA_WORKTREE_PATH"

API archive replaces setup with archive. Appliance uses orca-appliance.py with the same arguments. Both remote projects run setup by default and wait for it before agent startup. Dashboard is added through the API task, not a dashboard-first hook.

Change the default base

After verifying a candidate ref contains required lifecycle and reload fixes, use:

"$ORCA" repo set-base-ref --repo id:REPOSITORY_ID --ref origin/master

First fetch and inspect the intended repository on Shipyard; do not reset active worktrees. The setting affects future tasks. Current recorded bases are shipyard-ready for API and search-worktree-setup for appliance. API PR 6139 is merged; nodemon PR 6141 and draft appliance PR 2925 were open on 6 October 2026. Do not switch solely because a runbook says a merge is expected.

Deletion and review nuances

Orca 1.4.220 desktop Delete successfully ran remote archive hooks and preserved data/companion edits. Its CLI worktree rm --run-hooks refused SSH archive execution. Prefer the desktop path. A CLI waiver is not a normal fix; only consider one after explicit archive and verification, within the user’s deletion scope.

API and dashboard are separate repositories. The API source-control panel does not combine them. The companion can be reviewed separately, and an agent must report both diffs.

Reconnect

SSH/UI disconnection does not stop tmux/Docker. The existing noVNC viewer sometimes needs Reload after reconnect. Browser startup after machine reboot remains manual. Browser recovery.