사용 가이드

구매하신 이음(ieum)을 설치하고, 팀을 고르고, 일을 맡기고, 결과를 확인하는 방법을 처음부터 순서대로 설명합니다.

대상 판: ieum 2.7.7-41 · Linux(데비안·우분투 계열, RHEL 계열) · 대상 독자: 라이선스 키와 전용 설치 명령을 메일로 받으신 개발자·운영자

01이음이 하는 일, 1분 요약

이음은 여러 AI 에이전트를 한 화면에 띄워 하나의 팀처럼 일하게 하는 도구입니다. 터미널(ieum-term)의 칸마다 에이전트 CLI(Claude Code, Codex)가 하나씩 뜨고, 칸마다 역할이 정해져 있습니다. 칸 사이의 메시지는 이음 엔진이 확인하고 전달하고 기록합니다.

• ORCH(지휘) — 사용자가 말을 거는 유일한 칸입니다. 요청을 작업(TASK)으로 나누고 작업자에게 배정합니다.
• 작업자 — 팀마다 다릅니다(예: 웹 개발 팀의 UIUX·BACKEND·FRONTEND). 배정받은 일을 하고 완료(DONE)를 보고합니다.
• EVALS(검증) — 작업자의 결과를 검사해 통과(PASS) 또는 반려(FAIL)를 판정합니다. 2.7.7-41의 7개 팀에서는 글·코드·스펙을 Claude가 만들고 EVALS는 Codex가 맡습니다. 만든 쪽과 다른 계열의 모델이 검사합니다.
• 엔진 — 모든 메시지는 Ed25519로 서명된 뒤 저널에 기록되고, 엔진은 서명된 메시지만 전달합니다. DONE 보고가 오면 엔진이 알아서 검증 역할에게 넘기므로 사람이 중계할 필요가 없습니다.
• PASS 뒤에만 끝납니다 — EVALS가 PASS를 내면 엔진이 자동 점검(ieum check)을 한 번 더 돌리고, 이것까지 통과해야 작업이 닫힙니다.

FAIL이면 판정은 ORCH에게 돌아가고, ORCH가 같은 작업을 재작업 번호(…_r2)로 다시 배정합니다.

02준비물

03설치

전용 설치 명령 실행

구매 메일에는 고객님 라이선스 키가 들어간 설치 명령이 한 줄 적혀 있습니다. 형태는 다음과 같습니다.

bash -c "$(curl -fsSL https://ieumworks.com/install/<라이선스 키>)"

• 메일에 적힌 명령을 그대로 복사해 실행하십시오. 주소를 브라우저로 열면 설치 스크립트 대신 “브라우저용이 아닙니다”라는 안내만 나옵니다.
• 이음을 쓸 계정으로 실행하고, 앞에 sudo를 붙이지 않습니다. 패키지를 설치하는 순간에만 스크립트가 sudo 비밀번호를 묻습니다.
• 명령 하나로 저장소 등록, 패키지 설치, 이 계정의 트리 만들기, 활성화까지 진행됩니다. 마지막에 프로젝트 폴더 이름을 물으면 입력하거나, Enter로 건너뛴 뒤 나중에 ieum setup으로 정할 수 있습니다(5장).

저장소가 라이선스로 잠겨 있다는 것

이음 패키지 저장소는 구매자 전용입니다. 인증 없이 저장소에 접근하면 401이 돌아옵니다. 설치 명령이 이 기기에 라이선스 키로 된 저장소 인증 정보를 등록하므로, 그 뒤로는 평소처럼 apt·dnf로 업데이트를 받으실 수 있습니다. 인증 정보는 root만 읽을 수 있는 파일(권한 0600)로 저장됩니다. 업데이트가 401로 막히면 문제 해결을 참고하십시오.

패키지 직접 설치

저장소가 등록된 기기에서는 패키지 이름 ieum으로 설치합니다. 전용 설치 명령을 썼다면 이미 설치되어 있으므로 다시 할 필요는 없습니다.

# 데비안·우분투
sudo apt-get install ieum
# RHEL 계열
sudo dnf install ieum

설치되는 자리: 제품 트리와 계정 트리

이음은 두 벌의 트리를 씁니다.

계정 트리는 ieum install-account로 처음 만들어집니다(전용 설치 명령이 대신 실행합니다). 패키지를 올린 뒤 계정 트리를 새 판에 맞추는 명령이 ieum update입니다. 보통은 ieum up·setup·doctor·team을 실행할 때 이음이 판 차이를 알아채고 자동으로 맞춥니다.

ieum install-account   # 이 계정의 트리를 처음 만듭니다
ieum update            # 새로 설치된 판에 이 계정을 맞춥니다
ieum version           # 엔진·계정 트리·패키지 판을 한 화면에 확인합니다

