2026년 Hermes Agent Mac 완전 보안 설정 가이드: 권한·API 키·파일 경계 설정법

2026년 Mac에 Hermes를 설치할 때 흔한 실수는, 첫날부터 「모델이 연결됐다」「Gateway가 떴다」는 것만 확인하고 기기 전체를 에이전트에 넘기는 일입니다. 공식 문서(SECURITY.md)도 분명히 말합니다. 악의적인 LLM 행동에 대한 유일한 하드 경계는 OS입니다. 명령 승인, 컨테이너 격리, Gateway 허용 목록은 OS 제한 위에 얹는 심층 방어이며, 직접 정의하는 파일·비밀 범위를 대체하지 않습니다.

먼저 결론: Hermes Agent에 홈 디렉터리 전체와 모든 셸 명령을 기본으로 주면 안 됩니다. 최소 워크스페이스, 최소 API 키, approvals.mode: manual로 시작해 실제 작업 하나를 통과한 뒤, 의도적으로만 권한을 넓히세요. 아래는 설치 후 약 30분 안에 끝낼 설정 순서입니다.

1. 실제 업무 전에 잡아 둘 보안 baseline

Hermes는 기본값이 terminal.backend: local이라 명령이 현재 macOS 사용자 권한으로 실행됩니다. Gateway에 허용 목록이 없으면 시작 시 외부 사용자를 거부합니다—건전한 fail-closed 동작입니다. 동작 확인만 위해 GATEWAY_ALLOW_ALL_USERS=true를 켜면, 봇에 닿을 수 있는 누구나 도구 호출을 일으킬 수 있습니다.

현실적인 위험은 SF 「폭주 AI」가 아니라, 예측 가능한 세 가지입니다.

• 실수로 삭제·덮어쓰기: 재귀 rm, ~/.ssh·~/.hermes/.env 파괴;
• 비밀 유출: 로그, MCP 자식 프로세스, 컨테이너 환경 변수로 API 키 노출;
• 무단 트리거: 승인되지 않은 Telegram/Discord/Slack 사용자가 배포·대량 발송·결제 스크립트 실행.

보안 설정은 기능을 전부 끄는 것이 아닙니다. 에이전트가 실제로 일하는 범위 안에서만 움직이게 하는 것입니다. 아래 계층 표를 이후 절의 지도로 쓰세요.

2. 전용 워크스페이스 쓰기

2.1 일상 macOS 계정 vs 전용 계정

가능하면 매일 쓰는 macOS 계정에서 Gateway를 장기 실행하지 마세요. 일상 계정에는 사진, 메일, 브라우저 비밀번호 등 TCC 권한이 이미 많고, local 터미널 백엔드는 그 표면을 그대로 물려받습니다.

실무에서 쓰기 쉬운 세 단계:

• 로컬 시험(낮은 위험): 본 계정 유지, CLI만, local 백엔드, cwd를 전용 폴더로 고정;
• 전용 macOS 사용자(권장): 시스템 설정 → 사용자 및 그룹에서 표준 사용자 hermes 생성, 워크스페이스와 필요한 SSH 키만 연결;
• 별도 기기·VM(프로덕션 Gateway): terminal.backend: ssh로 Mac mini 또는 Linux 워커에 실행, Gateway는 메시지 라우팅만.

Hermes SECURITY.md는 다중 사용자 격리가 OS/호스트 계층에서 이뤄져야 한다고 강조합니다. 앱 내 세션 키는 트래픽 분기용이지 인가 경계가 아닙니다.

2.2 디렉터리 구성과 MESSAGING_CWD

전용 계정에서 격리 워크스페이스를 만들고, 기본 cwd를 ~로 두지 마세요.

mkdir -p ~/hermes-workspace/{inbox,outbox,scratch,backups}
chmod 700 ~/hermes-workspace

~/.hermes/.env에:

MESSAGING_CWD=/Users/hermes/hermes-workspace

권장 구역:

• inbox: 에이전트가 읽기만 하거나 반쯤 읽기 전용인 입력;
• scratch: 쓰기 가능한 임시 스크립트·빌드 산출물;
• outbox: 외부 공유 전에 사람이 검토할 출력;
• backups: 에이전트 쓰기 금지—Time Machine·rsync만.

저장소를 붙일 때는 ~/Projects 전체가 아니라 단일 프로젝트 하위 디렉터리만. Docker 영속화 시 컨테이너 /workspace는 ~/.hermes/sandboxes/docker/ 아래에 매핑됩니다. 오래된 샌드박스는 주기적으로 지워 민감 파일이 남지 않게 하세요.

3. 비밀·API 키

3.1 자격 증명 보관 위치

