토큰 청구서는 하네스가 정한다: Agav(prapaa-ai/agav) 0.2.8 심층 해부 — 반복 실패 리다이렉트·검증 강제 루프·프롬프트 캐시 97%·bubblewrap 스냅숏 샌드박스, 목 서버로 박스 실측까지

한 줄 요약: prapaa-ai/agav는 Claude Code·Codex CLI·OpenCode와 같은 줄에 서는 터미널 네이티브 AI 코딩 에이전트입니다. 내세우는 건 “더 똑똑한 모델”이 아닙니다. “같은 모델로 돈을 덜 쓰는 하네스”예요. 캐시된 컨텍스트를 다시 쓰고, 같은 실패를 되풀이하는 루프를 끊고, 편집 뒤 검증 없이 끝내려는 모델을 붙잡고, 턴 예산과 OS 샌드박스로 범위를 묶습니다. 이 글은 v0.2.8(2026-11-12 21:07 KST 릴리스) 기준으로 루프 코드(agent/loop.ts)와 권한·샌드박스 계층을 뜯어봅니다. 이어서 API 키 없이 목(mock) OpenAI 서버를 붙여 박스에서 루프 개입 3종과 bubblewrap 샌드박스 탐침 9개를 직접 돌려 본 결과를 정리합니다. 문서와 실제 동작이 다른 지점도 두 군데 나왔습니다.

Agav 한눈에 보기: 모델이 아니라 하네스가 토큰 청구서를 정한다. 왼쪽은 박스 실측에서 본 루프 개입, 오른쪽은 팀 자체 비용 연구의 사용량 영수증(Terminal-Bench 2.1, GPT-5.6 Luna) (PIL로 직접 그린 일러스트)
Agav 한눈에 보기: 모델이 아니라 하네스가 토큰 청구서를 정한다. 왼쪽은 박스 실측에서 본 루프 개입, 오른쪽은 팀 자체 비용 연구의 사용량 영수증(Terminal-Bench 2.1, GPT-5.6 Luna) (PIL로 직접 그린 일러스트)

1. 한눈에 보기

항목 내용 (2026-11-21 KST 확인)
저장소 github.com/prapaa-ai/agav · npm 패키지 이름 agav-cli, 명령은 agav
정체 “Terminal-native autonomous agent for real repositories and projects”: 코드 읽기·편집·명령 실행·테스트·검증까지 하는 CLI 에이전트
최신 안정판 v0.2.8 (2026-11-12 21:07 KST). 저장소 생성 2026-07-31, 첫 릴리스 v0.1.1(2026-08-13). 베타 포함 릴리스 42개. README 첫 줄에 “Experimental Beta” 경고
언어·런타임 TypeScript(React 19 + Ink 계열 TUI). 소스 빌드는 Node.js 22.13+ · pnpm 10.34.9. 배포 바이너리는 Bun 1.4.4 build --compile로 만든 단일 실행 파일(Node 불필요)
라이선스 Apache-2.0
규모 스타 198 · 포크 80. source/ 아래 테스트 제외 TypeScript 약 7.6만 줄, 테스트 파일 446개(박스 실행 기준 테스트 6,759개)
프로바이더 Anthropic · OpenAI(Responses/Chat) · OpenRouter · NVIDIA NIM · DeepSeek · Gemini · Vertex AI · Ollama (CLI 도움말 기준 8종)
내세우는 숫자 SWE-bench-Live Lite 62.0%(186/300) · Terminal-Bench 2.1 84.7%(제출 PR 심사 중) · 자체 비용 연구에서 Codex 대비 총비용 49.1% 절감(단, 통과율은 더 낮음)

2. 왜 지금 이 저장소인가

출발점은 last30days 랭킹입니다. ‘GitHub AI open source’ 쿼리에서 해커뉴스 글 “Show HN: Agav – an open-source terminal agent designed to waste fewer tokens”(2026-11-17 23:13 KST, 27포인트·댓글 10개)가 14위에 잡혔습니다. 그 위의 Mastra Factory·AgentRun·Octomind는 이미 다룬 주제였고, 나머지는 저장소가 아닌 목록 기사이거나 날짜가 없는 검색 결과였어요. 반응이 큰 글은 아닙니다. 그래도 “에이전트 비용은 모델 문제가 아니라 하네스 문제”라는 주장을 데이터와 코드로 내놓은 드문 사례라 골랐습니다.

해커뉴스 댓글에서 나온 질문은 세 가지로 모입니다. ① OpenCode 같은 기존 오픈소스와 뭐가 다른가: 팀은 “정확도를 크게 잃지 않는 비용 효율”과 보안 두 축에 집중한다고 답했습니다. ② 샌드박스는 뭘 쓰나: macOS Seatbelt, Linux bubblewrap, Windows 제한 토큰을 쓰고, 터미널 세션 전체가 아니라 도구 실행 단위로 적용한다고 했어요. ③ AI로 만들었나: “광범위하게 썼지만 리뷰·테스트·보안 점검을 거친다”고 했습니다. 수익 모델은 “상위 모델 토큰 재판매를 검토 중이며 오픈소스는 그대로 간다”고 밝혔습니다.

