Honcho 셀프 호스팅 설치 기록

1✓

1. 개요 section 01

Plastic Labs의 Honcho(AI 에이전트용 메모리 인프라)를 로컬 Docker 환경에 자체 호스팅하고, Hermes Agent와 연동했다. LLM은 OpenRouter 경유 deepseek/deepseek-v4-flash, 임베딩은 OpenAI 직접 호출 text-embedding-3-small을 사용한다.

최종 아키텍처

snippet

┌─────────────────────────────────────────────────────┐
│  Mac mini M4  (172.30.1.11)                         │
│                                                     │
│  Hermes Agent ──── ~/.hermes/honcho.json            │
│       │                                             │
│       └─► http://localhost:8000 (Honcho API)        │
│                  │                                  │
│      ┌───────────┴────────────┐                     │
│      │   Docker Compose       │                     │
│      ├────────────────────────┤                     │
│      │  api         :8000     │  ◄── 0.0.0.0 바인딩 │
│      │  deriver     (worker)  │                     │
│      │  database    :5432     │  PostgreSQL+pgvector│
│      │  redis       :6379     │                     │
│      └────────────────────────┘                     │
│                  │                                  │
│                  ├─► OpenRouter (deepseek-v4-flash) │
│                  └─► OpenAI (embedding-3-small)     │
└─────────────────────────────────────────────────────┘

2✓

2. 사전 환경 section 02

구성 요소	상태	비고
Docker Desktop	29.1.2	이미 설치됨, 데몬은 수동 시작 필요
Homebrew	5.1.13
Hermes Agent	0.14.0 (2026.5.16)	Python 3.14 환경
Git	정상
RAM	16GB	M4 칩, 충분
Honcho repo	없음	새로 클론

3✓

3. 설치 단계 section 03

3.1 Docker 데몬 시작

bash

open -a Docker
# 데몬 준비까지 대기 (until 루프)
until docker info --format '{{.ServerVersion}}' >/dev/null 2>&1; do sleep 2; done

3.2 Honcho 저장소 클론

가이드에서 언급된 서드파티 자동 스크립트 elkimek/honcho-self-hosted 대신 공식 저장소 직접 클론을 선택. 안정성 + 디버깅 용이.

bash

git clone https://github.com/plastic-labs/honcho.git ~/honcho
cd ~/honcho
cp .env.template .env
cp docker-compose.yml.example docker-compose.yml

3.3 외부 접속 허용 (docker-compose.yml)

같은 와이파이의 다른 기기에서 API에 접근할 수 있도록 API 포트만 외부 바인딩으로 변경. database/redis는 보안상 127.0.0.1로 유지.

yaml

# docker-compose.yml — api 서비스
ports:
  - "0.0.0.0:8000:8000"  # 127.0.0.1 → 0.0.0.0

3.4 환경 변수 설정 (~/honcho/.env)

LLM (OpenRouter 경유 deepseek-v4-flash)

LLM_OPENAI_API_KEY는 변수명만 OpenAI일 뿐, OpenAI 호환 엔드포인트면 어떤 키든 사용 가능. OpenRouter 키를 여기에 넣고 각 모듈의 BASE_URL을 OpenRouter로 override.

bash

LLM_OPENAI_API_KEY=sk-or-v1-<OpenRouter key>

# Deriver
DERIVER_MODEL_CONFIG__TRANSPORT=openai
DERIVER_MODEL_CONFIG__MODEL=deepseek/deepseek-v4-flash
DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1

# Summary
SUMMARY_MODEL_CONFIG__TRANSPORT=openai
SUMMARY_MODEL_CONFIG__MODEL=deepseek/deepseek-v4-flash
SUMMARY_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1

