maxOS란 무엇인가

maxOS는 로컬 모델에서 작동하는 ООО «Гарипофф» 사의 오픈소스 AI-native 플랫폼입니다. 이 플랫폼의 오픈소스 코어는 에이전트입니다. 에이전트는 프로젝트 내의 파일을 읽고 수정하며 터미널에서 명령어를 실행하지만, 이 모든 작업을 사용자의 로컬 머신에서 실행되는 언어 모델을 통해 수행합니다. 코드도, 요청도, 파일 내용도 외부 클라우드로 전송되지 않습니다.

코어는 Apache-2.0 라이선스로 공개되어 있습니다: github.com/LLC-Garipoff/maxos. 여기서부터 시작하겠습니다.

자동 완성이 아닌 에이전트

자동 완성은 다음 줄을 추천해 줄 뿐입니다. 반면 에이전트는 프로젝트를 파악하고, 여러 파일을 수정하며, 빌드와 테스트를 실행하고, 출력 결과를 확인한 뒤 다음 단계로 나아가는 등 작업 전체를 스스로 해결합니다.

maxOS의 내부 작동 방식은 단순한 루프 구조입니다. 모델에 작업과 사용 가능한 도구 설명이 전달됩니다. 모델은 텍스트로 응답하는 대신 도구를 호출하기로 결정합니다. 도구는 다음 네 가지입니다:

• read_file — 파일 읽기
• list_dir — 디렉터리 내용 확인
• write_file — 파일 생성 또는 덮어쓰기
• run_bash — 셸에서 명령어 실행 (빌드, 테스트, 실행)

maxOS는 작업 디렉터리에서 호출을 실행하고 그 결과를 모델에 반환합니다. 이 루프는 모델이 도구 호출을 중단하고 최종 결과를 응답할 때까지 반복됩니다. 모든 경로는 작업 폴더 내로 제한되며, 폴더 범위를 벗어나려는 호출은 거부됩니다. 파일을 저장하거나 명령어를 실행하기 전에 maxOS는 기본적으로 사용자에게 확인을 요청합니다.

이것이 작동 원리의 전부입니다. 숨겨진 클라우드 오케스트레이터는 전혀 없으며, 루프, 도구, 프롬프트는 런타임 의존성 없이 단 몇 백 줄의 코드로 구현되어 있습니다.

오직 로컬 모델만 사용

maxOS 자체는 신경망 연산을 직접 수행하지 않습니다. 대신 OpenAI 호환 API를 지원하는 로컬 런타임(예: Ollama 또는 llama.cpp)에 추론을 위임합니다. 사용자는 로컬 환경에서 다음과 같이 모델을 실행합니다:

ollama pull qwen2.5-coder:7b

그러면 maxOS는 http://localhost를 통해 모델과 통신합니다. 이 구조에는 클라우드 엔드포인트가 전혀 존재하지 않습니다. 사용자의 컴퓨터가 모델을 감당할 수만 있다면, 에이전트는 완전히 오프라인으로 작동합니다.

여기에는 별도의 레이어를 작성해야 했던 기술적인 디테일이 있습니다. 일부 로컬 모델은 OpenAI 호환 프로토콜의 규격에 맞게 구조화된 tool_calls 필드로 도구 호출을 깔끔하게 반환합니다. 하지만 qwen2.5-coder를 포함한 많은 모델은 응답 본문에 직접 JSON 텍스트 형식으로 호출을 작성합니다. maxOS는 두 가지 경우를 모두 인식합니다. 구조화된 필드가 없으면 텍스트에서 호출을 추출하며(<tool_call> 태그 형식 포함), 루프를 계속 진행합니다. 덕분에 이 프레임워크는 단 하나의 "정답" 모델에만 국한되지 않고 다양한 모델과 함께 작동할 수 있습니다.

코딩용 모델은 어떻게 연결되는가