Hermes는 모든 API 키·토큰을 ~/.hermes/.env에만 둔다고 가정합니다—config.yaml이나 git에는 넣지 않습니다. 설치 직후:

chmod 600 ~/.hermes/.env
chmod 700 ~/.hermes

보관 방식과 경계:

3.2 프로바이더 키를 컨테이너로 넘기지 않기

terminal.docker_forward_env와 terminal.env_passthrough는 Docker·로컬 자식 프로세스에 변수를 주입합니다. OpenAI/Anthropic 주 키를 passthrough로 넘기지 마세요—컨테이너 안 코드가 읽어 유출할 수 있습니다. 작업 스코프 토큰(예: 스코프 제한 GITHUB_TOKEN)만 전달하세요.

MCP 하위 프로세스는 MCP env: 블록에 명시하지 않는 한 안전한 기본값(PATH, HOME 등)만 받습니다—의도된 설계입니다.

3.3 키 순환 체크리스트

유출 의심·정기 점검 시 순서대로:

1. Gateway 중지: launchctl unload 또는 gateway 프로세스 종료;
2. 클라우드 콘솔에서 노출 가능한 모든 키 폐기·재발급(LLM, Telegram 봇, GitHub PAT);
3. ~/.hermes/.env 갱신, 이전 값이 남지 않았는지 확인;
4. ~/.hermes/logs/·셸 기록에서 평문 secret 검색;
5. Gateway 토큰 유출 시 페어링 재설정: hermes pairing list / revoke;
6. Gateway 재시작, 자동화 재개 전 최소 작업으로 검증.

4. 명령·파일 권한

Hermes에는 위험 명령 감지(tools/approval.py)가 있습니다. ~/.hermes/config.yaml에서:

approvals:
  mode: manual    # manual | smart | off
  timeout: 60     # 시간 초과 시 거부 (fail-closed)

smart는 보조 모델로 위험도를 점수화합니다—숙련 운영자용. off나 /yolo는 승인을 끕니다—일회용 컨테이너·CI에서만. rm -rf /, 포크 폭탄 등 하드 블록리스트는 YOLO에서도 거부됩니다.

4.1 허용 / 확인 / 거부 템플릿

CLI 승인 선택: once / session / always / deny. 프로덕션에서 rm·systemctl에 always를 쓰지 마세요—command_allowlist에 영구 기록됩니다. hermes config edit로 정기 감사하세요.

4.2 프로덕션에서는 Docker 격리 우선

terminal.backend: docker(또는 modal/daytona/vercel_sandbox)에서는 위험 명령 검사를 건너뛰고 컨테이너가 경계가 됩니다. Docker 기본값은 capability 축소, PID 상한, /tmp tmpfs 격리입니다. 예:

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_forward_env: []          # 비우면 호스트 secret 미주입
  container_cpu: 1
  container_memory: 5120
  container_disk: 51200
  container_persistent: true

컨테이너는 기본적으로 공인 인터넷에 나갈 수 있습니다. Skill에 네트워크가 필요 없으면 Docker 계층에서 egress를 제한하거나 --network=none을 검토하세요.

5. macOS 개인정보 보호 프롬프트

Hermes CLI/Gateway는 파일, 브라우저 제어, 스크린샷 등으로 TCC 대화상자를 띄울 수 있습니다. 메뉴 경로는 macOS 버전마다 다르지만 원칙은 같습니다. 필요한 최소만, 가능하면 전용 사용자 계정에서 부여하세요.

• 파일 및 폴더: hermes-workspace만 추가. 「전체 디스크」·문서 폴더는 피함;
• 자동화(Apple Events): Mail/Notes를 Hermes로 다루지 않으면 거부;
• 손쉬운 사용 / 화면 기록: 브라우저 도구가 필요할 때만;
• 전체 디스크 접근: 구체적 필요가 없으면 피함—TCC를 우회합니다.

시스템 설정 → 개인정보 보호 및 보안 → 해당 항목에서 언제든 철회. macOS 메이저 업그레이드 후 목록을 다시 점검하세요.

6. Gateway 인가와 감사 로그

6.1 봇과 대화할 수 있는 사람

~/.hermes/.env에 허용 목록을 설정하세요. 프로덕션에서 GATEWAY_ALLOW_ALL_USERS=true는 쓰지 마세요.

TELEGRAM_ALLOWED_USERS=your_numeric_id
GATEWAY_ALLOWED_USERS=your_numeric_id
# 또는 DM 페어링: 미지 사용자에게 8자리 코드 → hermes pairing approve로 승인

판정 순서: 플랫폼 전체 허용 플래그 → 승인된 페어링 목록 → 플랫폼 화이트리스트 → 전역 화이트리스트 → 기본 거부. 페어링 코드는 1시간 만료, 10분당 속도 제한, 5회 실패 시 1시간 잠금—고정 ID만 쓰는 것보다 유연합니다.

