Mac Mini 48GB + Docker + Ollama 로컬 AI 환경 구축 가이드
Mac Mini M4 Pro 48GB는 2026년 현재 로컬 AI 인프라를 구성하기 위한 가장 현실적이고 강력한 소비자용 하드웨어 중 하나입니다. 애플 실리콘의 통합 메모리(Unified Memory) 아키텍처 덕분에 CPU와 GPU가 동일한 48GB 메모리 풀을 공유하기 때문에, 별도의 GPU 없이도 300억 파라미터급 대형 언어 모델을 로컬에서 구동할 수 있습니다. 여기에 Nous Research가 개발한 자기학습 AI 에이전트 Hermes Agent와 Docker 기반 격리 실행 환경을 결합하면, 클라우드 API 비용 없이 24시간 항상 켜진(always-on) AI 에이전트 인프라를 자택 또는 사무실에 구축할 수 있습니다.
이 가이드는 이전 Hermes Agent 완벽 가이드의 확장판으로, Mac Mini 48GB라는 구체적인 하드웨어 환경에 초점을 맞춥니다. Docker Desktop의 메모리·CPU·GPU 리소스 배분 전략부터 시작해, Ollama를 통해 최고 성능 로컬 모델을 선정하고 설정하는 방법, 그리고 Hermes Agent를 Docker 컨테이너로 배포해 Ollama와 연동하는 전 과정을 단계별로 안내합니다. 48GB라는 충분한 메모리 자원을 최대한 효율적으로 활용하여 도구 호출(Tool Calling), 자율 스킬 생성, 크로스 세션 메모리 같은 Hermes의 핵심 기능을 로컬 모델만으로 완벽하게 구동하는 것이 이 글의 목표입니다.
목 차
1. 로컬 AI 허브로서의 아키텍처 이해 | Mac Mini 48GB
Mac Mini M4 Pro 48GB가 로컬 AI 환경에서 특별한 이유를 이해하려면, 먼저 애플 실리콘의 통합 메모리(Unified Memory) 구조를 알아야 합니다. 일반적인 PC에서는 CPU 메모리(RAM)와 GPU 메모리(VRAM)가 물리적으로 분리되어 있어서, AI 모델이 GPU로 올라가려면 CPU 메모리에서 GPU VRAM으로 데이터를 복사하는 과정이 필요합니다. 하지만 M4 Pro 칩에서는 CPU와 GPU가 동일한 48GB 메모리 풀을 직접 공유하기 때문에 이 복사 과정이 사라지고, 메모리 대역폭 활용률이 극적으로 향상됩니다. 그 결과, 48GB 전체를 모델 가중치와 KV 캐시에 사용할 수 있어 일반 PC의 24GB VRAM 전용 GPU보다 훨씬 큰 모델을 구동할 수 있습니다.
M4 Pro 칩의 메모리 대역폭은 약 273GB/s로, RTX 3090(936GB/s)보다는 낮지만 소비 전력 대비 효율은 압도적입니다. AI 추론(Inference)에서 토큰 생성 속도는 메모리 대역폭에 정비례하기 때문에, Mac Mini는 RTX 3090 대비 토큰 속도가 30~60% 느리지만 전력 소비는 약 8배 낮습니다. Mac Mini M4 Pro는 AI 추론 시 30~40W를 소비하며, 이는 연간 전기요금으로 환산해도 수만 원 수준에 불과해 클라우드 API 구독료와 비교하면 압도적으로 경제적입니다.
이 환경에서 우리가 구성할 소프트웨어 스택은 크게 세 레이어로 나뉩니다.
- 첫 번째는 Ollama - macOS 네이티브로 직접 설치되어 Metal 가속을 활용해 LLM 추론을 담당합니다.
- 두 번째는 Docker Desktop - 리눅스 가상 머신(VM) 위에서 컨테이너를 실행하며, Hermes Agent와 Open WebUI 같은 지원 서비스를 격리된 환경에서 운영합니다.
- 세 번째는 Hermes Agent - Docker 컨테이너로 실행되며 Ollama의 OpenAI 호환 API(포트 11434)를 통해 로컬 모델과 통신합니다. Ollama를 Docker 안에 넣지 않고 macOS 네이티브로 설치하는 이유가 바로 여기에 있습니다. Docker VM 레이어를 거치면 Metal GPU 가속에 접근할 수 없어 추론 속도가 CPU 전용 수준으로 떨어지기 때문입니다.
[48GB Mac Mini 소프트웨어 스택 구성]
+------------------------------------------+
| macOS (Sequoia 이상) |
| +----------------------------------+ |
| | Ollama (네이티브 설치) | |
| | - Metal GPU 가속 | |
| | - Port 11434 | |
| | - 모델 메모리: ~20-28GB | |
| +----------------------------------+ |
| +----------------------------------+ |
| | Docker Desktop VM | |
| | - 할당 메모리: 12GB | |
| | +----------------------------+ | |
| | | Hermes Gateway (8642) | | |
| | | Hermes Dashboard (9119) | | |
| | | Open WebUI (3000) | | |
| | +----------------------------+ | |
| +----------------------------------+ |
| macOS 시스템 예약: ~8GB |
+------------------------------------------+
총 48GB 사용 계획:
- Ollama 모델: 20-28GB
- Docker VM: 12GB
- macOS 시스템: 8GB
- 여유: 0-8GB (모델에 따라 다름)[참고] M4 Pro Mac Mini와 M4 Max Mac Mini의 차이점도 간략히 짚고 넘어가겠습니다. M4 Pro 48GB는 12코어 CPU(4 Performance + 8 Efficiency)와 20코어 GPU를 탑재하며, M4 Max 48GB는 14코어 CPU와 32코어 GPU를 탑재합니다. AI 추론에서 GPU 코어 수가 많을수록 병렬 처리가 개선되어 M4 Max가 약 15~25% 더 빠른 토큰 속도를 보입니다. 그러나 가격 차이를 고려하면 M4 Pro 48GB가 대부분의 로컬 AI 워크로드에서 최고의 가성비를 제공합니다.
2. Docker Desktop 리소스 배분 전략 | 48GB에서의 최적 설정
Mac Mini 48GB에서 Docker Desktop을 설정할 때 가장 중요한 원칙은 "Ollama에게 충분한 메모리를 남겨두는 것"입니다. Docker Desktop은 macOS 위에서 경량 리눅스 VM(가상 머신)을 실행하며, 이 VM에 할당된 메모리는 Docker 컨테이너들이 공유합니다. 문제는 이 VM에 지나치게 많은 메모리를 할당하면 macOS와 Ollama가 사용할 수 있는 통합 메모리가 줄어들어, 대형 모델 로딩 시 메모리 스왑(Memory Swap)이 발생하고 추론 속도가 급격히 저하된다는 점입니다. 반대로 Docker VM에 너무 적은 메모리를 할당하면 Hermes Agent 컨테이너가 OOM(Out Of Memory) 오류로 종료될 수 있습니다.
48GB 통합 메모리에서의 최적 배분 전략은 다음과 같습니다. Docker VM에는 12GB를 할당합니다. Hermes Agent 컨테이너 자체는 약 1~2GB를 소비하지만, 브라우저 자동화 기능을 활성화하면 2~4GB까지 늘어나고 여러 컨테이너(Hermes Gateway + Dashboard + Open WebUI)를 동시에 실행하면 최대 8GB까지 필요합니다. 12GB를 할당하면 이러한 상황에도 충분한 여유가 생깁니다. CPU는 전체 10코어(M4 Pro 기준) 중 6코어를 Docker에 배정합니다. 나머지 4코어는 macOS 시스템과 Ollama의 CPU 연산(KV 캐시 처리 등)에 사용됩니다. 스왑(Swap)은 2GB로 설정합니다. 스왑이 실제로 사용된다는 것은 메모리가 부족하다는 신호이므로 비상용으로만 존재해야 합니다.
Docker Desktop 설정 방법
Docker Desktop의 리소스 설정은 GUI를 통해 간단하게 조정할 수 있습니다. Docker Desktop 메뉴바 아이콘을 클릭하고 Settings(설정) > Resources(리소스)로 이동합니다.
Docker Desktop 설정 경로:
Docker Desktop 아이콘 (메뉴바) -> Settings -> ResourcesGUI 슬라이더로 조정하는 것도 좋지만, 설정 파일을 직접 수정하는 방법이 더 정확하게 값을 지정할 수 있습니다. Docker Desktop의 설정 파일은 아래 경로에 JSON 형식으로 저장되어 있습니다.
# Docker Desktop 설정 파일 위치 확인
cat ~/Library/Group\ Containers/group.com.docker/settings.json | \
python3 -c "import json,sys; d=json.load(sys.stdin); \
print('CPU:', d.get('cpus'), 'Memory:', d.get('memoryMiB'), 'Swap:', d.get('swapMiB'))"48GB Mac Mini에 최적화된 설정값을 직접 적용하려면 아래 스크립트를 사용합니다. Docker Desktop을 완전히 종료한 상태에서 실행해야 합니다.
# Docker Desktop 종료 후 실행
# Apple 메뉴 -> 강제 종료 또는 아래 명령어로 종료
osascript -e 'quit app "Docker Desktop"'
sleep 3
# 48GB Mac Mini 최적화 설정 적용
python3 << 'EOF'
import json, os
settings_path = os.path.expanduser(
"~/Library/Group Containers/group.com.docker/settings.json"
)
with open(settings_path, "r") as f:
settings = json.load(f)
# 48GB Mac Mini M4 Pro 최적화 값
settings["cpus"] = 6 # 10코어 중 6코어 할당 (나머지 4코어는 macOS/Ollama)
settings["memoryMiB"] = 12288 # 12GB (나머지 36GB는 macOS + Ollama)
settings["swapMiB"] = 2048 # 2GB 스왑 (비상용)
settings["diskSizeMiB"] = 102400 # 100GB 디스크 (Docker 이미지 저장)
with open(settings_path, "w") as f:
json.dump(settings, f, indent=2)
print("[완료] Docker Desktop 리소스 설정이 업데이트되었습니다.")
print(f" CPU: {settings['cpus']} cores")
print(f" Memory: {settings['memoryMiB']}MB ({settings['memoryMiB']//1024}GB)")
print(f" Swap: {settings['swapMiB']}MB")
EOF
# Docker Desktop 재시작
open -a "Docker Desktop"
Apple Silicon에서의 Docker 특이사항
Apple Silicon Mac에서 Docker Desktop은 Apple의 Virtualization.framework를 사용하여 ARM64 기반 리눅스 VM을 실행합니다. 이 방식은 Intel Mac의 QEMU 기반 VM보다 훨씬 효율적이며, 파일 공유도 VirtioFS를 통해 크게 개선되었습니다. 그러나 중요한 제약이 있습니다. Docker 컨테이너 내부에서는 Metal GPU 가속에 직접 접근할 수 없습니다. VM 레이어가 중간에 있어 GPU 드라이버를 통과시킬 수 없기 때문입니다. 이것이 바로 Ollama를 Docker 컨테이너가 아닌 macOS 네이티브로 설치해야 하는 핵심 이유입니다.
[!] 주의: Docker 컨테이너 내부에서 --gpu 플래그를 사용하거나 CUDA/ROCm 관련 설정을 하더라도 Mac에서는 효과가 없습니다. Mac의 GPU 가속은 Metal 프레임워크를 통해서만 가능하며, 이는 macOS 네이티브 프로세스(Ollama, LM Studio 등)에서만 활성화됩니다.
개별 컨테이너 메모리 제한 설정
Docker Compose나 docker run 명령어에서 개별 컨테이너의 메모리를 제한하면, VM 내 메모리를 여러 컨테이너가 효율적으로 나눠 사용할 수 있습니다. Hermes Agent 컨테이너는 기본 모드에서 약 1~2GB, 브라우저 자동화 활성화 시 약 3~4GB를 소비합니다. 아래와 같이 docker-compose.yml에 메모리 제한을 명시하면 컨테이너 하나가 VM 전체 메모리를 독점하는 상황을 방지할 수 있습니다.
# docker-compose.yml 내 메모리 제한 예시
services:
hermes:
image: nousresearch/hermes-agent
deploy:
resources:
limits:
cpus: "3.0" # VM CPU 6코어 중 3코어
memory: 6G # VM 12GB 중 6GB
reservations:
memory: 2G # 최소 보장 메모리3. Ollama 설치 및 최적 모델 선정 | 48GB 전용 추천 목록
Ollama는 macOS에서 가장 간편하게 LLM을 로컬 구동할 수 있는 도구입니다. 단 하나의 명령어로 설치되고, 모델 다운로드부터 서버 실행까지 모든 것을 자동으로 처리합니다. 무엇보다 Apple Silicon의 Metal 프레임워크를 자동으로 활용하여 GPU 가속 추론을 별도 설정 없이 제공합니다. 2026년 4월 기준 Ollama는 MLX 프레임워크 지원도 추가되어, 지원 모델에서는 기존 llama.cpp 대비 지원 모델 기준 prefill +57%, decode +93% (단, 미지원 모델은 Metal 폴백) 더 빠른 추론 속도를 제공합니다. (OLLAMA_USE_MLX=1 환경 변수 설정 필요 (0.19버전에서는 기본값 비활성, 0.21+버전에서는 환경설정 불필요하며 지원 모델 pull시 자동 활성화))
Hermes Agent와 Ollama를 연동하기 위해서는 반드시 최소 64K(65,536) 토큰의 컨텍스트 길이를 가진 모델(0.19 버전 기준 지원 모델: Qwen3.5 35B-A3B, Gemma4(0.20 추가))을 선택해야 합니다. Hermes는 시스템 프롬프트, SOUL 정의, 도구 스키마(Tool Schema), 대화 기록을 모두 컨텍스트에 담아 작업합니다. 기본 도구와 SOUL.md를 합산하면 한 번의 CLI 턴에 약 6~8K 토큰, Telegram 메시지 처리 시 약 15~20K 토큰을 사용합니다. 따라서 4K~8K 컨텍스트 모델은 시스템 프롬프트와 도구 스키마만으로 창이 가득 차버려 Hermes가 시작조차 거부합니다. 48GB 환경에서는 넉넉한 메모리 덕분에 컨텍스트를 128K~262K로 설정할 수 있어 훨씬 긴 작업 세션이 가능합니다.
Ollama 설치
# Homebrew를 통한 설치 (권장 - 업데이트 관리가 용이)
brew install ollama
# 또는 공식 스크립트 설치
curl -fsSL https://ollama.com/install.sh | sh
# Ollama를 시스템 서비스로 등록 (Mac 시작 시 자동 실행)
brew services start ollama
# 설치 확인
ollama --version
# 예상 출력: ollama version 0.9.x설치 후 Ollama는 기본적으로 http://localhost:11434에서 API 서버를 시작합니다. 단, 기본 설정에서는 로컬호스트만 접근을 허용합니다. Hermes Agent가 Docker 컨테이너 내부에서 이 API를 호출할 수 있도록 아래 설정이 필요합니다. 이 부분은 4장에서 상세히 다루겠습니다.
48GB Mac Mini 전용 모델 추천 목록
48GB 통합 메모리는 로컬 AI 구동에 있어 "골든 존(Golden Zone)"에 해당합니다. 300억 파라미터급 모델을 높은 양자화 수준으로 구동할 수 있어 오픈소스 모델 중 최고 수준의 품질을 경험할 수 있습니다. 모델을 선택할 때 중요한 구분이 하나 있습니다. Ollama에는 같은 모델이라도 GGUF 태그와 MLX 태그 두 가지 포맷으로 제공되는 경우가 있습니다. GGUF 포맷은 기존 llama.cpp 기반으로 실행되고, -nvfp4 · -mxfp8 · -mlx-bf16 같은 MLX 태그 포맷은 MLX 런너로 실행되어 더 높은 추론 성능을 냅니다. 48GB 환경에서는 두 포맷 모두 선택이 가능하므로, 목적에 따라 최적의 조합을 고를 수 있습니다.
[i] MoE(Mixture of Experts)란? 모델의 파라미터 전체를 매번 활성화하지 않고, 입력에 따라 일부 전문가(Expert) 레이어만 선택적으로 활성화하는 구조입니다. Qwen3.6 35B MoE는 전체 파라미터는 35B이지만 실제 토큰 생성 시에는 3B만 활성화되어 27B Dense 모델보다 훨씬 빠른 속도를 냅니다.
아래 표는 Hermes Agent와의 호환성, 도구 호출 안정성, 추론 속도를 종합적으로 고려한 2026년 5월 기준 추천 목록입니다. 각 모델의 GGUF 태그와 MLX 태그를 함께 표기하였습니다.
| 순위 | 모델명:GGUF 태그 | 모델명:MLX태그 | 48GB 적합 크기 | 토큰 속도 | 컨텍스트 | 추천용도 |
| 1 | batiai/qwen3.6-35b:iq4 | qwen3.6:35b-a3b-nvfp4 | 20GB / 38GB | 35-46 t/s | 262K | 범용 최고 성능 |
| 2 | qwen3.6:27b-q6_k | qwen3.6:27b-nvfp4 | 22GB / 20GB | 20-28 t/s | 256K | 코딩 특화 |
| 3 | batiai/gemma4-26b | gemma4:26b (MLX 0.20+) | 13GB / 16GB | 55-63 t/s | 256K | 멀티모달/속도 |
| 4 | gemma4:12b | - | 9.6GB | 70-85 t/s | 128K | 24h 상시 게이트웨이 |
1순위 | Qwen3.6 35B-A3B MoE (범용 최우선 추천)
Qwen3.6 35B-A3B는 2026년 현재 Mac 로컬 AI 커뮤니티에서 "48GB 기본 모델"로 자리잡은 모델입니다. MoE 구조로 토큰당 3B 파라미터만 활성화되어 속도가 빠르고, 262K의 넓은 컨텍스트를 지원합니다. SWE-bench Verified 73.4%, AIME26 92.7%, MMLU-Pro 85.2%로 코딩, 수학적 추론, 일반 지식 모두에서 최고 수준의 성능을 보입니다. GGUF 버전과 MLX 버전이 모두 제공되므로, 현재 Homebrew의 libmlxc 버그 상황에 따라 선택합니다.
[!] 주의: Ollama 공식 라이브러리의 qwen3.6:35b-a3b GGUF 태그는 멀티모달 비전(mmproj) 파일 분리 문제로 Ollama에서 정상 동작하지 않는 경우가 있습니다. 텍스트 전용으로 안정적으로 사용하려면 batiai/qwen3.6-35b 커뮤니티 모델을 권장합니다.
# [권장] GGUF 텍스트 전용 - 안정적 (약 20GB)
# M4 Max 실측 기준 ~46 t/s, 도구 호출 검증 완료
ollama pull batiai/qwen3.6-35b:iq4
# [MLX 런너] MLX 태그 버전 - 더 빠른 성능 (약 38GB)
# Homebrew libmlxc 버그 해결 후 권장
ollama pull qwen3.6:35b-a3b-nvfp42순위 | Qwen3.6 27B Dense (코딩 특화)
코딩 작업에 특화된 Dense 모델입니다. MoE보다 토큰 속도는 느리지만 코드 품질과 정확성이 더 높습니다. MLX 태그인 nvfp4(20GB)와 mxfp8(31GB)가 제공되어 48GB 환경에서 MLX 런너의 성능 향상을 온전히 누릴 수 있습니다. 복잡한 코드 생성, 리팩토링, 버그 수정 등 코딩 중심의 에이전트 작업에 최적이며, 코딩 특화 파인튜닝 버전인 -coding-nvfp4 태그도 별도 제공됩니다.
# [MLX 런너] NVFP4 양자화 (약 20GB, GGUF Q4_K_M과 유사한 크기)
ollama pull qwen3.6:27b-nvfp4
# [MLX 런너] MXFP8 고품질 양자화 (약 31GB, 더 높은 정밀도)
ollama pull qwen3.6:27b-mxfp8
# [MLX 런너] 코딩 특화 파인튜닝 버전 (약 20GB)
ollama pull qwen3.6:27b-coding-nvfp43순위 | Gemma4 26B-A4B (멀티모달 + 최고 속도)
Google의 Gemma4 26B는 4B 활성 파라미터로 MoE 아키텍처를 사용하며, 55~63 tok/s의 빠른 생성 속도와 이미지 이해 능력(멀티모달)을 제공합니다. Ollama 0.20 릴리즈에서 Gemma4 MLX 텍스트 전용 런타임이 추가되어 MLX 런너 지원이 시작되었습니다. 이미지 분석이 필요한 작업이나 빠른 응답이 중요한 자동화 워크플로우에 적합합니다.
# GGUF 커뮤니티 버전 (약 13GB, 가장 가벼운 옵션)
ollama pull batiai/gemma4-26b
# 공식 태그 (약 16GB, 멀티모달 지원)
ollama pull gemma4:26b4순위 | Gemma4 12B (24시간 상시 게이트웨이 모델)
24시간 상시 실행하는 Hermes Agent의 Telegram/Discord 게이트웨이 기본 모델로 이상적입니다. 약 9.6GB로 메모리 부담이 적고, 70~85 tok/s의 빠른 응답으로 일상적인 메시지 처리에 최적화되어 있습니다. 단순한 작업 요청이나 일상 대화에는 12B로 충분하며, 복잡한 코딩이나 분석 작업이 들어오면 Hermes의 폴백(fallback) 설정을 통해 대형 모델로 자동 전환하도록 구성할 수 있습니다.
# Gemma4 12B (약 9.6GB, 빠른 로딩)
ollama pull gemma4:12b모델 다운로드 및 확인
초기 권장 구성은 안정성을 최우선으로 GGUF 텍스트 전용 모델로 시작하고, Homebrew의 MLX libmlxc 버그가 해결된 버전으로 업그레이드 후 MLX 태그 모델로 전환하는 전략을 권장합니다. MLX 런너와 libmlxc 관련 상세 내용은 4-A장을 참고합니다.
# --- 초기 권장 구성 (GGUF, 안정적) ---
# Qwen3.6 35B-A3B 텍스트 전용 IQ4 (약 20GB)
ollama pull batiai/qwen3.6-35b:iq4
# Gemma4 12B 상시 모델 (약 9.6GB)
ollama pull gemma4:12b
# --- MLX 버그 해결 후 전환 구성 ---
# Qwen3.6 35B-A3B MLX NVFP4 (약 38GB)
# ollama pull qwen3.6:35b-a3b-nvfp4
# Qwen3.6 27B NVFP4 코딩 특화 (약 20GB)
# ollama pull qwen3.6:27b-coding-nvfp4
# 설치된 모델 목록 확인
ollama list
# 모델 테스트 실행 (--verbose로 토큰 속도 측정)
ollama run batiai/qwen3.6-35b:iq4 --verbose \
"안녕하세요, 간단한 파이썬 Hello World 코드를 작성해 주세요"
# eval rate 항목에서 실제 t/s 확인 가능4. Ollama 고성능 설정 | 컨텍스트, 상주 로딩, 네트워크 바인딩
Ollama를 설치하고 모델을 받았다고 해서 바로 최고 성능이 나오는 것은 아닙니다. 기본 설정은 매우 보수적으로 되어 있어, 명시적인 최적화 없이는 Mac Mini 48GB의 잠재력 중 상당 부분이 미사용 상태로 남습니다. 특히 컨텍스트 길이는 Hermes Agent 연동에서 가장 중요한 설정입니다. Ollama는 기본 컨텍스트를 모델 사양보다 훨씬 작은 2048~4096 토큰으로 설정하는 경우가 많으며, 이 상태에서는 Hermes Agent가 시작 시 "컨텍스트 길이가 64K에 미치지 못함"이라는 오류와 함께 모델을 거부합니다. 환경 변수 설정은 Homebrew 서비스 기반이기 때문에 ~/.zshrc에 export로 선언하면 서비스 재시작 시에도 자동으로 적용됩니다.
환경 변수 설정
Ollama는 여러 환경 변수로 동작을 제어합니다. ~/.zshrc에 아래 설정을 추가하고 brew services restart ollama로 적용합니다.
# ~/.zshrc에 추가
# Ollama API를 모든 네트워크 인터페이스에서 수신 (Docker 컨테이너 접근용)
export OLLAMA_HOST=0.0.0.0
# 동시 요청 처리 수 (기본값: 1)
# Hermes Agent와 Open WebUI를 동시에 사용할 때 필요
export OLLAMA_NUM_PARALLEL=2
# 모델 메모리 상주 시간 (기본: 5분 후 언로드)
# -1로 설정하면 메모리에 영구 상주 (재로딩 시간 없음)
export OLLAMA_KEEP_ALIVE=-1
# 최대 컨텍스트 길이 강제 설정
# Hermes Agent 최소 요구사항: 65536
export OLLAMA_CTX_SIZE=131072 # 128K (넉넉하게 설정)
# 설정 적용 및 서비스 재시작
source ~/.zshrc
brew services restart ollama[!] 주의: OLLAMA_HOST=0.0.0.0 설정은 Ollama API를 로컬 네트워크의 모든 기기에서 접근 가능하게 만듭니다. 공용 Wi-Fi 환경이나 신뢰할 수 없는 네트워크에서는 보안 위험이 있으므로, 방화벽 설정을 통해 접근을 제한하거나 127.0.0.1로 되돌리는 것이 좋습니다.
Modelfile로 Hermes 전용 모델 설정
Ollama의 Modelfile은 모델의 동작 파라미터를 커스터마이징하는 방법입니다. Hermes Agent에 최적화된 Modelfile을 만들면, 매번 컨텍스트 길이나 파라미터를 지정하지 않아도 됩니다. 기반 모델로 GGUF 태그와 MLX 태그 모두 지정할 수 있으며, 지정한 태그에 따라 자동으로 적합한 런너(llama.cpp 또는 MLX)가 선택됩니다.
# Hermes 전용 Qwen3.6 35B 모델 설정 파일 생성 (GGUF 기반, 안정적)
cat << 'EOF' > ~/Modelfile-hermes-qwen
FROM batiai/qwen3.6-35b:iq4
# 컨텍스트 길이: Hermes Agent 최소 요구사항의 2배
PARAMETER num_ctx 131072
# 온도(Temperature): 에이전트 작업에 적합한 낮은 값
PARAMETER temperature 0.7
# 반복 패널티: 동일 문장 반복 방지
PARAMETER repeat_penalty 1.1
# 메모리 상주 유지
PARAMETER keep_alive -1
PARAMETER num_predict -1
EOF
# 커스텀 모델 생성
ollama create hermes-qwen -f ~/Modelfile-hermes-qwen# Hermes 전용 Gemma4 12B 상시 모델 설정
cat << 'EOF' > ~/Modelfile-hermes-gemma
FROM gemma4:12b
PARAMETER num_ctx 131072
PARAMETER temperature 0.8
PARAMETER repeat_penalty 1.05
PARAMETER keep_alive -1
EOF
ollama create hermes-gemma -f ~/Modelfile-hermes-gemma모델 성능 검증
모델이 정상적으로 Metal 또는 MLX 가속을 사용하고 있는지, 컨텍스트 길이가 올바르게 설정되었는지 확인합니다.
# 현재 로드된 모델 상태 확인
ollama ps
# 출력 예시 (GGUF/Metal 백엔드):
# NAME SIZE PROCESSOR CONTEXT UNTIL
# hermes-qwen 25.3GB 12%/88% CPU/GPU 131072 Forever
#
# 출력 예시 (MLX 백엔드 모델):
# NAME SIZE PROCESSOR CONTEXT UNTIL
# qwen3.6:35b-a3b-nvfp4 38.0GB MLX 131072 Forever
# GPU 전력 및 활용률 확인 (Metal 가속 동작 중)
sudo powermetrics --samplers gpu_power -i 2000 -n 5
# 모델 정보 및 컨텍스트 길이 확인
ollama show hermes-qwen --verbose
# 토큰 생성 속도 직접 측정
ollama run hermes-qwen --verbose \
"Write a 200-word essay about artificial intelligence."
# eval rate 항목에서 실제 t/s 확인4-A. Ollama MLX 백엔드 완전 가이드
MLX 백엔드는 Ollama가 Apple Silicon에서 성능을 끌어올리기 위해 도입한 가장 중요한 변화입니다. 기존 llama.cpp는 Metal을 GPU 가속기처럼 취급하여 CPU 메모리와 GPU 메모리 사이에 데이터 복사 오버헤드가 발생했습니다. 반면 MLX(Apple Machine Learning framework)는 통합 메모리 구조를 네이티브로 이해하기 때문에, CPU와 GPU가 동일한 물리 메모리를 복사 없이 직접 참조합니다. 이 차이가 prefill 속도 약 57%, decode 속도 약 93% 향상으로 이어집니다. 48GB Mac Mini에서는 MLX 런너를 지원하는 모델을 선택함으로써 이 성능 향상을 그대로 누릴 수 있습니다.
버전별 MLX 동작 방식 변화
MLX 지원은 Ollama 버전에 따라 동작 방식이 달라집니다. 이 변화를 이해하면 불필요한 환경 변수 설정이나 트러블슈팅을 피할 수 있습니다.
| Ollama 버전 | MLX 동작 방식 | 환경변수 필요 여부 |
| 0.18 이하 | llama.cpp + Metal 백엔드만 존재 | 해당 없음 |
| 0.19 (2026-03-30) | MLX 프리뷰 도입, 지원 모델 한정 | OLLAMA_USE_MLX=1 필요 (프리뷰) |
| 0.20 이상 | MLX가 Apple Silicon 기본 백엔드 | 불필요 (자동 적용) |
| 0.21+ | MLX 런너 기능 확장, GGUF는 여전히 Metal 사용 | 불필요 |
[i] 핵심 구분: MLX 백엔드가 "기본"이 되었다는 것은 MLX 태그 모델(-nvfp4, -mxfp8, -mlx-bf16)을 내려받으면 자동으로 MLX 런너로 실행된다는 의미입니다. 기존 GGUF 포맷 모델(-q4_k_m, -q6_k 등)은 0.20 이후에도 여전히 llama.cpp + Metal 백엔드로 실행됩니다. 포맷이 백엔드를 결정합니다.
MLX 모델 포맷 이해 | GGUF vs MLX 태그
같은 Qwen3.6 35B-A3B 모델이라도 Ollama 라이브러리에서 어떤 태그를 선택하느냐에 따라 실행 백엔드와 성능이 달라집니다. 아래는 Qwen3.6 기준으로 48GB 환경에서 사용 가능한 태그 전체를 정리한 목록입니다.
[Qwen3.6 35B-A3B 태그 비교]
GGUF 포맷 (Metal/llama.cpp 런너):
batiai/qwen3.6-35b:iq4 ~20GB 텍스트 전용, 안정적, 도구 호출 검증
batiai/qwen3.6-35b:iq3 ~16GB 텍스트 전용, 더 작은 크기
MLX 포맷 (MLX 런너):
qwen3.6:35b-a3b-nvfp4 ~38GB [48GB 적합] NVFP4 양자화, 더 빠른 속도
qwen3.6:35b-a3b-mxfp8 ~48GB [48GB 한계] MXFP8, 고품질, 메모리 주의
qwen3.6:35b-a3b-mlx-bf16 ~70GB [48GB 불가] BF16 전체 정밀도, 용량 초과
[Qwen3.6 27B 태그 비교]
GGUF 포맷:
qwen3.6:27b-q6_k ~22GB 고품질 GGUF
MLX 포맷:
qwen3.6:27b-nvfp4 ~20GB [48GB 적합] 균형 잡힌 선택
qwen3.6:27b-mxfp8 ~31GB [48GB 적합] 고품질 MLX
qwen3.6:27b-coding-nvfp4 ~20GB [48GB 적합] 코딩 특화 파인튜닝
qwen3.6:27b-coding-mxfp8 ~31GB [48GB 적합] 코딩 특화 고품질
qwen3.6:27b-mlx-bf16 ~55GB [48GB 불가] BF16 전체 정밀도, 용량 초과Homebrew 설치 시 libmlxc 버그 현황 및 대처
Ollama 0.20.4부터 0.21.0까지 Homebrew 공식 빌드에서 MLX 런너 모델 실행 시 libmlxc.dylib를 찾지 못하는 패키징 버그가 보고되고 있습니다. 이 버그는 일반 GGUF 모델 실행에는 영향을 주지 않으며, MLX 태그 모델(-nvfp4, -mxfp8, -mlx-bf16)을 사용할 때만 발생합니다.
# MLX 런너 버그 여부 확인 - 오류 발생 예시
ollama run qwen3.6:35b-a3b-nvfp4 "test"
# 오류: Error: 500 Internal Server Error: mlx runner failed:
# MLX not available: failed to load MLX dynamic library
# (searched: [.../Cellar/ollama/0.21.0/bin/lib/ollama])
# --- 임시 우회 방법 ---
# 방법 1: GGUF 텍스트 전용 모델로 대체 (가장 안정적)
ollama pull batiai/qwen3.6-35b:iq4
# 방법 2: Ollama 최신 버전으로 업데이트 (버그 수정 확인)
brew upgrade ollama
ollama --version
# 방법 3: DMG 설치 버전으로 전환 (라이브러리 경로 문제 없음)
# -> 단, DMG 버전은 환경 변수 적용이 복잡하여 권장하지 않음[참고] Ollama GitHub Issues #15479, #15648에서 이 버그가 추적되고 있습니다. 버그가 해결된 버전으로 업데이트하면 brew upgrade ollama 한 줄로 MLX 런너 모델이 정상 작동하게 됩니다.
MLX 런너 모델 설치 및 검증
버그가 해결된 버전에서 MLX 런너 모델을 설치하고 정상 동작을 확인하는 방법입니다.
# MLX 태그 모델 설치 (48GB 적합 옵션)
ollama pull qwen3.6:35b-a3b-nvfp4 # 38GB, 범용
ollama pull qwen3.6:27b-coding-nvfp4 # 20GB, 코딩 특화
# MLX 런너 정상 동작 확인
ollama ps
# MLX 백엔드 사용 중이라면 PROCESSOR 열에 "MLX" 표기
# 출력 예시:
# NAME SIZE PROCESSOR CONTEXT UNTIL
# qwen3.6:35b-a3b-nvfp4 38.0GB MLX 131072 Forever
# 서버 로그에서 MLX 런너 확인
tail -f ~/.ollama/logs/server.log | grep -i mlx
# 정상: "using mlx runner" 또는 "MLX runner loaded"
# 성능 비교 테스트 (GGUF vs MLX)
echo "=== GGUF 기반 (Metal 백엔드) ===" && \
ollama run batiai/qwen3.6-35b:iq4 --verbose \
"Explain what MLX is in one paragraph." 2>&1 | grep "eval rate"
echo "=== MLX 런너 ===" && \
ollama run qwen3.6:35b-a3b-nvfp4 --verbose \
"Explain what MLX is in one paragraph." 2>&1 | grep "eval rate"
# eval rate 수치가 MLX 쪽이 약 1.5~2배 높으면 정상MLX 전용 Modelfile 설정
MLX 태그 모델을 기반으로 Hermes Agent 전용 Modelfile을 생성합니다. Modelfile 문법은 GGUF와 동일하며, FROM 지시자에 MLX 태그를 지정하기만 하면 됩니다.
# Hermes 전용 MLX 모델 설정 (버그 해결 후 사용)
cat << 'EOF' > ~/Modelfile-hermes-qwen-mlx
FROM qwen3.6:35b-a3b-nvfp4
PARAMETER num_ctx 131072
PARAMETER temperature 0.7
PARAMETER repeat_penalty 1.1
PARAMETER keep_alive -1
PARAMETER num_predict -1
EOF
# 커스텀 MLX 모델 생성
ollama create hermes-qwen-mlx -f ~/Modelfile-hermes-qwen-mlx
# Hermes config.yaml에서 모델 전환
# default: hermes-qwen <- GGUF 안정 버전
# default: hermes-qwen-mlx <- MLX 고속 버전 (버그 해결 후)M4 Pro vs M5 MLX 성능 차이
MLX 백엔드의 성능 향상 폭은 칩 세대에 따라 다릅니다. Mac Mini M4 Pro 48GB 환경에서의 현실적인 기대치를 정리합니다.
| 칩 | MLX 가속 특이사항 | prefill 향상 | decode 향상 |
| M5 / M5 Pro / M5 Max | GPU Neural Accelerator 탑재, 최대 가속 | 최대 4x | 최대 4x |
| M4 / M4 Pro / M4 Max | 통합 메모리 최적화 혜택 | 약 +57% | 약 +93% |
| M3 이하 | MLX 기본 지원 | 약 +40~60% | 약 +60~80% |
[i] M4 Pro Mac Mini 48GB 기준, MLX 런너 적용 시 Qwen3.6 35B-A3B-NVFP4 모델에서 decode 약 60~70 t/s를 기대할 수 있습니다. GGUF IQ4 기준의 35~46 t/s 대비 약 1.5~2배 향상입니다. M5 칩의 4배 수치는 GPU Neural Accelerator가 탑재된 기종에만 해당하므로 과도한 기대는 금물입니다.
5. Hermes Agent Docker 설치 및 초기 설정
이제 Hermes Agent를 Docker 컨테이너로 설치할 차례입니다. Docker 방식은 Hermes의 모든 파이썬 의존성과 런타임을 격리된 환경에 담아 macOS 시스템을 오염시키지 않으며, 버전 업그레이드도 이미지 교체만으로 완료됩니다. Nous Research는 공식 Docker 이미지 nousresearch/hermes-agent를 DockerHub에 제공하며, 이 이미지 하나로 게이트웨이 실행, 대시보드 실행, Setup Wizard 실행 등 모든 역할을 수행할 수 있습니다.
Docker 기반 Hermes는 /opt/data 경로를 데이터 저장소로 사용합니다. 이 경로를 Mac의 ~/.hermes 디렉토리로 볼륨 마운트하면, 모든 설정 파일·API 키·메모리·스킬·세션 기록이 컨테이너 외부인 Mac에 영구 저장됩니다. 덕분에 컨테이너를 삭제하고 재생성해도 에이전트의 학습 결과와 개인화된 메모리가 그대로 유지됩니다.
Setup Wizard 실행 | 최초 1회
Hermes Agent를 처음 시작할 때는 반드시 Setup Wizard를 통해 초기 설정을 완료해야 합니다. Wizard는 API 키 설정, LLM 프로바이더 선택, 메시징 게이트웨이(Telegram 등) 연동을 대화형으로 안내합니다. 이 단계에서 Ollama를 직접 연결하는 것이 가능하지만, 먼저 Setup Wizard를 완료한 뒤 6장에서 Ollama 연동을 별도로 설정하는 것을 권장합니다.
# 데이터 디렉토리 생성
mkdir -p ~/.hermes
# Setup Wizard 실행 (대화형 설정)
docker run -it --rm \
-v ~/.hermes:/opt/data \
nousresearch/hermes-agent setup
Setup Wizard는 다음 순서로 진행됩니다.
- 먼저 에이전트의 이름과 SOUL(성격 정의)을 설정합니다.
- 다음으로 LLM 프로바이더를 선택합니다. 이 단계에서 "Custom endpoint"를 선택하고 Ollama URL을 입력할 수 있지만, Wizard가 완료되기 전에 Ollama 설정이 완료되어야 합니다. 편의상 이 단계에서는 임시로 OpenRouter를 선택하고 나중에 변경하는 방법도 있습니다.
- 마지막으로 메시징 게이트웨이(Telegram, Discord, Slack 등)를 설정합니다. Telegram Bot은 @BotFather에서 5분 안에 생성할 수 있으며, 생성된 토큰을 Wizard에 입력합니다.
[Setup Wizard 진행 순서]
1. 에이전트 이름 설정
-> "HermesLocal" 또는 원하는 이름 입력
2. SOUL 설정 (에이전트 성격)
-> 기본값 사용 권장 (나중에 SOUL.md로 수정 가능)
3. LLM 프로바이더 선택
-> [이 단계에서] "Custom endpoint" 선택
-> URL: http://host.docker.internal:11434/v1
-> API Key: ollama (아무 값이나 입력, Ollama는 인증 불필요)
-> 모델명: hermes-qwen (또는 qwen3.6:35b-a3b-q4_k_m)
-> 컨텍스트 길이: 131072
4. 메시징 게이트웨이 (선택사항)
-> Telegram Bot Token 입력 (권장)
-> 또는 "skip" 입력하고 나중에 설정
5. 설정 완료
-> ~/.hermes/.env 와 config.yaml 파일 생성
[i] host.docker.internal은 Docker 컨테이너에서 Mac 호스트의 서비스에 접근하기 위한 특수 DNS 이름입니다. Docker Desktop for Mac에서는 기본적으로 이 이름이 호스트 IP로 해석되므로, 컨테이너 내부에서 host.docker.internal:11434로 Mac에서 실행 중인 Ollama에 접근할 수 있습니다.
게이트웨이 컨테이너 실행
Setup Wizard가 완료되면 Hermes Agent의 핵심인 게이트웨이(Gateway) 컨테이너를 백그라운드에서 실행합니다. 게이트웨이는 Telegram·Discord 등 메시징 플랫폼과 연결을 유지하고, OpenAI 호환 API 서버를 포트 8642에서 노출합니다.
# Hermes Gateway 컨테이너 실행 (백그라운드)
docker run -d \
--name hermes \
--restart unless-stopped \
-v ~/.hermes:/opt/data \
-p 8642:8642 \
--add-host=host.docker.internal:host-gateway \
--memory="6g" \
--cpus="3.0" \
nousresearch/hermes-agent gateway run
# 컨테이너 상태 확인
docker ps | grep hermes
# 로그 확인 (시작 과정 모니터링)
docker logs -f hermes
# 헬스 체크
curl http://localhost:8642/health
# 정상: {"status": "ok"}
# Hermes 대시보드 컨테이너 실행 (선택사항, 웹 UI)
# HOST_IP에 Mac의 실제 로컬 IP 입력 (예: 192.168.1.100)
HOST_IP=$(ipconfig getifaddr en0)
docker run -d \
--name hermes-dashboard \
--restart unless-stopped \
-v ~/.hermes:/opt/data \
-p 9119:9119 \
-e GATEWAY_HEALTH_URL=http://${HOST_IP}:8642 \
--memory="2g" \
--cpus="1.0" \
nousresearch/hermes-agent dashboard
# 대시보드 접속
open http://localhost:9119
설정 파일 구조 이해
Setup Wizard 완료 후 ~/.hermes/ 디렉토리에 생성되는 파일들을 이해하면 이후 설정 변경이 훨씬 수월합니다. 각 파일의 역할을 파악해 두겠습니다.
~/.hermes/
|-- .env # API 키 및 민감한 환경 변수
|-- config.yaml # 에이전트 핵심 설정 (모델, 도구, MCP 등)
|-- SOUL.md # 에이전트 성격 및 행동 지침 정의
|-- skills/ # 학습된 스킬 저장소
|-- memory/ # 장기 메모리 데이터베이스
|-- sessions/ # 과거 대화 세션 기록 (FTS5 검색 가능)
|-- logs/ # 에이전트 실행 로그
config.yaml은 에이전트의 두뇌 설정 파일입니다. 모델 선택, 터미널 백엔드, MCP 서버, 컨텍스트 엔진, 보조 모델 등 거의 모든 설정이 이 파일에서 이루어집니다. 다음 장에서 이 파일을 통해 Ollama와의 연동을 설정합니다.
6. Hermes + Ollama 연동 | 로컬 모델 완전 설정 가이드
Hermes Agent와 Ollama를 연동하는 데 있어 가장 중요한 세 가지 사항이 있습니다.
- 첫째, Ollama API를 Docker 컨테이너에서 접근 가능하도록 OLLAMA_HOST=0.0.0.0으로 설정해야 합니다.
- 둘째, Ollama의 실제 컨텍스트 길이와 Hermes 설정의 컨텍스트 길이가 일치해야 합니다.
- 셋째, Hermes의 스트리밍 타임아웃을 로컬 모델에 맞게 늘려야 합니다. 로컬 모델은 클라우드 API보다 응답이 느리기 때문에 기본 타임아웃인 120초로는 긴 작업에서 연결이 끊어질 수 있습니다.
Ollama 접근 설정 확인
Hermes 컨테이너가 Mac의 Ollama에 접근할 수 있는지 먼저 확인합니다.
# Ollama가 모든 인터페이스에서 수신 중인지 확인
curl http://localhost:11434/api/tags
# Docker 컨테이너 내부에서 Ollama 접근 테스트
docker run --rm \
--add-host=host.docker.internal:host-gateway \
curlimages/curl \
curl -s http://host.docker.internal:11434/api/tags | python3 -m json.tool
# 정상이라면 설치된 모델 목록이 JSON으로 출력됨
# 오류 시: OLLAMA_HOST 환경 변수가 설정되지 않은 것
Ollama가 0.0.0.0으로 수신하지 않고 있다면, 다음과 같이 설정을 추가합니다.
# ~/.zshrc에 추가 (이미 4장에서 했다면 생략)
echo 'export OLLAMA_HOST=0.0.0.0' >> ~/.zshrc
source ~/.zshrc
# Ollama 서비스 재시작
brew services restart ollama
# 재시작 후 확인
curl http://0.0.0.0:11434/api/version
~/.hermes/config.yaml 설정
Hermes 컨테이너를 잠시 중지하고 설정 파일을 수정합니다. 이 파일은 컨테이너 외부인 Mac의 ~/.hermes/config.yaml에 있으므로, Mac에서 직접 편집할 수 있습니다.
# 컨테이너 중지 (설정 변경 중)
docker stop hermes
# 설정 파일 편집
nano ~/.hermes/config.yaml
아래는 48GB Mac Mini에서 Ollama와 연동하기 위한 완전한 config.yaml 설정 예시입니다.
# ~/.hermes/config.yaml
# 48GB Mac Mini + Ollama 최적화 설정 (2026년 5월 기준)
# --- 메인 LLM 설정 ---
model:
# Ollama 커스텀 엔드포인트 사용
provider: custom
base_url: http://host.docker.internal:11434/v1
default: hermes-qwen # Modelfile로 생성한 커스텀 모델명
# 또는 직접 모델 태그 사용:
# default: qwen3.6:35b-a3b-q4_k_m
# 컨텍스트 길이 - Ollama Modelfile 설정과 반드시 일치해야 함
context_length: 131072
# --- 컨텍스트 엔진 ---
context:
# 컨텍스트 창이 가득 찰 때 중간 대화를 요약하여 압축
engine: compress
# --- 보조(Auxiliary) 모델 설정 ---
# 요약, 메모리 처리 등 가벼운 작업에 사용되는 보조 모델
# 메인 모델보다 빠른 소형 모델을 지정하면 전체 응답 속도 향상
auxiliary:
compression:
# 로컬 Gemma4 12B를 보조 요약 모델로 사용
provider: custom
base_url: http://host.docker.internal:11434/v1
model: hermes-gemma # Modelfile로 생성한 Gemma4 12B 기반 모델
# 보조 모델의 컨텍스트 길이는 메인 모델 이상이어야 함
context_length: 131072
# --- 폴백(Fallback) 체인 설정 ---
# Ollama 서버가 다운될 경우 자동으로 클라우드 모델로 전환
fallback_providers:
- provider: openrouter
model: qwen/qwen3-235b-a22b:free # OpenRouter 무료 티어 모델
- provider: google-gemini-cli
model: gemini-2.5-flash # Google 무료 티어
# --- 터미널 백엔드 ---
terminal:
# Docker를 터미널 백엔드로 사용 (작업 격리)
backend: docker
docker:
# Hermes가 작업 실행용으로 생성하는 내부 컨테이너 설정
image: ubuntu:22.04
memory: 2g
cpus: "1.0"
# --- 스트리밍 타임아웃 ---
# 로컬 모델은 클라우드 API보다 응답이 느려 타임아웃 연장 필요
stream:
read_timeout: 1800 # 30분 (기본값 120초에서 연장)
# --- MCP 서버 설정 (선택사항) ---
# mcp_servers:
# github:
# command: npx
# args: ["-y", "@modelcontextprotocol/server-github"]
# env:
# GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"# 설정 파일 수정 후 컨테이너 재시작
docker start hermes
# 로그로 Ollama 연결 확인
docker logs -f hermes
# 정상 시: "Connected to model: hermes-qwen (via http://host.docker.internal:11434/v1)"
# 오류 시: "Failed to connect to Ollama endpoint" -> OLLAMA_HOST 설정 확인
~/.hermes/.env 설정
API 키는 config.yaml이 아닌 .env 파일에 보관합니다. Ollama는 API 키가 필요 없지만, 폴백 체인에 클라우드 프로바이더를 설정한 경우 해당 키를 여기에 추가합니다.
# ~/.hermes/.env 파일 편집
nano ~/.hermes/.env
# ~/.hermes/.env 예시
# Ollama는 인증 불필요, 더미 값 입력
OPENAI_API_KEY=ollama
# 폴백 체인용 클라우드 프로바이더 키 (선택사항)
OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxx
# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
# Telegram 봇 토큰 (게이트웨이 사용 시)
# TELEGRAM_BOT_TOKEN=xxxxxxxxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Hermes CLI로 Ollama 연결 검증
실제로 Hermes가 Ollama 모델과 정상 통신하는지 검증합니다.
# 실행 중인 Hermes 컨테이너에 접속
docker exec -it hermes bash
# 컨테이너 내부에서 Hermes CLI 실행
hermes doctor
# 출력 예시:
# [v] Python environment: OK
# [v] Config file: OK
# [v] Model connection: OK (hermes-qwen via http://host.docker.internal:11434/v1)
# [v] Context length: 131072 tokens (>= 64000 required)
# [v] Tool calling: OK
# [v] Telegram gateway: OK
# 간단한 대화 테스트
hermes
# > 현재 디렉토리에 있는 파일들을 나열하고, 가장 최근에 수정된 파일이 무엇인지 알려줘
7. Docker Compose로 풀스택 AI 환경 구성
개별 docker run 명령어로 컨테이너를 하나씩 실행하는 것은 관리가 번거롭습니다. Docker Compose를 사용하면 Hermes Gateway, Hermes Dashboard, Open WebUI를 하나의 파일로 선언적으로 관리하고, docker compose up -d 한 번으로 전체 스택을 실행할 수 있습니다. 이 설정을 Mac Mini의 시작 서비스로 등록하면 재부팅 후에도 자동으로 AI 환경이 복원됩니다.
docker-compose.yml 작성
# 작업 디렉토리 생성
mkdir -p ~/hermes-stack
cd ~/hermes-stack
# ~/hermes-stack/docker-compose.yml
# Mac Mini 48GB 최적화 풀스택 AI 환경
version: "3.9"
services:
# ----------------------------------------
# Hermes Agent Gateway (메인 에이전트)
# ----------------------------------------
hermes:
image: nousresearch/hermes-agent:latest
container_name: hermes
restart: unless-stopped
command: gateway run
volumes:
- ~/.hermes:/opt/data
ports:
- "8642:8642" # OpenAI 호환 API + 헬스 엔드포인트
extra_hosts:
# Mac 호스트 (Ollama) 접근을 위한 특수 DNS
- "host.docker.internal:host-gateway"
deploy:
resources:
limits:
memory: 6G # VM 12GB 중 6GB
cpus: "3.0" # VM 6코어 중 3코어
reservations:
memory: 2G
environment:
# 스트리밍 타임아웃 연장 (로컬 모델 대응)
- HERMES_STREAM_READ_TIMEOUT=1800
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8642/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 15s
# ----------------------------------------
# Hermes Dashboard (웹 모니터링 UI)
# ----------------------------------------
hermes-dashboard:
image: nousresearch/hermes-agent:latest
container_name: hermes-dashboard
restart: unless-stopped
command: dashboard
volumes:
- ~/.hermes:/opt/data
ports:
- "9119:9119" # 웹 대시보드
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
- GATEWAY_HEALTH_URL=http://hermes:8642
depends_on:
hermes:
condition: service_healthy
deploy:
resources:
limits:
memory: 2G
cpus: "1.0"
# ----------------------------------------
# Open WebUI (ChatGPT 스타일 웹 인터페이스)
# ----------------------------------------
open-webui:
image: ghcr.io/open-webui/open-webui:main
container_name: open-webui
restart: unless-stopped
ports:
- "3000:8080" # 웹 UI 접속 포트
volumes:
- open-webui-data:/app/backend/data
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
# Hermes Agent의 OpenAI 호환 API를 백엔드로 사용
- OPENAI_API_BASE_URL=http://hermes:8642/v1
- OPENAI_API_KEY=hermes-local-key
# Ollama 직접 연결도 추가 (모델 탐색용)
- OLLAMA_BASE_URL=http://host.docker.internal:11434
depends_on:
hermes:
condition: service_healthy
deploy:
resources:
limits:
memory: 2G
cpus: "1.0"
# 영구 볼륨 선언
volumes:
open-webui-data:
driver: local
# 전체 스택 시작 (백그라운드)
docker compose up -d
# 상태 확인
docker compose ps
# 로그 모니터링 (전체 서비스)
docker compose logs -f
# 개별 서비스 로그
docker compose logs -f hermes
# 서비스 접속 확인
curl http://localhost:8642/health # Hermes API
open http://localhost:9119 # Hermes 대시보드
open http://localhost:3000 # Open WebUI
Mac Mini 시작 시 자동 실행 설정
Docker Desktop이 시작되면 자동으로 docker compose up이 실행되도록 launchd 서비스를 등록합니다. 이렇게 하면 Mac Mini를 재시작한 후에도 AI 에이전트 스택이 자동으로 복원됩니다.
# launchd plist 파일 생성
cat << 'EOF' > ~/Library/LaunchAgents/com.hermes.stack.plist
http://www.apple.com/DTDs/PropertyList-1.0.dtd">
Label
com.hermes.stack
ProgramArguments
/usr/local/bin/docker
compose
--project-directory
/Users/YOUR_USERNAME/hermes-stack
up
-d
StartInterval
60
RunAtLoad
StandardOutPath
/tmp/hermes-stack.log
StandardErrorPath
/tmp/hermes-stack-error.log
EOF
# YOUR_USERNAME을 실제 사용자명으로 변경
sed -i '' "s/YOUR_USERNAME/$USER/" \
~/Library/LaunchAgents/com.hermes.stack.plist
# launchd에 등록
launchctl load ~/Library/LaunchAgents/com.hermes.stack.plist
echo "자동 시작 서비스가 등록되었습니다."
8. 실전 활용 시나리오 | 로컬 AI 에이전트의 일상
Mac Mini에 Hermes Agent와 Ollama가 완전히 설치되었다면, 이제 실제로 어떻게 활용할 수 있는지 알아보겠습니다. 로컬 모델 기반 Hermes는 클라우드 API 비용 걱정 없이 24시간 자유롭게 사용할 수 있다는 것이 가장 큰 장점입니다. 모든 대화와 작업이 Mac Mini 내에서 처리되기 때문에 민감한 기업 문서나 개인 데이터도 외부 서버로 전송되지 않아 프라이버시가 완벽하게 보호됩니다.
Telegram 봇으로 어디서나 접근
Hermes의 Telegram 게이트웨이가 설정되어 있다면, Mac Mini에 앉아 있지 않아도 스마트폰 어디서든 로컬 AI 에이전트에 명령을 내릴 수 있습니다. 집 Wi-Fi를 벗어나더라도 Telegram 서버가 중간 메시지 브로커 역할을 하기 때문에 외부 접속 설정(포트 포워딩 등) 없이도 가능합니다.
[Telegram 봇 사용 예시]
사용자: 지금 내 Mac Mini에서 실행 중인 Docker 컨테이너 목록 보여줘
Hermes: 현재 실행 중인 Docker 컨테이너입니다:
[도구 사용: 터미널 실행 -> docker ps]
CONTAINER ID IMAGE STATUS PORTS
a1b2c3d4e5f6 nousresearch/hermes-agent Up 3hrs 0.0.0.0:8642->8642/tcp
f6e5d4c3b2a1 open-webui:main Up 3hrs 0.0.0.0:3000->8080/tcp
9z8y7x6w5v4u nousresearch/hermes-agent Up 3hrs 0.0.0.0:9119->9119/tcp
총 3개 컨테이너가 정상 실행 중입니다.
크론(Cron) 기반 자동화 작업
Hermes의 내장 스케줄러를 활용하면 정기적인 자동화 작업을 설정할 수 있습니다. 로컬 모델이기 때문에 API 사용료 걱정 없이 매 시간, 매일, 매주 작업을 실행할 수 있습니다.
[Hermes CLI 또는 Telegram에서 크론 등록]
> 매일 오전 9시에 지난 24시간 동안의 주요 AI 뉴스를 요약해서 Telegram으로 보내줘
Hermes: 일일 AI 뉴스 요약 작업을 등록했습니다.
스케줄: 매일 09:00 KST
작업: 웹 검색 -> 뉴스 요약 -> Telegram 전송
다음 실행: 내일 오전 9시
# Hermes 컨테이너 내부에서 직접 크론 등록 (CLI 방식)
docker exec -it hermes hermes cron add \
--schedule "0 9 * * *" \
--task "오늘의 AI 및 개발자 뉴스 상위 5건을 검색하고 한국어로 요약해 Telegram으로 발송해줘" \
--name "daily-ai-news"
# 등록된 크론 작업 확인
docker exec -it hermes hermes cron list
코딩 에이전트로 활용
Hermes의 터미널 백엔드를 Docker로 설정했기 때문에, 코드 실행이 격리된 환경에서 안전하게 이루어집니다. 파이썬 스크립트 작성부터 실행, 결과 확인, 버그 수정까지 에이전트가 연속적으로 처리합니다.
[코딩 작업 예시]
> ~/Desktop/sales_data.csv 파일을 분석해서 월별 매출 추이 그래프를 생성하고
이상치(Outlier)가 있으면 찾아서 보고서로 정리해줘
Hermes:
[도구: 파일 읽기] ~/Desktop/sales_data.csv (1,247행, 8개 컬럼)
[도구: 코드 실행] Python - pandas, matplotlib 로드
[도구: 코드 실행] 월별 집계 및 IQR 이상치 탐지
[도구: 파일 저장] ~/Desktop/sales_analysis.png (그래프 저장)
[도구: 파일 쓰기] ~/Desktop/sales_report.md (보고서 생성)
분석 완료. 2024년 3월과 8월에 각각 평균 대비 +185%, -42%의 이상치가 발견되었습니다.
그래프는 ~/Desktop/sales_analysis.png, 보고서는 sales_report.md로 저장했습니다.
모델 동적 전환
로컬 모델과 클라우드 모델 사이에서 작업 복잡도에 따라 동적으로 전환하는 것도 가능합니다. 일상적인 메시지는 빠른 Gemma4 12B로 처리하고, 복잡한 코딩이나 심층 분석은 Qwen3.6 35B 또는 클라우드의 Claude Opus로 전환하는 하이브리드 전략을 사용할 수 있습니다.
# Hermes CLI에서 실시간 모델 전환
docker exec -it hermes hermes model
# 또는 Telegram/CLI에서 직접 명령
# /model hermes-qwen -> Qwen3.6 35B로 전환 (고품질)
# /model hermes-gemma -> Gemma4 12B로 전환 (고속)
# /model anthropic/claude-opus-4.6 -> Claude Opus로 전환 (최고 품질)
9. 성능 모니터링 및 튜닝
Mac Mini에서 Hermes Agent와 Ollama를 운영하다 보면 메모리 사용량, 토큰 생성 속도, 컨테이너 상태 등을 주기적으로 확인하고 최적화해야 할 시점이 옵니다. Apple 기본 제공 도구인 Activity Monitor와 커맨드라인 도구들을 조합하면 종합적인 성능 모니터링이 가능합니다. 특히 통합 메모리 압박(Memory Pressure)을 실시간으로 모니터링하는 것이 중요합니다. 메모리 압박이 황색이나 적색으로 바뀌면 스왑이 발생하고 있다는 신호이며, 이 상태가 지속되면 Ollama의 추론 속도가 급격히 저하됩니다.
실시간 시스템 모니터링
# --- 통합 메모리 사용 현황 ---
# 메모리 압박 확인 (macOS 네이티브)
memory_pressure
# 출력 예시:
# System-wide memory free percentage: 38%
# System-wide memory pressure... relieved (녹색)
# System-wide memory pressure... critical (적색 -> 스왑 발생)
# 메모리 통계 상세 확인
vm_stat 1 # 1초마다 갱신
# pageins/pageouts 값이 크면 스왑 발생 중
# --- Ollama 성능 모니터링 ---
# 현재 로드된 모델과 GPU/CPU 사용 비율
ollama ps
# NAME SIZE PROCESSOR CONTEXT UNTIL
# hermes-qwen 25.3GB 12%/88% CPU/GPU 131072 Forever
# GPU 전력 및 활용률 (Metal 가속 확인)
sudo powermetrics --samplers gpu_power -i 2000 -n 10
# --- Docker 컨테이너 리소스 사용량 ---
# 실시간 컨테이너 메모리/CPU 사용량
docker stats hermes hermes-dashboard open-webui
# 출력 예시:
# CONTAINER CPU% MEM USAGE/LIMIT MEM%
# hermes 2.4% 1.8GiB / 6GiB 30%
# hermes-dashboard 0.1% 412MiB / 2GiB 20%
# open-webui 0.3% 580MiB / 2GiB 28%
메모리 배분 최적화 시나리오별 가이드
48GB를 어떤 작업을 위주로 사용하느냐에 따라 최적의 Docker VM 메모리 배분이 달라집니다. 주요 사용 패턴별 권장 설정을 정리합니다.
| 사용 패턴 | Docker VM | Ollama 모델 | 예상 macOS 여유 | 비고 |
| 코딩 에이전트 집중 | 12GB | Qwen3.6 27B Q6 (22GB) | ~14GB | 코드 품질 최우선 |
| 범용 에이전트 | 12GB | Qwen3.6 35B MoE (20GB) | ~16GB | 속도+품질 균형 |
| 24시간 상시 운영 | 8GB | Gemma4 12B (10GB) | ~30GB | 전력·메모리 절약 |
| 이미지 분석 포함 | 12GB | Gemma4 26B (13GB) | ~23GB | 멀티모달 작업 |
| 대형+소형 모델 동시 | 8GB | Gemma4 26B + Gemma4 12B (23GB) | ~17GB | 병렬 처리 |
[!] 주의: 두 개의 모델을 동시에 메모리에 상주시키려면 OLLAMA_NUM_PARALLEL=2와 함께 충분한 메모리 확보가 필요합니다. 48GB 환경에서 Gemma4 26B(13GB)와 Gemma4 12B(10GB)를 동시 로드하면 약 23GB를 소비하며, Docker VM 8GB와 macOS 8GB를 합산하면 39GB로 여유가 있습니다.
성능 저하 시 점검 체크리스트
Ollama의 추론 속도가 예상보다 느리거나 Hermes Agent 응답이 늦어지는 경우 아래 체크리스트를 순서대로 확인합니다.
# [점검 1] Metal GPU 가속 활성화 여부
ollama ps
# PROCESSOR 열에서 GPU 비율이 80% 미만이면 문제
# [점검 2] 메모리 스왑 발생 여부
vm_stat | grep "Pages swapped"
# swapped 값이 지속적으로 증가하면 메모리 부족
# [점검 3] 컨텍스트 길이 불일치 확인
# Ollama Modelfile의 num_ctx와 config.yaml의 context_length가 다르면 성능 저하
ollama show hermes-qwen | grep num_ctx
grep "context_length" ~/.hermes/config.yaml
# [점검 4] Docker VM 메모리 부족 확인
docker stats --no-stream
# MEM% 가 90% 이상이면 Docker VM 메모리 부족
# [점검 5] Ollama 서비스 상태
brew services list | grep ollama
# 상태가 "started"가 아니면 재시작
brew services restart ollama
# [점검 6] Hermes 컨테이너 오류 로그
docker logs --tail=50 hermes | grep -i error
주기적 유지관리
Hermes Agent와 Ollama는 지속적으로 업데이트됩니다. 주기적으로 최신 버전으로 업데이트하면 성능 개선과 버그 수정 혜택을 받을 수 있습니다.
# Ollama 업데이트 (Homebrew)
brew upgrade ollama
brew services restart ollama
# Hermes Docker 이미지 업데이트
docker compose pull
docker compose up -d
# 컨테이너가 자동으로 새 이미지로 재생성됨
# ~/.hermes/ 데이터는 볼륨으로 보존됨
# Hermes 버전 확인
docker exec hermes hermes --version
# 불필요한 Docker 이미지 정리 (디스크 공간 확보)
docker image prune -f
# Ollama 사용하지 않는 모델 제거
ollama rm qwen3.5:27b # 더 이상 사용하지 않는 모델
ollama list # 남은 모델 확인
10. 프라이버시와 성능을 모두 갖춘 로컬 AI 환경
Mac Mini M4 Pro 48GB에 Ollama와 Hermes Agent를 Docker 기반으로 구축하면, 클라우드 API에 의존하지 않는 완전히 자율적인 AI 에이전트 인프라가 완성됩니다. 처음 설정 과정이 다소 복잡하게 느껴질 수 있지만, 한 번 구축하고 나면 Mac Mini는 24시간 깨어 있는 개인 AI 비서로 변신합니다. Telegram을 통해 출근길에 오늘의 뉴스 브리핑을 받고, 회사에서 코드 리뷰를 요청하고, 귀가 후 복잡한 분석 작업을 맡기는 일이 모두 가능합니다. 그 모든 처리가 외부 서버가 아닌 자택의 Mac Mini 위에서 이루어진다는 사실이 이 환경의 핵심 가치입니다.
2026년 현재 오픈소스 모델의 품질은 불과 1~2년 전과 비교해 극적으로 향상되었습니다. Qwen3.6 35B MoE나 Gemma4 26B는 이미 일상적인 코딩, 분석, 자동화 작업에서 GPT-4 수준에 근접한 결과를 내놓습니다. 여기에 Hermes Agent의 폐쇄 학습 루프(Closed Learning Loop)가 더해지면, 사용할수록 스킬이 쌓이고 개인화되는 에이전트가 완성됩니다. 월 수십만 원의 클라우드 구독료를 내는 대신, Mac Mini 한 대에 대한 일회성 투자로 훨씬 더 강력하고 프라이버시가 보장되는 환경을 얻을 수 있습니다.
물론 로컬 모델에는 아직 한계도 있습니다. 최신 GPT-4o나 Claude Opus 대비 복잡한 추론이나 창의적 글쓰기에서 품질 차이가 있을 수 있으며, 컨텍스트 길이를 크게 늘릴수록 메모리 사용량과 속도에 영향을 줍니다. 이런 경우를 대비해 config.yaml의 폴백 체인에 클라우드 프로바이더를 설정해두면, Ollama가 다운되거나 작업이 너무 복잡할 때 자동으로 클라우드 모델로 전환하는 하이브리드 전략으로 보완할 수 있습니다. 로컬 우선(Local-first), 필요 시 클라우드 보완이라는 이 전략이 현재 시점에서 가장 현실적이고 효율적인 접근입니다.
전체 설정 요약 체크리스트
이 가이드에서 진행한 모든 단계를 한눈에 확인할 수 있는 체크리스트입니다.
[Phase 1: Docker Desktop 설정]
[v] Docker Desktop 설치 (ARM64 버전)
[v] CPU: 6코어 할당
[v] Memory: 12GB (12,288MiB) 할당
[v] Swap: 2GB 할당
[v] VirtioFS 파일 공유 활성화
[Phase 2: Ollama 설치 및 설정]
[v] brew install ollama
[v] brew services start ollama
[v] OLLAMA_HOST=0.0.0.0 환경 변수 설정
[v] OLLAMA_KEEP_ALIVE=-1 설정 (모델 상주)
[v] OLLAMA_CTX_SIZE=131072 설정
[v] 모델 다운로드 (qwen3.6:35b-a3b, gemma4:26b 등)
[v] Modelfile로 hermes-qwen, hermes-gemma 생성
[v] GPU 가속 작동 확인 (ollama ps에서 GPU 80%+)
[Phase 3: Hermes Agent 설치]
[v] mkdir -p ~/.hermes
[v] Setup Wizard 실행 및 완료
[v] config.yaml Ollama 연동 설정
[v] .env 파일 API 키 설정
[v] hermes doctor로 연결 확인
[Phase 4: Docker Compose 통합]
[v] ~/hermes-stack/docker-compose.yml 작성
[v] docker compose up -d 실행
[v] 헬스 체크 통과 확인
[v] Open WebUI 접속 확인 (localhost:3000)
[v] launchd 자동 시작 등록
[Phase 5: 운영 확인]
[v] ollama ps에서 모델 상주 확인
[v] docker stats에서 메모리 사용량 정상 확인
[v] Telegram 봇 테스트 (선택)
[v] 주간 업데이트 일정 계획
참고 원문
'AI 활용' 카테고리의 다른 글
| Atomic Hermes - 터미널없이 시작하는 간단한 에이전트 (0) | 2026.04.27 |
|---|---|
| Hermes Agent - AI 에이전트를 활용한 생활 속 자동화 (0) | 2026.04.27 |
| NemoClaw를 라즈베리파이 5에 설치하고 운영하기 (0) | 2026.03.24 |
| NVIDIA - NemoClaw 설치부터 활용까지 (0) | 2026.03.24 |
| 중소기업 AI 도입 심화 분석 - 핵심 성공사례와 업종별 전략 (0) | 2026.03.09 |
