# Installation
> Orca·에이전트 CLI·git·gh·python3·bd·skills 전제조건, preflight FAIL/WARN, 셸 명령 등록, 클론 후 측정 신호.
- Repository: local/mogui-ADE-orchestrator
- Human docs: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac
- Complete Markdown: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/llms-full.txt
## Source Files
- `docs/public/getting-started.md`
- `scripts/onboarding-preflight.sh`
- `README.md`
- `tests/test_onboarding_preflight.py`
- `INSTALL-PROMPT.txt`
- `master-ops/ONBOARDING.md`
---
---
title: "Installation"
description: "Orca·에이전트 CLI·git·gh·python3·bd·skills 전제조건, preflight FAIL/WARN, 셸 명령 등록, 클론 후 측정 신호."
---
설치 게이트는 `scripts/onboarding-preflight.sh`다. 클론 후 이 스크립트가 호스트 도구, Orca 런타임·orchestration Run, skills 아티팩트, 조직 redaction 규칙, 에이전트/워커 CLI, 디스패치 레저 경로를 한 번에 측정하고, 필수 항목이 비면 exit 1과 `BLOCKED`로 founding을 막는다. 애플리케이션 설치는 수동이며, `--fix`는 전역 Orca skills 추가·갱신만 수행한다.
## 설치 경계
| 구분 | 내용 |
| --- | --- |
| 런타임 기판 | Orca 앱 + 셸에 등록된 CLI (`orca` / `orca-dev` / `orca-ide`) |
| 측정 게이트 | `bash scripts/onboarding-preflight.sh` (Step 0, `master-ops/onboarding/01-preflight.md`) |
| 에이전트 경로 | 클론 루트에서 태스크 없이 wake-up → `master-ops/ONBOARDING.md` 라우터 |
| 비대상 | 제품 코드 배포, 네트워크 API 키, CI 설치 파이프라인 |
이 저장소는 workspace/orchestrator 런타임과 ops 템플릿이다. 마스터 세션은 Orca 터미널에서 살고, preflight 없이 라이브 마스터를 띄우는 경로는 지원되지 않는다.
## 전제조건 (FAIL / WARN)
판정은 preflight 출력 라벨을 따른다.
- **FAIL** → `FAIL` 인쇄, failures 카운트, 종료 요약 `BLOCKED`, exit **1** (또는 `PREFLIGHT_WAIVE`로 명시 면제)
- **WARN** → `WARN` 인쇄, 단독으로는 exit 1을 만들지 않음. `ESSENTIAL_LABELS`에 속하면 요약의 essential 블록에 재강조
### FAIL — founding 차단
| 라벨 | 요구 | 부재 시 신호 |
| --- | --- | --- |
| `orca` | CLI 존재, basename이 `orca`·`orca-dev`·`orca-ide`, `status --json`에 `"ok": true` | 설치/셸 등록 힌트 포함 FAIL |
| `orchestration` | Orca ready 후 `orchestration run-current --json`: RPC ok, 비-legacy Run 바인딩, `legacy_read_only` 아님 | `run-create` 안내; 앱 재시작만으로는 legacy coordinator 미해결 |
| `skills` | 디스크에 `orca-cli`+`orchestration` 스킬 디렉터리, 또는 skills 패키지 전역 목록에 둘 다 존재 | 설치 명령 안내; `--fix`로 전역 추가 가능 |
| `agent-cli` | `ORCA_AGENT_CLI` 설정 + 해당 바이너리 `PATH` | unset이면 agent-specific 검사가 조용히 빠지므로 FAIL |
| `worker-runtime` | `codex` 또는 `cursor-agent` 중 **하나 이상** | 둘 다 없으면 FAIL; 하나만 있으면 나머지는 WARN |
| `bd` | `bd` 바이너리; ops 레포가 있으면 `bd where`가 그 안을 가리켜야 함 | 바이너리 없음 또는 ops 밖 해석 시 FAIL |
| `python3` | `PATH`의 `python3` | 버전 하한 없음; 엔트리포인트가 python3 스크립트 |
| `git` / `gh` | 바이너리 존재 | PR 관리 전제로 FAIL |
| `redaction-extra` | `REDACTION_EXTRA_PATTERNS` 또는 `~/.config/redaction-extra.txt`에 **컴파일 가능한 규칙 ≥1** | 내용 미인쇄, 개수만 보고; publish 게이트 2개가 거부 |
| `gate-ledger` | `DISPATCH_GATE_LEDGER`(기본 `.mogui/dispatch-ledger.jsonl`) 상위 디렉터리 생성·쓰기 가능 | 쓰기 불가 시 FAIL |
### WARN — 단독 비차단
| 라벨 | 조건 | 결과/비용 |
| --- | --- | --- |
| `gitleaks` | PATH 없음 | redaction 스캔이 결정 불가로 exit 2; 퍼블리시 전 설치 |
| `ctx` | 없거나 `ctx status` 실패 | 크로스-프로바이더 히스토리 조회 불가; 마스터 자체는 동작 |
| `skill-stack` | `superpowers` / `ponytail` 없음 | 마스터는 동작하나 방법론·절제 레이어 없이 다르게 동작 |
| `gh-auth` | `gh` 미인증, 또는 `workflow` 스코프 없음 | 푸시/PR 또는 Actions 워크플로 편집 실패 |
| `worker-runtime` | 나열된 런타임 중 일부만 없음 (다른 하나는 있음) | 단일 실행기로 라우팅하는 정상 구성 |
| `pytest` | 3.11+ pytest도 `uv`도 없음 | 테스트 게이트를 돌릴 에이전트에 둘 중 하나 필요 |
| `codex-plugin` | `ORCA_AGENT_CLI`가 claude/claude-code일 때만, Codex 플러그인 미설치 | Codex 워커 디스패치 호스트에 필요; 그 외 INFO skip |
### Essential 라벨
요약 끝 `!! ESSENTIAL COMPONENTS MISSING` 블록에 다시 찍히는 라벨:
`orca`, `orchestration`, `skills`, `agent-cli`, `worker-runtime`, `bd`, `python3`, `gitleaks`, `ctx`, `redaction-extra`, `skill-stack`
WARN이어도 essential이면 여기 반복된다. 마스터 spawn 전에 설치하거나, 거부와 수용 동작을 기록로 남겨야 한다.
## Orca 설치와 셸 명령 등록
Orca는 추상화 대상이 아니다. 세션 수명, 핸들, supervised dispatch 메일박스가 여기서만 성립한다.
### 플랫폼별 설치
```console
$ brew install --cask stablyai/orca/orca
```
앱과 번들 CLI 바이너리를 설치한다. Homebrew `--cask`는 macOS 전용이다.
[공식 다운로드](https://www.onorca.dev/download)를 사용한다. 유지자 보고: AppImage/`.deb`, Arch `yay -S stably-orca-bin`. Linux에서는 GNOME 스크린 리더 `orca`와 충돌을 피하기 위해 바이너리 이름이 `orca-ide`일 수 있다. 그 경우 preflight가 허용하는 basename을 쓰거나 `ORCA_CLI_COMMAND`로 경로를 지정한다.
### Shell command
앱을 연 뒤:
1. **Settings → Orca CLI**
2. **Shell command** 켜기
측정 성공 조건:
```console
$ command -v orca # 또는 orca-dev / orca-ide
$ orca status
# 기대: appRunning: true, runtimeState: ready
$ orca status --json
# 기대: "ok": true
```
앱이 닫혀 있으면 `orca open`이 런타임이 닿을 때까지 대기한다. UI 라벨이 빌드마다 바뀌어도 성공 판정은 위 측정이다.
### Orca CLI 해석 순서
preflight(및 동일 패턴을 쓰는 런북) 해석:
1. `ORCA_CLI_COMMAND` — 명시 경로/이름
2. `ORCA_DEV_REPO_ROOT` 설정 시 → `orca-dev`
3. 기본 → `orca`
지원 basename 외 이름은 `orca` FAIL이다.
## 저장소 클론과 Orca 등록
```console
$ git clone https://github.com/baksohyeon/mogui-ADE-orchestrator
$ cd mogui-ADE-orchestrator
```
두 개념을 섞지 않는다.
| 개념 | 역할 |
| --- | --- |
| 폴더 workspace root | 여러 레포를 묶는 절대 경로. 마스터 좌석 |
| 이 오케스트레이터 클론 | 설치 세션 자리 + 런타임/템플릿 소스. 마스터가 영구 거주하는 곳이 아님 |
```console
$ orca repo add --path
```
Orca UI에서 프로젝트를 추가해도 된다. 이후 **해당 프로젝트 안** 터미널에서 작업 디렉터리가 클론(또는 의도한 install seat)인지 `pwd`로 확인한다. 프로젝트 밖 셸에서 시작하면 placement/spawn이 잘못된 좌석을 측정한다.
## 클론 후 측정 신호
### Preflight 실행
```console
$ cd
$ ORCA_AGENT_CLI=claude bash scripts/onboarding-preflight.sh
```
| 옵션/환경 | 의미 |
| --- | --- |
| (인자 없음) | 읽기 전용 측정. 상태 변경 없음 |
| `--fix` | 승인 후: `skills add stablyai/orca -g --skill orca-cli --skill orchestration` 및 `update orchestration -g`. 앱 설치는 하지 않음 |
| 잘못된 인자 | `Usage: … [--fix]`, exit **2** |
#### 환경 변수
| 변수 | 역할 |
| --- | --- |
| `ORCA_AGENT_CLI` | 마스터 호스트 CLI 이름. unset → `agent-cli` FAIL |
| `ORCA_CLI_COMMAND` | Orca CLI 경로 오버라이드 |
| `ORCA_DEV_REPO_ROOT` | 설정 시 `orca-dev` 선택 |
| `ORCA_SKILLS_DIRS` | `:` 구분 skills 루트 오버라이드 (미설정 시 `~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills` 등) |
| `REDACTION_EXTRA_PATTERNS` | 조직 규칙 파일 경로 (기본 `~/.config/redaction-extra.txt`) |
| `DISPATCH_GATE_LEDGER` | 디스패치 레저 경로 (기본 `.mogui/dispatch-ledger.jsonl`) |
| `PREFLIGHT_WAIVE` | 쉼표 구분 라벨. 해당 FAIL을 인쇄·카운트되는 `WAIVED`로 강등 |
규칙 파일 한 줄 형식: `id|description|regex` (빈 줄·`#` 주석 무시, 정규식 컴파일 필수). preflight는 규칙 본문을 절대 출력하지 않는다.
### 요약 판정
| 출력 | exit | 의미 |
| --- | --- | --- |
| `READY: all required checks passed` | 0 | 필수 전부 PASS |
| `READY WITH WAIVERS: … downgraded, not satisfied` | 0 | 일부 FAIL이 면제됨. 충족이 아님 |
| `BLOCKED: fix every FAIL before onboarding` | 1 | 면제되지 않은 FAIL 존재 |
| `NOTE: PREFLIGHT_WAIVE named checks that did not run: … still enforced` | (해당 FAIL 유지) | 오타 면제 — 검사는 그대로 강제 |
| `!! ESSENTIAL COMPONENTS MISSING` | — | essential 갭 재나열 + 결과 문구 |
예시 (성공 요약 형태):
```text
INFO resolved Orca CLI: orca
PASS orca orca status --json returned ok:true
PASS orchestration RPC reachable and a non-legacy Run is bound to this terminal
…
Preflight summary
PASS: N
WARN: M
FAIL: 0
WAIVED: 0
READY: all required checks passed
```
### 세션 상태 신호 (도구 설치 외에 필요한 것)
| 신호 | 측정 | 복구 |
| --- | --- | --- |
| Orca runtime ready | `orca status` / `--json` ok | 앱 실행, Shell command, `orca open` |
| non-legacy Run 바인딩 | `orca orchestration run-current --json` | `orca orchestration run-create` |
| legacy coordinator | `legacy_read_only` / `effectsApplied:false` | 새 Run 생성 (앱 재시작만으로는 미해결) |
| Run null | `"run": null` | 동일하게 `run-create`; 바인딩 소실 후 empty mailbox와 구분 어려움 |
| agent CLI 선택 | `ORCA_AGENT_CLI` + `command -v` | onboarding이 설정; 바이너리는 그 전에 설치 |
### 조직 redaction 규칙 최소 스캐폴드
```console
$ mkdir -p ~/.config
$ printf '%s\n' 'org-example|example pattern only|EXAMPLE_SECRET_[0-9]+' > ~/.config/redaction-extra.txt
```
실제 조직 패턴으로 교체한다. 버전 관리에 올리지 않는다.
### Skills 수동 설치 (preflight 힌트와 동일)
아티팩트가 없고 skills 실행기가 있을 때:
```console
$ skills add stablyai/orca -g --skill orca-cli --skill orchestration
$ skills update orchestration -g
```
또는 `bash scripts/onboarding-preflight.sh --fix` (skills 명령이 가용할 때).
## 설치 절차 (사람 경로)
플랫폼에 맞게 Orca를 설치하고 앱을 연다. **Settings → Orca CLI → Shell command**를 켠 뒤 `orca status`가 ready/`ok:true`인지 확인한다.
마스터용 에이전트 CLI, 워커 런타임(`codex` 및/또는 `cursor-agent`), `git`, `gh`, `python3`, `bd`를 PATH에 둔다. 퍼블리시 예정이면 `gitleaks`, 히스토리 조회면 `ctx`. 조직 redaction 규칙 파일을 만든다.
이 저장소를 클론하고, workspace root(또는 임시 install seat)를 `orca repo add --path`로 등록한다. Orca 터미널을 그 프로젝트 안에서 연다.
`ORCA_AGENT_CLI= bash scripts/onboarding-preflight.sh`를 실행한다. `BLOCKED`면 FAIL을 고친다. 정당한 불가 항목만 `PREFLIGHT_WAIVE=
같은 터미널에서 에이전트 CLI를 시작하고, 구체 태스크 없이 wake-up 문구만 준다. 에이전트는 `master-ops/ONBOARDING.md`만 라우터로 읽고 세션 모드(Founding / Reverify / Upgrade / Template improve)를 묻는다. Founding은 ops 레포·lineage가 없을 때만.
에이전트 호스트가 루트 `CLAUDE.md`/`AGENTS.md`를 자동 로드하지 않으면 `INSTALL-PROMPT.txt` 문구로 동일 라우터 경로를 강제한다. Orca가 준비되지 않았으면 설치·기동 안내 후 중단한다.
## Preflight 이후 onboarding이 남기는 인스턴스 파일
Step 0 Verify는 다음을 요구한다 (커밋하지 않는 인스턴스 소유 파일; 템플릿은 `*.example.json`만 선적).
```console
$ test -f config/instance-runtime.json || cp config/instance-runtime.example.json config/instance-runtime.json
# master_host_runtime = 확인된 ORCA_AGENT_CLI
$ test -f config/model-tier-policy.json || cp config/model-tier-policy.example.json config/model-tier-policy.json
# version 2, consent, tiers / fanout_caps — 모델 id 추측 금지
```
해석 순서(소비자): 환경 오버라이드 → 인스턴스 파일 → unconfigured (하드코딩 기본값 없음).
## 첫 장애 대응
| 관측 | 확인 | 조치 |
| --- | --- | --- |
| spawn이 호스트를 못 부름 | `command -v orca`; `orca status` | Shell command 등록 |
| `BLOCKED` | FAIL 줄 전체 | 항목 수리 또는 의도적 `PREFLIGHT_WAIVE` |
| orchestration FAIL, legacy | 출력의 `legacy_read_only` / inspect-only | `orca orchestration run-create` 후 preflight 재실행 |
| orchestration FAIL, no Run | `"run": null` | 동일 `run-create` |
| `agent-cli` FAIL | `echo $ORCA_AGENT_CLI`; `command -v …` | 변수 설정 + 바이너리 설치 |
| `redaction-extra` FAIL | 파일 존재·유효 규칙 개수(내용 비공개) | 형식 `id\|description\|regex`로 재작성 |
| 면제했는데 여전히 FAIL | `named checks that did not run` | 라벨 철자 수정 (예: `redaction-extra` not `redaction-extras`) |
| Orca 없이 에이전트가 계속 진행 | 런타임 ready 여부 | 중단. 완료 감지가 스크린 폴링으로 degenerates — 실사고 기록됨 |
## 범위 밖 (이 페이지에서 끝내지 않는 것)
- Generation 1 spawn, boot smoke, 첫 supervised worker 검증 → [Quickstart](/quickstart), [온보딩](/onboarding)
- 인스턴스·티어 정책 상세 → [인스턴스 설정](/configure-instance)
- preflight 이후 장애 카탈로그 → [Troubleshooting](/troubleshooting)
## Next
클론 → Orca 준비 → wake-up → Gen-1 부트 → 첫 supervised worker까지 최단 경로
ONBOARDING 라우터, 1단계 1파일, Founding/Reverify/Upgrade
BLOCKED, placement, MODEL_PROBE_FAILED, seat 중복, revival
공개 표면, Orca 전제, 마스터/워커 역할, 네트워크·API 키 없음 제약