# Dialectic (5개 reasoning level 전부)
DIALECTIC_LEVELS__minimal__MODEL_CONFIG__TRANSPORT=openai
DIALECTIC_LEVELS__minimal__MODEL_CONFIG__MODEL=deepseek/deepseek-v4-flash
DIALECTIC_LEVELS__minimal__MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1
DIALECTIC_LEVELS__low__MODEL_CONFIG__TRANSPORT=openai
DIALECTIC_LEVELS__low__MODEL_CONFIG__MODEL=deepseek/deepseek-v4-flash
DIALECTIC_LEVELS__low__MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1
# ...medium, high, max 동일 패턴

# Dream
DREAM_DEDUCTION_MODEL_CONFIG__TRANSPORT=openai
DREAM_DEDUCTION_MODEL_CONFIG__MODEL=deepseek/deepseek-v4-flash
DREAM_DEDUCTION_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1
DREAM_INDUCTION_MODEL_CONFIG__TRANSPORT=openai
DREAM_INDUCTION_MODEL_CONFIG__MODEL=deepseek/deepseek-v4-flash
DREAM_INDUCTION_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1

임베딩 (OpenAI 직접)

OpenRouter에 임베딩 모델이 없는 것을 확인(API 카탈로그 356개 중 0개). OpenAI를 별도 키로 사용.

bash

EMBED_MESSAGES=true
EMBEDDING_VECTOR_DIMENSIONS=1536
EMBEDDING_MODEL_CONFIG__TRANSPORT=openai
EMBEDDING_MODEL_CONFIG__MODEL=text-embedding-3-small
EMBEDDING_MODEL_CONFIG__OVERRIDES__BASE_URL=https://api.openai.com/v1
EMBEDDING_MODEL_CONFIG__OVERRIDES__API_KEY_ENV=OPENAI_EMBEDDING_API_KEY
OPENAI_EMBEDDING_API_KEY=sk-proj-<OpenAI key>

핵심: API_KEY_ENV는 키 이름이 아니라 읽어올 환경변수 이름을 가리키는 문자열. 이 패턴 덕분에 LLM용 키(OpenRouter)와 임베딩용 키(OpenAI)를 완전히 분리할 수 있다.

3.5 Docker Compose 빌드 및 시작

bash

cd ~/honcho
docker compose up -d --build

초기 빌드 시간: 약 1분(M4). 4개 컨테이너 모두 healthy 확인:

snippet

honcho-api-1        0.0.0.0:8000        healthy
honcho-database-1   127.0.0.1:5432      healthy   (PostgreSQL 15 + pgvector)
honcho-deriver-1    (internal)          running
honcho-redis-1      127.0.0.1:6379      healthy

3.6 Hermes 통합

honcho-ai SDK 설치

Hermes Python 환경(/opt/homebrew/Cellar/hermes-agent/.../python3.14)에 SDK가 없어 수동 설치.

bash

/opt/homebrew/Cellar/hermes-agent/2026.5.16_1/libexec/bin/python3 \
  -m pip install 'honcho-ai>=2.0.1'
# → honcho-ai-2.1.2 설치됨

Hermes Honcho 플러그인 설정 (`~/.hermes/honcho.json`)

Hermes의 hermes memory setup 명령은 대화형이라 수동으로 JSON 작성. 플러그인 코드(plugins/memory/honcho/cli.py)를 읽고 필요한 키 구조를 파악.

json

{
  "baseUrl": "http://localhost:8000",
  "hosts": {
    "hermes": {
      "enabled": true,
      "saveMessages": true,
      "peerName": "ninestone",
      "aiPeer": "hermes",
      "workspace": "hermes",
      "observationMode": "directional",
      "writeFrequency": "async",
      "recallMode": "hybrid",
      "dialecticCadence": 2,
      "dialecticReasoningLevel": "low",
      "sessionStrategy": "per-session"
    }
  }
}

HOST = "hermes" (호스트 키), 로컬 자체 호스팅이면 apiKey 생략 가능 (_resolve_api_key 로직이 baseUrl 보고 자동으로 "local" 반환).

