Locals로 맥에서 코딩 에이전트 여러 개 동시에 돌리기

Locals는 맥 안에서 AI 모델을 실행하고 다른 프로그램의 요청을 받아 답을 돌려주는 서버예요. 터미널 명령 하나로 맥 메모리에 맞는 모델을 켜고, 그 폴더에서 여는 코딩 에이전트를 이 모델에 연결해요. 모델과 대화하는 창이 아니라, 여러 에이전트가 같은 모델에 요청을 보내도 처리량⁵이 크게 떨어지지 않게 만든 것이 이 프로그램의 목적이에요.

에이전트는 채팅창에 한 줄 보내는 것과 다르게 움직여요. 파일을 읽고 명령을 실행하려고 도구를 호출하고, 그 호출이 정해진 형식으로 나와야 다음 단계가 이어져요. 대화가 길어질수록 프롬프트도 길어지고, 코딩 도우미는 보조 에이전트를 동시에 여러 개 띄워요. 보통의 맥용 추론 도구는 이 상황을 기준으로 만들어지지 않아서, 요청이 겹치면 한 건씩 처리할 때보다 오히려 느려져요.

애플 실리콘 M1 이상과 macOS 14 이상이 필요해요. 메모리가 16GB면 기본 모델이 잘 맞고, 8GB라면 더 작은 모델을 골라야 해요. 설치 스크립트를 실행하거나 uv로 PyPI에서 받아요.

새 터미널 창에서 프로젝트 폴더를 지정해 실행해요.

locals code ~/my-project

처음 실행하면 맥 메모리에 맞는 모델을 약 3GB 내려받아 백그라운드에서 켜고, 그 폴더에서 OpenCode를 열어요. 내려받기가 끝나면 에디터에서 파일 하나를 열고 짧은 수정을 요청해 첫 답이 나오는지 확인하세요. 모델 파일과 대화 기록은 맥 밖으로 나가지 않아요.

OpenCode는 locals setup으로 한 번 연결하면 모델 목록에서 Locals를 고를 수 있어요. VS Code 확장과 Zed, JetBrains처럼 OpenAI 호환 공급자를 지원하는 도구는 서버 주소를 직접 넣어요.

Ollama 형식만 지원하는 앱은 locals launch ollama로 연결해요. Open WebUI나 Raycast처럼 Ollama를 지원하는 앱은 주소를 따로 넣지 않아도 돼요.

서버 주소와 모델 이름은 locals launch editor를 실행하면 지금 켜져 있는 모델 기준으로 다시 출력돼요.

서버는 터미널 창을 닫아도 계속 돌아가요. locals status로 상태를 확인하고 locals stop으로 멈춰요. 같은 에이전트를 다른 서버와 번갈아 쓰려면 locals disconnect opencode로 설정을 되돌려요.

M2 Pro 19코어 GPU⁶와 16GB 메모리를 가진 맥북 프로에서 Qwen3.5-4B를 4비트로 돌린 측정이에요. 요청 하나만 보낼 때는 mlx-lm과 비슷하지만, 동시에 보내는 수가 늘어나면 차이가 벌어져요.

측정 조건은 맥북 프로 M2 Pro 19코어 GPU와 16GB, Qwen3.5-4B 4비트, MLX⁷ 0.32이고, 두 도구를 같은 프로세스 안에서 비교했어요. 같은 모델을 서버 API⁸로 호출해 클라이언트에서 세면 8개 동시에 244토큰으로 배수가 3.2배로 거의 같아요.

배수가 커지는 이유는 요청을 따로 계산하지 않기 때문이에요. 여러 에이전트의 요청을 한 묶음으로 GPU에 올려 한 번의 계산으로 처리하고, 그 묶음 크기에 맞춘 커널을 따로 만들어요. 도구 호출을 쓰는 단계에서도 GPU 위에서 형식 규칙을 강제해, 형식이 어긋나 다시 시도하는 일을 줄여요.

다른 서버와 같은 조건에서 비교한 값도 있어요. 1,000토큰 프롬프트를 8개 동시에 보냈을 때 첫 토큰까지 Locals 1.6초, llama.cpp 2.1초, Ollama 41.8초가 걸렸고, 초당 토큰은 110, 71, 34였어요.

요청 하나만 보내고 다시 쓸 것도 없으면 차이가 거의 없어요. 같은 M2 Pro에서 초당 64토큰으로 mlx-lm의 61토큰과 비슷해요. 답이 프롬프트를 다시 쓰는 작업이나 프롬프트 캐시가 맞을 때는 한 건이라도 빨라져요.

프롬프트를 읽는 일은 GPU 연산량에 묶여 있어요. 8,000토큰 프롬프트를 8개 동시에 보내면 초당 57토큰까지만 나와요. 시간의 대부분이 프롬프트를 읽는 데 들어가기 때문이에요.

4비트 affine 양자화⁹(그룹 64)에 맞춘 커널만 조정되어 있어요. mxfp4 같은 다른 형식은 mlx-lm과 같은 속도로 돌아요. M5의 신경 가속기는 MLX 자체 커널이 이미 쓰고 있어서 배수가 1.5배로 줄어요.

모델은 한 번에 하나만 돌아요. locals start --model lfm처럼 이름을 붙여 바꾸고, 지금 켜진 모델은 locals status에서 확인해요.

8개를 동시에 보낸 값이고, 기본값은 맥 메모리에 따라 달라져요. 12GB 미만이면 Qwen3.5-2B가 기본이 돼요.

메모리가 24GB 이상이면 Flint(총 40B, 토큰당 2.5B 활성)를 고를 수 있어요. 파일이 17.8GB이고, M4 Pro 24GB에서 요청 하나에 초당 115토큰, 8개 동시에 264토큰이 나왔어요. 24GB 맥은 GPU에 16GB만 넘겨주는 경우가 있어서 locals start가 늘리는 방법을 안내해요.

긴 작업에는 LOCALS_KV_BITS=8을 붙여 키와 값을 8비트로 유지해요. Flint 기준으로 요청 길이가 약 3만 5,800토큰에서 6만 7,584토큰으로 늘고, 쓰기 속도는 4~13% 느려져요.

저장소는 2026년 10월 12일에 공개됐고, 10월 25일 기준 PyPI 최신 버전은 0.2.1이에요. 명령 이름과 기본 모델이 빠르게 바뀌는 단계라, 설치한 버전에서 locals --help가 보여주는 옵션을 기준으로 따라가세요.

서버는 이 맥 안에서만 요청을 받고 외부로 열지 않아요. locals run으로 여러 에이전트를 돌릴 때는 에이전트마다 프로젝트 사본을 따로 주고, 테스트가 통과해야 원본 폴더가 바뀌어요.

같은 도구를 계속 호출하거나 같은 문장을 반복하는 경우를 감지해 멈추는 장치가 들어 있고, 메모리가 모자라 중단되는 상황을 막는 보호 장치도 있어요.

Apache 2.0으로 배포되고, 계산 방식은 arXiv 2610.09139 논문에 정리되어 있어요.