LlamaStash 소개: 오버헤드가 없는 터미널 네이티브 llama.cpp 런처

원문은 deepu.tech에서 처음 게시되었습니다.

저의 완전 오프라인 AI 지원 Linux 개발 환경에 관한 최근 포스트에서, 저는 하단 부분에 작은 세부 사항 하나를 언급했습니다. 저는 별칭(alias)을 사용하여 로컬 모델을 실행합니다.

llamaServer

저는 그것을 "작은 스크립트입니다. GGUF 모델, 컨텍스트 크기(context size), 그리고 추론 모드(reasoning mode)를 선택할 수 있게 해줍니다. 마지막 선택을 기억하기 때문에, 대부분의 경우 그냥 실행하고 바로 시작하면 됩니다."라고 설명했습니다.

그 스크립트가 성장했습니다. 오늘 저는 오버헤드가 없는 llama.cpp를 위한 빠르고 크로스 플랫폼을 지원하는 터미널 네이티브(terminal-native) 런처의 첫 번째 공개 버전인 LlamaStash를 출시합니다.

이것은 TUI(Text User Interface)입니다. 또한 CLI(Command Line Interface)이기도 합니다. 또한 백그라운드 데몬(background daemon)이기도 합니다. 또한 OpenAI 호환 프록시(proxy)이기도 합니다. 하나의 작은 Rust 바이너리(약 5MB 다운로드), 세 가지 페르소나, 어디서나 동일한 기본 요소(primitives)를 제공합니다.

이것이 왜 존재하나요?

음: ADHD, 불면증, 그리고 아래의 이유 때문입니다 😆

로컬 LLM(Large Language Models)은 어정쩡한 간극 사이에 놓여 있습니다.

한쪽에는, 가공되지 않은 llama-server가 빠르고 정직합니다. 하지만 또한 지루합니다. 플래그(flags)를 외워야 합니다. 래퍼 스크립트(wrapper scripts)를 작성해야 합니다. 모델이 어떤 포트(port)에 있는지 기억해야 합니다. VRAM에 맞을 수도 있고 안 맞을 수도 있는 컨텍스트 크기를 추측해야 합니다. 시간이 지나면 아무도 읽을 수 없는 쉘 별칭(shell aliases)으로 가득 찬 ~/scripts/ 폴더를 갖게 됩니다.

다른 한쪽에는, Ollama와 LM Studio가 llama.cpp를 더 친숙한 쉘(shell)로 감싸고 있습니다. Ollama는 모델 저장, 형식, 설정에 대해 주관적인 방식(opinionated)을 가집니다. LM Studio는 GUI(Graphical User Interface) 중심이며 터미널 네이티브가 아닙니다. 두 가지 모두 가공되지 않은 llama-server와 비교했을 때 실제 성능 비용이 발생하며, 제가 실제로 작업하기 좋아하는 기본 요소(primitives)들을 숨겨버립니다.

저는 그 중간 지점에 있는 무언가를 원했습니다. 다음과 같은 런처(launcher) 말이죠:

• llama.cpp의 방식을 방해하지 않음 (포크(fork)나 패치된 복사본을 만들지 않으며, llama.cpp의 플래그(flags)에 대해 어떠한 의견도 강요하지 않음).
• 터미널에서 호출하기 빠르고, 스크립트(script)로 제어하기 빠름.
• TUI(Terminal User Interface)로서도 훌륭함. 저는 진심으로 터미널 인터페이스를 좋아하기 때문입니다.
• 에이전트(agent)와 인간을 동등하게 취급함. 사람이 TUI에서 할 수 있는 모든 것은 에이전트가 --json을 통해 수행할 수 있습니다.
• 하단에 데몬(daemon)이 있어 TUI를 종료해도 모델이 유지되며, 여러 클라이언트(client)가 동시에 동일한 모델에 접속할 수 있음.
• 루프백(loopback) 상에 OpenAI/Ollama 호환 프록시(proxy)를 노출하여, 기존의 모든 OpenAI 클라이언트(사용자의 에디터, 에이전트, 스크립트 등)가 모델별 설정 없이 바로 작동함.