날짜 (KST) 이벤트
2026-07-31 저장소 생성
2026-08-13 v0.1.1 첫 릴리스
2026-10-27 비용 연구 “The economics of coding with Agav” 공개 (Terminal-Bench 2.1, GPT-5.6 Luna, max effort)
2026-11-12 v0.2.8: detach 세션, -c key=value 오버라이드, provider idle timeout, fetch_url SSRF 강화, Linux 스냅숏 샌드박스, 네트워크 deny 옵션
2026-11-17 Show HN 게시, 같은 날 베타 변경분을 main으로 승격

3. 문제 정의: 에이전트 비용은 어디서 새나

코딩 에이전트 청구서를 키우는 건 대개 “모델이 비싸서”가 아닙니다. 하네스 설계에서 새요. Agav README와 비용 연구가 짚는 누수 지점은 넷입니다.

누수 지점 증상 Agav의 대응
컨텍스트 재전송 긴 대화마다 같은 시스템 프롬프트·도구 스키마·이력을 새 입력 요금으로 다시 보냄 프로바이더별 프롬프트 캐시 활용. Anthropic 경로는 시스템 프롬프트·도구 목록·대화 중간에 cache_control: ephemeral 중단점을 찍음
헛도는 수리 루프 같은 명령이 같은 오류로 계속 실패하는데 모델이 재시도만 반복 오류 “지문”을 비교해 3회 연속 같으면 내부 메시지로 방향 전환 지시 1회 주입
검증 없는 완료 선언 파일을 고치고 “완료”라고 말하지만 실행해 본 적은 없음 편집 후 셸 실행이 없거나 마지막 검증이 실패하면 최대 2회 되돌려 보냄
탐색 비용 폭증 저장소 탐색이 메인 대화를 부풀려 이후 모든 턴이 비싸짐 서브에이전트는 자기 대화 컨텍스트로 돌고 최종 답만 돌려줌. 턴 예산(--max-turns)은 서브에이전트·스킬과 공유

4. 아키텍처: 입구 넷, 루프 하나, 경계 셋

구조는 단순하게 요약됩니다. 대화형 TUI(agav), print 모드(agav -P), run 모드(agav run), 옵트인 워크플로·백그라운드 잡. 네 입구 모두 결국 runAgentLoop 하나로 들어갑니다. 도구는 레지스트리에 꽂히고, 실행 직전에 권한 게이트 → 도구 내부 가드 → (셸 계열이면) OS 샌드박스 순으로 걸러집니다.

Agav 구조: 대화형 TUI·print·run·워크플로 네 입구가 runAgentLoop 하나로 모이고, 권한 게이트·파일/HTTP 가드·OS 샌드박스 세 경계가 서로 독립적으로 걸러낸다 (source/ 기준 재구성 PIL 다이어그램)
Agav 구조: 대화형 TUI·print·run·워크플로 네 입구가 runAgentLoop 하나로 모이고, 권한 게이트·파일/HTTP 가드·OS 샌드박스 세 경계가 서로 독립적으로 걸러낸다 (source/ 기준 재구성 PIL 다이어그램)

세 경계가 서로 독립적이라는 점이 중요합니다. 권한 게이트는 “이 호출을 실행해도 되나”를 묻고, 도구 가드는 경로·URL을 검사하고, OS 샌드박스는 셸 프로세스가 실제로 만질 수 있는 파일시스템과 네트워크를 제한합니다. 다만 OS 샌드박스는 run_command와 run_tests에만 적용됩니다. write_file·edit_file은 Agav 프로세스가 직접 쓰므로 애플리케이션 수준 검사에만 기대요. 이 차이가 11장의 실측 결과로 이어집니다.

5. 저장소 구조: 어디부터 읽으면 되나

