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

snippet

# 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 on

Terminology

MTP (Multi-Token Prediction)일반적으로 LLM은 토큰을 하나씩 생성하는데, MTP는 드래프트 모델이 여러 토큰을 미리 예측해 던져주고 본 모델이 빠르게 검증하는 방식이다. 맞으면 그대로 쓰고, 틀리면 버린다. 검증이 생성보다 훨씬 빠르기 때문에 전체 속도가 올라간다.

Speculative Decoding작고 빠른 드래프트 모델이 먼저 여러 토큰을 생성하고, 큰 메인 모델이 한꺼번에 맞는지 검사하는 기법. 품질은 메인 모델 수준을 유지하면서 속도만 높일 수 있다.

GGUFllama.cpp에서 사용하는 모델 파일 포맷. 양자화(모델 용량을 줄이는 압축) 정보와 메타데이터를 하나의 파일에 담아 배포하기 편리하게 만든 포맷이다.

양자화 (Quantization)모델의 가중치를 32비트 부동소수점에서 4비트나 8비트 정수로 압축하는 기법. 파일 크기와 메모리 사용량을 크게 줄일 수 있지만, 약간의 품질 손실이 생길 수 있다.

MetalApple이 만든 GPU 가속 API. llama.cpp를 Metal로 빌드하면 Mac의 GPU(Unified Memory 포함)를 활용해 모델 추론 속도를 크게 높일 수 있다.

MLXApple Silicon에 최적화된 머신러닝 프레임워크로 Apple이 직접 만들었다. Metal을 기반으로 하며 Mac 전용이라 최적화가 잘 될 것 같지만, 이 글에서는 범용 llama.cpp보다 느린 결과가 나왔다.