04라이선스 활성화

전용 설치 명령을 썼다면 활성화까지 끝나 있습니다. 상태는 다음 명령으로 확인합니다.

ieum license

출력의 첫 줄이 상태입니다.

• active — user licence for …, expires … — 활성 상태입니다. 라이선스 종류, 사용자 이름, 만료일이 나옵니다.
• not active — … — 활성화되지 않았습니다. 뒤에 이유가 붙습니다.

그 아래에 user fingerprint(이 기기와 계정의 지문), server fingerprint(기기 지문), 활성화 서버에 마지막으로 연결된 시각(last contact)이 나옵니다.

활성화 명령

# 라이선스 키로 이 기기를 등록하고 라이선스를 받아 옵니다
ieum activate --key <라이선스 키>

# 이미 발급받은 라이선스 파일을 적용합니다
ieum activate --file <파일>

--key와 --file은 함께 쓸 수 없습니다. 재설치나 기기를 옮긴 뒤에는 새 설치 링크를 받지 않고 ieum activate --key로 다시 활성화할 수 있습니다. 라이선스 키는 IEUM-으로 시작합니다. 이전 모델의 HARNESS- 키는 거절됩니다.

기기 바인딩이 뜻하는 것

• 사용자 라이선스는 이 기기(machine-id)와 이 계정에 묶입니다. 라이선스 파일을 다른 기기나 다른 계정에 복사해도 동작하지 않습니다.
• 서버 라이선스는 기기 단위로 발급되며, 그 서버의 모든 계정에서 쓸 수 있습니다.
• 라이선스는 서명으로 보호됩니다. 만료일이나 이름을 한 글자만 바꿔도 무효가 됩니다.
• 엔진은 기동할 때와 10분마다 라이선스를 다시 확인합니다. 도중에 무효가 되면 새 배정을 멈춥니다.
• 구매처에서 등록을 해제한 기기는 12시간 안에 멈춥니다. 같은 기기에서 유효한 키로 다시 활성화하면 풀립니다. 회수된 라이선스는 폐기 목록에 올라 기동할 때와 주기 재확인 때 거부됩니다.
• 키마다 등록할 수 있는 기기 수에 한도가 있을 수 있습니다. 한도에 닿으면 활성화가 거부되니 구매처에 문의하십시오.

05처음 설정

ieum setup — 세션·프로젝트·팀 정하기

ieum setup
# 또는 묻지 않고 한 번에
ieum setup --project ~/work

ieum setup은 세 가지를 묻습니다. 이미 값이 있으면 지금 값이 기본으로 나오므로 Enter만 누르면 그대로 유지됩니다. 몇 번을 다시 실행해도 안전합니다.

1. ieum-term 세션 이름 — 기본값은 harness입니다. 공백, ., :는 쓸 수 없습니다.
2. 프로젝트 폴더 — 에이전트가 일할 폴더입니다. 이름만 적으면 홈 아래에 만듭니다(예: work → ~/work).
3. 팀 구성 — 번호로 고릅니다(6장).

바꿀 내용을 먼저 보여 주고 확인을 받은 뒤 기록하며, 이전 설정은 harness.local.json.bak.<시각>으로 남깁니다. 이어서 개인 상태 폴더 준비, 설정 검사, 칸별 서명키 발급, 설치 봉인, 에이전트 CLI 최신판 확인, 규약·훅·스킬 배치까지 [1/5]~[5/5] 단계로 진행합니다.

git 처리 방식은 다음과 같습니다.

• 새로 만든 폴더라면 git 저장소로 만들고 초기 커밋을 남깁니다.
• 이미 있는 폴더가 git 저장소가 아니거나, 다른 저장소 안에 있거나, 커밋이 없으면 작업 공간 격리를 끄고 모든 칸이 같은 폴더를 씁니다. 커밋을 만든 뒤 ieum setup을 다시 실행하면 격리가 켜집니다(12장).

ieum ready — 역할마다 일을 시킬 수 있는가

ieum ready
ieum ready --verbose   # 판정 근거까지

역할마다 한 줄씩 READY 또는 NOT READY와 이유를 보여 줍니다. CLI가 있는지, 모델이 요구하는 CLI 판을 만족하는지, 역할 규칙 파일이 있는지를 보고, 세션이 떠 있으면 칸이 살아 있는지도 봅니다. CLI 로그인 상태는 보지 않습니다. 칸이 떴는데 응답이 없으면 그 칸에서 CLI가 로그인을 기다리고 있지 않은지 직접 확인하십시오.

ieum doctor — 실행을 막는 문제 찾기

ieum doctor