LlamaStash가 바로 그것입니다.

왜 TUI인가?

저는 터미널 UI(TUI)를 사랑합니다 (KDash, JWT-UI, battleship-rs 참조).
저는 Rust로 작성된 Kubernetes 대시보드 TUI인 KDash를 만들었습니다. 그게 2020년이었죠. 당시의 Rust TUI 생태계는 tui-rs와 엄청난 인내심이 필요했습니다. 스레딩(threading)은 직접 구현해야 했고, 레이아웃(layout)은 산술 계산으로 처리해야 했으며, 상태 관리(state management)는 알아서 해결해야 하는 문제였습니다.

LlamaStash를 만드는 과정은 저를 다시 그 시절로 데려다 놓았지만, 지형은 변해 있었습니다. ratatui (tui-rs의 유지 관리되는 포크 버전)는 이제 정말 세련되고 다듬어진 프레임워크가 되었습니다. tokio는 비동기(async) 데몬 구현을 (좋은 의미로) 지루할 만큼 쉽게 만들어 줍니다. hyper는 단 몇 백 줄의 코드로 준수한 HTTP 서버를 제공합니다. crossterm은 교차 플랫폼(cross-platform) 터미널의 복잡한 문제를 처리해 줍니다. sysinfo는 호스트 메트릭(host metrics)을 다룹니다. 모든 부품이 갖춰져 있으며, 이제는 LLM(대규모 언어 모델)의 도움을 받아 모든 과정을 10배 더 빠르게 진행할 수 있습니다.

저는 여전히 당시 제가 썼던 글의 내용을 믿습니다. Rust는 어느 하나만 선택하지 않고도 안전성(Safety), 속도(Speed), 그리고 훌륭한 UX를 제공합니다. LlamaStash는 약 180개의 Rust 파일로 구성되어 있으며, 단 한 번의 프로덕션 패닉(Production panic)도 발생하지 않았습니다. 이는 제 커리어 초기에 배포했던 JavaScript나 Java 툴링에서는 결코 느낄 수 없었던 견고함을 제공합니다.

자, 향수는 이쯤 해두죠. 이 도구가 실제로 무엇을 하는지 보여드리겠습니다.

한 번의 명령으로 채팅 시작하기

llamastash init

이것은 첫 실행 마법사(Wizard)입니다. 이 마법사는 사용자의 하드웨어를 감지하고, 사용자의 OS/GPU 조합에 맞는 llama-server를 설치하며, 사용 가능한 VRAM을 확인합니다. 그 후 적합한 GGUF 모델을 추천하고, 이를 다운로드하며, 튜닝된 설정(Config)을 작성합니다. 또한 사용자의 AI 도구(OpenCode, Zed 등)를 위한 설정을 업데이트하고, 전체 파이프라인이 엔드투엔드(End-to-end)로 작동하는지 확인하기 위해 스모크 테스트(Smoke-launch)를 실행합니다.

제 Strix Halo 머신에서는 합리적인 기본값과 함께 자동화된 ROCm/HIP 경로를 의미합니다. MacBook에서는 Metal을 선택합니다. NVIDIA Linux 환경에서는 Vulkan을 선택합니다(CUDA는 곧 지원 예정). Windows 11 머신에서는 그에 맞는 win-cpu / win-cuda / win-vulkan llama.cpp 에셋을 선택합니다. GPU가 없는 오래된 노트북의 경우 CPU를 선택하고 조용히 더 작은 모델을 추천합니다.

이미 마음에 드는 llama.cpp 빌드가 있다면 --llama-server로 해당 경로를 지정하세요. 만약 ~/.cache/huggingface/, ~/.ollama/models, 또는 ~/.lmstudio/models에 이미 GGUF 파일이 있다면, LlamaStash가 이를 찾아냅니다. 또한 모델 경로를 실시간으로 감시하므로, 재시작 없이도 새로 다운로드한 모델이 바로 나타납니다.