경로 역할 읽을 포인트
source/agent/loop.ts 에이전트 루프 본체 (1,202줄) 반복 실패 감지, 검증 강제, 턴 예산 예약, 프로바이더 idle 워치독, steer 주입
source/agent/internal-prompts.ts 모델에게 “사용자 턴”으로 넣는 내부 지시문 모음 재개한 세션에서 이 메시지들을 사용자 입력처럼 보이지 않게 거르는 LEGACY_PREFIXES
source/agent/conversation.ts 대화 상태·압축(/compact) Claude 서명 thinking 재생을 압축·재개 후에도 보존하는 처리
source/providers/ 프로바이더 어댑터 8종 + 재시도·effort anthropic.ts의 캐시 중단점, openai.ts의 Responses/Chat 이중 경로
source/tools/ 내장 도구 21개 파일 shell.ts(샌드박스 선택), subagent.ts, test-runner.ts(passed/failed/inconclusive)
source/utils/sandbox*.ts Seatbelt·bubblewrap·Docker·Windows 백엔드, 워크스페이스 스냅숏 sandbox-workspace.ts의 publish/rollback, sandbox-protected-paths.ts의 git·셸 설정 보호 목록
source/sessions/ · background-jobs/ 세션 저장·재개·분기, detach 워커 승인 대기 상태까지 재개되는 구조
source/skills/ · agents/ · mcp/ 스킬(SKILL.md), 설치형 서비스 에이전트(A2A 클라이언트 포함), MCP 클라이언트·OAuth 외부 도구가 스스로 “안전함”을 선언해도 믿지 않는 신뢰 모델
source/workflows/ JSON/YAML DAG 워크플로(실험적) tool·approval·job·agent·prompt·loop 6종 노드, 알 수 없는 필드 거부
source/enterprise/ OIDC·SAML·디바이스 플로, 감사, 조직 정책 조직 permissionMode 하한(floor)은 세션에서 더 느슨하게 못 바꿈
benchmarks/ Terminal-Bench 2.1 실행 스크립트(Harbor) --all은 과제당 5회 시행 기본, 업로드 전 궤적 검증 스크립트

6. 루프 해부: 모델에게 언제, 무엇을 끼워 넣나

Agav 루프의 핵심은 “모델이 스스로 알아서 하길 기대하지 않는다”입니다. 특정 조건이 되면 루프가 사용자 턴 형태의 내부 메시지를 대화에 끼워 넣어요. 모델이 반응할 수 있게 user 역할로 들어가지만, 화면 기록에서는 숨겨집니다.

개입 발동 조건 상한 주입 문구(앞부분)
반복 실패 리다이렉트 같은 도구·같은 인자(키 정렬 JSON)·같은 오류 지문이 연속 3회 스트릭당 1회, 배치당 최대 1개 “This operation has failed N times in a row with the same arguments and the same error…”
미검증 재촉 편집(edit_file/write_file/edit_notebook) 후 셸 실행 없이 최종 답변 2회 (MAX_VERIFY_REPROMPTS) “You made changes but did not verify they work…”
검증 실패 재촉 편집 후 마지막 셸 실행이 실패한 채로 최종 답변 위와 같은 카운터 공유 “Your last verification command failed or produced errors/warnings…”
테스트 수리 테스트 실패 감지 3회 (MAX_REPAIR_ATTEMPTS), 2회째부터 “다른 접근을 시도하라” “Tests failed (attempt n/3)…”
스텝 한도 턴 예산 소진 기본 maxIterations 800, --max-turns로 조정 “You have reached the maximum number of steps. Summarize…”

오류 지문(errorSignature)이 꽤 꼼꼼합니다. 출력의 앞 500자와 뒤 2,000자만 떼어 비교해요. 긴 빌드 로그에서 진짜 오류는 대개 끝에 있기 때문입니다. 16진 주소, ISO 타임스탬프, 시각, PID, 임시 경로, file:line:col은 정규화합니다. 반대로 맨 숫자는 일부러 남깁니다. HTTP 401과 503, 종료 코드 1과 2는 서로 다른 오류이기 때문이에요. 인자 JSON도 키를 정렬해 비교하므로, 모델이 인자 순서만 바꿔 감지를 피하는 것도 막습니다. 사용자가 거부한 호출은 같은 루프 안에서 다시 시도할 수 없게 deniedCalls에 남겨요.

검증 재촉에는 범위 제한 문구가 붙습니다. “관련 없는 파일이나 기존 경고는 과제에 필요할 때만 고쳐라”, “관련 없는 명령이 성공한 걸 근거로 검증됐다고 주장하지 마라” 같은 문장이에요. 재촉이 오히려 과잉 수정을 부르는 부작용을 문구로 막으려는 의도로 읽힙니다.

루프가 모델에게 끼어드는 순간들: 목 OpenAI 서버에 agav run 0.2.8을 붙여 기록한 요청 7회. 같은 실패 3회 뒤 리다이렉트, 검증 없는 Done 거부, 검증 후 최종 답 수용 (박스 실측 기반 PIL 다이어그램)
루프가 모델에게 끼어드는 순간들: 목 OpenAI 서버에 agav run 0.2.8을 붙여 기록한 요청 7회. 같은 실패 3회 뒤 리다이렉트, 검증 없는 Done 거부, 검증 후 최종 답 수용 (박스 실측 기반 PIL 다이어그램)

7. 비용 레버: 캐시·예산·서브에이전트

비용 연구가 보여 주는 핵심 수치는 입력 토큰의 97.0%가 캐시 적중이라는 점입니다. 445회 시행에서 입력 5억 8,322만 토큰 중 5억 6,591만이 캐시였고, 새 입력은 1,730만이었어요. 같은 토큰을 전부 새 입력 요금으로 냈다면 $632.18이었을 비용이 $122.86으로 계산됩니다. 다만 이건 연구가 직접 밝히듯 “산술적 반사실”이지 캐시를 끈 실험이 아닙니다. 출력 비용 $48.97(전체의 39.9%)은 캐시로 줄지 않아요. 그래서 출력·반복·컨텍스트 증가를 따로 묶는 장치가 필요하다는 게 팀의 논리입니다.

