herdr로 로컬 코딩 에이전트 돌릴 때 뭐부터 설정하나?

먼저 답부터 드리면: 여러 에이전트를 엮는 오케스트레이션보다 먼저 ① 작업 루트(워크스페이스·경로), ② 모델·프로바이더를 어디서 설정하는지, ③ 권한과 금지 경로, ④ 에이전트에게 작업을 어떻게 넘기는지 네 가지를 정해야 합니다. 이 넷이 흐리면 패인을 아무리 많이 띄워도 결과를 믿기 어렵습니다.

이 글은 2026-09-27 기준 herdr 공식 문서만 근거로 삼습니다. 문서에서 확인하지 못한 옵션 이름은 지어내지 않고 개념으로만 설명한 뒤, 해당 공식 문서 링크를 붙였습니다.

herdr는 무엇을 해 주는 도구인가?

한 줄 답: herdr는 코딩 에이전트를 실제 터미널 패인에서 여러 개 돌리고, 그 상태를 한 화면에 모아 주는 로컬 런타임입니다.

공식 Agents 문서는 herdr가 코딩 에이전트를 동시에 여러 개 돌리기 위해 만들어졌다고 설명합니다. 에이전트는 셸·로그·프롬프트가 그대로 살아 있는 터미널 패인 안에서 실행되고, herdr는 어떤 패인에 에이전트가 있는지 감지해 working, blocked, done, idle 같은 상태를 탭과 워크스페이스 단위로 사이드바에 올려 줍니다. 스크립트나 다른 에이전트가 CLI와 로컬 소켓 API로 작업을 넘길 수도 있습니다.

여기서 중요한 점이 하나 있습니다. herdr는 모델을 직접 호출하는 에이전트가 아닙니다. claude, codex, cursor 같은 에이전트 CLI를 패인에서 실행하고 관리하는 층입니다. 그래서 설정도 “herdr 쪽”과 “에이전트 CLI 쪽”으로 나눠서 봐야 합니다.

첫 설정 체크리스트는 무엇인가?

한 줄 답: 작업 루트 → 도구(어떤 에이전트를 쓸지) → 모델 설정 위치 → 시크릿 분리 순서로 정리하면 충분합니다.

항목	어디서 설정하나	처음 정할 것
작업 루트	herdr 워크스페이스, `config.toml`의 `[terminal]`	저장소 하나 = 워크스페이스 하나. 새 패인이 어느 디렉터리에서 열리는지
도구	herdr가 감지하는 에이전트 CLI	처음에는 에이전트 한 종류만. 필요하면 integration 설치
모델·프로바이더	에이전트 CLI 자체 설정	어떤 모델·엔드포인트를 쓸지는 각 에이전트 문서 기준
권한·금지 경로	에이전트 CLI 설정 또는 샌드박스 래퍼	쓰기 가능한 범위, 읽으면 안 되는 경로
시크릿	환경 변수·자격 증명 저장소	규칙 파일(AGENTS.md 등)에는 절대 넣지 않음

1) 작업 루트. 공식 Concepts 문서는 활성 프로젝트마다 워크스페이스를 하나씩 두는 방식을 권합니다. 프로젝트 디렉터리에서 herdr를 실행해 시작하면 되고, 새 패인·탭·워크스페이스가 어느 경로에서 열릴지는 Configuration 문서의 [terminal] 섹션 new_cwd로 정합니다. 기본값 follow는 원래 패인이나 워크스페이스의 경로를 이어받습니다. 설정 파일은 Linux·macOS 기준 ~/.config/herdr/config.toml이고, 기본 설정 전체는 아래처럼 뽑아 볼 수 있습니다.

herdr --default-config

설정을 고친 뒤에는 herdr server reload-config로 실행 중인 서버에 반영합니다. 한 저장소에서 에이전트 여러 개가 같은 파일을 건드릴 것 같다면, 같은 문서의 [worktrees] 섹션으로 Git worktree 체크아웃 위치를 정해 두고 에이전트마다 체크아웃을 나누는 편이 안전합니다.

2) 도구. Agents 문서에 지원 에이전트 목록과 상태 판별 방식이 나옵니다. 화면 인식만으로도 동작하지만, lifecycle hook을 지원하는 에이전트는 integration을 설치하면 상태 보고가 더 정확해집니다. 설치 명령과 에이전트별 차이는 공식 Integrations 문서를 따르십시오.