이미 디스크에 코딩 모델이 있나요? 마법사를 건너뛰세요.

llamastash start qwen-coder --ctx 16384 --reasoning on

이것이 명령의 전부입니다. 또는 TUI(Text User Interface)를 사용하여 목록에서 선택할 수도 있습니다.

TUI

이것이 대부분의 사용자가 시간을 보내게 될 공간이 되기를 바랍니다.

알아두면 좋은 몇 가지 사항:

• 어디서나 가능한 Vim 스타일 내비게이션 (Vim-style navigation). hjkl, Ctrl+F/Ctrl+B, 0/$, 탭 전환을 위한 gt/gT, 필터링을 위한 /, 도움말을 위한 ?를 지원합니다. 키 바인딩 (Keybindings)은 정체불명의 모달 방식이 아니라, 실제적이고 문서화되어 있으며 재설정(rebindable)이 가능합니다.
• 우측 패널은 스모크 테스트 (smoke test) 역할을 합니다. 로그 (Logs), 채팅 (Chat), 임베딩 (Embed), 리랭크 (Rerank) 탭은 외부 클라이언트가 사용하는 것과 동일한 OpenAI 호환 엔드포인트 (OpenAI-compatible endpoint)를 호출합니다. 따라서 TUI에서 무언가가 작동한다면, 여러분의 에디터, 에이전트 (agent), 스크립트 (script)에서도 동일하게 작동합니다.
• TUI 내 HuggingFace 브라우저. 검색, 정렬, 페이지 매김 (paginate), 파일별 하드웨어 적합성 확인, 취소 가능한 다운로드를 지원합니다. 웹사이트로 탭을 전환할 필요가 없습니다.
• 5가지 테마 및 커스텀 지원. 당연하게도 Catppuccin Macchiato가 기본 테마입니다.
• 적응형 레이아웃 (Adaptive layout). 60셀 (cells) 크기부터 작동합니다. 아주 작은 터미널인가요? 리스트 열과 힌트 칩 (hint chips)이 우선순위 순으로 사라져 모델 이름의 가독성을 유지합니다.
• 접근성 (Accessibility). 상태는 색상과 글리프 (glyph)로 이중 인코딩되어 있어, 단색 (mono) 터미널에서도 읽을 수 있습니다.

마우스는 기본적으로 꺼져 있습니다 (스크롤 제외). 따라서 터미널 본연의 클릭 앤 드래그 (click-and-drag) 텍스트 선택 기능을 유지할 수 있습니다. 마우스 사용을 원한다면 --mouse-focus 옵션을 사용하거나 config.yaml에 한 줄을 추가하여 선택할 수 있습니다.

CLI

TUI가 할 수 있는 모든 것을 CLI에서도 할 수 있습니다. CLI는 나중에 덧붙여진 기능이 아니라, 일급 시민 (first-class surface)으로서 설계되었습니다.

# 모델 목록을 사람이 읽기 편한 형태로 출력
llamastash list

...

스크립팅 (scripting) 시 중요한 몇 가지 사항:

• --json은 안정적인 에이전트 계약 (agent contract)입니다. 사람이 읽기 편한 출력 형식을 변경하더라도, --json을 사용하는 스크립트는 계속 작동합니다.
• 실패 클래스별 종료 코드 (exit codes per failure class)가 문서화되어 있습니다. 메시지 텍스트가 아닌 숫자를 기준으로 분기 처리하세요.
• TTY 출력은 색상이 지정되고 패딩(padding)이 적용됩니다. 파이프(Piped) 출력은 바이트 안정적인 TSV 형식이므로, awk 및 column 파이프라인이 그대로 작동합니다.

또한, 코딩 에이전트가 CLI를 적절하게 사용하도록 교육하는 Agent Skills 번들이 저장소에 포함되어 있습니다. 이를 OpenCode, OpenClaw 또는 Claude Code의 스킬 디렉토리에 넣으면, 에이전트는 --json을 선호하고, 종료 코드(exit codes)를 기준으로 분기하며, OpenAI 호환 클라이언트를 설정하기 전에 status --json을 읽는 법을 학습합니다.

