마블로 최초 시작 가이드 — 다운로드부터 첫 에이전트 완주까지

마블로를 처음 켜면, 대부분의 사람은 에이전트를 한 번도 스폰하지 못하고 앱을 닫습니다. 제품이 나빠서가 아니라, 가치를 보기 전에 세 개의 벽에 막히기 때문입니다. 이 글은 그 세 벽을 미리 알려 주고, 하나씩 넘어 첫 에이전트가 티켓 하나를 끝까지 완료하는 순간까지 데려가는 실전 가이드입니다.

개발자를 1차 독자로 쓰되, Node.js 설치 단계까지 포함해 AI 도구가 처음인 분도 혼자 끝까지 갈 수 있게 했습니다.

★시작 전에 — 솔직하게 말씀드립니다 (BYOK)

마블로는 여러분의 AI 계정으로 에이전트를 돌립니다. 이걸 BYOK(Bring Your Own Key, 자기 키 가져오기)라고 부릅니다. 그래서 시작하려면 두 가지 준비물이 필요하고, 둘 다 없으면 첫 스폰에서 막힙니다.

• 유료 구독

폴더연결첫완주벽 ① Node.js 부재 · 벽 ② 유료 Claude 계정 미인증 · 벽 ③ 무료 계정으로 통과 후 첫 스폰 크래시

준비물 1 — 본인 유료 Claude 구독(또는 API 키)

마블로가 스폰하는 에이전트는 Claude Code CLI로 도는데, Claude Code는 유료 플랜(Claude Pro 이상) 또는 Anthropic API 키가 있어야 실제로 동작합니다. 무료 계정으로 claude login을 하면 로그인 자체는 되지만, 첫 작업에서 조용히 실패합니다 (이게 벽 ③입니다).

• 가장 매끄러운 길: 이미 Claude Pro(또는 Max)를 쓰고 있다면 그대로 claude login 하면 됩니다.
• API 키로도 됩니다: ANTHROPIC_API_KEY를 발급받아 쓰면 구독 없이도 동작합니다. 사용한 만큼 과금됩니다.
• Codex를 쓸 거면 OpenAI 쪽도 동일합니다 — 유료 ChatGPT 구독 또는 OPENAI_API_KEY.

요점: 마블로 로그인은 무료지만, 에이전트를 실제로 돌리는 비용은 여러분의 AI 계정에서 나갑니다. 이 사실을 모르고 시작하면 첫 스폰에서 막힙니다.

준비물 2 — Node.js / npm

에이전트 CLI(Claude Code · Codex)는 npm 패키지로 설치됩니다. 그래서 컴퓨터에 Node.js와 npm이 있어야 합니다. 개발자라면 이미 있을 가능성이 높지만, 없으면 아래 Step 2에서 5분 안에 설치합니다.

지금 있는지 확인하려면 터미널에 이렇게 칩니다:

node -v && npm -v

버전 번호(예: v20.11.0 / 10.2.4)가 나오면 준비 완료입니다. command not found가 나오면 Step 2로 가세요.

Step 0 — 파운더 승인 & 앱 다운로드

현재 마블로는 파운더(선정된 베타 사용자)에게만 데스크톱 앱을 배포합니다. 그래서 다운로드 페이지에 바로 가면 앱 대신 로그인/신청 안내가 뜹니다.

순서는 이렇습니다.

1. 파운더 신청에서 이메일 한 줄로 신청합니다 (선착순이 아니라 검토 후 선정).
2. 선정되면 접근 안내가 이메일로 옵니다.
3. 로그인한 상태로 다운로드 페이지에 들어가면, 그제서야 macOS(Apple Silicon·Intel)·Windows용 빌드를 받을 수 있습니다.

🎥 영상 슬롯 A — 파운더 이메일을 받은 화면 → 로그인 → 다운로드 버튼이 열리는 흐름. (앱 밖 웹 화면이라 실캡처 가능)

Step 1 — 설치하고 처음 실행하기

내려받은 파일을 실행합니다.

• macOS: .dmg를 열어 마블로를 응용 프로그램 폴더로 드래그합니다.
• Windows: 설치 관리자를 그대로 진행합니다.

