오르카 설치 튜토리얼: 5분 병렬 AI 코딩

앱은 설치됐지만 에이전트가 보이지 않거나, 두 작업이 같은 파일을 덮어쓰는 문제가 먼저 발생합니다.

Git과 목표 CLI Agent가 이미 설치되고 로그인까지 끝났다면, 오르카 설치 튜토리얼은 몇 분 안에 첫 Orca 실행까지 진행할 수 있습니다. 다만 처음에는 격리된 작은 작업 2개만 실행하고, worktree·테스트·병합 과정을 확인한 뒤 동시 작업 수를 늘리는 방식이 안전합니다.

이 글은 Orca를 처음 설치하는 Windows, macOS, Linux 개발자를 위한 안내서입니다. 로컬 환경을 원격 Mac 또는 Linux 서버로 옮기려는 개발자와 팀의 AI 코딩 환경을 검증하는 운영 담당자도 대상입니다.

주의: 여기서 말하는 “5분”은 다운로드, 계정 가입, 대형 저장소 초기화에 걸리는 시간을 제외한 첫 실행 기준입니다. 네트워크 상태와 운영체제 보안 정책에 따라 실제 소요 시간은 달라질 수 있습니다.

시작 전 10분: 설치 조건부터 확인합니다

Orca는 모델이나 구독을 제공하는 서비스가 아닙니다. 이미 사용하는 Claude Code, Codex, Cursor CLI 같은 터미널 에이전트를 한 화면에서 실행하고, 작업별 Git worktree를 관리하는 데스크톱 도구입니다. 각 작업이 별도 worktree와 터미널을 사용한다는 구조는 Orca 공식 문서에서 확인할 수 있습니다.

다음 항목을 설치 전에 확인해야 합니다.

• [ ] 운영체제와 프로세서 유형을 확인했습니다.
• [ ] Git이 터미널에서 실행됩니다.
• [ ] 사용할 CLI Agent가 독립적으로 실행됩니다.
• [ ] Claude Code 또는 다른 Agent 계정 로그인이 완료됐습니다.
• [ ] 변경 사항을 되돌릴 수 있는 테스트 저장소를 준비했습니다.
• [ ] 저장소에 커밋되지 않은 중요한 변경 사항이 없습니다.
• [ ] 두 작업이 같은 파일을 동시에 수정하지 않도록 역할을 나눴습니다.

Git은 여러 작업 디렉터리를 하나의 저장소에 연결할 수 있지만, worktree마다 브랜치와 인덱스가 분리되고 일부 저장소 메타데이터는 공유됩니다. 환경 파일과 공용 설정까지 자동으로 분리되는 것은 아니므로, Git worktree 공식 문서를 먼저 확인하는 편이 좋습니다.

첫 단계: 운영체제에 맞는 Orca를 설치합니다

공식 설치 문서에는 macOS용 Apple Silicon과 Intel 빌드, Windows 설치 파일, Linux AppImage와 deb 패키지가 구분되어 있습니다. macOS에서는 Homebrew 경로도 제공됩니다. 실제 설치 파일과 시스템 요구 사항은 Orca 설치 안내의 최신 내용을 기준으로 확인해야 합니다.

환경	권장 설치 경로	설치 뒤 확인할 점
macOS Apple Silicon	공식 Apple Silicon 빌드 또는 Homebrew	앱 서명과 첫 실행 권한
macOS Intel	공식 Intel 빌드	프로세서 유형과 실행 권한
Windows	공식 설치 파일	PowerShell 또는 CMD 설정
Linux	AppImage 또는 deb 패키지	실행 권한, 그래픽 세션, 의존성

macOS에서 Homebrew를 사용할 경우 공식 문서에 제시된 명령은 다음과 같습니다.

brew install --cask stablyai/orca/orca

Windows에서는 공식 설치 파일을 내려받은 뒤 게시자와 서명 정보를 확인합니다. Linux AppImage는 파일을 실행하기 전에 실행 권한을 부여해야 할 수 있습니다.

chmod +x Orca.AppImage
./Orca.AppImage

Linux 파일명은 릴리스마다 달라질 수 있으므로 위 이름을 그대로 가정하지 말고, 공식 릴리스 페이지에서 실제 파일명을 확인해야 합니다.

다운로드한 파일의 출처가 검색 광고나 제3자 배포 페이지가 아닌지도 확인합니다. 릴리스 페이지에 체크섬이 제공되는 경우 로컬 파일과 비교합니다. 체크섬이 없으면 임의의 숫자를 신뢰하지 말고 공식 릴리스 페이지의 서명, 게시자, 파일명을 기준으로 검증해야 합니다.

두 번째 단계: 첫 실행과 Agent 연결을 분리합니다

