SandBase Harness, 도구 실행이 멈췄을 때 승인 흐름을 확인하는 법
에이전트가 도구 호출 앞에서 멈췄다면 오류부터 찾기보다 권한 정책과 승인 이벤트를 함께 확인하는 편이 빠릅니다. SandBase Harness는 도구 요청, 사용자 승인, 실행 결과를 세션 이벤트로 남기므로 로컬 콘솔에서 흐름을 따라갈 수 있습니다. 승인은 한 번의 도구 호출에만 실행 권한을 줍니다.
30초 요약
- SandBase Harness v0.3.8은 Node.js 22 이상에서 실행하는 로컬 우선 에이전트 런타임입니다.
- 로컬 콘솔은
http://127.0.0.1:3000/dashboard에서 열립니다.- 에이전트의 도구 설정과
permission_policy를 먼저 보고, 세션 타임라인에서 도구 요청과 승인 결과를 이어서 확인합니다.- 공식 API의 승인 응답은
user.tool_confirmation이벤트이며tool_use_id와result: "allow"를 담습니다.- 로컬 샌드박스는 보안 경계가 아니므로 신뢰하지 않는 명령은 Docker나 Kubernetes에서 검증해야 합니다.
SandBase Harness는 무엇을 나눠서 보여주나
SandBase Harness는 모델에게 답을 받는 반복문만 제공하는 도구가 아닙니다. 에이전트 정의, 세션, 샌드박스, 도구, 자격 증명, 이벤트 기록을 한 런타임에서 관리하고 같은 프로세스가 React 기반 콘솔을 제공합니다.
생활 비유로 보면 에이전트는 작업 지시서, 세션은 작업 건, 샌드박스는 작업실입니다. 권한 정책은 출입 규칙이고 승인 이벤트는 서명된 출입증에 가깝습니다. 규칙과 기록을 분리해 보면 “왜 멈췄는지”와 “누가 실행을 허용했는지”를 섞지 않게 됩니다.
공식 설계 문서의 실행 흐름은 단순합니다. 사용자 메시지가 이벤트 로그에 들어가고, 모델이 도구 호출을 만들면 정책을 확인한 뒤 도구가 실행되며, 결과와 상태 변화가 다시 이벤트 로그에 쌓입니다. 콘솔은 별도 데이터베이스를 몰래 읽는 화면이 아니라 공개 API와 서버 전송 이벤트(SSE)를 사용하는 클라이언트입니다.
설치 전에 버전과 배포 경로부터 고정하세요
확인일인 2026년 9월 20일 기준 공식 최신 릴리스 표시는 v0.3.8, 공개일은 2026년 8월 30일입니다. package.json은 Node.js 22 이상과 Apache-2.0 라이선스를 명시합니다.
공식 문서는 태그가 고정된 소스를 내려받는 방식을 안내합니다. 동명의 비공식 npm 패키지를 피하기 위한 선택이므로 npx managed-agents부터 입력하지 않는 편이 안전합니다.
git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build
mkdir ../my-agents && cd ../my-agents
node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start
시작 로그에서 API 주소, 대시보드 주소, 불러온 에이전트, 샌드박스 제공자, 인증 상태를 확인합니다. 브라우저 주소는 다음과 같습니다.
http://127.0.0.1:3000/dashboard
이 글의 명령과 화면 흐름은 공식 v0.3.8 문서에 근거한 재현 절차입니다. 별도의 실측 성능이나 실제 운영 후기를 뜻하지 않습니다.
도구 권한은 어디에서 확인하나
에이전트 정의에는 도구 목록과 기본 설정이 함께 들어갑니다. 공식 Usage Guide의 YAML 예시는 내장 도구 세트를 켜고 권한 정책을 always_allow로 둡니다.
tools:
- type: agent_toolset_20260401
default_config:
enabled: true
permission_policy:
type: always_allow
always_allow는 승인 대기를 관찰하려는 데모와 맞지 않습니다. 승인 흐름을 시험할 때는 자동 허용 정책을 그대로 두지 마세요. 현재 빌드의 에이전트 편집 화면에서 확인을 요구하는 정책을 제공한다면 그 옵션을 선택하고, 화면에 없는 정책 이름을 YAML에 추측해서 넣지는 않습니다.
도구 이름만 보는 것도 부족합니다. 기본 로컬 도구 세트에는 bash, read, write, edit, glob, grep가 포함됩니다. 어떤 도구가 켜졌는지, 어떤 정책이 붙었는지, 어느 샌드박스에서 실행되는지를 한 묶음으로 확인해야 합니다.
| 확인 대상 | 콘솔에서 볼 곳 | 판단할 내용 |
|---|---|---|
| 에이전트 도구 | Agents의 해당 버전 | 허용된 도구와 permission_policy |
| 실행 환경 | Environments 또는 Settings > Sandbox | local, docker, kubernetes, self-hosted 중 실제 등록된 제공자 |
| 승인 대기 | Sessions의 해당 세션 타임라인 | 도구 요청 뒤 사용자 확인이 필요한지 |
| 실행 결과 | 같은 타임라인과 이벤트 | 승인한 호출의 결과·오류·상태 변화 |
| 런타임 진단 | Settings > Logs, Monitoring | 미등록 백엔드나 기능 부족 경고 |
최소 데모는 읽기보다 쓰기 요청이 분명합니다
빈 작업 공간에서 파일 하나를 만드는 요청은 입력과 출력이 작고 성공 여부도 눈에 보입니다. 다음 프롬프트는 문서 기반 예상 동작 예시이며, 승인 정책을 실제로 선택한 뒤 사용해야 합니다.
현재 세션 작업 공간에 hello.txt 파일을 만들고,
내용을 SandBase approval demo 한 줄로 저장해 주세요.
도구 실행이 필요하면 먼저 요청하고 결과를 알려 주세요.
예상 흐름은 사용자 메시지 → write 도구 요청 → 승인 대기 → 사용자 허용 → 도구 결과 → 에이전트 응답입니다. 파일이 생겼다는 최종 답만 보지 말고, 세션 타임라인에서 요청과 승인 사이에 같은 tool_use_id가 이어지는지 확인합니다.
API 수준에서 사용자가 허용할 때 보내는 이벤트 형식은 다음과 같습니다.
{
"events": [
{
"type": "user.tool_confirmation",
"tool_use_id": "toolu_abc123",
"result": "allow"
}
]
}
공식 v0.3.8 변경 기록은 확인된 도구 호출을 원시 AI SDK v4 스트림 수명주기 데이터와 대조한다고 설명합니다. 형식이 깨졌거나 미완성·중복·투영만 된 호출은 거부하고, 검증된 호출에만 일회성 실행 권한을 줍니다.
승인 버튼이 눌렸다는 사실과 도구 실행 성공은 별개입니다. 승인은 호출을 진행시킬 뿐이며 파일 경로 오류, 샌드박스 준비 실패, 명령 실패는 이후의 도구 결과에서 따로 확인해야 합니다.
콘솔에서 승인 과정이 안 보일 때 무엇부터 볼까
첫째, 에이전트 버전을 확인합니다. 세션을 특정 에이전트 버전에 고정하면 나중에 에이전트 정의를 바꿔도 해당 세션의 프롬프트·도구·스킬은 바뀌지 않습니다. 정책을 수정한 뒤 예전 세션만 새로고침하면 변화가 없는 이유입니다.
둘째, 세션 상태와 이벤트 순서를 봅니다. 공식 상태 머신에는 사용자 입력이 필요한 requires_action이 있으며, 이벤트 로그에는 사용자 메시지·도구 호출·도구 결과·상태 변화·오류가 지속됩니다. 도구 요청 이벤트 자체가 없다면 승인 UI보다 모델과 도구 해석 단계를 먼저 점검해야 합니다.
셋째, 샌드박스 등록 상태를 확인합니다. Docker 데몬이나 Kubernetes 클러스터에 연결할 수 없으면 해당 백엔드는 등록되지 않습니다. 격리 백엔드를 요청했는데 사용할 수 없을 때 로컬 실행으로 조용히 바꾸지 않고 세션을 실패시키는 설계입니다.
넷째, 설정을 저장한 뒤 재시작 표시를 놓치지 않습니다. Settings V2의 첫 릴리스 필드는 저장값과 현재 적용값을 나눠 보여주며, Restart required가 보이면 재시작 전까지 기존 설정이 계속 적용됩니다.
curl http://127.0.0.1:3000/v1/sessions/SESSION_ID/events
콘솔 화면만으로 순서가 애매하면 위 API로 지속 이벤트를 확인할 수 있습니다. 실시간 스트림은 Last-Event-ID로 이어 받을 수 있지만, 일시적인 스트림 조각은 저장되지 않을 수 있으므로 감사 판단에는 지속된 이벤트를 기준으로 삼는 편이 낫습니다.
로컬 실행을 샌드박스라고 안심하면 안 됩니다
공식 Usage Guide는 로컬 프로세스를 보안 경계로 보지 않습니다. 파일 도구는 세션 작업 공간으로 제한되고 자식 프로세스 환경도 허용 목록으로 줄이지만, 셸 명령은 런타임과 같은 운영체제 사용자로 실행되어 작업 공간 밖을 읽거나 네트워크에 접근할 수 있습니다.
신뢰하지 않는 에이전트 출력은 local이 아니라 Docker나 Kubernetes에서 실행하세요. 두 백엔드는 런타임 호스트와 격리되고 자원 제한도 지원하지만, 실제 보호 수준은 이미지·네트워크·볼륨·권한 설정에 달려 있습니다.
Kubernetes를 쓸 때 서비스 계정을 비워 두면 문서 예시상 automountServiceAccountToken: false로 생성됩니다. 클러스터 접근이 꼭 필요할 때만 서비스 계정을 지정하고 RBAC 범위를 좁히는 방식이 안전합니다.
API를 신뢰된 로컬 네트워크 밖에 노출할 때는 인증도 별도 문제입니다. 로컬 개발에서는 인증이 기본 비활성화이며 API 키가 하나라도 생기면 활성화됩니다. 공개 전에 관리 API 키를 만들고 Bearer 인증을 적용해야 합니다.
바이브코딩으로 확장할 때는 감사 결과를 산출물로 남기세요
승인 화면을 한 번 확인하는 데서 멈추면 다음 변경에서 다시 수동으로 찾아야 합니다. 작은 내부 도구로 발전시키려면 세션 이벤트를 읽어 승인 요청, 사용자 응답, 도구 결과를 같은 호출 ID로 묶은 보고서를 만들 수 있습니다.
다음은 코딩 에이전트에 전달할 수 있는 확장 프롬프트입니다. 구현 전 현재 v0.3.8 API 응답 스키마를 다시 확인하도록 범위를 좁혔습니다.
SandBase Harness v0.3.8의 공식 /v1 세션 이벤트 API만 사용해 주세요.
입력은 base URL과 session ID입니다.
지속된 이벤트를 읽어 tool_use_id 기준으로
1) 도구 요청, 2) user.tool_confirmation, 3) 도구 결과를 묶고,
누락·중복·순서 역전을 경고하는 TypeScript CLI를 작성해 주세요.
원문 비밀값은 출력하지 말고, 먼저 API 응답 타입과 오류 처리를 제시한 뒤
샘플 이벤트를 사용하는 단위 테스트를 추가해 주세요.
실제 스키마에 없는 필드는 만들지 마세요.
제품화할 수 있는 지점은 팀별 승인 이력 내보내기, 변경 전후 정책 비교, 세션별 미완료 호출 경고입니다. 다만 v0.3.8 문서에는 범용 커스텀 도구 등록·발견이 아직 계획 단계라고 적혀 있습니다. 현재 구현과 계획 기능을 섞지 않는 것이 첫 번째 제품 요구사항입니다.
누구에게 맞고, 언제 더 가벼운 선택이 나을까
세션을 오래 유지하면서 도구, 자격 증명, 메모리, 감사·재생까지 같은 로컬 제어면에서 보고 싶은 팀에 맞습니다. 권한 정책을 코드와 콘솔에서 함께 검토해야 하는 에이전트 인프라 실험에도 유용합니다.
모델 하나를 호출하고 결과만 받는 짧은 스크립트라면 런타임 전체가 과할 수 있습니다. 공식 README도 가벼운 연결만 필요할 때는 별도 SandBase CLI를 안내합니다. 단순성보다 세션 상태와 승인 이력이 필요한 시점에 Harness를 선택하면 됩니다.
작업 환경을 함께 정리한다면
콘솔 타임라인과 터미널 로그를 나란히 비교하려면 휴대용 모니터가 창 전환을 줄이는 데 도움이 됩니다. 아래 제품은 USB-C 연결과 화면 확장이 필요한 장면에 맞춰 골랐지만, 노트북의 USB-C 영상 출력 지원 여부와 제품 사양은 구매 전에 상품 페이지에서 다시 확인해야 합니다.
외부 화면을 연결한 채 전원과 주변기기를 함께 쓰려면 PD와 HDMI를 지원하는 멀티허브가 편합니다. 이 카드는 연결 편의 역할로 분리했으며, 필요한 포트 수와 노트북·모니터의 HDMI 규격 및 PD 입력 조건은 실제 구성과 대조해야 합니다.
이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
출처
- SandBase Harness 공식 저장소: https://github.com/sandbaseai/sandbase-harness
- 공식 README: https://raw.githubusercontent.com/sandbaseai/sandbase-harness/v0.3.8/README.md
- 공식 Usage Guide: https://raw.githubusercontent.com/sandbaseai/sandbase-harness/v0.3.8/docs/usage.md
- 공식 API Reference: https://raw.githubusercontent.com/sandbaseai/sandbase-harness/v0.3.8/docs/api.md
- 공식 Requirements: https://raw.githubusercontent.com/sandbaseai/sandbase-harness/v0.3.8/docs/spec/requirements.md
- 공식 Architecture: https://raw.githubusercontent.com/sandbaseai/sandbase-harness/v0.3.8/docs/spec/architecture.md
- 공식 Changelog: https://raw.githubusercontent.com/sandbaseai/sandbase-harness/v0.3.8/CHANGELOG.md
- 공식 v0.3.8 릴리스: https://github.com/sandbaseai/sandbase-harness/releases/tag/v0.3.8
- Apache-2.0 라이선스: https://raw.githubusercontent.com/sandbaseai/sandbase-harness/v0.3.8/LICENSE
핵심 정리: 다섯 가지 질문과 답
Q. 도구 호출 앞에서 멈추면 가장 먼저 무엇을 보나요?
에이전트 버전의 도구 목록과 permission_policy를 확인한 뒤 같은 세션의 도구 요청 이벤트를 봅니다.
Q. 승인은 어디에 기록되나요?
공식 API에서는 user.tool_confirmation 이벤트에 tool_use_id와 허용 결과가 기록됩니다.
Q. 승인하면 같은 도구를 계속 실행할 수 있나요?
v0.3.8 변경 기록은 검증된 호출 하나에 일회성 실행 권한을 부여한다고 설명합니다.
Q. local 샌드박스면 신뢰하지 않는 명령도 안전한가요?
아닙니다. 로컬 프로세스는 보안 경계가 아니며, 신뢰하지 않는 출력에는 Docker나 Kubernetes를 검토해야 합니다.
Q. 설정을 바꿨는데 기존 세션이 그대로인 이유는 무엇인가요?
세션이 에이전트 버전에 고정됐거나 저장한 Settings V2가 재시작 전이라 아직 적용되지 않았을 수 있습니다.
'AI > 오픈 소스 소개' 카테고리의 다른 글
| Smithers 0.35.0 복구 데모, 실패한 에이전트 작업을 처음부터 다시 돌리기 전에 (0) | 2026.09.22 |
|---|---|
| VeloxQuant-MLX로 긴 대화를 붙잡을 때, 압축률보다 먼저 볼 것 (0) | 2026.09.21 |
| Obsidian 노트 검색 AI, 하루 MVP는 어디까지 만들까 (0) | 2026.09.14 |
댓글