필요한 명령, 패키지와 계정 트리의 판, 설정, 개인 상태 권한, 서명 신원, 라이선스, 세션, 규약·훅 배치, 에이전트 CLI를 차례로 점검하고, 막힌 항목마다 해결 명령을 붙여 줍니다. 읽는 법은 문제 해결 · doctor 출력 읽기를 참고하십시오.

06팀 고르기

팀은 “어떤 역할이 있고, 누가 무엇을 검증하고, 어떤 순서로 넘어가는가”를 한 벌로 정한 구성입니다. 11개 팀이 준비되어 있고, 기본값은 web-development입니다.

ieum team                     # 지금 팀과 고를 수 있는 구성을 봅니다
ieum team research            # research 팀으로 바꿉니다
ieum down -y && ieum up        # 떠 있는 세션을 새 구성으로 다시 띄웁니다

11개 팀

역할은 화면 칸 순서대로 적었습니다. “게이트”는 ORCH가 진행 전에 사용자 승인을 받는 지점이고, “사람이 하는 단계”는 이음이 대신하지 않는 일입니다.

모델 배치(2.7.7-41)

• 그림은 두 단계로 만듭니다(web · app · iot · marketing · video). 디자인 역할(UIUX · HARDWARE · CREATIVE · STORYBOARD)이 먼저 크기·구성·색·문구·파일 이름을 적은 글 스펙을 쓰고, 그 스펙이 EVALS를 통과한 뒤에만 VISUAL 칸이 그림 파일을 만듭니다. 반려된 스펙에는 그림 비용이 들지 않습니다.
• 7개 팀의 Claude 칸은 도구를 쓸 때마다 승인을 기다리지 않습니다(auto mode). 위험한 명령은 이음의 안전장치(가드 훅)가 막습니다. 나머지 4개 팀의 Claude 칸은 예전처럼 도구마다 승인을 묻습니다.
• publishing 팀에는 별도의 사실 확인 칸이 없고, EVALS가 판정과 함께 사실 확인까지 합니다.

–tier

tier는 “각 역할이 어떤 모델을 어느 effort로 쓰는가”를 정하는 토큰 정책입니다. 지금 제품에 들어 있는 tier는 high 하나이며, 팀 프리셋의 모델을 바꾸지 않고 구성 규칙만 검사합니다.

ieum team research --tier high

팀을 바꿀 때 --tier를 함께 주지 않으면 이전에 적어 둔 tier 기록은 지워지고, 그 팀의 기본값으로 동작합니다.

팀을 바꾸면 달라지는 것

• 제품 설정이 그 팀의 프리셋으로 통째로 바뀝니다(역할, 검증자, 흐름). 고른 팀 이름은 계정 설정에 기록되어 업그레이드 뒤에도 유지됩니다.
• 새 칸의 서명키를 발급하고, 규칙·훅·스킬을 각 칸 자리에 다시 배치합니다.
• 그 팀의 단계 정본을 <프로젝트>/plans/pipeline.md에 둡니다. 직접 고쳐 둔 파일이 있으면 pipeline.md.bak으로 남깁니다. ORCH는 이 파일에 적힌 순서·한도·승인 게이트대로 움직입니다.
• 설치 봉인이 깨끗했다면 새 구성으로 다시 봉인합니다.
• 이전 팀의 끝나지 않은 작업이 있으면 목록을 보여 주고 닫을지 묻습니다. 새 팀의 칸은 이전 배정을 모르기 때문입니다. 묻지 않고 정하려면 --close-tasks(닫기) 또는 --keep-tasks(남기기)를 붙입니다.
• 이미 세션이 떠 있다면 ieum down -y && ieum up이 필요합니다. ieum restart는 엔진만 다시 띄우므로 칸이 이전 역할 그대로 남습니다.

07시작과 종료

ieum up                # 세션·칸·에이전트·엔진을 시작하고 화면에 연결합니다
ieum up --no-attach    # 시작만 하고 화면에는 연결하지 않습니다

ieum up은 무엇을 만들기 전에 먼저 확인합니다. 라이선스가 활성 상태가 아니거나, 프로젝트 폴더가 없거나, 팀이 쓰는 에이전트 CLI가 없으면 아무것도 만들지 않고 멈춥니다. 설치 봉인이 없거나 맞지 않으면 경고를 냅니다. 통과하면 규약을 배치하고, 칸을 만들고, 각 칸에 에이전트를 띄우고, 엔진을 시작한 뒤 화면에 연결합니다.

08일 맡기기

ORCH 칸에 말합니다

