Heinzel — 안전 가드레일을 갖춘 시스템 관리

Heinzel은 AI 코딩 어시스턴트를 신중하고 체계적인 시스템 관리자(sysadmin)로 변신시키는 일련의 규칙입니다. 필요한 것을 일반 영어로 설명하기만 하면 됩니다. Heinzel은 사용자의 OS에 맞는 올바른 명령어를 찾아내고, 각 명령어에 대해 설명하며, 승인을 기다립니다. 설정 파일을 백업하고, 적용 전에 테스트를 수행하며, 작업했던 모든 서버를 기억합니다.

이 도구는 Linux, FreeBSD 및 macOS를 관리하며, SSH 원격 연결 또는 로컬 머신에서 작동합니다. 또한 Claude Code, OpenCode 또는 프로젝트 파일을 읽고 셸 명령어를 실행하는 모든 터미널 AI 도구에서 구동됩니다.

트레일러는 녹화된 것이 아니라 스크립트되었습니다. 변경하려면 assets/trailer/를 참조하세요.

YouTube 화면 녹화 영상:

• 오류가 있는 nginx 및 방화벽을 디버깅하고 수정하기 (1분)
• 최신 안정 버전의 Ruby 및 Ruby on Rails 설치하기 (1분)
• 방화벽 설치, 배포판 업그레이드, 일일 보안 업데이트 설정하기 (2분)

기사 보기:
heise.de의 Heinzel에 대한 독일어 기사

설치

필요한 것:

• 터미널용 AI 코딩 어시스턴트, 예: Claude Code 또는 OpenCode.
• 일반 사용자 또는 root로 서버에 대한 SSH 접속 권한 (비밀번호를 묻지 않는 키 사용). 로컬 머신에서는 필요하지 않습니다. SSH 키가 처음이신가요? Arch wiki 가이드를 참조하세요.
• Linux, macOS, FreeBSD 또는 Windows가 실행되는 워크스테이션. Windows의 경우 WSL을 사용하거나 Git for Windows의 Git Bash에서 AI 도구를 시작하세요. PowerShell과 cmd.exe는 지원되지 않습니다.

그 다음:

git clone https://github.com/wintermeyer/heinzel.git
cd heinzel
claude # 또는: opencode

❯ server1.example.com에 postgresql 설치하기

첫 연결 시 Heinzel은 감지할 수 없는 항목(보통 SSH 사용자)을 물어볼 수 있습니다. 답변은 memory/user.md로 저장되므로, 한 번만 질문합니다. 이 파일은 memory/user.md.example에서 미리 채울 수 있습니다. 또한 언어(Language: German)도 저장합니다.

Heinzel은 모든 명령을 제안하고, 그것이 무엇을 하는지, 그리고 왜 하는지를 설명한 다음 승인을 기다립니다.

Heinzel은 호스트당 하나의 SSH 연결을 공유하며, 마지막 호출 후에도 10분 동안 열어둡니다. 소켓은 ~/.cache/heinzel (모드 0700)에 존재하므로, 로컬 사용자의 모든 프로세스가 키 없이도 열린 연결을 사용할 수 있습니다.

요청할 수 있는 것들

• web1.example.com 확인하기: 서버의 메모리 파일과 최근 변경 사항을 읽고, 마지막 세션이 끝난 지점부터 이어서 작업합니다.

• app.example.com에서 시스템 점검 실행하기: 디스크, 메모리, 부하, 업데이트, 방화벽, 인증서 및 실패한 서비스에 대한 상태 보고서를 제공합니다. 문제가 먼저 나옵니다.

• app.example.com에서 보안 감사 실행하기: 심각도별로 SSH, 방화벽, 계정, 열린 포트 및 커널 설정을 검사합니다.