Hermes 글로벌 설정에서 provider 활성화

bash

hermes config set memory.provider honcho
# → ~/.hermes/config.yaml의 memory.provider 변경

연결 검증

bash

/opt/homebrew/Cellar/hermes-agent/2026.5.16_1/libexec/bin/python3 -c "
from plugins.memory.honcho.client import HonchoClientConfig, get_honcho_client, reset_honcho_client
reset_honcho_client()
hcfg = HonchoClientConfig.from_global_config(host='hermes')
get_honcho_client(hcfg)
print('OK:', hcfg.workspace_id, hcfg.peer_name, hcfg.ai_peer)
"
# → OK: hermes ninestone hermes

hermes memory status 출력에서 Provider: honcho 및 Status: available ✓ 확인.

4✓

4. 검증 결과 section 04

4.1 API 헬스

bash

$ curl http://localhost:8000/health
{"status":"ok"}

4.2 워크스페이스 생성

bash

$ curl -X POST http://localhost:8000/v3/workspaces \
       -H "Content-Type: application/json" \
       -d '{"name":"hermes"}'
{"id":"hermes","metadata":{},"configuration":{},"created_at":"2026-05-27T09:05:01..."}
# HTTP 201 ✓

4.3 임베딩 동작 확인

테스트 메시지 → DB 검사:

sql

SELECT message_id, LEFT(content, 30), sync_state, embedding IS NOT NULL
FROM message_embeddings
ORDER BY created_at DESC LIMIT 1;

-- 결과:
-- message_id   | gMavsXolzKabZECZIQxl-
-- content      | 두번째 임베딩 테스트 - 저는 인생OS ...
-- sync_state   | synced       ← 임베딩 완료
-- has_embed    | t            ← 벡터 저장됨 (1536차원)

OpenAI 임베딩 호출 1회 = 9 토큰 = $0.00000018. 사실상 무료.

5✓

5. 작업 중 발견한 문제와 해결 section 05

5.1 첫 OpenAI 키 — quota 부족

처음 받은 OpenAI 키는 유효했으나 결제수단 미등록 상태.

json

{"error": {
  "type": "insufficient_quota",
  "message": "You exceeded your current quota..."
}}

→ 결제 설정된 두 번째 OpenAI 키로 교체. 첫 키를 그대로 .env에 넣었다면 deriver가 매 메시지마다 에러로 도배되었을 것. 적용 전 curl 테스트가 중요.

5.2 가이드의 모델명 `deepseek-v4`는 존재하지 않음

OpenRouter /api/v1/models 조회 결과 실제 가용 변형:

deepseek/deepseek-v4-flash (paid)
deepseek/deepseek-v4-flash:free
deepseek/deepseek-v4-pro

flash로 자동 치환 (도구 호출 지원 확인, 1M 컨텍스트). 사용자 가이드 문서에 적힌 모델명을 맹신하면 안 된다는 교훈.

5.3 `docker compose restart`는 env_file을 다시 읽지 않는다 ⚠️

가장 큰 함정. .env를 수정 후 docker compose restart를 했더니 컨테이너의 EMBED_MESSAGES가 여전히 false였다. 컨테이너 내부 확인:

bash

$ docker compose exec api env | grep EMBED
EMBED_MESSAGES=false  # ← .env에는 true인데?!

원인: restart는 동일 컨테이너를 재시작만 한다. env_file은 컨테이너 생성 시점에 읽어 컨테이너 환경에 박힌다.

해결:

bash

docker compose up -d --force-recreate api deriver
# → 컨테이너 재생성, env_file 재로드

이 함정을 메모리에도 저장. 향후 비슷한 작업에서 반복 실수 방지.

5.4 Anthropic 키 혼동

사용자가 임베딩용으로 Anthropic API 키를 보냈는데, Anthropic은 임베딩 미제공. Claude는 채팅/완성 전용이며, Anthropic 공식 추천 임베딩은 Voyage AI 외부 사용이다.