사용자가 입력하는 곳은 화면 왼쪽 아래의 ORCH 칸입니다. 다른 칸에 직접 입력할 수도 있지만, 일을 맡기는 것은 ORCH에게 합니다. 나머지 전달은 엔진이 하므로 사람이 메시지를 옮겨 적을 필요가 없습니다.

요청할 때 무엇을 원하는지, 어디까지인지, 무엇이 되면 끝인지, 지켜야 할 조건을 함께 적으면 ORCH가 작업을 더 정확히 나눕니다.

# web-development 팀 예시
회원 가입 기능을 만들어 주세요. 이메일과 비밀번호로 가입하는 API와 가입 화면이 필요합니다.
기존 코드는 src/ 아래에 있고, 테스트는 make test 로 돌립니다.
새 라이브러리는 추가하지 말고, 끝나면 무엇을 바꿨는지 알려 주세요.

# publishing 팀 예시
신입 사원용 사내 보안 안내서 초안을 써 주세요. 대상은 비개발 직군이고, 10쪽 안팎입니다.
출처가 있는 내용만 쓰고, 출처 목록을 끝에 붙여 주세요.

# research 팀 예시
국내 전기차 충전 요금 정책의 최근 변화를 조사해 한 장짜리 요약으로 정리해 주세요.
수치마다 출처를 달아 주세요.

ORCH가 하는 일

1. 요청을 받아 계획(plans/plan.md)을 쓰고 작업(TASK)으로 나눕니다.
2. 팀의 단계 정본(plans/pipeline.md)에 적힌 순서대로 작업자에게 배정합니다. 파일이 겹치지 않는 작업끼리는 동시에 배정합니다.
3. 작업자가 DONE을 보고하면 엔진이 EVALS에게 검증을 넘기고, ORCH는 판정을 기다립니다.
4. PASS가 나면 격리된 작업자의 브랜치를 본선에 병합하고 다음 단계로 넘어갑니다.
5. 모든 단계가 끝나면 PASS 근거와 함께 결과를 보고합니다.

ORCH가 사용자에게 묻는 때(NEED_INPUT)

진행에 사용자 결정이 필요하면 ORCH가 NEED_INPUT으로 묻습니다. ORCH 칸에 답하시면 됩니다.

• 승인 게이트 — 팀마다 정해진 게이트(예: web-development의 REVIEW · DEPLOY)에서는 PASS 근거를 붙여 승인을 요청합니다.
• 사람이 하는 단계 — 배포, 스토어 제출, 실기기 플래싱, 게시처럼 이음이 대신하지 않는 일은 작업자가 “어디까지 했고 사람이 무엇을 실행하면 되는지”를 적어 넘기고, ORCH가 그 내용을 사용자에게 전합니다.
• 검증 한도에 닿았을 때, 테스트 도구가 없을 때(아래)도 사용자에게 묻습니다.

PASS와 FAIL

09화면 다루기

화면 배치

• 위쪽 — 작업자와 EVALS 칸입니다. 읽기만 해도 되고, 필요하면 입력할 수도 있습니다.
• 아래 왼쪽 — ORCH 칸. 일을 맡기는 곳입니다.
• 아래 오른쪽 — SHELL. 사용자 전용 일반 셸입니다. 이음은 이 칸에 아무것도 입력하지 않고 일도 배정하지 않습니다.
• 맨 아래 파란 상태줄 — 지금 키 입력이 어느 칸으로 가는지 보여 줍니다. 오른쪽에는 ! 1 blocked · 2 to review 또는 all clear · N working 같은 요약이 나옵니다.
• 칸 제목은 “역할 · 지금 작업”입니다. 배치가 흐트러지면 ieum arrange로 되돌립니다. 이 명령은 칸의 자리만 바꾸며 에이전트는 그대로 둡니다.

칸 사이 이동(Ctrl-b 다음 키)

이동은 표준 접두키 Ctrl-b를 누른 뒤 다음 키를 누르는 방식입니다. 이음은 화살표나 글자 키만 따로 가로채지 않으므로, 에이전트 CLI 안의 명령 이력·메뉴·승인 선택은 평소대로 동작합니다.

F키와 메뉴

이음은 다음 F키를 겁니다. 단, 그 키를 다른 설정이 이미 쓰고 있으면 걸지 않고 대체 키로 내려갑니다. 접두키 쪽 대체 키는 언제나 걸려 있으므로, F키가 터미널에서 먹히지 않아도 쓸 수 있습니다. 지금 실제로 걸린 키는 ieum keys로 확인합니다.

아래 프로그램에서 원래 F키가 필요하면 Ctrl-b 다음 그 F키를 누르십시오. 그대로 전달됩니다.