처음 실행하면 macOS Gatekeeper 또는 Windows SmartScreen 경고가 뜰 수 있습니다. 정식 서명·공증된 빌드이니 이렇게 넘어갑니다.

• macOS: 시스템 설정 > 개인정보 보호 및 보안에서 "확인 없이 열기".
• Windows: 추가 정보 > 실행.

🎥 영상 슬롯 B — 첫 실행 시 Gatekeeper/SmartScreen 경고를 넘기고 앱이 켜지는 순간.

Step 2 — Node.js / npm 설치 (벽 ①)

node -v가 command not found였다면 여기서 해결합니다. 이미 있으면 이 단계는 건너뛰세요.

1. nodejs.org에 접속합니다.
2. 초록색 "Get Node.js®" 버튼(LTS 버전, 예: v24.x)을 눌러 설치 파일을 받습니다.
3. 설치 관리자를 그대로 진행합니다. npm은 Node.js에 함께 딸려 옵니다.

설치가 끝나면 터미널을 새로 열고 다시 확인합니다:

node -v && npm -v

두 버전 번호가 모두 나오면 벽 ①을 넘은 것입니다.

왜 필요한가요? 마블로는 에이전트 CLI를 npm install -g로 자동 설치합니다. npm이 없으면 그 자동 설치가 실패하고, 앱은 "npm을 찾을 수 없습니다. Node.js / npm 설치 후 다시 시도하세요"라고 알려 줍니다. Node.js를 먼저 깔아 두면 이 우회로를 아예 건너뜁니다.

Step 3 — CLI 자동 설치 확인 & 인증 (벽 ②·③)

이 단계가 신규 사용자가 가장 많이 막히는 곳입니다. 침착하게 두 가지만 하면 됩니다: (a) CLI가 깔렸는지 확인, (b) 본인 유료 계정으로 인증.

3-1. 필수 CLI는 자동 설치됩니다

첫 실행 시 마블로가 Claude Code · Codex · 마블로 MCP를 백그라운드에서 자동 설치합니다. 하네스 탭에서 손으로 깔 필요가 없습니다. (Step 2에서 Node.js를 미리 깔았다면 이 자동 설치가 조용히 성공합니다.)

3-2. ★인증 — 여기서 유료 계정이 필요합니다

오케스트레이터를 열려고 하면 마블로가 CLI 인증 게이트를 띄웁니다. "인증 실행"을 누르면 터미널 탭이 열리고 로그인 명령이 자동으로 실행됩니다. 직접 친다면:

claude login

브라우저가 열리면 본인 Anthropic 계정으로 로그인합니다. Codex도 쓸 거면:

codex login

⚠️ 여기가 벽 ②·③입니다. 게이트 문구는 "로그인"만 말해서 마치 무료 로그인이면 되는 것처럼 보입니다. 하지만:

• 로그인만으로는 부족합니다 — 로그인한 계정에 **유료 자격(Claude Pro/Max 또는 API 크레딧)**이 있어야 합니다.
• 무료 계정으로 로그인하면 게이트는 "준비 완료"로 통과시키지만, 첫 스폰에서 에이전트가 2초 만에 죽습니다 (벽 ③, 무자격 통과 후 크래시). 이때는 "왜 죽었지?" 하지 말고 맨 위 **"시작 전에 — BYOK"의 준비물 1(유료 구독/API 키)**을 확인하세요.

인증이 끝나면 각 CLI가 "인증됨" 상태로 바뀝니다. 상태가 안 바뀌면 앱을 재시작하세요.

🎥 영상 슬롯 C — CLI 인증 게이트 → "인증 실행" 클릭 → 터미널에서 claude login → 브라우저 로그인 → "인증됨"으로 바뀌는 전체 흐름. (첫 시작의 핵심 순간)

Step 4 — 폴더 연결 → 오케스트레이터 자동 오픈

인증까지 끝났으면 이제 쉬운 길입니다. 작업할 프로젝트 폴더 하나만 선택하면, 마블로가 그 폴더를 자동으로 등록하고(클릭 0번) 오케스트레이터를 자동으로 엽니다.