3) 모델·프로바이더. herdr 설정에는 모델 엔드포인트를 지정하는 곳이 없습니다. 모델 선택, 로컬 모델 서버 주소, API 프로바이더는 각 에이전트 CLI의 설정 파일이나 실행 인자에서 정합니다. herdr의 agent start는 -- 뒤의 인자를 해당 에이전트 실행 파일에 그대로 넘기므로, 모델 인자가 필요하면 그 에이전트 문서에 나온 형식을 그대로 붙이면 됩니다.

4) 시크릿. API 키는 환경 변수나 에이전트가 지원하는 자격 증명 저장 방식으로 주입하고, 규칙 파일·프롬프트·작업 지시문에는 넣지 않습니다. 규칙 파일은 에이전트가 매번 읽고 요약이나 로그에 옮길 수 있는 텍스트입니다.

권한과 금지 경로는 어디서 거나?

한 줄 답: herdr가 아니라 에이전트 CLI의 권한 설정과 샌드박스에서 겁니다. herdr는 그 에이전트가 무엇을 하는지 보여 줄 뿐입니다.

herdr 공식 문서에서 파일 접근을 막는 설정은 확인하지 못했습니다. 대신 Agents 문서는 샌드박스 래퍼 안에서 에이전트를 돌리는 경우를 따로 다룹니다. 래퍼가 실제 에이전트 프로세스를 가리면 herdr가 에이전트를 인식하지 못하므로, 래퍼 명령에 HERDR_AGENT를 붙여 어떤 에이전트인지 알려 주라고 안내합니다. 문서의 예시는 다음과 같습니다.

HERDR_AGENT=claude fence -- claude

즉 권한 설계는 이렇게 나눕니다.

쓰기·실행 권한: 에이전트 CLI의 승인(approval)·샌드박스 설정. 옵션 이름은 에이전트마다 다르니 그 에이전트의 공식 문서를 보십시오.
금지 경로: .env*, secrets/, 개인 키 같은 경로를 에이전트의 ignore·deny 설정과 .gitignore에 겹쳐 겁니다.
herdr의 역할: blocked 상태로 승인 요청이 떴다는 사실을 사이드바에 올려 주는 것. 공식 문서도 blocked 판별이 엄격해서 새로운 승인 화면은 처음에 idle로 보일 수 있다고 적고 있습니다.

에이전트에게 작업은 어떻게 넘기나?

한 줄 답: 처음에는 패인에서 직접 입력하고, 반복되는 흐름만 agent prompt·agent wait로 스크립트화합니다.

Agent automation 문서는 레이아웃·패인·에이전트 세 가지 기본 단위를 나눕니다. 에이전트는 이미 있는 셸 패인에서만 시작할 수 있고, agent start가 레이아웃을 만들거나 바꾸지는 않습니다. 작업 전달에 쓰는 명령은 문서 기준으로 다음과 같습니다.

목적	명령
기존 패인에서 지원 에이전트 시작	`herdr agent start <이름> --kind <종류> --pane <패인ID>`
프롬프트 전달(필요하면 완료까지 대기)	`herdr agent prompt <이름> "<지시>" --wait`
특정 상태가 될 때까지 대기	`herdr agent wait <이름> --until blocked`
결과 읽기	`herdr agent read <이름>`

도구보다 중요한 것은 지시문 자체입니다. 작업 하나에 목표, 건드려도 되는 경로, 완료 조건(테스트 통과 등), 멈추고 물어봐야 할 조건을 적어 두십시오. 결과가 길면 공식 문서도 임시 디렉터리에 Markdown으로 쓰게 하고 경로만 돌려받는 방법을 권합니다.

첫 주에 자주 하는 실수는 무엇인가?

한 줄 답: 너무 넓은 파일 범위, 금지 경로 없음, 흐릿한 작업 지시 세 가지가 대부분입니다.

