에이전트 주도 새 머신 셋업

이 문서는 AI 코딩 에이전트(Claude Code, Codex, Hermes 등)가 "새 머신에 ADHDev를 셋업하라"는 지시를 받았을 때 그대로 따르는 절차입니다. 아래 번호 단계를 순서대로 따르고, 각 명령을 적힌 그대로 실행하세요.

사람 독자용: 이 문서를 에이전트에게 건네며 "새 머신 셋업 가이드를 따라 이 머신에 ADHDev를 셋업해줘" 라고 말하면, 브라우저 로그인 승인(당신만 할 수 있는 1회)을 제외한 모든 작업을 에이전트가 수행합니다.

목표: 깨끗한 머신에서 시작해, 사람 개입을 최소화하면서 데몬 기동과 첫 adhdev launch까지 도달하는 것. 사람이 필요한 단계는 딱 하나 — Cloud 브라우저 로그인 — 이며 명확히 표시돼 있습니다.

먼저 모드를 고르세요

ADHDev는 두 가지 모드로 실행됩니다. 시작 전에 결정하세요. 설치 명령은 동일하고 계정 흐름만 다릅니다.

	A — Standalone	B — Cloud
계정 / 로그인	없음	GitHub 또는 Google (브라우저 로그인)
사람 단계 필요	아니오 — 완전 자율	예 — 브라우저 승인 1회
대시보드	`http://localhost:3000`	`https://adhf.dev`
적합한 경우	단일 머신, 로컬 사용, 계정 없음, 완전 무인 셋업	멀티 머신, 원격 접근, 공유, Repo Mesh

에이전트 판단 기준: 사용자가 cloud/멀티머신/원격 기능을 요청하지 않았다면 Standalone (A) 를 선택 — 사람도 계정도 필요 없습니다. 사용자가 계정, 원격 접근, mesh를 명시적으로 원하고 브라우저 로그인을 승인할 수 있을 때만 Cloud (B) 를 선택하세요.

1단계 — 사전조건 체크

ADHDev는 Node.js ≥ 22 를 필요로 합니다.

bash

node --version

Node ≥ 22: 좋습니다, 계속 진행.
Node 없음 또는 < 22: 2단계의 설치 스크립트가 런타임을 자동 부트스트랩합니다(macOS/Linux는 nvm/fnm/brew/apt/dnf/yum, Windows는 portable Node 22). 직접 먼저 설치하고 싶다면 22.x LTS 를 설치하세요 — Windows에는 Node 24+ 를 설치하지 마세요(아래 경고 참고).

Windows + Node 24+

Windows에서는 Node.js 24+ 에서의 전역 npm install -g adhdev 가 차단됩니다. 대신 PowerShell 설치 스크립트를 사용하세요 — ~/.adhdev/tools/node22 아래에 portable Node.js 22를 provision하고 그것을 사용합니다. 더 최신 Node를 강제해 우회하려 하지 마세요.

이 시점에 OS도 확인해 2단계에서 올바른 설치 명령을 고르세요: macOS, Linux, Windows.

2단계 — CLI 설치 (무인)

설치 스크립트는 플랫폼을 감지하고, Node.js가 없으면 설치하며, adhdev 를 PATH에 등록합니다.

무인 에이전트 주도 셋업에서는 ADHDEV_NO_SETUP=1 을 설정해 설치 스크립트가 설치만 하고 대화형 setup 위저드를 띄우지 않게 하세요(setup은 이후 단계에서 직접 진행).

macOS / Linux:

bash

ADHDEV_NO_SETUP=1 curl -fsSL https://adhf.dev/install | sh

Windows (PowerShell):

powershell

$env:ADHDEV_NO_SETUP=1; iwr https://adhf.dev/install.ps1 -useb | iex

이미 Node ≥ 22 가 있다면 (모든 플랫폼):

bash

npm install -g adhdev

Homebrew (macOS / Linux) — 별도 Node 불필요:

bash

brew tap vilmire/adhdev && brew install adhdev

Homebrew는 자체 Node.js 런타임을 함께 설치합니다. 위 무인 설치 스크립트도 macOS에서 brew 가 있으면 이 경로를 자동으로 우선 사용하므로, 보통은 직접 실행할 필요가 없습니다.

선택: preview 채널

ADHDEV_CHANNEL=preview 를 설정하면 stable 대신 @next(릴리스 후보) 빌드를 설치합니다. 일반 stable 설치에는 생략하세요. Homebrew tap은 stable 릴리스만 추적하므로 preview 설치는 항상 npm 경로로 진행됩니다.

설치 확인:

bash

adhdev --version

버전 번호가 출력돼야 합니다. 설치 스크립트는 현재 세션의 PATH도 갱신하고 영구 등록도 하므로, 보통은 새 터미널 없이 바로 동작합니다.

