구독 프록시 — 공유 게이트웨이 | Easy Understand Hermes Agent

구독 프록시 — 공유 게이트웨이

헬스장 멤버십을 떠올려 보세요. 친구에게 내 실제 카드를 맡겨서 잃어버릴 위험을 감수하진 않잖아요? 대신 게스트 패스를 줘야죠. 구독 프록시(Subscription Proxy)는 바로 AI 구독을 위한 그런 게스트 패스 역할을 합니다.

해결하는 문제

OpenViking이나 Open WebUI 같은 많은 AI 앱들은 OpenAI API 형식을 사용합니다. 여기에 Nous Portal 구독 키를 직접 넣을 수도 있지만, 그건 위험하고(유출 가능성) 귀찮은 일입니다(키 만료 문제). 프록시는 아주 작은 로컬 서버를 실행해서 이 문제를 해결합니다. 앱에서 오는 모든 요청은 프록시를 거치고, 프록시가 자동으로 실제 인증 정보를 붙여 줍니다. 앱에는 아무 가짜 키나 넣어도 되고, 프록시가 뒤에서 실제 키로 바꿔치기하는 방식입니다.

API 서버와의 차이점

	API 서버	구독 프록시
제공하는 것	전체 Hermes 에이전트(도구, 메모리, 스킬)	순수 모델 추론
최적의 용도	“Hermes를 채팅 백엔드로 쓰기”	“Portal 구독을 다른 앱과 공유하기”
인증	`API_SERVER_KEY` 필요	아무 베어러 토큰이나 사용(프록시가 교체)
도구 호출	지원	미지원(순수 패스스루)

한 문장으로 요약하면: 에이전트가 필요하면 API 서버를, 모델만 필요하면 프록시를 쓰세요.

시작하는 세 단계

1. 한 번 로그인하기

hermes portal

브라우저가 열리면서 Nous Portal 인증 페이지가 표시됩니다. 로그인하면 Hermes가 리프레시 토큰을 ~/.hermes/auth.json에 저장합니다.

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:    아무거나 (예: "sk-unused")
Model:      Hermes-4-70B    # 또는 Hermes-4.3-36B, Hermes-4-405B

프록시는 입력한 키를 무시하고 실제 Portal 인증 정보로 교체하며, 만료 전에 자동으로 갱신해 줍니다.

상태 확인

hermes proxy status

ready 상태가 보이면 정상입니다. not logged in이 표시되면 hermes portal을 다시 실행하세요. credentials need attention이 표시되면 리프레시 토큰이 폐기된 것입니다(보통 Portal 웹사이트에서 로그아웃했을 때 발생). 그냥 다시 로그인하면 됩니다.

지원 엔드포인트

프록시는 업스트림이 실제로 지원하는 경로만 전달하며, 나머지는 명확한 메시지와 함께 404를 반환합니다:

경로	용도
`/v1/chat/completions`	채팅 완성(스트리밍 지원)
`/v1/completions`	레거시 텍스트 완성
`/v1/embeddings`	임베딩 벡터
`/v1/models`	사용 가능한 모델 목록

요약 및 실용 팁

구독 프록시는 안전한 어댑터입니다. 실제 키를 노출하지 않고도 다른 앱이 내 구독을 공유할 수 있게 해 주고, 만료 처리도 알아서 해 줍니다. 현재는 Nous Portal과 xAI(Grok)를 지원하며, 더 많은 제공자가 추가될 예정입니다.

실용 팁 하나: 여러 앱을 사용한다면 각 앱마다 다른 가짜 키를 부여하세요(예: sk-app1, sk-app2). 그러면 프록시 로그에서 어떤 앱이 어떤 요청을 보내는지 정확히 확인할 수 있어 디버깅이 훨씬 쉬워집니다. 또한 프록시는 기본적으로 127.0.0.1에서만 수신합니다. 이걸 0.0.0.0으로 바꾸지 마세요. 네트워크상의 다른 기기도 내 구독을 사용할 수 있게 됩니다.