maxOS는 프롬프트, 도구, 루프, 샌드박스, 확인 절차를 관리하는 오케스트레이터입니다. 실제 코드를 작성하고 수정하는 것은 연결된 모델의 몫입니다. 코딩 작업을 위해 런타임에는 도구 호출 기능이 있는 qwen2.5-coder, llama3.1 등과 같은 특화된 모델이 설치됩니다. 모델을 변경하는 것은 단 한 줄의 옵션 지정(--model)이나 환경 변수 설정만으로 가능하며, 에이전트의 나머지 부분은 그대로 유지됩니다.

이러한 역할 분담은 의도된 것입니다. 에이전트 루프는 연산 성능보다는 디스크 및 네트워크 I/O에 주로 의존하므로, 빠른 이터레이션과 쉬운 설치를 위해 TypeScript로 작성되었습니다. 반면 대규모 저장소 인덱싱 및 검색, Node 의존성 없는 단일 바이너리 제공 등 향후 추가될 고성능 시스템 모듈은 Rust 기반의 네이티브 코어로 이전할 계획입니다. I/O 병목이 발생하는 부분까지 무리하게 Rust로 작성하기보다는, 특정 목적에 맞는 도구를 적재적소에 활용한다는 논리입니다.

SpotMax와의 연관성

SpotMax는 "나를 돕는 모델은 외부 데이터 센터가 아닌 바로 내 곁에서 작동해야 한다"는 동일한 아이디어에서 출발한 개발 팀의 데스크톱 애플리케이션입니다. 이름 자체도 Spotlight + max의 합성어로, 운영체제에 밀접하게 통합되어 언제든 손쉽게 꺼내 쓸 수 있는 도구를 의미합니다.

원래는 자체 프레젠테이션과 피칭 등 영업 활동을 지원하기 위해 개발되었습니다. 대화를 실시간으로 경청하고 힌트를 제공하여 대화의 맥락과 흐름을 놓치지 않도록 돕는 비서 역할을 했습니다. 하지만 실제로는 구직자나 HR 담당자에게도 유용하다는 것이 밝혀지며 더 넓은 분야에서 활용되기 시작했습니다. 오늘날에는 해외 파트너와의 협상에 SpotMax를 사용하는 경우가 점점 늘고 있습니다. 기기에서 직접 음성을 인식하고 텍스트로 변환하여, 대화의 본질을 놓치지 않고 원활하게 소통할 수 있도록 지원합니다. SpotMax가 통화를 감지하고 음성을 텍스트로 변환하며 힌트를 제공하는 구체적인 원리는 별도 글에서 다루고 있습니다: SpotMax 작동 원리: 통화 중 전사, 번역 및 힌트 제공.

음성 인식과 화자 분리는 로컬에서 작동하며, 이 역시 기기 내에서 구동되는 모델들입니다. maxOS는 이러한 기술들의 공통적이고 개방된 기반이 됩니다. 누구나 코드를 읽고, 검증하고, 개선할 수 있도록 에이전트 레이어를 오픈소스로 공개한 것입니다.

왜 로컬인가

클라우드 기반의 코드 에이전트는 사용자의 소스 코드, 요청 사항, 그리고 종종 터미널 출력 결과까지 외부 서버로 전송합니다. 비공개 코드, 규제 대상 데이터, NDA(기밀유지협약) 준수 필요성, 혹은 단순히 불안정한 네트워크 환경 등 많은 업무 상황에서 이는 받아들이기 어렵습니다. maxOS는 오직 로컬 경로만을 사용하도록 설계되었습니다. 소스 코드가 공개되어 있으므로 이를 직접 검증해 볼 수 있습니다.

코드, 버그 리포트, 개선 제안은 GitHub에서 확인하실 수 있습니다: github.com/LLC-Garipoff/maxos. 또한, 로컬 모델의 구체적인 성능 향상 기여에 대해서는 보상 프로그램을 운영하고 있습니다.