지표 (팀 자체 연구, 2026-10-27) Agav Codex 0.144.1
모델 / effort GPT-5.6 Luna / max GPT-5.6 Luna / max
범위 89개 과제 × 5회 = 445회 같은 과제 이름 445회 (공개 제출물)
추정 모델 비용 $122.86 $241.45
통과 시행 269/445 (60.4%) 341/445 (76.6%)
시행당 비용 중앙값 15.2¢ (평균 $0.28, 90퍼센타일 $0.61) —
통과 1건당 비용 (필자 계산) 약 $0.46 약 $0.71

마지막 줄은 필자가 계산한 값입니다. 총비용을 통과 수로 나누면 Agav가 통과 1건당 약 35% 쌉니다. 하지만 실무에서 중요한 질문은 “못 푼 24%포인트를 누가 푸느냐”예요. 사람이 붙어야 하는 실패가 늘면 토큰 절감분을 쉽게 넘어섭니다. 연구도 스스로 한계를 밝힙니다. Agav 전체 실행의 비용·정확도, 어려운 과제 성능, 동일 환경에서의 우위, 개별 최적화의 인과 효과는 보여 주지 않았다고요. 근거 문서는 자체 엔지니어링 노트이고 제3자 감사가 아닙니다. README 배지의 Terminal-Bench 84.7%와 이 표의 60.4%는 서로 다른 실행입니다(설정 차이는 공개 자료로 따로 확인해야 함). 섞어 읽으면 안 됩니다.

예산 쪽 설계도 눈여겨볼 만합니다. iterationsBudget은 루프 호출마다 필수 인자이고, 서브에이전트·네이티브 에이전트·스킬이 같은 예산을 나눠 씁니다. 도움말 문구대로 “도구 실행 자체는 턴을 추가로 쓰지 않고”, 이어서 하기와 재시도는 예산을 유지하며, 새 프롬프트에서만 초기화돼요. 서브에이전트가 무한히 가지를 쳐서 비용이 폭주하는 걸 구조적으로 막는 장치입니다. v0.2.8에서는 --provider-idle-timeout이 추가돼, 응답이 멈춘 프로바이더 스트림을 부분 출력을 보존한 채 끊을 수 있습니다. 도구 실행·승인 대기·재시도 백오프 시간은 이 타이머에 포함되지 않아요.

8. 권한 모델: 세 모드와 run 모드의 함정