6✓

6. 운영 명령어 section 06

상태 확인

bash

cd ~/honcho && docker compose ps
# 모든 컨테이너 healthy 상태여야 함

curl http://localhost:8000/health

로그

bash

cd ~/honcho && docker compose logs -f api deriver
cd ~/honcho && docker compose logs --tail 50 deriver
cd ~/honcho && docker compose logs deriver | grep -i error

재시작

bash

# 코드/이미지 변경 없을 때
cd ~/honcho && docker compose restart

# .env 수정한 경우 (★ 핵심)
cd ~/honcho && docker compose up -d --force-recreate api deriver

# 완전 재빌드 (의존성 변경 등)
cd ~/honcho && docker compose down && docker compose up -d --build

중지 / 재가동

bash

cd ~/honcho && docker compose down       # 데이터 유지하고 중지
cd ~/honcho && docker compose down -v    # 볼륨까지 삭제 (DB 초기화)
cd ~/honcho && docker compose up -d      # 다시 시작

Honcho 업데이트

bash

cd ~/honcho && git pull && docker compose up -d --build

데이터베이스 직접 조회

bash

cd ~/honcho && docker compose exec database psql -U postgres postgres

# 메시지 수, 임베딩 수
SELECT COUNT(*) FROM messages;
SELECT COUNT(*) FROM message_embeddings WHERE sync_state='synced';

# 최근 메시지의 임베딩 상태
SELECT message_id, LEFT(content,40), sync_state
FROM message_embeddings ORDER BY created_at DESC LIMIT 5;

백업 / 복원

bash

# 백업
cd ~/honcho && docker compose exec database \
  pg_dump -U postgres postgres > ~/honcho-backup-$(date +%Y%m%d).sql

# 복원
cat ~/honcho-backup-YYYYMMDD.sql | \
  docker compose exec -T database psql -U postgres postgres

Mac 잠자기 방지 (장시간 자리비울 때)

bash

caffeinate -d &       # 디스플레이까지 활성 유지
caffeinate -i &       # CPU만 활성 유지
# 종료: 위 명령으로 받은 PID에 kill, 혹은 터미널 닫기

또는 시스템 설정 → 배터리/에너지 절약 → "디스플레이 끄기" 시간 늘리고 "절전 모드 비활성화".

7✓

7. 비용 추정 section 07

LLM (OpenRouter, deepseek-v4-flash)

Flash 모델은 입력 $0.10/M, 출력 $0.40/M 토큰 (참고치, 변동 있음)
일반 사용량(메시지 100개/일, 평균 toolchain 5회 호출, 1500 토큰)이면

→ 약 $0.05~0.20/일 → 월 $1.5~6

임베딩 (OpenAI, text-embedding-3-small)

$0.02/M 토큰
메시지 1000개/일 × 평균 200 토큰 = 200K 토큰/일

→ $0.004/일 → 월 $0.12

인프라

전기세: Mac mini M4 24시간 가동 시 약 월 5,000~8,000원
인터넷, 하드웨어 감가상각 별도

합산

월 $2~10 (약 3,000~15,000원) 수준. Honcho 클라우드 구독이나 별도 VPS 운영 대비 압도적으로 저렴.

8✓

8. 알려진 제약 / 주의사항 section 08

Mac mini가 꺼지면 메모리 끊김 — 다른 기기(스마트폰, 노트북)에서 동일 메모리 접근이 필요하면 24/7 가동 필요. 잠자기 모드도 회피해야 함.

OpenRouter는 임베딩 미제공 — LLM과 임베딩이 분리된 이중 키 구조가 필수. 만약 완전 단일 제공자를 원하면 OpenAI 직접 사용으로 통일 가능.

