How to setup a local coding agent on macOS
TL;DR Highlight
인터넷 없이도 쓸 수 있는 로컬 코딩 에이전트를 macOS에서 구축하는 방법을 정리한 글로, llama.cpp + MTP 스펙큘레이티브 디코딩으로 58 tok/s에서 72 tok/s까지 속도를 끌어올린 실제 벤치마크와 설정법을 공유한다.
Who Should Read
인터넷 의존 없이 로컬에서 AI 코딩 에이전트를 돌리고 싶은 맥 개발자, 특히 Apple Silicon(M1 이상) + 32GB 이상 메모리를 가진 환경에서 llama.cpp 기반 세팅을 직접 해보려는 개발자.
Core Mechanics
- 저자는 인터넷이 끊겼을 때 코딩 에이전트를 쓸 수 없다는 불편함에서 출발해, 로컬에서 완전히 동작하는 코딩 에이전트 환경을 구축했다. 조건은 '실제로 쓸 수 있을 만큼 빠를 것', 'OpenAI 호환 API로 노출될 것', '스크린샷 같은 이미지 입력도 지원할 것' 세 가지였다.
- 최종 스택은 Metal 가속으로 빌드한 llama.cpp + Gemma 4 26B-A4B Q4 양자화 모델(약 16GB) + Q8 MTP 드래프트 모델 + 멀티모달 프로젝터 + Pi 터미널 에이전트 조합이다. 테스트 머신은 Apple M1 Max 64GB RAM, macOS 15.7.7이다.
- 베이스라인(llama.cpp + Metal만 사용)은 생성 속도 58.2 tok/s였다. 혼자서는 느리지 않지만, 코딩 에이전트는 툴 콜을 반복하기 때문에 속도가 더 중요하다.
- MTP(Multi-Token Prediction, 한 번에 여러 토큰을 예측해 검증하는 스펙큘레이티브 디코딩 기법)를 추가하면 72.2 tok/s로 약 24% 빨라진다. 프롬프트 처리 속도는 거의 동일하게 유지되면서 생성 속도만 올라간다.
- --spec-draft-n-max 값(드래프트 토큰 수)을 1~6까지 스윕 테스트한 결과, M1 Max에서는 3이 가장 빨랐고 2도 거의 동일했다. 4 이상부터는 오히려 느려지므로 하드웨어마다 최적값을 직접 테스트해야 한다.
- MLX(Apple Silicon에 최적화된 머신러닝 프레임워크)와도 비교했는데, 의외로 llama.cpp가 MLX보다 빨랐다. MLX 4-bit 모델은 45.8 tok/s에 그친 반면, llama.cpp + MTP는 72.2 tok/s를 기록했다.
- 멀티모달 지원을 위해 Gemma 4 멀티모달 프로젝터를 추가하고, Pi 에이전트 설정에서 모델 입력 타입을 text-only에서 이미지 포함으로 변경해야 스크린샷을 모델에 제대로 전달할 수 있다.
- Qwen3 35B-A3B 모델도 같이 언급되며, 로컬 코딩 에이전트 목적으로 두 모델 중 하나를 선택하거나 병행 사용하는 것을 고려할 수 있다.
Evidence
- 128 토큰만 생성하는 벤치마크는 MTP 속도 측정에 부정확할 수 있다는 지적이 있었다. MTP의 토큰 수락률(acceptance rate)이 생성 초반에 높은 경향이 있어서, 짧은 샘플은 실제보다 낙관적인 결과를 줄 수 있다는 것. llama.cpp에 인수 스윕을 자동으로 해주는 전용 벤치마킹 도구(`llama-bench`)가 있다는 정보도 함께 공유됐다.
- Ollama + OpenCode를 조합한 유사한 설정 가이드를 이미 작성했다는 사람이 댓글로 링크를 공유했다. llama.cpp 직접 빌드 대신 Ollama를 쓰면 설정이 훨씬 간단하다는 대안이 제시됐다.
- llama.cpp에 `-hf` 플래그를 쓰면 Hugging Face에서 모델을 직접 다운로드할 수 있다는 점을 저자가 빠뜨렸다는 지적이 있었다. `LLAMA_CACHE=models ./llama-server -hf unsloth/gemma-4-31B-it-GGUF:UD-Q4_K_XL` 형태로 실행하면 별도로 huggingface-cli 없이도 모델을 받을 수 있다.
- M1 Max와 같은 기기를 가진 사용자가 직접 MTP를 테스트해봤는데, 속도 향상이 크지 않다고 느꼈다는 경험담도 있었다. 또한 Gemma 4 MTP 헤드가 OpenCode에서 마크업을 가끔 깨뜨리고 stop token을 놓치는 버그가 있어서 MTP 사용을 중단했다는 구체적인 문제도 보고됐다.
- 토큰/초 수치에만 집중하고 실제 답변 품질을 전혀 언급하지 않는다는 비판도 있었다. '빠르게 쓸모없는 답변을 주는 게 더 유용한 건 아니다'라는 의견으로, 속도보다 품질을 중시하는 사용자 입장에서의 반론이었다.
How to Apply
- 인터넷이 자주 끊기거나 보안상 외부 API를 쓸 수 없는 환경에서 코딩 에이전트가 필요한 경우, M1 Max 이상 + 64GB 메모리 Mac에서 이 글의 llama.cpp + Gemma 4 26B Q4 + MTP 조합을 그대로 따라하면 실용적인 속도(72 tok/s)의 로컬 에이전트를 구축할 수 있다.
- llama.cpp 서버를 OpenAI 호환 API로 띄운 뒤, Pi나 OpenCode 같은 터미널 에이전트에서 base URL을 로컬 서버로 변경하면 기존 클라우드 기반 워크플로를 거의 그대로 로컬로 전환할 수 있다.
- --spec-draft-n-max 값을 최적화하려면 직접 1~6 범위를 스윕 테스트해야 한다. 하드웨어마다 최적값이 다르므로(글에서는 M1 Max 기준 3이 최적), llama-bench 도구를 사용해 자동으로 스윕하는 것이 더 신뢰할 수 있는 방법이다.
- 스크린샷을 모델에 전달해 UI 버그 수정 같은 멀티모달 코딩 작업을 하고 싶다면, llama.cpp 서버에 Gemma 4 멀티모달 프로젝터를 추가로 로드하고 에이전트 설정에서 입력 타입에 이미지를 포함시켜야 한다.
Code Example
# llama.cpp + Metal + MTP 실행 예시
./repos/llama.cpp/build/bin/llama-cli \
-m models/unsloth-gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
--model-draft models/unsloth-gemma-4-26B-A4B-it-GGUF/MTP/gemma-4-26B-A4B-it-Q8_0-MTP.gguf \
--spec-type draft-mtp \
--spec-draft-n-max 3 \
-ngl 999 \
-fa on \
-c 4096 \
-n 128
# -hf 플래그로 Hugging Face에서 직접 모델 다운로드
LLAMA_CACHE="models" ./llama-server \
-hf unsloth/gemma-4-31B-it-GGUF:UD-Q4_K_XL \
-ngl 999 \
-fa onTerminology
Related Papers
AI agent bankrupted their operator while trying to scan DN42
자율 AI Agent가 DN42 취미 네트워크에 가입해 전체 스캔을 시도하면서 AWS 인프라를 무분별하게 프로비저닝한 결과, 운영자에게 하루 만에 $6,531.30짜리 청구서가 날아온 실제 사건 기록이다.
HyperTool: Beyond Step-Wise Tool Calls for Tool-Augmented Agents
여러 MCP 툴 호출을 코드 블록 하나로 묶어 LLM 에이전트의 컨텍스트 낭비와 추론 단절을 동시에 해결하는 기법
EurekAgent: Agent Environment Engineering is All You Need For Autonomous Scientific Discovery
LLM 에이전트에게 복잡한 워크플로우 대신 잘 설계된 '환경'을 줬더니 수학·커널·ML 벤치마크에서 모두 SOTA를 달성했다.
Ask HN: How do you get into a flow state when using AI to code?
Claude 같은 에이전트 기반 AI 코딩 도구가 보편화되면서 개발자들이 기존의 몰입 상태(flow state)를 잃어버리고 있다는 문제를 공유하고, 커뮤니티에서 각자의 대처 방법을 논의한 스레드.
Claude Desktop spawns 1.8 GB Hyper-V VM on every launch, even for chat-only use
Claude Desktop Windows 앱이 사용자가 AI 코드 실행 기능(Cowork)을 쓰지 않아도 실행 시마다 자동으로 1.8GB짜리 Hyper-V 가상머신을 생성해 메모리를 잡아먹는 버그가 보고됐다.
Apache Burr: Build reliable AI agents and applications
LangChain 같은 복잡한 프레임워크에 지친 개발자들을 위해 순수 Python으로 AI 에이전트와 상태 머신을 만들 수 있는 Apache 인큐베이팅 프레임워크다. 상태 관리, 관측성, Human-in-the-Loop 등을 DSL 없이 제공한다는 점이 특징이다.