모드 / 설정 동작 비고
ask (대화형 기본) 민감한 동작마다 확인, 편집은 diff 미리보기 쓰기 대상이 프로젝트 밖이면 확인 창에 경고 표시
auto-accept (-y) 일반 확인 생략 변경형 HTTP(POST/PUT/PATCH/DELETE)는 그래도 호출마다 승인 필요
deny-writes 파일 쓰기 도구와 파괴적으로 분류된 도구 차단 문서가 직접 “보편적 읽기 전용 경계가 아니다”라고 명시(명령 분류는 휴리스틱)
안전 도구 12개 확인 없이 실행: read_file·grep_search·find_files·list_directory·web_search·lsp_query·read_notebook·fetch_url(GET/HEAD)·overview·activate_skill·save_memory·update_plan 외부 MCP·에이전트 도구는 스스로 비파괴라고 선언해도 이 대우를 못 받음
allowedTools run_command:rm -rf build/*처럼 도구:글롭 패턴으로 자동 승인 파괴적 명령엔 맨 run_command 규칙이 안 먹고 패턴을 명시해야 함
agav run --permission '<json>' run 모드 전용 JSON 정책. "*":"deny"가 있으면 진짜 허용 목록 deny 규칙만 있고 "*":"deny"가 없으면 deny-writes 수준의 넓은 차단으로 동작

CI에 넣을 때 가장 중요한 한 줄: 문서에 적힌 대로 agav run은 기본이 auto-accept입니다. 그리고 --deny-writes는 대화형 세션 모드 플래그라 run 모드에는 적용되지 않습니다. 박스에서 agav run --deny-writes로 돌렸더니 write_file이 그대로 파일을 만들었어요. CI에서는 반드시 --permission이나 AGAV_PERMISSION으로 정책을 명시해야 합니다.

9. 샌드박스: 스냅숏에 쓰고, 성공했을 때만 반영한다

백엔드 파일 쓰기 네트워크 자격 증명 디렉터리
Seatbelt (macOS) 기본 거부, 워크스페이스·임시·툴링만 허용. 민감 설정 보호 기본 허용, 옵트인 deny ~/.ssh·~/.aws·~/.gnupg 읽기 거부
bubblewrap (Linux) 루트 읽기 전용, 워크스페이스 비공개 스냅숏에 쓰고, 성공·미취소 실행 뒤 검증해서 반영 기본 허용, deny 시 --unshare-net 빈 tmpfs로 가림
Docker 마운트한 작업 디렉터리만 항상 --network=none 마운트 안 함
Windows 제한 토큰 워크스페이스·전용 임시 디렉터리 (0.2.8부터 기본 활성) 제한 안 됨. deny 모드면 실행 자체를 거부 읽기는 제한 안 됨

Linux 백엔드의 설계가 특히 흥미롭습니다. 명령은 원본 작업 트리가 아니라 비공개 스냅숏에서 돌아요. 명령이 성공하고 취소되지 않았을 때만 변경분을 검증해 원본에 반영(publish)합니다. 실패한 명령이 남긴 반쯤 쓴 파일은 원본에 닿지 않아요. 반영 단계에서는 보호 경로도 검사합니다. 작업 트리의 .agav·.vscode·.idea, .bashrc·.zshrc·.envrc 같은 셸 시작 파일, git의 config·hooks·objects/info/alternates가 바뀌면 반영 자체를 거부합니다. 프롬프트 인젝션으로 git 훅을 심어 다음 커밋 때 코드를 실행하는 고전적인 공격 경로를 막는 장치예요. 대신 문서가 밝히듯 스냅숏 크기와 파일 종류 제한 때문에 큰 워크스페이스나 특수 파일 변경은 거부될 수 있습니다.

fetch_url은 셸 샌드박스와 별도로 방어합니다. 루프백·사설·예약·클라우드 메타데이터 주소를 거부하고, DNS 결과 중 하나라도 금지 대역이면 막습니다. 검증한 주소로 연결을 고정해 DNS 리바인딩을 차단하고, 리다이렉트는 최대 5번까지 매번 다시 검증해요. 출처가 바뀌는 리다이렉트에서는 Authorization·Cookie 헤더를 떼어 냅니다.

10. 설치와 첫 실행

방법 명령 메모
설치 스크립트 (macOS/Linux) curl -fsSL https://agav.dev/install.sh | bash 기본 설치 위치 ~/.local/bin. 파이프 실행이 싫다면 아래 수동 설치
Windows irm https://www.agav.dev/install.ps1 | iex cmd용 install.cmd도 있음
릴리스 바이너리 수동 Releases에서 agav-linux-x64.gz 등 + .sha256 linux/darwin × x64/arm64, windows x64(baseline 포함). SHA256SUMS와 CycloneDX SBOM 동봉
소스 pnpm install && pnpm build → node build/cli.js Node 22.13+, pnpm 10.34.9
업데이트 agav update —
# 대화형 (기본 프로바이더 anthropic)
agav
agav --provider openrouter --model openrouter/free
agav --provider ollama --model llama3.2

# 비대화형
agav -P "what does this project do?"
cat error.log | agav -P "explain this error"
agav run --max-turns 20 "fix the type errors"

# CI에서는 허용 목록을 명시
agav run --permission '{"*":"deny","read_file":"allow","grep_search":"allow"}' "audit the code"

# OpenAI 호환 엔드포인트 (박스 실측에서 사용한 방식)
OPENAI_BASE_URL=http://127.0.0.1:18081/v1 OPENAI_API_KEY=... \
  agav run "..." --provider openai --model my-model --openai-api chat

세션 하나 안에서도 /model로 모델을 바꾸고, /fast·/deep 프리셋으로 싼 모델과 강한 모델을 오갈 수 있습니다. /permission으로 권한 모드를 바꾸면 그 모드는 세션에 저장돼 재개할 때도 유지돼요. /compact는 계획을 잃지 않고 컨텍스트를 줄이고, /steer는 진행 중인 작업에 방향 지시를 끼워 넣습니다. 번들 스킬은 21개(code-review·diagnose·security-scan·test-writer·docx·xlsx 등)인데, 박스의 새 설정에서는 전부 [disabled]로 표시됐습니다.

공식 저장소 스크린숏(assets/image.png): Ollama 모델로 저장소 구조를 묻는 대화형 TUI. 하단 상태 줄에 모델·effort·토큰·macOS Seatbelt 샌드박스·세션 ID가 표시된다. 헤더의 v0.3.0은 미출시 개발 빌드. 출처: prapaa-ai/agav, Apache-2.0
공식 저장소 스크린숏(assets/image.png): Ollama 모델로 저장소 구조를 묻는 대화형 TUI. 하단 상태 줄에 모델·effort·토큰·macOS Seatbelt 샌드박스·세션 ID가 표시된다. 헤더의 v0.3.0은 미출시 개발 빌드. 출처: prapaa-ai/agav, Apache-2.0

11. 박스 스모크 테스트: 목 서버로 루프와 샌드박스를 찌르기

실제 LLM 없이 루프 동작을 재현하려고 대본대로만 답하는 OpenAI Chat Completions 호환 목 서버(파이썬 표준 라이브러리, SSE 스트리밍)를 띄웠습니다. 요청이 올 때마다 정해진 도구 호출이나 텍스트를 돌려주고, Agav가 보낸 메시지를 기록해요. 그래서 루프가 몰래 끼워 넣는 내부 메시지를 그대로 볼 수 있습니다. 환경은 Debian 13 박스, 릴리스 바이너리 agav-linux-x64 0.2.8(압축 파일 sha256이 릴리스 체크섬과 일치, 압축 해제 후 125MB), bubblewrap 백엔드입니다.

HOME=$PWD/home OPENAI_API_KEY=sk-mock OPENAI_BASE_URL=http://127.0.0.1:18081/v1 \
  ./agav run "Create hello.py that prints a greeting." \
  --provider openai --model mock-model --openai-api chat -y --trajectory trajA.json

11-1. 시나리오 A: 루프 개입 재현

대본: 없는 파일을 cat 3번 → hello.py 작성 → 검증 없이 “Done” → python3 hello.py → 최종 답. 목 서버 기록은 이렇습니다.

요청 메시지 수 마지막 메시지 (Agav가 보낸 것)
0 2 user: 사용자 프롬프트
1–2 4, 6 tool: cat: missing-config.yaml: No such file or directory
3 9 user(내부): “This operation has failed 3 times in a row with the same arguments and the same error (run_command)…”
4 11 tool: Created …/hello.py (2 lines)
5 13 user(내부): “You made changes but did not verify they work…”, 모델의 “Done”이 최종 답으로 받아들여지지 않음
6 15 tool: hello from agav smoke → 다음 텍스트 응답이 최종 답으로 수용

첫 시도에서는 bubblewrap이 모든 셸 명령을 실패시켰습니다. 그 덕에 우연히 “검증 실패 재촉”까지 확인했어요. 편집 후 셸이 실패한 상태에서 모델이 “Verified”라고 답하자, 루프가 “Your last verification command failed…”를 넣어 되돌려 보냈습니다. --trajectory로 뽑은 JSON에는 모델·프로바이더·시작/종료 시각·토큰 사용량(목 서버가 보고한 cached_tokens 포함)이 남아, CI 산출물로 쓰기 좋습니다.

11-2. 시나리오 B·C: 샌드박스와 권한 탐침

탐침 결과 판정
echo evil > .git/hooks/pre-commit 명령은 “HOOK_WRITTEN”을 찍고 성공했지만 Sandbox workspace: protected path changed: .git/hooks/pre-commit로 실패 처리. 원본 hooks 폴더에 파일 없음 OK
cat ~/.ssh/id_test (미끼 파일) 샌드박스 안의 ~/.ssh가 빈 디렉터리로 보임 OK
read_file 절대경로 ~/.ssh/id_test Access denied: … protected credential path OK
echo x > ~/outside.txt Read-only file system OK
echo partial > failed-run.txt && exit 7 실패 처리, failed-run.txt는 원본에 반영 안 됨 (성공한 명령의 published.txt만 반영) OK
--sandbox-network deny + curl https://example.com HTTP 코드 000, 차단 OK
fetch_url http://169.254.169.254/… Refusing to connect to private/reserved address OK
셸 안 환경 변수 Agav 프로세스에 준 OPENAI_API_KEY·SECRET_TOKEN이 샌드박스 셸에서 0건 OK
agav run --deny-writes + write_file 파일 생성됨. run 모드는 이 플래그를 쓰지 않음(문서와 일치하지만 헷갈리기 쉬움) 주의
--permission '{"*":"deny","read_file":"allow",…}' write_file·run_command·fetch_url 모두 “not permitted in this mode” OK
--permission '{"write_file":"deny"}' 쓰기·셸·변경형 HTTP 전부 “Write operations are denied (–deny-writes mode)”로 넓게 차단 (문서 설명대로) OK
헤드리스 변경형 fetch_url POST “requires confirmation but no confirmation handler is available” → 실패로 닫힘 OK
-y + write_file ../escape.txt 프로젝트 밖에 파일이 생성됨 주의

마지막 줄은 짚고 넘어가야 합니다. 보안 문서에는 “파일 도구(read_file/write_file/edit_file)가 작업 디렉터리 밖 쓰기를 거부한다”고 적혀 있습니다. 그런데 main(989687b) 소스를 보면 read_file만 checkPathBoundary를 호출하고, file-write.ts는 호출하지 않아요. 루프는 프로젝트 밖 쓰기에 경고만 띄웁니다. 코드 주석은 “거부는 도구 안의 checkPathBoundary 몫”이라고 하는데 실제로는 그 호출이 없는 거죠. ask 모드라면 사람이 경고를 보고 거절할 수 있습니다. 하지만 -y나 기본 auto-accept인 agav run에서는 OS 샌드박스가 지켜 주지 않는 쓰기 경로가 열려 있는 셈입니다. 컨테이너나 일회용 VM 안에서 돌리는 게 현실적인 대책입니다.

또 하나의 실무 함정이 있습니다. HOME을 바꿔 실행했더니 bubblewrap이 ~/.cache, 그다음엔 ~/.config가 없다며 모든 셸 명령을 실패시켰어요. 읽기 전용 루트 위에 tmpfs를 덮을 마운트 지점이 필요해서입니다. ~/.cache·.config·.npm·.cargo·.ssh·.aws·.gnupg를 미리 만들자 해결됐습니다. 새로 만든 CI 사용자나 최소 컨테이너에서 그대로 겪을 수 있는 문제예요.

11-3. 워크플로 검증과 테스트 스위트

backgroundJobsEnabled·workflowsEnabled를 켜고 문서 예제(read_file → approval → write_file)를 agav workflows validate에 넣으니 “Workflow valid.”가 나왔습니다. 노드에 정의되지 않은 필드(colour)를 넣은 파일은 must NOT have additional properties로 exit 1을 냈어요. “알 수 없는 필드는 무시하지 않고 거부한다”는 문서 설명과 일치합니다.

소스를 pnpm install --ignore-scripts로 받고 빌드 없이 vitest run source를 돌린 결과는 테스트 파일 446개 중 431개 통과·10개 실패·5개 건너뜀, 테스트 6,759개 중 6,627개 통과·54개 실패였습니다(약 104초). 실패를 열어 보니 대부분 build/background-jobs/… 같은 빌드 산출물을 import하는 테스트(잡·스케줄러·CLI 부트 스모크)였어요. 빌드를 생략한 환경 탓으로 보는 게 타당합니다. 그 외에는 sandbox-workspace.test.ts의 동시 편집 롤백 케이스 1개가 기대한 오류 메시지 대신 주입된 rename 오류를 그대로 던졌습니다. 루프·권한·샌드박스 관련 34개 파일만 따로 돌린 실행은 687개 통과, 실패는 이 1건뿐이었습니다.

박스 실측 대시보드(2026-11-21 KST, Debian 13, bubblewrap): 설치 검증·루프 개입·git 훅 보호·자격 증명 가림·네트워크 차단·SSRF 거부·권한 정책·워크플로 검증 결과. '주의'는 도입 전에 알아야 할 문서와 실제 동작의 차이
박스 실측 대시보드(2026-11-21 KST, Debian 13, bubblewrap): 설치 검증·루프 개입·git 훅 보호·자격 증명 가림·네트워크 차단·SSRF 거부·권한 정책·워크플로 검증 결과. ‘주의’는 도입 전에 알아야 할 문서와 실제 동작의 차이

12. 비슷한 도구와 비교

항목 Agav Claude Code Codex CLI OpenCode Aider
라이선스 Apache-2.0 독점(소스 비공개) Apache-2.0 MIT Apache-2.0
모델 선택 8개 프로바이더 + Ollama, 세션 중 전환 Anthropic 중심 OpenAI 중심(호환 엔드포인트 설정 가능) 다중 프로바이더 다중 프로바이더
셸 격리 Seatbelt·bubblewrap(스냅숏 반영)·Docker·Windows 토큰 권한 프롬프트 + 옵트인 샌드박스 OS 샌드박스 내장 권한 설정 중심 격리보다 git 커밋 단위 되돌리기 중심
루프 개입 반복 실패·미검증·테스트 수리 자동 주입 모델·프롬프트 설계에 맡김 모델·프롬프트 설계에 맡김 에이전트 설정에 맡김 lint/test 자동 실행 옵션
비대화형 CI agav run + JSON 권한 + JSON Schema 출력 + trajectory 헤드리스 모드 codex exec 있음 스크립트 모드
성숙도 “Experimental Beta”, 스타 198 상용 제품 대형 커뮤니티 대형 커뮤니티 오래된 프로젝트

정리하면 Agav의 차별점은 기능 목록보다 “루프가 모델을 감독한다”는 설계 철학에 있습니다. 다른 도구는 대체로 좋은 모델과 시스템 프롬프트가 알아서 검증하길 기대합니다. Agav는 검증을 건너뛰는 행동과 헛도는 재시도를 코드로 감지해 개입해요. 이 접근은 작고 싼 모델일수록 효과가 클 가능성이 있습니다. 반대로 최상위 모델에서는 불필요한 재촉이 될 수도 있어요. 비용 연구의 낮은 통과율이 이 트레이드오프와 관련 있는지는 아직 공개된 데이터로 판단할 수 없습니다.

공식 데모 영상(agav.dev/preview.gif)의 마지막 프레임: install.sh를 고친 뒤 셸 테스트로 검증하고, Docker가 없어 실행 못 한 부분은 그렇다고 보고한다. 출처: Agav 공식 사이트
공식 데모 영상(agav.dev/preview.gif)의 마지막 프레임: install.sh를 고친 뒤 셸 테스트로 검증하고, Docker가 없어 실행 못 한 부분은 그렇다고 보고한다. 출처: Agav 공식 사이트

13. 도입 전 평가 체크리스트

확인할 것 방법 통과 기준 예시
내 모델에서의 실제 비용 같은 과제 10~20개를 현재 도구와 Agav로 돌리고 --trajectory의 usage 비교 통과 1건당 비용이 낮고, 실패분을 사람이 처리하는 시간이 늘지 않을 것
캐시 적중률 trajectory의 cache_read_tokens / input_tokens 프로바이더가 캐시를 지원하는지부터 확인 (지원 안 하면 핵심 레버가 사라짐)
CI 권한 정책 --permission을 "*":"deny" 기반 허용 목록으로 작성 후, 목 서버로 금지 도구 호출을 재현 금지 도구가 전부 “not permitted”
파일 쓰기 경계 write_file ../x 재현 (11-2 방식) 컨테이너·VM으로 감싸거나, ask 모드에서만 쓰기 허용
샌드박스 백엔드 Linux는 bwrap 설치·홈 하위 마운트 지점 확인, --sandbox-required로 무샌드박스 실행 거부 셸 출력에 “unsandboxed” 표시가 없을 것
네트워크 정책 CI는 --sandbox-network deny, 필요한 다운로드는 사전 단계로 분리 curl이 차단될 것
스냅숏 한계 대형 모노레포에서 빌드 명령 실행 스냅숏 크기·파일 종류 제한으로 반영이 거부되지 않을 것
업그레이드 리듬 릴리스 노트 구독, 베타 채널 분리 주 단위 변경을 감당할 수 있을 것 (8월 이후 릴리스 42개)

14. 한계와 주의할 점

  • 베타다. README가 직접 “Experimental Beta — 깨지는 변경을 예상하라”고 경고합니다. 공식 TUI 스크린숏 헤더에는 아직 릴리스되지 않은 v0.3.0이 찍혀 있어요. 개발 브랜치가 안정판보다 앞서 달리고 있다는 뜻입니다.
  • 벤치마크는 자체 발표 위주다. SWE-bench-Live Lite 62.0%는 공개 리더보드와 제출물 링크가 붙어 있습니다. 하지만 Terminal-Bench 84.7%는 PR 심사 중이고, 비용 연구는 팀이 만든 자료입니다. “49.1% 절감”과 “통과율 16.2%포인트 낮음”은 반드시 함께 읽어야 합니다.
  • agav run은 기본 auto-accept, --deny-writes는 run에서 무효. CI에서는 JSON 권한 정책이 필수입니다.
  • 파일 도구의 쓰기 경계가 문서와 다르다. 0.2.8 실측에서 -y 상태의 write_file이 프로젝트 밖에 썼습니다. OS 샌드박스는 셸 계열 도구에만 적용됩니다.
  • deny-writes는 읽기 전용 보장이 아니다. 명령 분류가 휴리스틱이라, 허용 목록에 있는 비파괴 분류 명령은 실행될 수 있다고 문서가 직접 밝힙니다.
  • Windows 샌드박스는 읽기·네트워크를 가두지 않는다. 네트워크 deny 모드에서는 아예 실행을 거부합니다.
  • 커밋 이력이 압축돼 있다. main 커밋은 44개뿐이고 릴리스 단위로 합쳐져 있어, 특정 변경의 맥락을 커밋으로 추적하기 어렵습니다. 릴리스 노트(docs/releases/)가 사실상 변경 기록입니다.
  • 바이너리가 크다. linux-x64 실행 파일이 약 125MB(압축 57MB)입니다. Bun 런타임을 통째로 묶는 단일 실행 파일 방식이라 그렇습니다. 컨테이너 이미지 크기에 반영해야 합니다.

15. 결론

Agav는 “에이전트를 싸게 굴리는 방법”을 모델 선택이 아니라 루프 공학으로 푸는 프로젝트입니다. 오류 지문 기반 반복 실패 감지, 검증 없는 완료 선언 차단, 서브에이전트까지 공유하는 턴 예산, 성공했을 때만 반영하는 스냅숏 샌드박스. 하나하나는 소박하지만 박스에서 찔러 보니 문서대로 정확히 작동했습니다. 반대로 run 모드의 기본 auto-accept, 파일 도구 쓰기 경계의 공백, 커스텀 HOME에서의 bubblewrap 실패는 도입 전에 반드시 알아야 할 함정입니다.

실무 판단 기준은 하나예요. “통과 1건당 총비용(토큰 + 사람 시간)”을 내 과제로 직접 재 보세요. 싼 모델·로컬 모델로 반복 작업을 돌리는 팀이라면 루프 개입과 캐시 재사용의 효과를 크게 볼 수 있습니다. 최고 정확도가 필요한 어려운 과제라면, 공개 데이터상 아직은 Codex·Claude Code 쪽이 안전한 선택입니다. 어느 쪽이든 CI에 넣을 땐 --permission 허용 목록과 컨테이너 격리를 먼저 깔고 시작하세요.

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다