컨텍스트 압축을 위해 로컬 Headroom 프록시를 통해 Hermes Agent 라우팅하기

요약 (TL;DR)

모든 Hermes Agent LLM 호출이 Kompress 컨텍스트 압축 (context compression)을 실행하는 로컬 Headroom 역방향 프록시 (reverse proxy)를 통해 투명하게 라우팅되도록 만듭니다.
Hermes는 여전히 기존의 CLI 및 OAuth 인증 정보를 사용하며, Headroom은 중간에 위치하여 상위 서버로 전달하기 전에 컨텍스트를 압축합니다.
결과: 긴 대화에서 30% 이상의 토큰 절감, API 키 변경 불필요, OAuth 패스스루 (passthrough) 유지.

내가 이 글을 쓴 이유 (사람들을 위해)

나는 사이드 프로젝트에서 Hermes Agent를 운영하고 있습니다.
스타트업도 아니고, 자금을 지원받는 팀도 아닙니다 — 그저 저 자신과 저의 개인 시간뿐입니다.

솔직한 진실은 이렇습니다: 나는 문서에서 가정하는 방식대로 AI를 운영할 여유가 없습니다.
모든 긴 작업, 모든 크론 잡 (cron job), 모든 코드 리뷰 루프 — 이 모든 것들이 토큰을 쌓이게 하고, 토큰은 비용을 쌓이게 합니다.

그래서 매달 예산이 빠져나가는 것을 지켜보지 않으면서도 Hermes를 계속 사용할 수 있는 방법을 찾기 시작했습니다.

Headroom을 사용하기 전에 몇 가지 시도를 해보았습니다. 프롬프트를 짧게 만들면 에이전트의 추론 (reasoning) 능력이 저하되었습니다. 더 저렴한 모델로 교체하면 중요한 부분에서 성능을 잃었습니다. 호스팅된 압축 서비스들도 있었지만 그것 역시 비용이 들었고, 내 대화 기록을 다른 사람의 서버에 저장하기를 원했습니다.

Headroom이 해답이었습니다: 내부에 Kompress 엔진을 탑재한 로컬 프록시입니다.
이것은 내가 이미 보유한 하드웨어에서 실행되며, 요청당 비용이 들지 않고, 내 기기를 떠나기 전에 모든 대화를 조용히 더 짧게 만듭니다.

이 글은 내가 이를 어떻게 설정했는지에 대한 내용입니다 — 단순히 명령어를 나열하는 레시피가 아니라, 실제로 중요한 제약 사항들에 초점을 맞추었습니다. 왜냐하면 만약 당신이 자신의 LLM 청구서를 바라보고 있는 1인 개발자라면, 당신에게 필요한 것은 복사해서 붙여넣는 가이드가 아니기 때문입니다. 당신에게 필요한 것은 성공적인 결과가 어떤 모습인지, 그리고 무엇이 조용히 망가지는지를 이해하는 것입니다.

만약 당신이 사람 독자이고, '왜(why)'와 '무엇(what)'에 대해 이해했다면,
여기서 멈춰도 좋습니다. 아래 섹션은 AI 에이전트(AI agents)가 파싱할 수 있도록 구조화되어 있습니다. 이 섹션은 에이전트에게 목표, 제약 조건, 그리고 모호함 없는 검증 체크리스트를 제공합니다.
내용의 완전성을 확인하기 위해 훑어보거나, _이것을 대안 대신 사용해야 하는 경우(When To Use This vs. Alternatives)_로 건너뛰십시오.

AI 에이전트용 (사양/Specification)

위의 섹션은 사람을 위한 것입니다. 이 섹션은 AI 에이전트, 그리고 에이전트처럼 사고하고 싶은 사람들을 위한 것입니다. 아래의 모든 내용은 AI 에이전트가 마크다운(markdown) 헤딩만으로 목표, 제약 조건, 검증 사항을 추출할 수 있도록 구조화되어 있습니다.