그래도 command not found 가 나오면(PATH 변경을 못 받아들이는 제한된 셸), 새 터미널 없이도 되는 폴백이 두 가지 있습니다:

stable shim을 전체 경로로 실행 (설치 스크립트가 항상 여기에 adhdev 를 둡니다):

powershell

# Windows
& "$HOME\.adhdev\npm-global\adhdev.cmd" --version

bash

# macOS / Linux
"$HOME/.adhdev/npm-global/bin/adhdev" --version

Windows portable-Node 우회로 — shim 자체가 실행되지 않으면(예: CLI는 설치됐지만 node.exe PATH가 낡음), 설치 스크립트가 provision한 portable Node 22로 설치된 CLI 엔트리를 직접 호출하세요:
powershell
```
& "$HOME\.adhdev\tools\node22\node-v22.*-win-x64\node.exe" "$HOME\.adhdev\npm-global\node_modules\adhdev\dist\cli\index.js" --version
```

이도 저도 안 되면 새 터미널을 열면 항상 됩니다(PATH가 영구 등록돼 있음).

3단계 — 데몬 기동

모드 A — Standalone (로그인 없음)

Standalone은 계정이 필요 없습니다. 바로 시작하세요:

bash

adhdev standalone

데몬을 localhost:3847, 대시보드를 localhost:3000 에서 인증 없이 기동합니다. 4단계는 완전히 건너뛰고 5단계로 바로 이동하세요.

선택적 LAN 접근: adhdev standalone --host 0.0.0.0 --token <some-secret>. --token 은 선택이며 standalone을 localhost 밖으로 노출할 때만 관련됩니다.

모드 B — Cloud (로그인 필요)

Cloud는 계정이 필요합니다. 4단계의 로그인이 유일한 사람 단계입니다. 4단계가 머신 온라인을 보고하기 전까지 adhdev daemon 을 실행하지 마세요.

4단계 — 로그인 (Cloud 전용) ⏸ 사람 단계

⏸ 사람 단계 — 에이전트는 여기서 멈춰야 함

Cloud 로그인은 사람이 브라우저에서 승인하는 OAuth device flow를 사용합니다. 비대화형 로그인 플래그는 없으며, 이는 의도된 것입니다 — 계정 인가는 사람이 딱 1회 넘는 보안 경계입니다.

환경변수나 다른 우회 경로로 machine secret을 주입해 이 단계를 절대 우회하지 마세요. 지원되지 않으며, 문서화하거나 스크립트로 만들어서도 안 됩니다.

이 단계에서 에이전트가 할 일:

로그인 명령을 직접 실행해 대기하지 말 것. 대신 사용자에게 이렇게 안내하세요: "로그인이 필요합니다. adhdev setup(별칭 adhdev login)을 실행하고 GitHub 또는 Google 계정으로 브라우저 승인을 완료해 주세요."
멈추고 사용자에게 제어를 넘기세요. 로그인이 진행 중인 동안 다음으로 넘어가지 마세요.
계정 인가가 끝났을 때만 재개하세요. adhdev status 를 폴링하고, 머신/계정이 온라인으로 보고될 때만 5단계로 진행하세요. 그전까지는 계속 대기 — 설치나 데몬 명령을 재시도하지 마세요.

사람용: 아래를 실행하고 adhf.dev 로 열리는 브라우저 탭을 승인하세요:

bash

adhdev setup    # 또는: adhdev login

로그인에는 GitHub 또는 Google의 인증된 이메일이 필요하며, 없으면 거부됩니다. 브라우저에서 승인을 마쳤으면 제어를 에이전트에게 다시 넘기세요.

그다음 Cloud 데몬을 기동하세요(백그라운드 상주):

bash

adhdev daemon

데몬이 api.adhf.dev 에 연결하고, 머신을 등록하고, machine ID를 출력합니다.

5단계 — 검증

데몬이 정상인지 확인:

bash

adhdev status

예상:

Standalone: 데몬이 localhost:3847 에서 정상 보고.
Cloud: 머신이 online 으로 표시되고 api.adhf.dev 에 연결됨.

status가 정상이 아니면 launch 전에 아래 트러블슈팅을 확인하세요.

6단계 — 첫 에이전트 launch

사용자가 이미 설치한 CLI 에이전트를 launch하세요:

bash

adhdev launch claude    # Claude Code
# 또는:  adhdev launch codex
# 또는:  adhdev launch <target>

adhdev launch <target> 는 데몬 아래에서 에이전트를 시작하고 대시보드에 미러링합니다. ADHDev는 에이전트 자체의 API 키나 로그인을 관리하지 않습니다 — 각 도구는 자체 auth를 유지합니다. 에이전트가 자체 자격증명을 요구하면, 그것은 ADHDev가 아니라 에이전트 UI에서 처리됩니다.