오케스트레이터는 여러분의 사령탑입니다. 폴더가 연결되면 첫인사와 함께 "무슨 티켓을 만들까요 / 어떤 에이전트를 붙일까요"를 제안합니다.

🎥 영상 슬롯 D — 폴더 선택 한 번 → 오케스트레이터가 자동으로 열리고 첫인사를 건네는 순간.

Step 5 — 첫 에이전트 스폰

오케스트레이터에게 하고 싶은 일을 자연어로 말하면 됩니다. 예를 들어:

"README에 설치 방법 섹션을 추가하는 티켓을 만들고, 에이전트를 붙여 줘."

오케스트레이터가 티켓을 만들고 물리 에이전트(독립 CLI 프로세스)를 스폰합니다. 스폰된 에이전트는 자기 터미널 탭에서 실제로 코드를 읽고 씁니다.

이 순간 벽 ②·③이 다시 시험대에 오릅니다. 인증과 유료 자격이 갖춰져 있으면 에이전트가 살아서 일을 시작합니다. 만약 2초 만에 "error" 카드로 죽는다면 → Step 3의 유료 자격을 다시 확인하세요.

🎥 영상 슬롯 E — 오케스트레이터에 한 줄 지시 → 티켓 생성 → 에이전트 탭이 스폰되어 실제로 움직이기 시작하는 장면.

Step 6 — 첫 작업 완주 (가치의 순간)

에이전트가 작업을 마치면 티켓을 REVIEW로 넘깁니다. 여러분은 결과(diff, 변경 요약)를 확인하고 승인합니다. 티켓이 DONE으로 넘어가는 이 순간이 마블로의 핵심 가치 순간입니다 — 직접 타이핑하는 사람에서, 일을 나눠 주고 검수하는 사람으로 역할이 바뀌는 지점이죠.

여기까지 왔다면 축하합니다. 대부분의 사람이 못 넘는 세 벽을 모두 넘고, 에이전트가 티켓 하나를 끝까지 완료하는 것을 직접 본 것입니다.

🎥 영상 슬롯 F — 에이전트가 작업을 REVIEW로 올림 → 사용자가 diff 확인 → 승인 → DONE. (완주 = 가치 순간, 영상의 클라이맥스)

막히면? — 세 벽 트러블슈팅

| 증상 | 어느 벽인가 | 해결 | | ---------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------- | | 앱이 "npm을 찾을 수 없습니다"라고 함 | 벽 ① (Node.js 부재) | Step 2로 Node.js 설치 후 터미널 새로 열고 재시도 | | 인증 게이트가 안 사라짐 / "로그인 필요"만 반복 | 벽 ② (미인증) | claude login을 끝까지 완료. 브라우저 로그인 후 앱 재시작 | | 로그인은 됐는데 에이전트가 2초 만에 죽음(error 카드) | 벽 ③ (무자격 통과) | 로그인한 계정에 Claude Pro/Max 또는 API 크레딧이 있는지 확인. 무료 계정이면 여기서 막힘 | | 첫 실행 시 앱이 안 켜짐(경고창) | 설치 | Gatekeeper/SmartScreen을 Step 1대로 넘기기 | | 그래도 막힌다 | — | 버그 신고로 알려 주세요. 어디서 막혔는지가 다음 버전을 만듭니다 |

다음 단계

첫 완주까지 왔다면, 다음은 여러 에이전트를 동시에 굴리는 것입니다. 백엔드·프론트엔드·테스트 에이전트에게 역할을 나눠 배치하고, 의존성이 있는 티켓을 DAG로 묶으면 마블로가 순서를 지켜 가며 병렬로 돌립니다.

• 마블로란 무엇인가 — 오케스트레이터 중심의 큰 그림
• 한 명의 개발자, 여러 에이전트 — 혼자서 팀 규모로 일하는 법
• 충돌하지 않는 병렬 에이전트 — 워크트리 격리로 동시에 여러 에이전트 돌리기

준비물 두 개(유료 Claude 계정 + Node.js)만 갖추면, 나머지는 마블로가 대부분 자동으로 처리합니다. 세 벽만 넘으면 됩니다.