메뉴(F10 또는 ieum menu)에는 ORCH·SHELL·역할로 이동, 이전 칸으로 돌아가기, 복사·검색(스크롤백, 위로 검색, 칸 내용을 파일로 내보내기), 주의가 필요한 것(board), 화면(다시 그리기, 이음 배치 복원, 크게 보기), 입력과 클립보드 안내, 진단과 로그(훅 시간·실패, 엔진 로그, doctor, 진단 보고서 저장, 터미널 입력 복구), 도움말, 판·라이선스 정보, 빠져나오기가 있습니다. 메뉴와 키 안내는 일부 터미널의 한글 깨짐을 피하려고 영어로 표시됩니다.

명령으로 이동하기

ieum go UIUX                 # 역할로 이동
ieum go T20260921_API-1      # 그 작업을 맡은 칸으로 이동
ieum go                      # 지금 가장 급한 곳으로 이동

화면 밖(빠져나온 상태)에서 부르면 그 칸을 고른 채로 화면에 연결해 줍니다.

글자 복사

마우스는 기본으로 꺼져 있어서, SecureCRT·PuTTY 같은 터미널 프로그램이 평소처럼 글자를 선택·복사합니다. 칸 경계선이 섞이지 않게 하려면 Ctrl-b z로 칸을 크게 한 뒤 끌어서 선택하십시오. 휠로 칸을 스크롤하고 싶으면 ieum term mouse on을 쓰는데, 이때는 터미널 프로그램의 선택·복사가 되지 않습니다. 되돌리려면 ieum term mouse off입니다.

10결과 확인

저널

칸 사이의 모든 메시지는 <프로젝트>/data/journal.jsonl에 서명된 채 기록됩니다. 리포트의 모든 숫자는 이 저널에서 나오므로 특정 기록으로 되짚을 수 있습니다. 저널이 커지면(기본 64MB) 엔진이 보관 파일로 옮기고 최근 5개까지 남깁니다.

tail -n 20 ~/work/data/journal.jsonl   # 프로젝트 폴더가 ~/work 인 경우

자동 점검 ieum check

EVALS의 PASS는 모델의 판단입니다. 그 뒤에 엔진이 ieum check를 한 번 더 돌려 기계적으로 확인하고, 이것까지 통과해야 작업이 닫힙니다. 점검은 그 작업자가 일한 작업 공간에서 돌아갑니다.

ieum check             # 지금 팀의 점검을 실행합니다
ieum check --explain   # 실행하지 않고 무엇을 검사할지만 보여 줍니다

무엇을 검사하는지는 팀에 따라 다릅니다.

• 코드 팀(web-development · app-development · game-development · iot-hardware) — 프로젝트에 있는 테스트 도구를 찾아 돌립니다. Makefile의 test:(make test), go.mod(go vet·go test), package.json의 build·test 스크립트, pytest, cargo test, ./gradlew test, flutter test, ctest, phpunit 등입니다.
• 문서 팀(publishing · research · business · education · idea-planning) — docs/ 아래 산출물의 죽은 링크와, 인용한 출처가 실제로 있는지 봅니다.
• marketing은 코드·에셋·문서를, video-production은 문서·에셋(파일 실존·크기)을 봅니다.

11비용·사용량

엔진은 두 CLI가 남기는 호출별 사용량을 읽어 원장(<프로젝트>/data/usage.jsonl)에 적습니다. ieum cost가 이 원장을 보여 줍니다.

ieum cost                    # 역할별(기본)
ieum cost --by provider      # 계열(claude·codex)별
ieum cost --by task          # 작업별
ieum cost --by model         # 모델별
ieum cost --since 24h        # 최근 24시간만 (예: 30m)
ieum cost --json             # 또는 --csv

• --by provider는 Claude와 Codex가 쓴 토큰과 그 몫을 같은 기준(캐시 포함 총량, 캐시 읽기를 뺀 새 입력+출력)으로 나눠 보여 줍니다.
• 금액 앞의 ≈는 추정값이라는 뜻입니다. 단가를 모르는 호출은 0원이 아니라 “단가 없음”으로 표시하고, 합계가 전부가 아니면 그렇다고 알려 줍니다.
• 2.7.7-41부터 여러 역할이 한 폴더를 함께 쓸 때도 사용량이 역할·계열별로 제대로 나뉩니다.

12작업 공간 격리(워크트리)

두 에이전트가 같은 폴더를 동시에 고치면 서로의 작업을 덮어씁니다. 이음은 이것을 구조로 막습니다. 격리가 켜진 팀의 작업자는 프로젝트를 직접 고치지 않고, 각자 agent/<역할> 브랜치의 git 워크트리(<프로젝트>/.harness-worktrees/<역할>)에서 일합니다. EVALS가 PASS를 낸 뒤에 ORCH가 본선으로 병합합니다.

