본문으로 건너뛰기

구독 프록시

구독 프록시는 OpenViking, Karakeep, Open WebUI처럼 OpenAI 호환 Chat Completions를 사용하는 외부 앱이 Hermes에서 관리하는 제공자 구독을 LLM 엔드포인트로 사용할 수 있게 해 주는 로컬 HTTP 서버입니다. 프록시가 올바른 자격 증명을 첨부하고 자동으로 갱신하므로, 앱에는 고정 API 키를 넣을 필요가 없습니다.

이는 API 서버와 다릅니다:

API 서버구독 프록시
제공 대상사용자의 에이전트(전체 도구 세트, 메모리, 스킬)원시 모델 추론
사용 사례"Hermes를 채팅 백엔드로 사용""다른 앱에서 내 Portal 구독 사용"
인증API_SERVER_KEY임의의 bearer 토큰(프록시가 실제 토큰 첨부)
도구 호출예 — 에이전트가 도구를 실행합니다아니요 — 통과만 수행

백엔드로 에이전트가 필요하면 API 서버를 사용하세요. 구독을 통해 모델만 사용하고 싶다면 프록시를 사용하세요.

빠른 시작​

1. 제공자 계정에 로그인하세요 (한 번만)​

hermes login nous

이 명령은 Nous Portal OAuth 절차를 위해 브라우저를 엽니다. Hermes는 리프레시 토큰을 ~/.hermes/auth.json에 저장합니다. 다른 Hermes 제공자 로그인도 같은 위치에 저장됩니다.

2. 프록시 시작​

hermes proxy start
Starting Hermes proxy for Nous Portal
Listening on: http://127.0.0.1:8645/v1
Forwarding to: (resolved per-request from your subscription)
Use any bearer token in the client — the proxy attaches your real credential.

이 프로세스는 포그라운드에서 계속 실행해 두세요. 로그아웃 후에도 유지하려면 tmux, nohup, 또는 systemd 유닛을 사용합니다.

3. 앱이 프록시를 바라보도록 설정하세요​

OpenAI 호환 앱 설정은 보통 같은 세 가지 항목을 사용합니다.

Base URL:   http://127.0.0.1:8645/v1
API key: anything (e.g. "sk-unused")
Model: Hermes-4-70B # or Hermes-4.3-36B, Hermes-4-405B

프록시는 앱에서 들어오는 Authorization 헤더를 무시하고, 업스트림 요청에 실제 Portal 자격 증명을 붙입니다. bearer 토큰이 만료에 가까워지면 자동으로 갱신합니다.

사용 가능한 제공자​

hermes proxy providers

현재 포함된 제공자는 nous(Nous Portal)입니다. 다른 OAuth 제공자는 hermes_cli/proxy/adapters/에서 UpstreamAdapter 인터페이스를 구현해 추가할 수 있습니다.

상태 확인​

hermes proxy status
Hermes proxy upstream adapters

[nous ] Nous Portal — ready (bearer expires 2026-05-15T06:43:21Z)

not logged in이 보이면 hermes login nous를 실행하세요. credentials need attention이 보이면 리프레시 토큰이 취소된 상태입니다 (드물지만 Portal 웹 UI에서 로그아웃하면 발생할 수 있습니다). 이 경우 hermes login nous를 다시 실행하면 됩니다.

허용된 경로​

프록시는 업스트림이 실제로 제공하는 경로만 전달합니다. Nous의 경우 포털:

경로목적
/v1/chat/completions채팅 완성(스트리밍 + 비스트리밍)
/v1/completions레거시 텍스트 완성
/v1/embeddings임베딩
/v1/models모델 목록

다른 경로(/v1/images/generations, /v1/audio/speech 등)는 허용된 경로를 안내하는 명확한 오류와 함께 404를 반환합니다. 이렇게 하면 잘못 구성된 클라이언트가 이상한 요청을 업스트림으로 흘려보내는 것을 막을 수 있습니다.

