Butterneck이 사용자의 로컬 머신에서 샌드박스 내 AI 코딩 에이전트를 실행하는 방법

Butterneck은 제품 관리자(product manager)나 클라이언트가 앱의 라이브 복사본에 변경을 요청하면, 코딩 에이전트가 해당 수정을 수행하도록 합니다. 이 에이전트는 저희 서버에서 실행되지 않습니다. 대신 개발자가 이미 로그인한 코딩 CLI(Command Line Interface)를 사용하여 개발자 자신의 컴퓨터에서 실행됩니다. 사용되는 CLI는 Cursor (agent), Claude Code (claude), 또는 Antigravity (agy)입니다.

본 게시물에서는 이것이 어떻게 작동하는지, 그리고 실제 가드레일(guardrails)이 무엇인지 자세히 설명합니다. 여기서 '가드레일'은 하드 블록(hard block)이라기보다는 프롬프트 지침을 의미하며, 그러한 경우에만 그렇게 명시합니다.

구성 요소 (The pieces)

• 브릿지(The bridge). 개발자가 자신의 계정과 연결하는 작은 Node.js 데몬(Node 22 이상)입니다. 이 브릿지는 개발자가 연결한 프로젝트 폴더를 감시하고, 앱을 시작하며, Butterneck 서버와 WebSocket 연결을 유지합니다.
• 채팅 서버(The chat server). 연결된 각 폴더마다 브릿지와 함께 인프로세스(in-process)로 실행됩니다. 요청이 도착하면 프롬프트를 구성하고 코딩 CLI를 자식 프로세스(child process)로 시작합니다.
• 채팅 위젯(The chat widget). 라이브 미리 보기 화면에 임베드된 스크립트로, 요청하는 사람이 원하는 화면 옆에 직접 입력할 수 있게 합니다.

코딩 CLI는 비대화형 출력 모드(non-interactive print mode)로, 한 번의 턴(turn)씩 호출됩니다. 예를 들어, Cursor의 에이전트는 --print, --trust, --force, 그리고 --workspace <폴더> 플래그와 함께 시작됩니다. Claude Code는 --print와 자체적인 --system-prompt를 사용합니다. Antigravity는 --mode accept-edits와 --add-dir <폴더>로 실행됩니다.

이러한 플래그들은 중요합니다. CLI가 실행될 때, 터미널에 사람이 있어서 '허용(allow)'을 클릭할 수 없기 때문에 자체적인 권한 프롬프트는 건너뛰어집니다. 따라서 아래의 경계들이 한 턴이 제자리를 지키도록 유지하는 요소들입니다.

격리: 요청 스트림당 하나의 폴더 (Isolation: one folder per request stream)

각 개인 복사본(저희가 샌드박스라고 부릅니다)은 개발자의 컴퓨터에 있는 특정 폴더와 연결됩니다. 이 폴더는 개발자가 선택합니다. 다음 중 하나일 수 있습니다:

• 기존 프로젝트 폴더,
• 리포지토리의 새로운 클론(clone),
• 선택된 리포 내부에 .worktrees/ 아래에 생성된, 샌드박스 이름으로 지정된 git worktree (브릿지는 .worktrees/를 .gitignore에 추가합니다).

Worktrees는 팀이 여러 요청을 동시에 처리해야 할 때 유용한 옵션입니다. 각 작업은 자체 체크아웃과 브랜치를 가지며, 메인 작업 복사본(main working copy)에는 영향을 주지 않습니다.

에이전트의 작업 디렉터리는 해당 폴더로 설정됩니다. 시스템 프롬프트에는 필수적인 "파일 접근 경계(File access boundaries)" 섹션이 포함되어 있습니다: 첨부된 폴더 내부에서만 읽고 편집하며, 외부에는 절대 쓰기, 이동 또는 삭제해서는 안 됩니다.

정확히 말하자면: 이 경계는 에이전트에게 주어진 지침과 CLI 자체의 작업 공간 설정이 결합된 것입니다. 이는 컨테이너나 별도의 사용자 계정과 같은 OS 레벨 샌드박스가 아닙니다. 프로세스는 개발자 권한으로 실행됩니다.

비밀 정보(Secrets): .env는 항상 무시 목록에 포함됨

비활성화할 수 없는 내장 무시 목록이 있습니다:

.env
.env.*
**/.env
...

팀은 자체 글롭(glob)을 추가할 수 있습니다 (예: config/secrets/ 또는 *.pem). 브릿지(bridge)는 이 두 목록을 병합하고, 절대 경로이거나 ..를 포함하는 것은 제거하며, 결과를 프로젝트가 아닌 샌드박스 데이터 옆에 저장합니다.

