이온디

@eond

맥북 앞에 앉아 있는데 실제 작업은 리눅스 데스크탑에서 돌려야 할 때가 있다. 소스도 거기 있고, 도커도 거기 떠 있고, GPU도 거기 붙어 있는 경우다. Orca는 이런 상황을 위해 원격 런타임을 붙이는 방법을 따로 갖고 있다. SSH로 터미널만 여는 것과는 다르게, 워크트리와 터미널 세션까지 통째로 원격 머신 것을 쓰게 된다.

설정하면서 헷갈렸던 부분과 실제로 막혔던 지점을 정리해 둔다.

먼저 이해할 것: Orca가 머신을 부르는 방법은 세 가지다

이게 제일 헷갈리는 지점이고, 잘못 쓰면 결과가 비어서 나오거나 호스트를 못 찾는다는 에러가 난다. orca host list가 이걸 한 번에 알려준다.

종류 지정 방법 성격 지금 이 머신 --host local 기본값 SSH 타겟 --host ssh: 연결된 Orca 호스트가 SSH로 닿는 머신 페어링된 Orca 서버 --environment <이름> 머신이 아니라 연결이다

맥북에서 리눅스 데스크탑에 붙는 건 세 번째, 페어링된 Orca 서버다. SSH 타겟과 헷갈려서 --host 자리에 환경 이름을 넣으면 안 된다. 이 둘을 바꿔 쓰는 게 가장 흔한 실패다.

참고로 SSH 타겟 목록은 지금 연결되어 있는 Orca 호스트 기준으로 읽어온다. 다른 서버에 등록된 SSH 타겟은 여기 안 보인다.

1단계. 리눅스 데스크탑에서 런타임 열기

받는 쪽(리눅스)에서 창 없이 런타임 서버를 띄운다.

orca serve
orca serve --port 45678
orca serve --pairing-address wss://desk.example.com

포그라운드로 돌면서 바인딩된 주소, 클라이언트에 광고할 주소, 페어링 상태를 찍어준다. 종료는 Ctrl+C. 웹 클라이언트 번들이 있으면 페어링 정보가 박힌 브라우저 URL도 같이 나온다.

주의. --pairing-address는 클라이언트에게 알려줄 주소만 바꾼다. 실제로 그 주소로 닿을 수 있어야 하므로 LAN 주소, Tailscale, SSH 포워드, 리버스 프록시 중 하나를 실제로 준비해 두고 넣어야 한다. 공유기 안쪽 사설 IP를 그대로 광고해 놓고 밖에서 붙으려 하면 당연히 안 된다.

실제로 막혔던 곳

리눅스에서 Orca 데스크탑 앱을 이미 켜 둔 상태로 orca serve를 실행하면 이렇게 뜨고 그냥 종료된다.

[single-instance] Another Orca instance is already running
for this userData profile; exiting this launch after
requesting the existing window.

같은 userData 프로필을 두 프로세스가 못 쓴다. 헤드리스로 띄우려면 데스크탑 앱을 먼저 닫는다.

2단계. 맥북에 그 런타임을 등록하기

리눅스가 뱉은 페어링 코드를 맥북 쪽 Orca에 저장한다.

orca environment add --name linux-desktop --pairing-code "orca://pair?code=..."
orca environment list
orca environment show --environment linux-desktop

등록 전에는 orca environment list가 No saved environments.라고 나오고, orca host list에도 로컬 한 줄만 보인다. 이 두 명령이 현재 상태를 확인하는 기준점이다.

environment list에서 이름과 id를 둘 다 확인해 둔다. 다음 단계에서 id가 필요하다.

3단계. 원격 쪽에 저장소 등록하기

여기서 이름과 id를 헷갈리면 바로 막힌다. 저장소를 붙일 때는 --host runtime: 형식을 쓰는데, 이 자리에 들어가는 건 환경 이름이 아니라 environment list에 나오는 id다.

원격에 이미 클론해 둔 폴더가 있으면 그걸 그대로 가져다 쓴다.

orca project setup-existing-folder \
  --project github:myorg/myapp \
  --host runtime:03ef704c-b180-4b10-998d-e28fbd5de9a3 \
  --path /home/me/dev/myapp \
  --kind git

원격에 새로 클론하게 하려면 이쪽이다.

orca project setup-clone \
  --project github:myorg/myapp \
  --host runtime:03ef704c-b180-4b10-998d-e28fbd5de9a3 \
  --url https://github.com/myorg/myapp.git \
  --destination /srv

원격 런타임에 붙일 때 --path와 --destination은 반드시 원격 머신 기준 절대 경로여야 한다. 맥북에서 치는 명령이라고 맥북 경로나 ~를 쓰면 엉뚱한 데를 가리킨다. --destination은 클론이 들어갈 부모 디렉터리라는 점도 주의.

SSH 타겟에 저장소를 붙이는 건 CLI로 안 되고 데스크탑 UI에서 해야 한다. SSH 연결은 데스크탑 클라이언트가 들고 있기 때문이다. 페어링된 런타임은 CLI로 되고, SSH 타겟은 UI로 한다고 외워두면 편하다.

로컬 폴더를 그냥 Orca에 물리는 건 훨씬 단순하다.

orca repo add --path /home/me/dev/myapp

4단계. 원격에서 실제로 굴리기

등록이 끝나면 평소 쓰던 명령에 --environment만 붙이면 된다. 워크트리와 터미널이 전부 리눅스 쪽에서 생긴다.

orca worktree create --name fix-login --repo path:/home/me/dev/myapp \
  --environment linux-desktop

orca terminal create --worktree active --command "claude" --environment linux-desktop

orca terminal read --environment linux-desktop
orca terminal send --environment linux-desktop
orca terminal wait --environment linux-desktop

기존 체크아웃에서 에이전트만 새로 띄우고 싶으면 worktree create가 아니라 terminal create를 쓴다. 워크트리를 만들면 체크아웃이 새로 생긴다.

여러 워크트리를 동시에 굴리는 중이라면 orca worktree ps가 지금 뭐가 어디까지 갔는지 한 줄씩 요약해 준다.

정리

페어링된 원격 런타임은 --environment 이름, SSH 타겟은 --host ssh:id. 섞어 쓰지 않는다.
저장소를 붙일 때만 --host runtime:환경id 형식이고, 여기는 이름이 아니라 id다.
원격 경로는 항상 원격 머신 기준 절대 경로.
헤드리스 orca serve는 같은 프로필의 데스크탑 앱이 떠 있으면 안 뜬다.
--pairing-address는 광고용 주소일 뿐이라, 실제 경로(LAN, Tailscale, SSH 포워드, 리버스 프록시)는 따로 준비해야 한다.

맥북은 화면과 입력만 담당하고 빌드와 에이전트는 전부 리눅스에서 도는 구조가 되니, 노트북 팬 도는 소리가 확실히 줄었다. 배터리도 덜 먹는다.

명령 옵션은 orca <명령> --help에 다 나와 있고, 각 명령의 Notes 항목에 함정이 대부분 적혀 있다. 막히면 거기부터 보는 게 빠르다.

2026년 08월 27일 · 14:01

0 좋아요 0 답글 2 조회