OpenViking을 포털 사용으로 구성하기​

OpenViking는 VLM(비전/언어 모델, 메모리 추출에 사용)과 임베딩 모델을 위해 LLM 제공자가 필요한 컨텍스트 데이터베이스입니다. 프록시를 사용하면 vlm.api_base가 로컬 프록시를 바라보게 설정할 수 있습니다.

~/.openviking/ov.conf 편집:

{
"vlm": {
"provider": "openai",
"model": "Hermes-4-70B",
"api_base": "http://127.0.0.1:8645/v1",
"api_key": "unused-proxy-attaches-real-creds"
}
}

그런 다음 터미널 두 개에서 프록시와 openviking-server를 함께 실행하세요.

# Terminal 1
hermes proxy start

# Terminal 2
openviking-server

이제 OpenViking의 VLM 호출은 Portal 구독을 통해 흐릅니다. 임베딩 모델 쪽은 여전히 자체 제공자가 필요할 수 있습니다. Portal은 /v1/embeddings를 제공하지만, 사용 가능한 모델은 구독 등급에 따라 달라지므로 portal.nousresearch.com/models에서 확인하세요.

Karakeep 또는 북마크/요약 앱 설정​

Karakeep는 북마크 요약에 OpenAI 호환 API를 사용합니다. 설정에는 다음 값을 넣습니다.

# Karakeep .env
OPENAI_API_BASE_URL=http://127.0.0.1:8645/v1
OPENAI_API_KEY=any-non-empty-string
INFERENCE_TEXT_MODEL=Hermes-4-70B

같은 패턴은 Open WebUI, LobeChat, NextChat 등 다른 OpenAI 호환 클라이언트에서도 동작합니다.

LAN에서 노출​

기본적으로 프록시는 127.0.0.1(로컬호스트 전용)에 바인딩됩니다. 네트워크의 다른 기기에서도 사용하게 하려면 다음처럼 실행하세요.

hermes proxy start --host 0.0.0.0 --port 8645

⚠ 주의: 이제 네트워크 안의 누구나 Portal 구독을 사용할 수 있습니다. 프록시는 자체 인증이 없으며 모든 bearer 값을 허용합니다. 신뢰 네트워크 밖으로 노출해야 한다면 적절한 인증을 갖춘 방화벽, VPN, 또는 리버스 프록시 뒤에 두세요.

요청 제한​

Portal 등급의 RPM/TPM 제한은 프록시 전체에 적용됩니다. 프록시는 분산하거나 풀링하지 않습니다. 전체 구독 할당량을 가진 단일 bearer처럼 동작합니다. 사용량은 다음에서 모니터링하세요. portal.nousresearch.com.

아키텍처​

프록시는 의도적으로 최소화되어 있습니다. 요청마다 다음 순서로 동작합니다.

  1. 앱에서 POST /v1/chat/completions 받기
  2. 어댑터의 현재 자격 증명을 조회합니다(만료 예정이면 갱신)
  3. 요청 본문을 그대로 전달하되, Authorization: Bearer <minted-key>를 붙입니다.
  4. 응답을 변경하지 않고 다시 스트리밍합니다(SSE 유지).

변환도, 요청 본문 기록도, 에이전트 루프도 없습니다. 프록시는 자격 증명을 첨부하는 통과 장치입니다.

미래: 더 많은 OAuth 제공자​

어댑터 시스템은 플러그형입니다. HuggingFace, GitHub Copilot의 채팅 엔드포인트, OAuth 기반 Anthropic 같은 새 제공자를 추가하려면 hermes_cli/proxy/adapters/<provider>.py에서 UpstreamAdapter를 구현하고 adapters/__init__.py에 등록해야 합니다. 프로토콜 수준에서 OpenAI와 호환되지 않는 제공자(예: Anthropic Messages API)는 변환 계층이 필요하며, 이는 현재 형태의 범위를 벗어납니다.