MLX Harness 사용법.

1MLX Harness 설치하기

macOS 14.5 이상을 실행하는 Apple Silicon Mac이 필요합니다. 추론 엔진이 앱 안에 들어 있어 따로 설치할 것은 없습니다. 내려받아 MLX Harness를 '응용 프로그램'으로 옮기고 열면 됩니다.

MLX Harness는 JANGQ AI의 vMLX를 수정한 버전으로, Apache License 2.0으로 배포됩니다. 내부 엔진은 vMLX의 것을 그대로 쓰며, MLX Harness는 그 바깥의 앱을 바꾸고 Network 페이지를 더했습니다.

2모델 고르고 내려받기

모델은 Hugging Face에서 가져오며, 대부분 mlx-community 조직이 올린 MLX 형식입니다. 내려받기 전에 무엇이 들어가는지 확인하세요. Compare에서 내 Mac 메모리에 어떤 모델이 들어가는지, 각각 대략 얼마나 빨리 쓰는지 볼 수 있습니다.

1. Models를 열고 Find & download를 고르세요. 검색한 뒤 다운로드 수, 트렌드, 좋아요, 최근 업데이트, 모델 크기로 정렬할 수 있으며, 검색 결과에는 MLX 모델이 나옵니다.
2. 모델을 클릭해 README를 읽고 내려받으세요. 다운로드는 백그라운드에서 진행되며 Downloads에서 진행 상황을 볼 수 있습니다.
3. Llama 같은 게이트 모델은 먼저 HF Token: 칸에 Hugging Face 토큰을 넣고, huggingface.co에서 그 모델의 라이선스에 동의하세요.
4. Library & tools에는 Mac에 있는 모델이 나옵니다. Inspect Model은 모델의 메타데이터를 보여 주고, Diagnose Model은 상태 검사를 하며, Convert Model은 Hugging Face 모델을 양자화된 MLX 모델로 변환합니다. Balanced (4-bit), Quality (8-bit), Compact (3-bit) 중에서 고릅니다.

다운로드는 Download to:에서 다른 위치를 고르지 않는 한 Hugging Face 캐시 폴더에 저장됩니다. MLX Harness는 그 캐시와 ~/.mlxstudio/models, 그리고 Directories에 추가한 폴더에 이미 있는 모델도 찾아냅니다.

3채팅과 이미지

채팅과 추론

1. Chat & Images를 열고 채팅 도구 막대의 모델 메뉴에서 모델을 고르거나 Add local model을 고르세요. 모델은 감지된 기본값으로 시작하며, 고급 옵션은 Servers & API에 있습니다.
2. 메시지를 입력하세요. 추론 모델은 생각하는 과정을 별도 상자에 보여 줍니다. 채팅 설정의 Enable Thinking은 Auto, On, Off로 정하고, Reasoning Effort는 지원하는 모델에서 추론 깊이를 정합니다.
3. 비전 모델은 이미지를 받습니다. 파일을 채팅에 끌어다 놓거나 첨부 버튼을 쓰세요. 동영상, 오디오, 텍스트 파일도 이를 받는 모델에서 쓸 수 있습니다.
4. 채팅은 사이드바에 저장되고 검색할 수 있습니다. 설정은 모델별로 저장됩니다.

다른 곳에 있는 모델과 채팅할 수도 있습니다. Connect remote endpoint에는 OpenAI 호환 API 주소라면 무엇이든 넣을 수 있습니다. 프롬프트가 Mac 밖으로 나가는 것은 이때뿐입니다.

이미지 생성과 편집

Chat & Images에서 Image를 고르세요. 이미지 모델은 mflux로 실행되고, 이미지 서버는 Mac의 폴더에서 모델을 불러옵니다. Find mflux models를 누르면 Models에서 이미지 모델 검색이 열리고, Load selected folder로 시작합니다.

Flux Dev 같은 일부 이미지 모델은 Hugging Face에서 게이트가 걸려 있어, 토큰과 라이선스 동의가 있어야 내려받을 수 있습니다.

4에이전트와 도구

MLX Harness에서는 모델이 Mac에서 직접 작업하게 할 수 있습니다. 채팅 설정에서 Enable Built-in Coding Tools를 켜고 Working Directory를 고르면, 모든 파일 작업과 명령이 그 안에서 실행됩니다. 그런 다음 도구 범주를 켜거나 끕니다.

Max Tool Iterations는 메시지 하나가 도구 호출을 몇 번까지 할 수 있는지 정합니다(기본값 10). 셸과 파일 도구는 실제 파일을 다루므로, 작업 디렉터리는 홈 폴더가 아닌 프로젝트로 지정하고 믿을 수 있는 모델을 쓰세요.

