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

마블로는 여러분 본인의 Claude·Codex 구독을 연결해서 에이전트를 돌리는 플랫폼입니다. 그래서 Claude Code를 써 보지 않으셨던 분이라면, 마블로를 처음 켤 때 오케스트레이터와의 최초 연결 한 단계가 조금 낯설 수 있습니다. 이 첫 연결만 마치면 그다음은 순조롭게 이어지니, 앱을 처음 켰을 때 뜨는 최초 시작 팝업(연결 마법사)을 꼭 끝까지 따라와 주세요. 이 가이드는 그 연결 마법사가 안내하는 흐름을, 다운로드부터 첫 에이전트가 티켓 하나를 끝까지 완료하는 순간까지 하나씩 풀어 설명합니다.

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

★시작 전에 — 준비물 두 가지 (본인 계정 연결)

마블로는 여러분 본인의 AI 계정을 연결해서 에이전트를 돌립니다. 그래서 시작하려면 두 가지 준비물이 필요하고, 둘 다 갖춰야 최초 연결과 첫 스폰이 매끄럽게 이어집니다.

• 구독 연결

폴더연결첫완주준비 1 Node.js 설치 · 준비 2 CLI 인증과 구독 연결 · 그다음 폴더 연결로 첫 완주까지

준비물 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.

요점: 마블로 앱 자체는 무료로 쓰지만, 에이전트는 여러분이 연결한 본인 구독·API 키(모델)로 동작합니다. 그래서 실제 실행에 드는 모델 사용량은 연결하신 본인 계정 기준으로 처리돼요. 시작 전에 이 연결만 미리 해 두면 첫 스폰이 매끄럽게 이어집니다.

준비물 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용 빌드를 받을 수 있습니다.

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

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

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

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

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

Step 2 — Node.js / npm 설치

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

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

맥에서 터미널이 익숙하다면 — Homebrew로 한 줄 설치. 이미 Homebrew가 깔려 있다면, 설치 파일을 내려받는 대신 터미널에서 아래 한 줄이면 Node.js와 npm이 함께 설치됩니다:

brew install node

Homebrew가 없다면 위 nodejs.org 설치 파일 방식이 더 간단합니다. 둘 중 편한 한 가지만 하면 됩니다.

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

node -v && npm -v

두 버전 번호가 모두 나오면 Node.js 준비는 끝난 것입니다.

왜 필요한가요? 마블로는 에이전트 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

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

• 로그인만으로는 부족합니다 — 로그인한 계정에 구독 또는 API 크레딧(Claude Pro/Max 등)이 연결돼 있어야 실제로 동작합니다.
• 무료 계정으로 로그인하면 게이트는 "준비 완료"로 통과시키지만, 첫 스폰에서 에이전트가 곧바로 멈춥니다. 이때는 당황하지 말고 맨 위 ‘시작 전에 — 준비물 두 가지’의 준비물 1(구독·API 키)을 확인하세요.

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

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

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

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

Step 5 — 첫 에이전트 스폰

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

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

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

이 순간 앞서 마친 인증과 구독 연결이 다시 시험대에 오릅니다. 인증과 구독(또는 API 크레딧)이 갖춰져 있으면 에이전트가 살아서 일을 시작합니다. 만약 곧바로 "error" 카드로 죽는다면 → Step 3의 구독 연결을 다시 확인하세요.

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

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

여기까지 왔다면 축하합니다. 최초 연결의 세 단계를 모두 마치고, 에이전트가 티켓 하나를 끝까지 완료하는 것을 직접 본 것입니다.

막히면? — 최초 연결 트러블슈팅

• 앱이 "npm을 찾을 수 없습니다"라고 할 때 — Step 2로 Node.js를 설치하고, 터미널을 새로 연 뒤 다시 시도하세요.
• 인증 게이트가 안 사라지거나 "로그인 필요"만 반복될 때 — claude login을 끝까지 완료하고, 브라우저 로그인 후 앱을 재시작하세요.
• 로그인은 됐는데 에이전트가 곧바로 죽을 때(error 카드) — 로그인한 계정에 Claude Pro/Max 또는 API 크레딧이 연결돼 있는지 확인하세요. 무료 계정이면 여기서 막힙니다.
• 첫 실행 시 앱이 안 켜질 때(경고창) — Gatekeeper/SmartScreen을 Step 1대로 넘기세요.
• 그래도 막힌다면 — 버그 신고로 알려 주세요. 어디서 막혔는지가 다음 버전을 만듭니다.

다음 단계

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

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

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