vigil: 아무도 깨우지 않는 감시견

이 글은 Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle에 제출하는 내용입니다.

Tags: #devchallenge #hf26challenge

제가 만든 것

vigil은 소형 VPS 박스를 위한 에이전트 기반 감시견입니다. 단순한 점검과 스마트한 진단을 제공합니다.

대부분의 감시견(watchdog)은 '무언가 문제가 생겼다'고 알려줍니다. 그러고 나서 새벽 2시에 SSH로 접속해 로그를 20분 동안 뒤지다가, 서비스는 괜찮았는데—감시견이 잘못 알람을 울린 경우입니다. vigil은 이 간극을 메웁니다. 점검에 실패하면 로컬 AI 에이전트(동일 박스에서 오픈 가중치 모델 실행)를 깨워 실제 도구들—journalctl, systemctl, ss, df—로 조사하게 하고, 사용자의 실제 로그를 읽어 STATE / EVIDENCE / ACTION / CONFIDENCE가 포함된 보고서를 전송합니다.

vigil이 구축된 박스에서 새벽 1시 46분에 제 Telegram으로 전송된 실제 보고서입니다:

VIGIL — http://127.0.0.1:8764/hub/status (HTTP Error 401: Unauthorized)

STATE: healthy — 401은 예상되는 값이며, 서비스는 정상 작동하고 인증(auth)도 설계대로 작동함
...

만약 임계값 기반 감시견이었다면 그 보고서에 **

vigil은 비용이 많이 드는 diagnosis 단계를 대체합니다. 검사는 무료입니다(순수 stdlib), 모델도 무료입니다(오픈 웨이트, 박스에 탑재됨), 그리고 모든 보고서는 행동할지 아니면 다시 잠으로 돌아갈지 알려줍니다. 저는 이것을 일회성 구매(~15달러) 또는 홈랩 사용자들을 위한 기부 소프트웨어로 가격 책정할 것입니다. 시장은 정확히 하나의 서버를 소유하고 Datadog을 사기를 거부하는 모든 사람입니다.

저는 사용자 1입니다: vigil은 현재 제 프로덕션 VPS에서 systemd 서비스로 실행되며, 제 게이트웨이, LLM 라우터, 그리고 터널들을 감시합니다.

데모

10월 14일 01:26부터 내 박스에서 실시간으로 작동 (타임스탬프는 systemctl --user status vigil에서 가져옴):

• 설정 → 약 20분 만에 첫 실제 알림. 첫 번째 패스에서 vigil은 두 가지 검사를 플래그 지정했고, 에이전트는 둘 다 서비스 장애가 아닌 워치독 버그로 진단했습니다(시스템d 범위 불일치 — 서비스가 사용자 레벨인 경우 systemctl로 시스템 유닛을 확인하는 문제와 설계상 작동한 인증 401).
• 쿨다운 기능 작동. 각 알림이 한 번 진단된 후, 해당 검사는 조용해집니다(검사별 쿨다운, 기본값 15분). 하룻밤 동안 8시간 이상의 연속 작동에도 오탐지 페이지가 전혀 없습니다. 고요한 밤이야말로 제품이 작동하고 있다는 증거입니다.
• E2E 진단 지연 시간: 4코어 VPS에서 실패당 ~30–90초 (반복 실행을 통해 측정됨, 도구 접근 권한이 있는 일회성 에이전트 호출).

박스 자체: github.com/ZidoCode/vigil — 코드는 MIT 라이선스를 따릅니다. 설정은 세 개의 명령(클론, 구성, systemctl --user enable --now vigil)으로 완료됩니다.

제가 구축한 방법