6.2 로그에 남길 것

기본 로그 디렉터리: ~/.hermes/logs/. 보관·로테이션 대상:

• Gateway 시작 경고(허용 목록 누락 등);
• 위험 명령 승인 결과(승인/거부/시간 초과);
• 무단 접근 시도;
• Skill 설치·지연 설치 이벤트;
• hermes doctor 공급망 권고.

로그에는 경로, 명령 인자, 프롬프트 조각이 들어갈 수 있습니다—민감 정보로 취급하고 공개 클라우드 동기화 폴더에 두지 마세요. MCP 오류는 ghp_, sk- 등을 마스킹하지만, 처음부터 secret을 적게 남기는 것이 우선입니다.

security.website_blocklist로 내부 관리 URL을 차단하세요. SSRF 보호는 RFC1918·메타데이터 IP를 기본 차단합니다—LAN Ollama 등이 정말 필요할 때만 allow_private_urls: false를 바꾸세요.

7. 단계적으로 권한 넓히기

local + yolo + allow all users로 시작하지 마세요. 무난한 사다리:

1. 1주차: CLI + manual 승인 + 전용 디렉터리 + 프로바이더 키 1개;
2. 2주차: Gateway 추가, DM 페어링, 본인 ID만;
3. 3주차: docker 백엔드, 저장소 1개 바인딩;
4. 프로덕션: 전용 Mac mini/VM + ssh 백엔드 + 리소스 한도 + 로그 알림.

단계가 올라갈 때마다 15분간 의도적 승인 테스트: 임시 파일 삭제, 내부 IP curl, push 시도—차단이 유지되는지 확인하세요.

8. 사고 대응

실수 삭제: 워크스페이스 backups 또는 Time Machine에서 복구; 버전 관리 중이면 git checkout. 에이전트를 멈추고 로그에서 트리거 프롬프트를 추적하세요.

키 유출: 3.3절 순환 체크리스트; Telegram 노출 시 @BotFather에서 봇 토큰 재설정.

무단 호출: hermes pairing revoke <platform> <user_id>; Gateway webhook URL 유출 여부 확인; 방화벽·Tailscale로 접근 제한.

비정상 API 과금: 먼저 프로바이더 지출 한도 설정, 로그에서 도구 루프·cron 확인.

참고: Hermes는 「데이터가 기기를 절대 떠나지 않는다」를 보장하지 않습니다—모델 API, 브라우저 도구, 웹 검색은 모두 egress입니다. 완전 로컬만 쓰려면 온디바이스 모델로 라우팅하고 해당 도구를 직접 끄세요.

9. 설치 후 30분 보안 체크리스트

• ☐ ~/hermes-workspace 생성 및 MESSAGING_CWD 설정
• ☐ chmod 600 ~/.hermes/.env; config.yaml에 secret 없는지 확인
• ☐ approvals.mode: manual; YOLO 비활성
• ☐ command_allowlist 감사—비우거나 최소
• ☐ Gateway 허용 목록 또는 DM 페어링; GATEWAY_ALLOW_ALL_USERS 끔
• ☐ 프로덕션 Gateway는 docker 또는 ssh 백엔드, local 아님
• ☐ docker_forward_env: []; 프로바이더 키 미전달
• ☐ macOS 개인정보 권한을 워크스페이스로 제한
• ☐ hermes doctor 실행; 공급망 권고 처리
• ☐ ~/.hermes/logs/ 쓰기 가능, 동기화 클라우드 폴더 밖

Mac mini에서 Hermes를 돌리면 경계가 더 깔끔해집니다

Hermes Gateway를 전용 Mac mini에 두는 편이 「매일 쓰는 MacBook에 풀 권한」보다 낫습니다. 주 기기는 개발·메시징에 집중하고, mini가 에이전트·Docker 샌드박스·로그를 담당해 개인 사진·브라우저 쿠키와 물리적으로 분리됩니다. Apple Silicon 통합 메모리는 로컬 헬퍼 모델(Ollama 등)에도 유리하고, Gatekeeper·SIP·FileVault가 시스템 무결성을 보강하며 전용 계정에서는 TCC를 최소화하기 쉽습니다.

Mac mini M4는 유휴 시 약 4W, 팬 없이 조용해 24시간 Gateway에 적합합니다. terminal.backend: ssh와 함께 쓰면 명령 실행은 워커, Gateway 노드는 메시지·승인에 집중할 수 있습니다. 장기 가동 에이전트 호스트를 꾸린다면 Mac mini M4는 가성비 좋은 출발점입니다—지금 도입해 Hermes를 스스로 정한 경계 안에 두세요.