완료. 이제 데몬이 실행 중이고, 대시보드가 연결됐으며, 첫 에이전트가 라이브 상태입니다.

트러블슈팅

command not found: adhdev — 설치 스크립트가 현재 세션 PATH도 갱신하므로 드문 경우입니다. 발생하면 새 터미널을 여는 대신 stable shim을 전체 경로로 실행하세요: & "$HOME\.adhdev\npm-global\adhdev.cmd" (Windows) 또는 "$HOME/.adhdev/npm-global/bin/adhdev" (macOS/Linux). shim조차 안 되는 Windows 최후 수단: & "$HOME\.adhdev\tools\node22\node-v22.*-win-x64\node.exe" "$HOME\.adhdev\npm-global\node_modules\adhdev\dist\cli\index.js". 새 터미널을 열어도 됩니다 — PATH는 영구 등록돼 있습니다.
Node < 22 — 22.x LTS를 설치하세요(또는 설치 스크립트가 부트스트랩하게 하세요). ADHDev는 더 오래된 Node에서 실행을 거부합니다.
Windows, Node 24+ 에서 설치 실패 — npm install -g 대신 PowerShell 설치 스크립트(portable Node 22)를 사용하세요.
Windows PSSecurityException / "이 시스템에서 스크립트를 실행할 수 없으므로 ...\adhdev.ps1 을 로드할 수 없습니다" — 기본 Restricted 실행 정책이 npm이 만든 PowerShell shim을 막습니다(PowerShell은 adhdev.cmd 보다 adhdev.ps1 을 우선함). 설치 스크립트가 현재 사용자 정책을 자동으로 완화하지만, 막혀 있었다면(예: 그룹 정책) 직접 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 를 실행하거나, .cmd 를 직접 호출해 .ps1 정책을 우회하세요: & "$HOME\.adhdev\npm-global\adhdev.cmd" --version.
데몬이 온라인이 안 됨 (Cloud) — adhdev status 실행. 계속 오프라인이면 로그아웃 후 재로그인: adhdev logout → adhdev setup, 그다음 adhdev daemon 재실행.
launch 후 에이전트가 응답 없음 — adhdev status(데몬 정상?) 후 대상 프로바이더가 설치돼 있는지 확인.

부트스트랩 스크립트

동봉된 Node 스크립트가 사람 단계 가드레일을 내장한 채 1~6단계를 자동화합니다: scripts/bootstrap-new-machine.mjs.

bash

# 아무것도 실행하지 않고, 실행될 명령만 확인:
node scripts/bootstrap-new-machine.mjs --mode standalone --dry-run

# 완전 무인 standalone 셋업:
node scripts/bootstrap-new-machine.mjs --mode standalone --yes

# Cloud: 로그인 직전까지 진행 후 멈추고, 브라우저 승인을 기다림:
node scripts/bootstrap-new-machine.mjs --mode cloud --yes

플래그:

--mode cloud|standalone — 셋업할 모드.
--yes — 무인. 추가 확인 없이 설치/데몬을 실행. 없으면 파괴적 단계는 실행하지 않고 설명만 합니다.
--dry-run — 명령만 출력하고 아무것도 실행하지 않음. 먼저 이것으로 미리보기 하세요.

cloud 모드에서 스크립트는 의도적으로 로그인 단계에서 멈추고, 브라우저 승인 안내를 출력한 뒤, 머신이 온라인이 될 때까지 adhdev status 를 폴링한 후 재개합니다 — 위 ⏸ 사람 단계를 그대로 반영합니다. 자격증명을 절대 주입하지 않습니다.

에이전트 주도 새 머신 셋업 ​

먼저 모드를 고르세요 ​

1단계 — 사전조건 체크 ​

2단계 — CLI 설치 (무인) ​

3단계 — 데몬 기동 ​

모드 A — Standalone (로그인 없음) ​

모드 B — Cloud (로그인 필요) ​

4단계 — 로그인 (Cloud 전용) ⏸ 사람 단계 ​

5단계 — 검증 ​

6단계 — 첫 에이전트 launch ​

트러블슈팅 ​

부트스트랩 스크립트 ​

에이전트 주도 새 머신 셋업

먼저 모드를 고르세요

1단계 — 사전조건 체크

2단계 — CLI 설치 (무인)

3단계 — 데몬 기동

모드 A — Standalone (로그인 없음)

모드 B — Cloud (로그인 필요)

4단계 — 로그인 (Cloud 전용) ⏸ 사람 단계

5단계 — 검증

6단계 — 첫 에이전트 launch

트러블슈팅

부트스트랩 스크립트