• 격리를 쓰는 팀: web-development · app-development · game-development · iot-hardware · marketing. 나머지 팀은 모든 칸이 같은 폴더를 씁니다.
• 프로젝트 폴더가 자기 git 저장소의 루트이고 커밋이 하나 이상 있어야 격리가 켜집니다. 아니면 ieum setup이 격리를 끄고 알려 줍니다.

ieum worktree status            # 브랜치별 본선 대비 앞섬·뒤짐·미커밋
ieum worktree merge BACKEND     # PASS 뒤 본선으로 병합
ieum worktree sync BACKEND      # 본선을 그 브랜치로 끌어와 최신화
ieum worktree reset BACKEND     # 브랜치를 본선으로 되돌림(작업 폐기, 확인 후에만)

병합과 동기화는 보통 ORCH가 합니다. 사용자는 상태를 확인할 때 ieum worktree status를 쓰면 됩니다. ieum down으로 세션을 내려도 워크트리는 남습니다.

13업데이트

# 1) 패키지를 올립니다
sudo apt-get update && sudo apt-get install --only-upgrade ieum   # 데비안·우분투
sudo dnf upgrade ieum                                             # RHEL 계열

# 2) 계정마다 계정 트리를 새 판에 맞춥니다
ieum update

# 3) 떠 있는 칸을 새 판으로 다시 띄웁니다
ieum down && ieum up

• ieum update는 새 패키지를 내려받지 않습니다. 이미 설치된 패키지(/usr/lib/ieum)를 계정 트리로 옮길 뿐입니다. 받아 둔 저장소 목록에 더 새 판이 보이면 받는 명령을 알려 줍니다.
• 2단계는 보통 자동으로 됩니다. ieum up·setup·doctor·team을 실행하면 판 차이를 알아채고 계정 트리를 맞춥니다.
• ieum restart는 엔진만 다시 띄우므로 칸이 옛 판으로 남습니다. 판을 올린 뒤에는 ieum down && ieum up입니다.
• 계정 설정(세션, 프로젝트, 고른 팀과 tier)과 개인 상태(서명키, 라이선스)는 보존되므로 다시 활성화할 필요가 없습니다.
• 올린 뒤 ieum version으로 엔진·계정 트리·패키지 판이 맞는지 확인하십시오.

14문제 해결

무엇이 막혀 있는지 모를 때는 먼저 ieum doctor를 실행하십시오. 막힌 항목마다 해결 명령이 붙어 나옵니다.

칸이 CLI 안내 창·메뉴에 멈춰 있을 때

칸에 CLI의 안내 창이나 메뉴가 떠 있으면, 엔진은 메시지를 그 칸에 치지 않고 붙들어 두었다가 창이 닫힌 뒤 도착 순서대로 넣습니다. 알려진 창(Codex 훅 신뢰 확인, Claude auto mode 안내)은 이음이 스스로 닫습니다. 5분 넘게 넣지 못하면 ORCH에 [HARNESS]로 시작하는 알림이 갑니다. 붙든 메시지는 엔진을 다시 띄워도 남습니다.

1. ieum go <역할>로 그 칸에 가서 떠 있는 창에 직접 답합니다.
2. 로그인을 기다리는 화면이라면 그 CLI에 로그인합니다. ieum ready는 로그인 상태를 보지 않으므로 이 경우를 잡지 못합니다.
3. 칸의 에이전트가 멈춰 버렸다면 그 칸만 다시 띄웁니다.

ieum panes --pane 3          # 3번 칸의 에이전트만 다시 시작
ieum recover                 # 엔진을 다시 세우고 멈춘 칸만 다시 띄움

칸 재시작 횟수 한도를 다 쓰면 엔진이 더 이상 되살리지 않고 ORCH에 알립니다. 이때는 ieum panes --pane N --force로 직접 되살립니다.

봉인 불일치로 엔진이 뜨지 않을 때

설치 파일이 봉인(설치 직후 기록한 무결성 기준값)과 다르면, 엔진은 운영 모드에서 기동하지 않고 “설치물이 봉인과 N개 파일에서 다릅니다”라고 알립니다.

ieum seal verify             # 무엇이 달라졌는지 파일 단위로 확인
ieum seal write              # 직접 고친 것이 맞을 때만 다시 봉인
ieum down && ieum up

라이선스가 없다고 나올 때

ieum up이 “활성화되지 않았습니다 — 아무것도 만들지 않고 멈춥니다”라며 멈춥니다.

ieum license                          # 상태와 이유 확인
ieum activate --key <라이선스 키>      # 다시 활성화

다른 계정에서 활성화했거나 기기가 바뀌었거나 구매처에서 등록을 해제한 경우가 흔합니다. 키가 거절되면 메시지를 구매처에 전달해 주십시오.