첫 실행에서는 홈 디렉터리 접근 권한과 저장소 추가 화면이 나타날 수 있습니다. Orca는 기존 ~/.claude, ~/.codex 설정을 가져올 수 있으므로, 공유 컴퓨터에서는 어떤 인증 정보가 연결되는지 먼저 확인해야 합니다.

연결 순서는 다음이 안전합니다.

1. Orca를 실행하고 홈 디렉터리 접근 요청을 검토합니다.
2. 테스트 저장소 하나만 추가합니다.
3. Orca 외부의 터미널에서 CLI Agent를 먼저 실행합니다.
4. Claude Code라면 구독 로그인 또는 API 설정이 정상인지 확인합니다.
5. Orca의 Agent 목록에서 해당 실행 파일과 기본 셸을 확인합니다.
6. 짧은 읽기 전용 작업으로 연결 상태를 검증합니다.

오르카는 Claude Code에 어떻게 연결합니까?

Orca가 Claude Code의 구독이나 API 키를 대신 관리하는 구조는 아닙니다. Orca는 터미널에서 실행되는 CLI Agent를 연결해 작업을 실행하며, 로그인, 요금제, API 키, 조직 권한은 Claude Code 쪽에서 확인해야 합니다.

인증 토큰을 화면 녹화, 스크린샷, 로그 파일에 남기지 않습니다. 원격 서버로 옮길 때도 셸 기록과 환경 변수, 공유 터미널 캡처에 비밀 값이 포함되지 않았는지 점검해야 합니다.

세 번째 단계: 2개의 작은 작업으로 Parallel AI Coding을 검증합니다

처음부터 큰 기능을 여러 Agent에게 맡기면 실패 원인을 설치 문제와 작업 설계 문제로 나누기 어렵습니다. 다음처럼 서로 겹치지 않는 작업을 선택합니다.

• Agent A: 테스트 파일 1개를 추가하고 기존 테스트만 실행합니다.
• Agent B: 문서 또는 작은 유틸리티 함수 1개를 수정하고 린트만 실행합니다.

Orca에서는 작업마다 독립된 Git worktree와 Agent 터미널을 사용할 수 있습니다. Claude Code도 별도 디렉터리와 브랜치를 만드는 worktree 실행을 지원하므로 Claude Code의 worktree 안내를 함께 참고하면 격리 원리를 이해하기 쉽습니다.

확인 항목	정상 상태	중단해야 하는 상태
작업 디렉터리	두 작업의 경로가 다릅니다	두 Agent가 같은 경로를 사용합니다
브랜치	작업별 브랜치가 분리됩니다	기본 브랜치에서 직접 수정합니다
파일 변경	담당 파일만 바뀝니다	공용 설정과 비밀 파일까지 변경됩니다
테스트	각 worktree에서 독립 실행됩니다	한 작업의 설치 결과에 의존합니다
세션 상태	앱을 닫아도 작업 상태를 다시 확인할 수 있습니다	종료 뒤 작업 위치와 로그가 사라집니다

오르카에서 병렬 Git worktree를 어떻게 만듭니까?

저장소를 Orca에 추가한 뒤 새 작업을 만들고, 각 작업에 다른 이름과 책임을 부여합니다. 작업 화면에서 worktree 경로가 서로 다른지 확인합니다. 수동으로 만들 때는 다음과 같은 Git 명령을 사용할 수 있습니다.

git worktree add ../demo-test -b demo-test
git worktree add ../demo-docs -b demo-docs
git worktree list

이 방식은 Orca의 화면 동작을 검증하는 보조 수단입니다. 실제 앱에서는 공식 문서의 최신 작업 생성 흐름을 우선해야 합니다. .env처럼 추적되지 않는 파일은 새 worktree에 자동으로 존재하지 않을 수 있으므로, 필요한 파일을 별도로 준비해야 합니다.

네 번째 단계: 결과를 비교하고 병합 전 승인합니다

두 Agent가 끝났다고 바로 기본 브랜치에 병합하지 않습니다. 먼저 다음 순서로 확인합니다.

1. 각 worktree의 변경 파일 목록을 비교합니다.
2. diff에서 의도하지 않은 삭제와 설정 변경을 확인합니다.
3. 각 worktree에서 프로젝트 테스트를 독립 실행합니다.
4. 테스트 결과와 변경 범위를 함께 기록합니다.
5. 더 작은 변경으로 같은 요구를 충족한 작업을 선택합니다.
6. 선택한 브랜치만 검토 후 병합합니다.
7. 사용하지 않은 worktree를 제거합니다.

git worktree list
git worktree remove ../demo-test
git worktree prune