프록시 (The proxy)

모델이 실행되면, LlamaStash는 기본적으로 http://127.0.0.1:11435/v1에 OpenAI 호환 엔드포인트 (endpoint)를 노출합니다.

curl -s http://127.0.0.1:11435/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model": "qwen-coder", "messages": [{"role": "user", "content": "hi"}]}'

OpenCode, Pi, Cline, OpenAI SDK, llm-cli 등 OpenAI 규격을 따르는 모든 도구가 그대로 작동합니다.

알아두면 좋은 몇 가지 세부 사항입니다:

• 첫 요청 시 자동 시작 (Auto-start on first request). 요청된 모델이 아직 실행 중이 아니면, 프록시(proxy)가 모델을 시작하고 요청을 처리합니다.
• 감사 헤더를 통한 폴백 (Fallback with audit headers). 어떤 이유로든 실행에 실패하면, 프록시는 준비된(Ready) 피어 모델로 폴백(fallback)하며, 클라이언트가 대응할 수 있도록 x-llamastash-served-by 및 x-llamastash-fallback-reason 헤더를 추가합니다. 만약 강제 실패(hard failure)를 선호한다면 fallback_enabled 설정 옵션을 통해 이 동작을 끌 수 있습니다.
• Ollama 탐색 범위 (Ollama discovery surface). GET /api/tags, /api/version, /api/ps, POST /api/show. OLLAMA_HOST를 통해 Ollama를 자동 감지하는 도구들은 LlamaStash를 인식하며, 실제 추론(inference)을 위해 OpenAI 호환 엔드포인트로 넘어갑니다.
• 선택적 Ollama 드롭인 모드 (Opt-in Ollama drop-in mode). --ollama-compat (또는 LLAMASTASH_OLLAMA_COMPAT=1)을 사용하면 프록시가 11434 포트를 점유하고, 바이트 단위로 일치하는 "Ollama is running" 핸드셰이크(handshake)에 응답합니다. 공식 ollama CLI가 이와 통신하며, 대부분의 Ollama-Go 기반 클라이언트도 이와 통신합니다. 직접 작성하지 않은 워크플로우에서 Ollama를 교체하고 싶을 때 유용합니다.
• 루프백 전용, 인증 없음 (Loopback only, no auth). 단일 사용자 로컬 위협 모델(threat model)을 따릅니다. 프록시는 LAN 바인딩을 거부합니다. LAN 노출, 인증 및 TLS 기능은 로드맵에 포함되어 있으며, 0.0.2 버전에는 포함되어 있지 않습니다.

제로 오버헤드(Zero overhead)는 말 그대로 제로 오버헤드를 의미합니다

벤치마크 세부 사항은 별도의 포스트와 docs/benchmarks.md에 나와 있지만, 여기서는 한 줄 요약 버전으로 제공합니다.

LlamaStash는 수정되지 않은 업스트림(upstream) llama-server를 생성합니다. 따라서 래퍼(wrapper)가 llama-server를 직접 실행하는 것과 비교했을 때 측정 가능한 오버헤드를 추가해서는 안 됩니다. 저희는 이를 측정했습니다. 추가되지 않았습니다. LlamaStash는 AMD APU, Apple Silicon, NVIDIA 전반에 걸쳐 모든 셀에서 로우(raw) llama-server와 ≤1% 이내의 차이로 일치합니다. 프록시 홉(proxy hop)으로 인한 중간값 기준 TTFT(Time To First Token)는 +0.45 ms이며, 디코딩(decode)에는 영향이 전혀 없습니다.

Ollama와의 비교는 더 흥미롭지만, 그 부분은 벤치마크 포스트에서 다루도록 하겠습니다. 방법론은 공개되어 있습니다. 테스트 하네스(harness)는 재현 가능합니다. make bench-end-to-end를 실행하여 직접 확인해 보세요.

아키텍처를 한 단락으로 요약하면