업데이트가 401로 막힐 때

sudo apt-get update나 dnf가 이음 저장소에서 401을 받는다면, 이 기기의 저장소 인증 정보가 없거나 유효하지 않은 것입니다. 저장소가 잠기기 전에 설치한 기기에서 주로 생깁니다. 구매처에서 받은 저장소 인증 갱신 명령(설치 명령 주소 끝에 ?repo=1이 붙은 형태)을 이음을 쓰는 계정으로 실행하면 저장소 인증만 새로 등록합니다. 다시 활성화하지 않으며 설치 대수도 쓰지 않습니다.

bash -c "$(curl -fsSL 'https://ieumworks.com/install/<라이선스 키>?repo=1')"

명령을 받지 못하셨으면 구매처에 요청하십시오. 그 뒤에는 평소처럼 업데이트하면 됩니다.

CLI 판이 낮을 때

ieum ready에 NOT READY 판 부족(claude 2.1.xxx < 2.1.278, claude-opus-5-5)처럼 나옵니다. ORCH 모델은 claude 2.1.278 이상이 필요합니다.

claude update          # 전역 설치라 권한이 없으면: sudo claude update
codex update
ieum ready

CLI가 아예 없다는 메시지(claude 없음, codex 없음)가 나오면 이음 계정에서 보이는 자리에 설치하십시오. 다른 경로에 설치되어 있다는 안내가 나오면, 그 경로를 PATH에 넣거나 안내대로 harness.local.json의 provider_commands에 적습니다.

테스트 도구가 없을 때

코드 팀에서 ieum check가 “돌릴 검사를 찾지 못했습니다 — 통과시키지 않습니다”를 냅니다. 7개 팀에서는 작업이 BLOCKED가 되고 ORCH가 어떻게 할지 묻습니다. 프로젝트에 테스트 도구(make test, go test, npm test, pytest 등)를 두거나 ORCH에게 테스트를 만들어 달라고 요청한 뒤 다시 검증받으십시오. 무엇을 검사할 수 있는지는 ieum check --explain으로 확인합니다.