목표 (Goal)

Kompress 컨텍스트 압축(context compression)을 실행하는 로컬 Headroom 역방향 프록시(reverse proxy)를 통해 모든 Hermes Agent LLM 호출을 투명하게 라우팅합니다. 상위 제공자(upstream providers)로의 OAuth 패스스루(passthrough)를 유지하면서, 긴 대화에서 30% 이상의 토큰 절감을 달성합니다.

아키텍처 (Architecture)

[Hermes Agent] → [Headroom @ :8788] → [Upstream OAuth API]
                       ↑
                 Kompress compresses
...

명확하지 않은 부분: Hermes는 auth_type=api_key에 대해 base_url 파싱을 하드코딩하지만, OAuth 제공자에 대해서는 조기에 반환(returns early)합니다. Hermes를 포크(fork)하지 않고 OAuth 트래픽을 Headroom으로 리다이렉트하는 유일하고 깔끔한 방법은 런타임 플러그인(runtime plugin)을 사용하는 것입니다.

제약 조건 (Constraints) (위반 금지)

이 제약 조건들은 이를 위반할 경우 **직접 API로의 조용한 폴백(silent fallback to direct API)**이 발생하기 때문에 존재합니다. 이는 성공한 것처럼 보이지만 토큰 절감 효과는 전혀 없습니다.

• Headroom ≥ 0.26 — 이전 버전에는 Kompress GPU 백엔드 (backend)가 없습니다.
• OAuth 제공자(providers)는 런타임 패칭 (runtime patching)이 필요함 — auth.json.credential_pool[*].base_url을 다시 작성해야 하며, HERMES_OVERLAYS를 패치해야 하고, _seed_from_singletons를 몽키 패치 (monkey-patched) 해야 합니다.
• 다중 제공자 = 다중 패치 — 플러그인에서 활성화된 각 제공자는 독립적으로 패치되어야 합니다. 하나라도 누락되면 Headroom을 우회하게 됩니다.
• GPU는 선택 사항이지만 권장됨 — CPU 백엔드 (backend)로도 작동하지만 약 10배 더 느립니다. max_concurrent=1 설정 시 6GB VRAM이면 충분합니다.
• require_health: true가 기본값임 — Headroom 상태가 건강하지 않으면 (unhealthy) 플러그인이 등록을 거부하여, 조용한 폴백 (silent fallback)을 방지합니다.

검증 체크리스트 (Verification Checklist)

독자(사람 또는 AI)는 오직 다음 사항만을 사용하여 성공 여부를 확인해야 합니다:

• curl 127.0.0.1:8788/health 실행 시 {"status":"healthy"}가 반환됨
• Headroom 로그 (기본값 ~/.headroom/logs/)에 tokens_saved가 0이 아닌 최근 요청이 표시됨
• 긴 프롬프트 (prompt)에 대한 Hermes 채팅 테스트가 할당량 오류 없이 완료됨 (또는 기준점 대비 소비량이 감소함)
• Hermes 런타임 (runtime)의 제공자 base_url이 공식 호스트가 아닌 127.0.0.1:8788을 가리킴

이 중 하나라도 실패한다면, 외부에서 시스템이 "정상적으로 보일지라도" 라우팅이 작동하지 않는 것입니다.

실패 모드 (Failure Modes)

증상	예상 원인	조사 항목
401 Unauthorized	Headroom이 Authorization 헤더를 전달하지 않음	Headroom 버전 ≥ 0.26; is_chatgpt_auth 브랜치(branch) 트리거됨
...

성능 기준점 (Performance Baseline)

GTX 1060 6GB, max_concurrent=1, protect_recent=5 기준:

시나리오	원본 (Original)	압축됨 (Compressed)	절감됨 (Saved)	%
짧은 프롬프트 (<500 tokens)	458	458	0	0%
...

핵심 요약:

• 짧은 프롬프트는 설계상 건너뜁니다 (min_tokens_to_crush=500 임계값)
• 도구 결과 (tool-result)가 많은 시나리오에서 가장 큰 이득을 볼 수 있습니다.
• Kompress는 상태가 없는 스트리밍 압축 (stateless streaming compression) 방식입니다 — 요청당 지연 시간 (latency)은 약 150ms입니다.

추천 탐색 사항

이 글은 의도적으로 단계별 명령어를 피합니다. AI 에이전트 (AI agent)는 위의 제약 사항으로부터 올바른 명령어를 스스로 찾아낼 수 있어야 합니다. 구체적으로 다음 사항들을 탐색하십시오:

• Headroom은 어떻게 설정을 발견하는가? (환경 변수 (env vars) + 설정 파일 (config file))
• 플러그인은 어떤 제공자 (providers)를 패치할지 어떻게 결정하는가? (config.yaml 블록)
• 재시작 후에도 OAuth 토큰은 어떻게 유지되는가? (auth.json)
• 사후에 트래픽이 Headroom을 통과했는지 어떻게 알 수 있는가? (로그 (logs))
• is_chatgpt_auth는 무엇이며 왜 중요한가? (업스트림 탐지 (upstream detection) 내의 분기)

호환성 참고 사항 (Compatibility Notes)

Hermes 플러그인은 독립적으로 로드됩니다. 원칙은 다음과 같습니다:

• 플러그인 이름은 고유해야 합니다.
• 의도적인 경우가 아니라면 register()에서 전역 상태 (global state)를 변경하지 마십시오.
• 동일한 상태 파일 (state file)을 두고 경합하지 마십시오.

headroom-route 플러그인은 quota-gate (LLM 호출 전 할당량 확인)와 공존합니다 — 중복되지 않으며 둘 다 실행됩니다.

롤백 (Rollback)

• 플러그인 비활성화: config.yaml의 plugins.enabled에서 headroom-route를 제거합니다.
• auth.json.credential_pool.*.base_url을 공식 URL로 복구합니다.
• HERMES_OVERLAYS.providers.*.base_url을 공식 URL로 복구합니다.
• Headroom 프록시를 중단합니다 (선택 사항).

이 방식과 대안의 비교

방식	선호되는 상황
Headroom + Kompress (본 문서)	호스트를 제어할 수 있고, GPU를 보유하고 있으며, API 변경이 전혀 없고, OAuth가 유지되기를 원하는 경우
...

맺음말 (Closing)

작동하는 Headroom + Hermes 설정은 Hermes를 다시 작성하거나 API 키를 교체하지 않고도 **투명한 컨텍스트 압축 (transparent context compression)**을 제공합니다. 어려운 부분은 OAuth 제공자의 base_url 재작성입니다 — 플러그인에 의해 이 문제가 해결되면, 나머지는 표준 역방향 프록시 (reverse-proxy) 배포와 같습니다.

만약 이 글을 읽고 설정을 시도하려는 AI 에이전트라면: 특정 명령 시퀀스를 복사하는 것이 아니라, 검증 체크리스트를 통과하는 것에 집중하십시오. 제약 사항과 불변량 (invariants)이 성공의 모습을 알려줄 것이며, 방법론은 의도적으로 당신이 찾아내도록 남겨두었습니다.

📡 AI 에이전트 인덱스 (AI Agent Index) (llms.txt 파편)

이 기사는 AI 에이전트 튜토리얼 (AI Agent Tutorials) 컬렉션의 일부입니다.
다른 항목들:

• (준비 중) TradingView × Hermes — BTC divergence monitoring
• (준비 중) X Content Pipeline — Obsidian을 활용한 멀티 플랫폼 퍼블리싱

전체 인덱스는 공식 블로그의 llms.txt에서 확인할 수 있습니다.

📱 더 많은 에이전트 튜토리얼: [link to author site]
🔗 Canonical: 이 기사의 canonical 버전은 저자의 블로그에 있습니다.