reconciler는 5분 주기 — 메시지 임베딩이 즉시 되지 않고 다음 reconciler 사이클까지 pending 상태. 의미 검색에 즉시 반영 안 되므로 실시간성이 중요하면 RECONCILIATION_INTERVAL_SECONDS 단축 고려.

deepseek-v4-flash의 한국어 추론 품질 — 영어 대비 약간 약함. 메모리 추출(deriver)의 한국어 conclusion 품질이 부족하면 Claude Sonnet이나 GPT-4o-mini로 교체 검토.

임베딩 활성화 전 메시지 — EMBED_MESSAGES=false 시기에 들어온 메시지는 임베딩 row가 아예 생성되지 않음. 이전 메시지를 검색 대상에 포함하려면 별도 백필 스크립트 필요.

Docker Desktop 자원 — M4 16GB에서 Honcho 4개 컨테이너는 약 1.5~2GB RAM 사용. 다른 무거운 작업(VS Code, Chrome 탭 많이)과 동시 사용 시 스왑 발생 가능.

9✓

9. 키 / 시크릿 위치 section 09

⚠️ 이 파일에는 키를 적지 않음. 실제 위치:

키	파일	변수명
OpenRouter	`~/honcho/.env`	`LLM_OPENAI_API_KEY`
OpenAI (임베딩)	`~/honcho/.env`	`OPENAI_EMBEDDING_API_KEY`

Git에 커밋하지 말 것. ~/honcho/.gitignore에 .env가 포함되어 있는지 확인:

bash

grep -E "^\.env$" ~/honcho/.gitignore

10✓

10. 참고 자료 section 10

공식 저장소: https://github.com/plastic-labs/honcho
셀프 호스팅 문서: https://honcho.dev/docs/v3/contributing/self-hosting
OpenRouter 모델 카탈로그: https://openrouter.ai/models
OpenAI 임베딩 가격: https://openai.com/api/pricing/
Hermes Agent: https://github.com/NousResearch/hermes-agent (참고)
본 작업 메모리: ~/.claude/projects/-Users-user/memory/honcho-self-hosted-setup.md

11✓

11. 다음 단계 (선택) section 11

LAN 외부 기기에서 접속 테스트 (스마트폰 등) → http://172.30.1.11:8000caffeinate -d를 launchd로 등록해 자동화Hermes 채팅에서 honcho_search / honcho_profile 도구 호출 검증OpenAI/OpenRouter 사용량 알림 설정 (예산 초과 방지)자동 백업 cron (예: 매일 03:00 pg_dump 후 외장 드라이브 복사)HTTPS 종단점 필요 시 Caddy/nginx 리버스 프록시모니터링 활성화 — docker-compose.yml의 Prometheus/Grafana 섹션 주석 해제

12✓

12. Polaris shared memory 동기화 작업 로그 section 12

기록 시각: 2026-05-28 02:57:21 KST
목적: 맥북프로의 폴라와 맥미니의 Hermes/OpenClaw 폴라가 Honcho를 통해 같은 장기 메모리를 공유하도록 1차 구성

확인한 현재 상태

맥미니 호스트명: macmini.local
맥미니 LAN 주소: 172.30.1.11
Honcho API는 LAN 주소에서도 응답 가능:
http://localhost:8000/health
http://172.30.1.11:8000/health
Honcho compose 프로젝트 폴더:
/Users/user/honcho
실행 컨테이너:
honcho-api-1
honcho-deriver-1
honcho-redis-1
honcho-database-1
API 포트:
0.0.0.0:8000->8000/tcp

확인한 폴라 설정

Hermes 폴라 personality는 /Users/user/.hermes/config.yaml에 있음.
Hermes memory provider는 이미 honcho로 설정되어 있음.
Hermes Honcho 설정 파일:
/Users/user/.hermes/honcho.json
OpenClaw는 현재 파일 기반/session-memory 구조를 사용 중.
OpenClaw 장기 기억 및 운영 지침:
/Users/user/.openclaw/workspace/MEMORY.md
/Users/user/.openclaw/workspace/AGENTS.md
OpenClaw 폴라 관련 자동화:
/Users/user/.openclaw/cron/jobs.json
Check Pola notices every 30 minutes