커밋되지 않은 변경이나 추적되지 않은 파일이 있는 worktree를 강제로 삭제하면 결과물을 잃을 수 있습니다. --force는 작업 보존 여부를 확인한 뒤 사용해야 합니다.

다섯 번째 단계: 운영체제별 문제를 좁혀갑니다

Orca가 Windows 설치 후 실행되지 않을 때

먼저 설치 파일의 게시자와 Windows 보안 경고를 확인합니다. 그다음 Orca 설정에서 기본 셸이 PowerShell인지 CMD인지 확인하고, 같은 셸에서 Git과 CLI Agent가 실행되는지 검사합니다.

git --version
claude --version
where.exe git
where.exe claude

명령 중 하나라도 인식되지 않으면 Orca 문제가 아니라 PATH 또는 Agent 설치 문제일 가능성이 큽니다. 설치 파일을 반복 실행하기 전에 같은 터미널에서 먼저 경로를 복구해야 합니다.

macOS에서 설치가 차단될 때

Apple Silicon과 Intel 빌드를 혼동하지 않았는지 확인합니다. 이후 시스템 설정의 보안 승인 화면을 검토하고, 공식 다운로드 경로에서 다시 받은 파일인지 확인합니다. 서명 상태가 의심되면 임의의 우회 명령보다 공식 릴리스 파일을 다시 내려받는 편이 안전합니다.

Linux에서 앱이 열리지 않을 때

AppImage 실행 권한, 그래픽 세션, 시스템 라이브러리 상태를 순서대로 확인합니다. 데스크톱이 없는 서버에서 GUI 앱을 직접 실행하려는 경우에는 일반 설치와 다른 접근이 필요합니다. 헤드리스 Linux 서버에서는 Orca의 서버 실행 안내와 현재 릴리스 요구 사항을 먼저 확인해야 합니다.

여섯 번째 단계: 원격 Mac과 Linux 서버로 이전할지 판단합니다

오르카를 원격 서버에 설치할 수 있습니까?

가능하지만 “설치 가능”과 “운영하기 좋은 환경”은 다릅니다. 원격 작업에서는 SSH 재접속, 장시간 세션 유지, 헤드리스 실행, 로그 보존을 함께 검증해야 합니다.

운영 위치	적합한 경우	먼저 검증할 조건
로컬 PC	짧은 실험과 코드 리뷰	자동 절전, 로컬 디스크
원격 Mac	macOS 도구와 장시간 작업	SSH 재접속, 화면 세션, 권한
무인 Linux 서버	지속 실행과 팀 공유	헤드리스 실행, 백업, 로그
Zutcloud의 원격 Mac	임시 테스트와 외부 접근	임대 기간, 원격 접속, 인증 분리

이전 전에 자동 절전을 끄고, worktree가 저장될 디스크 공간을 확인하며, SSH 키와 Agent 인증을 분리합니다. 작업 완료 뒤에는 결과 브랜치, 테스트 로그, 남은 worktree, 임시 비밀 파일을 인수 기준에 포함해야 합니다.

원격 Mac 선택지를 검토한다면 Zutcloud의 Mac 렌탈 안내와 도움말 센터를 함께 확인할 수 있습니다.

마지막 점검: 설치 성공보다 인수 가능한 흐름을 확인합니다

다음 조건을 모두 만족하면 첫 실험을 종료해도 됩니다.

• [ ] Orca가 운영체제에 맞는 공식 빌드로 설치됐습니다.
• [ ] Git과 Claude Code가 Orca 밖에서도 실행됩니다.
• [ ] 두 Agent가 서로 다른 worktree에서 작업했습니다.
• [ ] 각 작업의 변경 파일과 테스트 결과를 비교했습니다.
• [ ] 기본 브랜치에 직접 덮어쓰지 않았습니다.
• [ ] 선택하지 않은 worktree를 정리했습니다.
• [ ] 앱 종료 뒤 세션과 작업 상태를 다시 확인했습니다.
• [ ] 원격 이전 시 절전, 디스크, SSH, 인증, 백업 조건을 기록했습니다.

로컬 PC에서 Orca를 시험하는 방식은 빠르지만, 자동 절전과 제한된 디스크, 개인 계정에 묶인 인증, 장시간 작업 중 네트워크 단절이 운영상의 약점이 될 수 있습니다. 반대로 원격 Mac은 상시 접근과 공유 환경을 구성하기 쉽지만, 임대 기간과 원격 접속 정책, 계정 격리를 먼저 검증해야 합니다.

첫 작업을 마친 뒤 하루 종일 실행하거나 여러 사람이 같은 환경을 사용해야 한다면, Zutcloud의 원격 Mac 환경을 기준으로 필요한 임대 기간과 접속 방식을 비교하는 편이 현실적입니다.