화면에 ^[[<35;23;1M 같은 글자가 찍힐 때

터미널의 마우스 보고가 켜진 채로 남은 것입니다(글꼴 문제가 아닙니다).

ieum term restore      # 같은 기기에 있을 때
ieum term recover      # 이미 Windows 프롬프트로 빠져나온 뒤의 복구 방법 보기

화면이 얼거나 반쯤 그려졌다면 메뉴 → Screen → Redraw를 씁니다. 어떤 프로세스도 건드리지 않습니다.

팀을 바꾼 뒤 이전 작업이 남아 있을 때

ieum down
ieum tasks cancel --open      # 끝나지 않은 작업을 전부 닫습니다(엔진이 멈춰 있을 때만)
ieum up

doctor 출력 읽기

ieum doctor는 다음 순서로 점검합니다: 명령(ps, jq, ieum-term, 엔진, 메시지 송신기) → 설치본(패키지와 계정 트리 판) → 설정 → 개인 상태(폴더 0700, 서명키 0600) → 서명 신원 → 라이선스 → 세션(칸 수, 칸과 역할의 대응, 프로젝트 경로) → 규칙·훅 배치(CLAUDE.md·AGENTS.md 규약, 훅, 스킬, 가드 정책) → 에이전트 CLI.

자주 보는 FAIL과 해결 방법입니다.

• 패키지 2.7.7-41 · 계정 설치본 2.7.7-40 → ieum update
• 활성화되지 않음 → ieum license로 확인한 뒤 활성화
• 세션 없음 → 아직 띄우지 않은 상태라면 ieum up
• 홈에 공유 규약이 없음, 훅이 설치되지 않음 → ieum sync-rules
• claude 없음 (claude) → CLI 설치 또는 경로 지정

도움을 요청할 때는 메뉴 → Diagnostics → Save a diagnostic report로 진단 보고서를 저장해 전달하셔도 됩니다. 키·토큰·환경변수·대화 기록은 담기지 않고, 어디로도 전송되지 않습니다.

15자주 묻는 질문

API 키를 따로 발급받아야 하나요?

아니요. 모든 역할은 이 계정에 로그인된 Claude Code와 Codex CLI로 뜹니다. 두 서비스의 구독은 고객이 준비합니다.

Claude나 Codex 중 하나만 있어도 되나요?

11개 팀 모두 ORCH는 Claude, EVALS는 Codex이므로 두 CLI가 모두 필요합니다. 하나가 없으면 ieum up이 세션을 만들기 전에 멈추고, 어느 칸이 뜨지 못하는지 알려 줍니다.

터미널을 닫으면 작업이 멈추나요?

멈추지 않습니다. 창을 닫거나 Ctrl-b d로 빠져나와도 에이전트는 계속 일합니다. ieum attach로 돌아오십시오. 모든 것을 멈추는 명령은 ieum down입니다.

ORCH 말고 다른 칸에 입력해도 되나요?

입력할 수는 있지만, 일을 맡기는 곳은 ORCH입니다. ORCH가 배정과 검증 흐름을 관리하기 때문에 작업자에게 직접 시키면 그 일은 흐름 밖에 놓입니다. SHELL 칸은 사용자 전용이라 자유롭게 쓰셔도 됩니다.

배포나 게시까지 해 주나요?

하지 않습니다. 배포, 스토어 제출, 실기기 플래싱, 게시, 캠페인 집행, 렌더처럼 되돌리기 어렵거나 이음에 도구가 없는 단계는 사람이 합니다. 작업자는 어디까지 했고 무엇을 실행하면 되는지 정리해 넘기고, ORCH가 그 내용을 전합니다.

에이전트가 위험한 명령을 실행하지는 않나요?

각 칸에 이음의 가드 훅이 걸려 있어 파괴적 명령, 비밀 열람, 권한 상승, 작업 범위 밖 쓰기를 막습니다. 검증 역할은 파일을 고칠 수 없고, 지휘 역할은 직접 구현할 수 없습니다. 운영 모드에서는 CLI의 권한 우회 옵션이 빠지고, Codex 칸은 쓸 수 있는 곳이 작업 폴더 등으로 제한된 샌드박스에서 돕니다.

같은 작업이 계속 반려되면 어떻게 되나요?

7개 팀에서는 한 작업의 검증이 최대 3번이고, 같은 이유로 거듭 반려되면 엔진이 멈추고 ORCH가 사용자에게 어떻게 할지 묻습니다. 끝없이 비용이 나가지 않습니다.

테스트가 없는 프로젝트에서도 쓸 수 있나요?

쓸 수 있습니다. 다만 코드 팀에서는 자동 점검이 테스트 없이 통과시키지 않으므로, 7개 팀에서는 ORCH가 테스트 도구를 둘지 먼저 묻습니다. 문서·기획 계열 팀은 테스트 도구가 필요 없습니다.

팀을 바꾸면 진행하던 작업은 어떻게 되나요?

이전 팀의 끝나지 않은 작업 목록을 보여 주고 닫을지 묻습니다. 새 팀의 칸은 이전 배정을 모르므로 보통 닫는 것이 좋습니다. 파일과 저널은 그대로 남습니다.

업데이트를 했는데 판이 그대로입니다.

ieum update는 패키지를 내려받지 않습니다. 먼저 apt·dnf로 패키지를 올리고, ieum update 뒤 ieum down && ieum up을 하십시오. ieum version으로 세 판이 맞는지 확인할 수 있습니다.

한 기기에서 여러 계정이 쓸 수 있나요?

계정마다 ieum install-account로 자기 트리를 만들어 씁니다. 사용자 라이선스는 기기와 계정에 묶이므로 계정마다 활성화가 필요하고, 서버 라이선스는 그 기기의 모든 계정에서 쓸 수 있습니다.

메뉴와 키 안내가 왜 영어인가요?

일부 터미널에서 한글이 깨진다는 보고가 있어 화면 안의 메뉴와 키 안내(ieum keys, ieum guide)는 영어로 표시합니다.

칸의 글자를 복사할 수 없습니다.

마우스가 켜져 있으면(ieum term mouse on) 터미널 프로그램의 선택이 되지 않습니다. ieum term mouse off로 끄고, Ctrl-b z로 칸을 크게 한 뒤 선택하십시오.

제거하려면 어떻게 하나요?

먼저 ieum uninstall --dry-run으로 무엇이 지워지는지 확인한 뒤 ieum uninstall을 실행합니다. 기본으로는 계정 트리와 홈에 배치한 규약·훅만 지우며, 서명키·라이선스(--keys)와 프로젝트의 data/·워크트리(--project)는 옵션을 줄 때만 지웁니다. 시스템 패키지는 지우지 않고 명령만 알려 줍니다. 패키지를 지워도 계정 트리와 개인 상태는 남습니다.

16명령 요약표

ieum help의 기본 화면에 나오는 명령입니다. 평소에 쓰지 않는 명령은 ieum help --all로 봅니다.

준비

기동

작업 요청 및 상태 확인

작업 통합

점검 및 관리

평소에는 쓰지 않는 명령(ieum help –all)

도움말 화면에는 없지만 제공되는 명령

맨 위로