병합된 목록은 시스템 프롬프트에 들어갑니다: 이 경로들은 절대 건드리지 말아야 하며, 이들이 필요한 요청 부분은 거부해야 합니다. 동일한 매처(isPathAllowed)는 코드 내 검사를 위해 CLI 패키지에 의해 내보내집니다.

위와 동일한 주의사항입니다: 에이전트에게 해당 파일을 건드리지 말라고 지시합니다. 확실한 보장이 필요하다면, 프로덕션 비밀 정보는 브릿지를 실행하는 머신에 두지 마십시오. 이는 어쨌든 좋은 관행입니다.

모든 턴(turn)은 되돌릴 수 있음

턴이 시작되기 전에 채팅 핸들러는 폴더의 기준선(baseline)을 포착합니다. git 저장소에서는 git을 사용하고; 그렇지 않은 경우 파일들을 복사합니다 (node_modules, .git, 빌드 출력, 매우 큰 파일을 건너뜁니다).

질문하는 사람이나 개발자가 턴을 중지하면, 에이전트 프로세스는 중단되고 파일들은 그 기준선으로 되돌아갑니다. 잘못된 턴이라도 절반만 편집된 프로젝트를 남기지 않습니다.

절대 병합(merge)하지 않음, PR을 열지 않음, 배포하지 않음

브릿지나 채팅 서버에는 푸시(push)하거나, 풀 리퀘스트(pull request, PR)를 열거나, 병합하거나, 배포하는 코드 경로는 없습니다. 에이전트는 폴더 내의 파일을 편집할 뿐입니다. 그것이 전부입니다.

시스템 프롬프트는 또한 에이전트에게 채팅 턴 동안 프로덕션 빌드를 실행하지 않도록 지시합니다. 개발 서버(dev server)가 이미 실행 중이며 편집 내용을 핫 리로드(hot-reload)하고 있으므로, 프로덕션 빌드는 실행 중인 미리보기(preview)를 손상시킬 수 있습니다.

무엇을 배포할지는 개발자에게 달려 있습니다. 그들은 대화를 읽고, 실행 중인 앱을 살펴보고, 자체 도구에서 변경 사항(diff)을 확인한 다음, 팀이 이미 하는 방식대로 커밋하고 게시합니다. 또는 그냥 버릴 수도 있습니다.

배포 없이 미리보기 링크 사용하기

브릿지(bridge)가 앱을 시작합니다 (개발 명령어와 포트를 감지함). 그리고 Butterneck 서버는 이에 공용 공유 URL을 제공합니다. 이 URL로의 요청은 브릿지의 WebSocket을 통해 개발자 기기의 앱으로 전달됩니다. 이 릴레이는 핫 리로드 WebSocket, 이벤트 스트림(event streams), 그리고 오피스 문서와 같은 바이너리 파일까지 처리합니다.

따라서 요청하는 사람은 VPN, 스테이징 배포(staging deploy), 또는 로컬호스트 링크 없이도 자신이 요청했던 바로 그 화면에서 변경 사항이 나타나는 것을 볼 수 있습니다. 개발자는 누가 요청을 보낼 수 있는지 제어할 수 있습니다: 지정된 목록의 사용자이거나 링크를 가진 누구든지 가능합니다. 뷰어는 계정이 필요하지 않습니다.

기기 외부로 전송되는 데이터

여기서는 정확하게 설명할 가치가 있습니다. 왜냐하면 "로컬에서 실행된다(runs locally)"는 표현은 오해하기 쉽기 때문입니다:

• 소스 파일은 사용자의 기기에서 편집됩니다. Butterneck이 자체 모델을 실행하지 않습니다.
• 코딩 CLI는 프롬프트와 코드 컨텍스트를 자체 AI 제공업체로 전송하며, 이는 사용자가 직접 사용할 때와 동일합니다. 이는 Cursor, Anthropic 또는 Google과의 계약에 의해 규정됩니다.
• 미리보기 트래픽(렌더링된 앱)은 공유 링크가 작동하도록 Butterneck 서버를 통과합니다.
• 채팅 메시지는 브릿지에 도달하기 위해 Butterneck 서버를 거쳐 이동합니다.

사용해 보기

Butterneck은 개발자 한 명과 변경 사항을 요청하는 사용자 한 명에게 무료 스타터 플랜(Starter plan)을 제공합니다. 만약 팀이 요청을 만드는 시간보다 작은 요청들을 전달하는 데 더 많은 시간을 소비한다면, butterneck.com을 확인해 보세요.</div>