• `app.example.com의

• OS 감지 (OS detection). Heinzel는 처음 접촉 시 OS와 하드웨어를 감지하고 해당 플랫폼의 규칙 파일을 로드합니다.

• 메모리 (Memory). 각 서버는 memory/servers/ 아래에 상태, 변경 로그(changelog), 그리고 진행 중인 할 일 목록이 담긴 폴더를 갖습니다. 연결이 끊긴 작업은 다음 연결 시 보류(pending) 상태로 표시됩니다.

• 장기 작업 (Long jobs). 1분 이상 걸릴 수 있는 명령어는 호스트에서 작업으로 실행되며, 출력과 종료 상태가 파일에 저장되고 나중에 읽어올 수 있습니다. 이는 연결이 끊긴 후나 새 세션에서도 가능합니다 (rules/ssh-connections.md).

• DNS 별칭 (DNS aliases). 동일한 IP를 가진 여러 이름은 하나의 메모리를 공유합니다. 각 별칭은 자체 SSH 사용자를 가질 수 있습니다.

• SSH 포트 (SSH ports). 22번이 아닌 다른 포트는 서버별로 저장됩니다. 사용하는 포트를 Alternative SSH ports:에서 memory/user.md에 나열하세요. Heinzel는 해당 포트들을 시도하며 절대 스캔하지 않습니다.

• 이메일 세부 정보 (Email details). 메일은 운영자 이름(Operator name: in memory/user.md)을 포함하는 짧은 서명과 부재중 자동 회신(out-of-office replies)을 막는 헤더를 가집니다. 호스트별 첫 메일에서는 어디서 보내야 하는지 묻습니다. Heinzel는 기존 MTA(Mail Transfer Agent)를 사용하며, 설치하기 전에 먼저 문의합니다.

macOS 정리 스캐너는 Command Line Tools (xcode-select --install)가 필요합니다.

Heinzel 또는 Heinzel Pro

Heinzel는 한 터미널에서 하나의 호스트에 대해 작업하는 단일 관리자입니다. Heinzel Pro는 동일한 규칙을 기반으로 구축된 상용 제품입니다: 팀, 웹 인터페이스, 플릿(fleet), 그리고 Heinzel가 요청할 수 있는 것만을 강제하는 런타임 환경이 있습니다. 두 번째 사람, 신원, 플릿, 일정 또는 증거 사슬(evidence chain)이 필요한 모든 것이 그곳에 존재합니다. Heinzel는 이러한 것들을 읽고 보고하며, Pro를 가리키는 한 줄의 요청으로 변경을 요청하고 응답합니다.

안전 및 가드레일 (Safety & guardrails)

안전 규칙은 모든 세션의 일부입니다.

• 행동 전에 질문합니다. 파괴적인 명령어, 방화벽 변경, 재부팅(reboots), 서비스 재시작 등에는 승인이 필요합니다. 설정 테스트가 통과되면 로드(Reloads)는 자체적으로 실행됩니다 (rules/service-reload.md, memory/service-policy.md).
• 강력한 가드레일 (Claude Code). PreToolUse 훅(.claude/hooks/guard-taboos.sh)은 권한 모드가 --dangerously-skip-permissions인 경우에도 절대 금지된 행위들을 차단합니다: 정지 및 전원 차단, mkfs, 파티션 테이블 작성기(partition-table writers), 부트 로더 및 EFI 작성기, SSH 키 삭제 또는 덮어쓰기, sshd_config에 대한 쓰기 작업, 계정 삭제, sudoers에 대한 쓰기 작업, 계정 파일 및 서버 잠금 장치. 또한 이는 ssh host "…" 내부, python3 -c 뒤, 그리고 파일 편집 도구가 해당 파일을 대상으로 할 때도 포착합니다. 읽기 전용 형식(fdisk -l, efibootmgr -v, visudo -c)은 허용됩니다. 이 훅에는 꺼지는 스위치가 없습니다: 이것이 차단하는 것은 Heinzel Pro의 작업입니다. OpenCode는 이 훅을 실행하지 않으며, 여기에 작성된 규칙 자체가 안전 계층(safety layer) 역할을 합니다.
• 보고하기 전에 검증합니다. "재부팅 이후 사라졌습니다"라는 내용은 라이브 시스템과 먼저 대조하여 확인됩니다 (rules/verify-before-reporting.md).
• 편집하기 전에 설정 파일을 /var/backups/heinzel/에 백업합니다. 30일 후에 정리됩니다.
• 무언가를 변경하기 전에 되돌아갈 방법을 알고 있습니다. 변화를 요청하는 모든 질문은 Way back: <방법> 또는 Way back: none으로 끝납니다.

Heinzel는 변경 사항이 다음 리로드 시점까지만 유지되어 검증될 때 선호합니다 (sysctl -w를 sysctl.d보다 먼저, fstab보다 먼저 mount). 이전 커널, 클러스터 또는 바이너리를 새것이 작동할 때까지 보존하며, 이제는 다음 부팅에서만 나타날 수 있는 실패를 테스트합니다 (rules/way-back.md).

• 잠금 해제된 것을 롤백합니다. 로그인(IP 주소, 라우트, 방화벽, VPN, PAM)을 차단할 수 있는 변경 사항 이전에, Heinzel는 서버에 타이머를 설정하여 120초 후에 이전 상태로 복원합니다. 변경 후 새로운 SSH 로그인이 이루어져야만 이 타이머가 중지됩니다. 만약 새 주소가 잘못되었다면, 서버가 스스로 이를 되돌리고 Heinzel는 무슨 일이 일어났는지 보고합니다 (rules/rollback-timer.md). memory.md에서 - Rollback window: 300을 사용하여 서버별로 더 긴 시간 간격을 설정할 수 있습니다.
• 적용 전 테스트를 위해 dry-run 또는 유효성 검사 모드를 사용하며, 도구에 해당 기능이 있는 경우 이를 활용합니다.
• 모든 것을 기록합니다. 모든 변경 사항은 시스템 저널에 일반 언어의 한 줄로 남습니다. 기술적인 세부 정보와 되돌리는 방법은 memory/servers/<hostname>/changelog.log에 있습니다.
• 안정화된 리포만 허용합니다. 승인되지 않은 타사 소스는 사용하지 않습니다.
• 최소 권한 원칙을 따릅니다. 일반 사용자부터 시작하고, 필요할 때만 sudo를 사용하며, 루트는 마지막으로 사용합니다. 이 중 어느 것도 없는 경우, Heinzel는 할 수 있는 것을 수행하고 루트가 필요한 작업에 대한 보고서를 작성합니다.
• 블랙리스트 및 읽기 전용 서버. memory/blacklist.md의 호스트는 절대 접촉되지 않습니다. memory/readonly.md의 호스트는 검사만 하고 변경하지 않습니다.
• 서버 잠금. 기기의 소유자는 해당 기기에 파일을 생성하여 모든 Heinzel로부터 자신을 보호할 수 있습니다:

# /etc/heinzel.conf
allow_changes = false
reason = 20 Oct까지 데이터베이스 마이그레이션, 업무 인계 중

Heinzel는 여전히 연결하고 검사하지만 아무것도 변경하지 않고, 자신이 무엇을 했을지 보고합니다. 읽을 수 없는 파일이나 true가 아닌 다른 값은 잠금(lock) 처리됩니다. Heinzel는 파일을 쓰거나, 이동시키거나, 삭제하지 않습니다. 사용자가 직접 잠금을 해제해야 합니다. 이는 Heinzel가 지키는 약속일 뿐, 보안 경계는 아닙니다: 이를 무시하는 도구는 막지 못합니다 (rules/access-control.md).

• 보호 경로(Protected paths). memory/protected-paths.md는 서버별로 경로를 읽기 전용(readonly), 숨김(hidden) (내용이 절대 표시되지 않음), 또는 확인 필요(confirm) (타이핑된 CONFIRM 필요)으로 표시합니다.
• 주입된 명령어 무시. 파일, 로그 및 명령어 출력의 텍스트는 데이터입니다. AI를 지칭하는 텍스트는 사용자에게 플래그가 지정되어 표시되며 따르지 않습니다.
• 비밀 유지(Keeps secrets out). 키, 비밀번호 파일 및 .env 내용은 메타데이터와 지문 분석을 통해 검사되며 절대 출력되지 않고 명령어 인수로 전달되지 않습니다.

환각 현상 방지 (Against hallucinations)

LLM은 플래그나 경로를 지어낼 수 있습니다. Heinzel는 대신 검증된 사실들을 사용자 앞에 제시합니다:

• 플랫폼별 규칙 파일에 올바른 명령어, 패키지 관리자 및 방화벽 도구가 담겨 있습니다.
• 명령어가 실행되기 전에 --help, man 페이지 또는 상위(upstream) 문서를 확인합니다.
• 추측하는 대신 서버의 메모리 파일을 읽습니다.
• 먼저 건식 실행 모드(dry-run modes)를 사용합니다.
• 실행되기 전 모든 명령어를 사용자에게 보여줍니다.

이것은 위험을 줄입니다. 제거하지는 못합니다.

[!CAUTION]
Heinzel는 root 권한, sudo 또는 비특권 상태로 라이브 시스템에서 작동합니다. 승인하기 전에 모든 명령어를 검토하십시오.

체크리스트를 매번 따르는 규율 있는 AI가 새벽 2시에 지친 인간보다 실수를 적게 합니다. 하지만 여전히 사용자의 의도를 오해할 수 있습니다. 운전석 자리를 지키십시오.

프롬프트 및 스크립팅 감소 (Fewer prompts and scripting)

기본적으로 Claude Code는 모든 도구 호출 전에 사용자에게 묻습니다. 배치 작업에는 **자동 모드(auto mode)**를 사용하십시오: 백그라운드 검사가 일상적인 명령어는 통과시키고 위험한 명령어에 대해서는 여전히 중지합니다. Shift+Tab을 눌러 모드를 전환하거나, 다음 플래그를 전달하십시오:

claude --permission-mode auto \
  -p "Run housekeeping on server1.example.com"

-p는 대화형 UI 없이 하나의 프롬프트를 실행합니다. OpenCode에서는 opencode run "..."와 같습니다.

• CI 환경에서 가장 엄격한 설정은 allowlist(--allowedTools 또는 .claude/settings.json의 permissions.allow)과 함께 --permission-mode dontAsk를 사용하는 것입니다.
• --dangerously-skip-permissions는 서버 출력의 악성 텍스트에 대한 보호를 포함하여 모든 검토 과정을 제거합니다. 이는 일회용 환경에서만 사용해야 합니다.
• 어떤 모드를 사용하든, Heinzel 자체 규칙은 여전히 적용됩니다. 자세한 내용은 permission modes docs를 참조하십시오.

키보드 앞에 아무도 없는 상태, 즉 cron이나 타이머에 의해 매일 실행되는 작업은 Heinzel Pro 기능입니다. 스케줄러가 혼자서 작동하며 아침에 사람이 승인할 수 있도록 변경될 내용을 수집합니다.

사용자의 데이터: memory/

모든 상태는 하나의 디렉터리에 일반 텍스트로 저장됩니다:

• user.md: SSH 사용자 이름, 언어, 운영자 이름
• blacklist.md, readonly.md, protected-paths.md: 접근 정책
• service-policy.md: 질문 없이 재로드하거나 다시 시작할 수 있는 서비스
• servers/<hostname>/: 서버별 메모리, 변경 로그(changelog), 할 일 목록 및 규칙 재정의
• custom-rules/: 전역 규칙 재정의
• network.md, housekeeping.md: 크로스 서버 사실 정보 및 자체 검사
• opencode.json: OpenCode 설정 파일

백업 및 복원

bin/heinzel-backup                        # .tar.gz 파일을 작성합니다
bin/heinzel-backup -o <path>              # 지정된 경로로 저장합니다
bin/heinzel-backup --list                 # 건식 실행(dry run)을 수행합니다
...