5다른 앱에서 쓰기: 로컬 API

실행한 모든 모델은 Mac에서 제공됩니다. http://localhost:8080의 API Gateway는 요청에 담긴 모델 이름으로 각 요청을 알맞은 모델에 보내고, 멈춰 있는 모델이 요청되면 시작합니다. 모델마다 8000번부터 시작하는 자체 포트도 있습니다. 기본적으로 내 Mac만 접근할 수 있으며, LAN을 켜면 네트워크에 열립니다.

API 뒤에서 엔진은 이미 읽은 내용을 캐시합니다. Continuous Batching을 켜면 Prefix Cache 덕분에 긴 채팅이나 코딩 에이전트의 반복되는 지시를 다음 차례에 다시 처리하지 않아도 되고, KV Cache Quantization은 그 캐시를 줄이며, Disk Cache (Persistent)는 SSD에 보관합니다. 이 옵션들은 각 모델의 서버 설정에 있습니다.

API 페이지에 표시된 모델 이름을 쓴 OpenAI 형식 요청 예시입니다.

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR-MODEL",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

OpenAI SDK라면 무엇이든 base_url을 http://localhost:8080/v1로 정하면 쓸 수 있습니다. 세션에 키를 설정하지 않았다면 키는 아무 텍스트나 괜찮습니다. 코딩 에이전트용으로는 Coding Tool Integration이 Auto-Configure로 Claude Code, Codex CLI, OpenCode, OpenClaw, Hermes Agent를 설정하거나 Manual Setup을 보여 줍니다. Claude Code라면 다음 내용을 ~/.claude/settings.json에 병합하면 됩니다.

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8080",
    "ANTHROPIC_MODEL": "YOUR-MODEL",
    "ANTHROPIC_API_KEY": "mlxstudio"
  }
}

6Network 페이지와 MLX Node

Network는 mlx.app에서 가져온 MLX Network의 실시간 현황을 보여 줍니다. 온라인 상태로 일하는 Mac, 초당 토큰 수, 오늘의 AI 토큰 수, 국가 수입니다. 이 Mac에 MLX Node가 설치되어 실행 중인지 확인하고, MLX Node를 열거나 다운로드 링크를 보여 줍니다. Your wallet에 지갑 이름을 넣고 Show를 누르면 채굴한 MLX가 늘어나는 것을 볼 수 있으며, 이름은 이 Mac에만 저장됩니다.

MLX Harness 자체는 채굴하지 않습니다. 나를 위해 모델을 돌릴 뿐입니다. MLX Node는 별도의 메뉴 막대 앱으로, Mac의 쉬는 시간을 MLX Network에 빌려주고 MLX 토큰을 법니다. 무료 좌석으로 하루 최대 1 MLX이며 30일 동안 잠깁니다. 둘 다 쓰면 같은 메모리와 GPU를 나눠 쓰므로, MLX Node의 Memory MLX may use 한도와 수동 시작·정지로 방해받지 않게 할 수 있습니다. MLX 토큰은 가치가 떨어질 수 있으니 위험 고지를 읽어 보세요.

7자주 묻는 질문

MLX Harness는 무료인가요?

네. 무료이며, 바탕이 된 프로젝트 vMLX와 마찬가지로 Apache License 2.0을 따릅니다.

MLX Harness는 언제 내려받을 수 있나요?

지금 바로 가능합니다. harness.mlx.app과 mlx.app/download에서 무료로 내려받을 수 있으며, macOS 14.5 이상을 실행하는 Apple Silicon Mac용입니다. 소스 코드는 GitHub의 github.com/MLXapp/studio에 있습니다.

MLX Harness는 어떤 Mac에서 실행되나요?

macOS 14.5 이상을 실행하는 Apple Silicon(M1 이후) Mac입니다. 어떤 모델이 들어가는지는 Mac의 메모리가 정하며, mlx.app의 Compare에서 확인할 수 있습니다.

MLX Harness가 내 프롬프트를 어딘가로 보내나요?

아니요. 로컬 모델은 Mac에서 실행되고, LAN을 켜지 않는 한 API는 내 Mac 안에서만 요청을 받습니다. 프롬프트가 Mac 밖으로 나가는 것은 원격 엔드포인트에 연결했을 때뿐입니다.

MLX Harness로 MLX 토큰을 벌 수 있나요?

아니요. MLX Harness는 나를 위해 모델을 돌리고 공개된 네트워크 수치만 읽습니다. AI 작업으로 MLX 토큰을 버는 앱은 MLX Node입니다.