• 점검 기능 (Checks): 순수 Python stdlib로 작성된 약 230줄 분량의 코드입니다. 외부 의존성(dependencies)이 전혀 없습니다. systemd 유닛 상태, HTTP 프로브, TCP 리스너, 디스크/메모리 임계값 등을 점검합니다. 각 점검 항목별 냉각기(cooldown)가 적용되어 엣지 트리거 방식의 경고를 발생시키므로, 실패한 점검이 폭주하는 대신 한 번 진단하게 합니다.
• 진단 (Diagnosis): Hermes Agent를 사용하여 일회성 호출(hermes -z)을 수행하며, 도구 접근(tool access) 기능을 활용합니다. 이 에이전트는 같은 시스템의 자체 호스팅 게이트웨이를 통해 제공되는 오픈 가중치 모델 (예: Qwen3.8-27B를 사용자의 라우터로 설정)을 대상으로 합니다. 에이전트는 실패한 점검 항목과 원본 실패 상세 정보를 받으면, 스스로 조사합니다. 즉, 저널(journals)을 읽고, 리스너를 확인하며, 서비스 상태를 검증하는 식입니다. 저는 조사를 스크립트로 작성하지 않았습니다. 모델이 어떤 증거를 수집할지 결정하게 합니다.
• 전달 (Delivery): 표준 입력(stdin)을 읽는 모든 명령어를 사용합니다. 예를 들어, hermes send --to telegram -f -와 같습니다. 전달 실패 시에는 표준 출력(stdout)으로 폴백(fallback)하여 보고서가 절대 손실되지 않도록 합니다.
• 작동하지 않은 점 (솔직한 목록): 제가 처음 Telegram으로 전송을 시도했을 때(hermes send -s) 플래그가 없어서 실패했고, 표준 입력 파이프(|)를 사용하는 방식으로 변경해야 했습니다. 첫 번째 systemd 점검은 서비스가 사용자 레벨(user-level)인데 시스템 범위 유닛(system-scope units)을 프로브했기 때문에 잘못된 경고를 발생시켰습니다. 하지만 에이전트가 이 문제를 최초 진단 과정에서 포착해냈는데, 이는 버그 스토리이자 동시에 제품의 최고의 데모였습니다. 그리고 모델이 바쁜 시스템에서는 한 번 약 90초가 걸리기도 했습니다. 즉, 진단 지연 시간은 모델에 의해 결정되며, vigil은 자동 복구 장치가 아니라 감시견(watchdog)입니다.

제가 구축한 것에 오픈 혁신이 중요한 이유

진단 단계 자체가 이 제품 전체이며, 이것이 작동하는 이유는 모델이 로컬에서 실행되기 때문입니다:

• 비즈니스 수학은 오픈 웨이트(open weights)에서만 작동합니다. 모든 작은 문제에 대해 유료 API를 호출하는 감시견은 자체 가치 제안과 충돌하는 비용 곡선을 갖게 됩니다. 따라서 진단 요청을 주저하게 될 것입니다. 장치에 탑재된 오픈 웨이트 모델을 사용하면 진단이 무료이므로, vigil은 자원을 아끼기보다 모든 일시적인 이상 징후를 조사할 수 있습니다.
• 프라이버시는 정책이 아닌 구조적입니다. 장애를 진단한다는 것은 로그와 프로세스 테이블을 읽는 것을 의미합니다. 클라우드 API의 경우, 해당 증거가 경고 발생 시마다 제3자에게 전송됩니다. 여기서는 네트워크를 건너가지 않습니다. 로그를 읽는 모델은 해당 로그를 작성한 장치에서 실행됩니다.
• 뇌에 대한 벤더 종속성이 없습니다. provider/model은 설정 키입니다. 게이트웨이가 제공하는 모든 오픈 웨이트 모델이 작동합니다. llama.cpp, vLLM, 자체 호스팅 라우터 등 어떤 것이든 가능합니다. 이 루프에서 가장 의견이 강한(opinionated) 구성 요소는 한 줄로 교체할 수 있습니다.

다음 계획 (What's next)

• 자체 에이전트가 발견한 두 가지 감시견 버그 수정 (범위 인식 시스템d 체크, 인증 인식 HTTP 프로브) — #1 및 #2로 등록되었으며, 현재 수정 작업 진행 중입니다.
• 모든 진단 기록을 담은 cases.jsonl 로그를 생성하여 vigil이 자체적인 실적을 보여줄 수 있도록 합니다.
• 요구사항이 있을 경우: 진단 이력을 기반으로 간단한 상태 페이지를 생성합니다.

저장소(Repo): https://github.com/ZidoCode/vigil — MIT 라이선스, 표준 라이브러리 약 230줄 분량이며, 모든 OpenAI 호환 엔드포인트와 작동합니다.

Hacktoberfest Week 2 동안 약 20시간 만에 구축되었으며, 발표 전에 배포되어 첫 순간부터 운영되고 있습니다.