핵심 요약
- Claude Code는 ARM64에 RAM 4 GB 이상인 Linux를 공식 지원 — 64비트 Raspberry Pi OS를 올린 Pi 4나 Pi 5는 문서화된 요건을 충족합니다.
- 설치는 명령 하나: curl -fsSL https://claude.ai/install.sh | bash — Node.js가 필요 없습니다. Node.js 22 이상이 필요한 건 npm 경로뿐입니다.
- 첫 부팅 전에 Imager에서 SSH를 켜세요. 이 스위치 하나가 Pi를 노트북에서 관리하는 헤드리스 에이전트로 바꿔 줍니다.
- Claude 구독이나 API 과금으로 로그인하고, 일상 작업은 Haiku로 전환하고, 더 큰 모델은 어려운 문제를 위해 아껴 두세요.
Installing Claude Code on a Raspberry Pi (full agent setup walkthrough)
채널: Jason Welsh31:02
Running Claude Code on a Raspberry Pi
채널: akash.gg
Setup — official documentation
공식 문서: code.claude.com/docs
이 페이지의 모든 요건, 명령, 플래그는 공식 셋업 문서와 akash.gg의 "Running Claude Code on a Raspberry Pi" 해설과 대조해 검증했습니다. 위 영상이 시각 자료입니다.
스크린샷의 권리는 각 제작자에게 있으며, 해당 타임스탬프로 바로 연결됩니다. 얼굴이 나온 장면은 사용하지 않았습니다.
빈 SD 카드에서 작동하는 Pi 에이전트까지
파트 1 — Pi와 SD 카드 준비
- 1
Imager로 64비트 Raspberry Pi OS 굽기
평범한 컴퓨터에서 raspberrypi.com에 가서 Raspberry Pi Imager를 설치하고, 보드를 고르고(RAM 4 GB 이상인 Pi 4나 Pi 5면 Claude Code의 문서화된 요건인 ARM64·4 GB를 충족), Raspberry Pi OS (64-bit)를 선택한 뒤 SD 카드를 지정합니다. 64비트 이미지 선택만은 협상 불가 — Claude Code의 ARM64 빌드는 32비트 OS에서 돌지 않습니다.
Imager에서 보드를 고르세요 — Pi 4도 Pi 5도 자격이 됩니다.3:12부터 시청 - 2
첫 부팅 전에 SSH 켜기
Imager의 OS 사용자 지정에서 사용자명과 비밀번호를 정하고, Wi-Fi 네트워크를 미리 넣고, Enable SSH를 켭니다. 워크스루가 이걸 "매우 중요"라고 부르는 데는 이유가 있습니다: SSH 덕분에 나중에 모니터를 뽑고 노트북만으로 Pi를 관리할 수 있거든요.
지금 SSH를 켜두면 나중에 본인이 고맙습니다.4:16부터 시청 - 3
부팅하고 64비트 확인
카드를 꺼내 Pi에 꽂고 전원을 넣으세요 — Raspberry Pi OS 데스크톱 환영 화면이 떠야 합니다. TV에서 글씨가 너무 작으면 Preferences → Screen Configuration을 열어 HDMI 해상도를 1024×768 같은 값으로 정하고 Apply.
64비트 환영 화면이 뜨면 올바른 이미지를 구운 겁니다.7:00부터 시청 - 4
설치 계획 확보
Pi의 브라우저에서 claude.ai에 로그인하고, 새 시스템에 Claude Code를 설치하는 단계별 절차를 부탁합니다. 생략하고 6단계의 공식 명령을 바로 붙여넣어도 됩니다 — 다만 계획이 화면에 있어야 녹화된 워크스루를 따라 가기 쉬웠죠.
Claude에게 계획을 물어도, 6단계 명령으로 곧장 가도 됩니다.12:00부터 시청
파트 2 — 설치와 인증
- 5
먼저 시스템 업데이트
터미널을 열고 sudo apt update && sudo apt full-upgrade -y로 시스템을 최신으로. 갓 구운 이미지에서도 arm64 패키지가 수십 개 내려와 몇 분 걸릴 수 있습니다.
새 이미지에서도 놀랄 만큼 많은 업데이트가 내려옵니다.13:50부터 시청 - 6
공식 설치 스크립트 실행
명령 하나로 Claude Code를 설치합니다: curl -fsSL https://claude.ai/install.sh | bash. 이 경로는 Node.js가 전혀 필요 없습니다. (npm이 좋다면? ARM64용 Node.js 22+를 설치한 뒤 npm install -g @anthropic-ai/claude-code — sudo는 붙이지 마세요. 공식 문서가 경고합니다.)
한 줄이면 Claude Code 설치 끝 — 문서가 권장하는 경로입니다.13:00부터 시청 - 7
PATH 고치고 확인
설치 스크립트는 마지막에 버전 배너와 바이너리 위치를 남깁니다. 로컬 bin 폴더가 PATH에 없다고 경고하면, 출력된 export 명령을 실행해 .bashrc에 추가하고 source ~/.bashrc. claude --version으로 확인하세요.
성공 배너와, 필요할지 모르는 PATH 수정.16:30부터 시청 - 8
Claude 계정 인증
프로젝트 폴더에서 claude로 Claude Code를 시작하고, 테마를 고르고, "Claude account with subscription"(또는 API 과금이면 Anthropic Console)을 선택합니다. Pi의 브라우저가 동의 페이지를 열어 줄 테니 Authorize를 누르고, 터미널로 돌아와 Enter.
동의 화면은 Pi 자체 브라우저에 나타납니다.17:05부터 시청
파트 3 — 다듬고 헤드리스로
- 9
사용량을 아끼려 Haiku로 전환
Pi에서 큰 모델의 응답은 어려운 문제를 위한 것. /model을 입력해 일상적인 셋업과 스크립트 작업은 Haiku로 — 녹화된 세션도 로그인 직후 전환했습니다. Sonnet이나 Opus로 올리는 건 언제든 가능합니다.
Haiku면 준비하는 동안에도 구독 사용량이 낮게 유지됩니다.18:30부터 시청 - 10
케이블을 치우고: 노트북에서 SSH 접속
이제 보조바퀴를 뗍니다. 2단계에서 SSH를 켜 뒀으니 HDMI 케이블과 키보드를 빼고 노트북에서 ssh youruser@pi-ip로 접속하세요. Claude Code에게 자기 검증을 부탁하면 — "SSH가 완전히 되는지 확인하고 내 로그인과 IP도 알려 줘" — whoami를 돌리고 IP를 확인하고 ssh 서비스를 점검해 줍니다. 완전 헤드리스라면 브라우저 있는 머신에서 오래가는 토큰을 발급하고(claude setup-token) Pi에서 CLAUDE_CODE_OAUTH_TOKEN으로 export하세요.
Claude는 스스로의 SSH 설정을 감사하고 IP를 보고할 수 있습니다.19:30부터 시청 - 11
Pi 에이전트를 실전에 투입
돌아가기 시작하면 어디서든 닿는 상시 가동·저전력 코딩 에이전트를 얻은 겁니다: 네트워크의 셀프호스팅 서비스 유지보수, 다른 머신에 SSH로 접속해 변경 적용, rsync 백업과 cron 작업 같은 유지보수 스크립트 작성·예약, 하드웨어 프로젝트의 마이크로컨트롤러 프로그래밍까지. 작게 시작하고, 실행 내용을 검토하고, 신뢰가 쌓이면 권한을 넓히세요.
Claude Code를 실제로 돌릴 수 있는 라즈베리파이는?
Claude Code는 ARM64 빌드를 내놓고, 문서화된 하한은 Debian 10+/Ubuntu 20.04+ 기반 RAM 4 GB입니다. Pi 모델로 옮기면:
- 1Raspberry Pi 5(4/8/16 GB) — 편안한 선택; 작은 노트북처럼 굴러갑니다.
- 2Raspberry Pi 4(4 GB 이상) — 이 가이드의 그림이 된 워크스루가 녹화된 모델; Haiku와 짝을 이루면 일상이 민첩합니다.
- 3Raspberry Pi 500 / Pi 400 — 키보드 폼팩터에도 ARM64 RAM 4/8 GB가 실려 문서 요건을 충족합니다.
- 4Raspberry Pi 3, Zero 2 W와 그 이전 — RAM 1 GB 또는 512 MB에 흔히 32비트 이미지; 문서 사양 미만이므로 지원 대상이 아니라 미검증 영역으로 취급하세요.
- 5Compute Modules — RAM 4 GB 이상 CM4/CM5면 같은 요건을 충족하고, 설치 스크립트에 Pi 전용 요소는 없습니다.
뭘 갖고 있는지 모르겠나요? uname -m을 실행하세요: aarch64면 설치 스크립트가 겨냥하는 64비트 ARM 시스템, armv7l이면 32비트이니 먼저 64비트 Raspberry Pi OS로 다시 구워야 합니다.
Pi에서의 설치 문제, 해결
Pi에서 만나는 실패는 거의 모두 이 통 중 하나로 떨어집니다:
- 1설치 후 claude: command not found — 바이너리가 ~/.local/bin에 떨어졌는데 아직 PATH에 없습니다. 설치 스크립트의 셋업 노트(7단계)의 export 명령을 실행하고 터미널을 다시 여세요.
- 2npm install 중 EBADENGINE 경고 — Node.js가 필수 버전 22보다 낡았습니다. ARM64용 Node를 올리거나, npm을 전혀 거치지 않는 curl 설치 스크립트로 전환하세요.
- 3설치나 실행이 아예 실패 — 64비트 Raspberry Pi OS를 구웠는지 다시 확인하세요. ARM64 빌드는 32비트 이미지에서 돌지 않습니다: 워크스루의 표현대로 "64비트를 고르지 않으면 작동하지 않습니다".
- 4sudo npm install -g는 절대 금지 — 공식 문서가 권한과 보안 문제로 짚습니다. 네이티브 설치 스크립트를 쓰거나 npm 전역 prefix를 고치세요.
- 5헤드리스 박스에는 브라우저가 없죠 — OAuth 로그인은 그걸 원합니다. 브라우저 있는 머신에서 한 번 인증하거나, claude setup-token으로 오래가는 토큰을 만들어 Pi에서 CLAUDE_CODE_OAUTH_TOKEN을 export하세요.
아직 막혔나요? 에러를 그대로 Claude Code 자신에게 붙여넣으세요(필요하면 다른 머신에서) — 녹화된 워크플로의 핵심 고리가 정확히 그것입니다: 목표를 한 번 말하고, 될 때까지 에러를 붙여넣는다.