맥북프로 탐지 결과

같은 네트워크에서 SSH 서비스 광고 발견:
mDNS 이름: MacBook Pro (6)
접속 호스트: MacBook-Pro-7.local.:22
SSH 직접 접속 시도 결과:
Permission denied (publickey,password,keyboard-interactive)
결론:
맥북프로는 네트워크에서 보이지만, 현재 맥미니에서 무인 SSH 접속 권한은 없음.
맥북프로 쪽 설정 적용은 사용자가 직접 실행하거나 SSH 키/접속 권한을 별도로 열어야 함.

작업 중 발생한 상태 변화

공유 workspace 생성을 시도하던 순간 localhost:8000 연결이 끊김.
원인 확인:
Docker daemon이 일시적으로 내려가 있었음.
조치:
Docker Desktop 재시작.
/Users/user/honcho에서 docker compose up -d 실행.
Honcho 4개 컨테이너 healthy 복구 확인.
복구 후 확인:
http://localhost:8000/health → {"status":"ok"}
http://172.30.1.11:8000/health → {"status":"ok"}

아직 완료하지 않은 다음 작업

polaris-shared workspace 생성.
peer 생성:
user
pola-macbookpro
pola-hermes-macmini
pola-openclaw-macmini
bootstrap session/message 기록.
맥북프로에서 실행할 Honcho 연결 설정 또는 동기화 스크립트 준비.
Hermes/OpenClaw 폴라가 이 shared workspace를 조회/기록하도록 안전한 방식 결정.

설계 메모

기존 Hermes workspace hermes를 바로 바꾸지 않고, 폴라 전용 polaris-shared workspace를 먼저 만드는 방향이 안전함.
이유:
기존 Hermes 메모리와 충돌하지 않음.
OpenClaw, Hermes, 맥북프로 폴라를 peer 단위로 분리 가능.
문제가 생겨도 polaris-shared만 롤백하면 됨.

원본 메타데이터

최종 아키텍처

3.1 Docker 데몬 시작

3.2 Honcho 저장소 클론

3.3 외부 접속 허용 (docker-compose.yml)

3.4 환경 변수 설정 (~/honcho/.env)

LLM (OpenRouter 경유 deepseek-v4-flash)

임베딩 (OpenAI 직접)

3.5 Docker Compose 빌드 및 시작

3.6 Hermes 통합

honcho-ai SDK 설치

Hermes Honcho 플러그인 설정 (~/.hermes/honcho.json)

Hermes 글로벌 설정에서 provider 활성화

연결 검증

4.1 API 헬스

4.2 워크스페이스 생성

4.3 임베딩 동작 확인

5.1 첫 OpenAI 키 — quota 부족

5.2 가이드의 모델명 deepseek-v4는 존재하지 않음

5.3 docker compose restart는 env_file을 다시 읽지 않는다 ⚠️

5.4 Anthropic 키 혼동

상태 확인

로그

재시작

중지 / 재가동

Honcho 업데이트

데이터베이스 직접 조회

백업 / 복원

Mac 잠자기 방지 (장시간 자리비울 때)

LLM (OpenRouter, deepseek-v4-flash)

임베딩 (OpenAI, text-embedding-3-small)

인프라

합산

확인한 현재 상태

확인한 폴라 설정

맥북프로 탐지 결과

작업 중 발생한 상태 변화

아직 완료하지 않은 다음 작업

설계 메모

Hermes Honcho 플러그인 설정 (`~/.hermes/honcho.json`)

5.2 가이드의 모델명 `deepseek-v4`는 존재하지 않음

5.3 `docker compose restart`는 env_file을 다시 읽지 않는다 ⚠️