홈 디렉터리를 작업 루트로 두기. new_cwd가 home이거나 홈에서 herdr를 시작하면 에이전트가 저장소 밖 파일까지 보게 됩니다. 워크스페이스는 저장소 루트에서 만드십시오.
금지 경로 없이 시작하기. herdr 사이드바가 보여 주는 것은 상태이지 접근 통제가 아닙니다. 에이전트 CLI 쪽 deny 설정이 비어 있으면 .env도 읽힐 수 있습니다.
“이거 고쳐 줘” 수준의 지시. 완료 조건이 없으면 에이전트가 idle로 돌아와도 끝났는지 판단할 수 없습니다. 공식 문서도 unknown 상태가 성공 완료를 뜻하지 않는다고 적고 있습니다.
에이전트 여러 개를 같은 체크아웃에 두기. 같은 파일을 동시에 고치면 충돌이 납니다. worktree로 나누거나 역할(구현·리뷰)을 분리하십시오.
시크릿을 규칙 파일에 적기. “키는 abc123 이야” 같은 문장은 규칙이 아니라 유출입니다.
오케스트레이션부터 짜기. 에이전트 하나가 안정적으로 돌기 전에 헬퍼 에이전트와 스크립트를 붙이면, 실패 원인이 어디인지 가리기 어려워집니다.

“이 정도면 충분한” 첫 설정은 어떤 모습인가?

한 줄 답: 저장소 하나, 에이전트 하나, 좁은 권한, 명확한 지시문 하나로 시작해 한 주 동안 돌려 보는 것입니다.

순서대로 적으면 다음과 같습니다. 명령은 공식 문서에 나온 것만 적었고, 에이전트별 옵션은 일부러 비워 두었습니다.

저장소 루트로 이동해 herdr를 실행합니다. 워크스페이스가 없으면 자동으로 하나가 열립니다.
herdr --default-config로 기본 설정을 확인하고, [terminal]의 new_cwd는 기본값 follow를 그대로 둡니다. 여러 에이전트를 돌릴 계획이면 [worktrees]의 directory도 정해 둡니다.
쓰려는 에이전트 CLI 하나에서 모델·프로바이더와 승인·샌드박스 설정을 그 에이전트 공식 문서대로 먼저 마칩니다. API 키는 환경 변수로만 넣습니다.
저장소에 .gitignore와 에이전트용 ignore·deny 설정을 두고, 규칙 파일에 “금지 경로를 읽지 말고, 시크릿이 필요하면 멈추고 물어볼 것”을 한 줄로 적습니다.
패인에서 에이전트를 직접 실행하고, 사이드바에서 working → blocked → done 흐름이 제대로 보이는지 확인합니다. 상태가 이상하면 herdr agent explain으로 원인을 봅니다.
이 흐름이 며칠 안정적으로 돌면, 그때 agent start·agent prompt --wait로 리뷰 에이전트 같은 헬퍼를 하나 붙입니다.

FAQ

질문	답
herdr에서 로컬 모델 주소를 설정할 수 있나?	확인한 공식 설정 문서에는 없습니다. 모델과 엔드포인트는 패인에서 실행하는 에이전트 CLI 쪽에서 설정합니다.
지원 목록에 없는 에이전트도 돌릴 수 있나?	공식 문서에 따르면 일반 터미널 프로세스로는 정상 실행됩니다. 다만 integration을 추가하거나 소켓 API로 상태를 보고하지 않으면 상세 상태는 안 보일 수 있습니다.
샌드박스 안에서 돌리면 인식이 안 되는데?	래퍼 명령에 `HERDR_AGENT=<에이전트>`를 붙입니다. VM이나 컨테이너 안에서만 설정하면 herdr가 볼 수 없다는 점에 주의하십시오.
설정을 바꾼 뒤 재시작이 필요한가?	대부분은 `herdr server reload-config`로 반영됩니다. 시작 시에만 읽는 설정은 재시작이 필요합니다.

출처

한 줄 답: 2026-09-27 기준으로 확인한 herdr 공식 문서만 근거로 삼았습니다.

Herdr documentation — 전체 안내
Agents — 지원 에이전트, 상태 판별, 샌드박스 래퍼와 HERDR_AGENT, blocked 판별
Agent automation — 레이아웃·패인·에이전트 기본 단위, agent start·agent prompt·agent wait
Configuration — config.toml 위치, --default-config, reload-config, [terminal], [worktrees]
Concepts — 워크스페이스·탭·패인 모델
인접 글: herdr-workspace-setup(워크스페이스 구성), agent-deny-paths(금지 경로), agent-secrets-in-rules(규칙 파일과 시크릿)