TL;DR

  • Zed, Docker Agent, ACP를 연결해 에이전트를 sbx 샌드박스 안에서 실행하면, 프로젝트 작업 기능은 유지하면서 호스트 시스템에 대한 접근을 제한함.
  • sbx(Docker Sandboxes)는 마이크로VM 기반 격리 환경으로, 공유한 작업 디렉터리만 에이전트에 제공하고 네트워크 정책과 프록시로 외부 통신 및 비밀 정보를 관리함.
  • 모델 서버인 llmman은 호스트에서 계속 실행하며, 샌드박스 안의 Docker Agent는 host.docker.internal을 통해 호스트의 모델 엔드포인트에 연결함.
  • 설정 변경은 Docker Agent YAML의 base_url 한 줄과 Zed의 agent_servers 항목 추가이며, sbx exec -i로 샌드박스 안에서 ACP 서버를 실행함.
  • 에이전트가 실행하는 명령과 프로젝트 파일 변경은 샌드박스에서 이뤄지고, 공유 작업 디렉터리의 변경 사항은 Zed에도 바로 표시됨.

2분 요약

  • 이전 구성에서는 Zed가 ACP(Agent Client Protocol)를 통해 Docker Agent에 연결하고, llmman이 로컬에서 모델을 제공함.
  • 기존 구성의 문제는 에이전트가 셸을 사용하며 호스트 머신에서 직접 명령을 실행한다는 점임.
  • 이번 구성은 Docker Agent를 Docker 샌드박스(sbx) 안에서 실행하고, Zed를 샌드박스 안의 에이전트에 연결함.
  • 설정 변경은 거의 없으며, llmman은 계속 호스트에서 실행됨.

sbx란?

  • sbx(Docker Sandboxes)는 Claude Code, Codex, Gemini, Docker Agent 및 직접 만든 에이전트 등을 마이크로VM 기반의 격리된 샌드박스에서 실행하는 Docker 도구임.
  • 에이전트는 공유 작업 디렉터리만 볼 수 있으며, 이 디렉터리는 호스트와 같은 경로에 마운트됨.
  • 에이전트는 호스트의 나머지 파일 시스템, SSH 키, 다른 프로젝트에 접근할 수 없음.
  • 외부 네트워크 트래픽은 네트워크 정책이 적용되는 프록시를 통과하며, 기본적으로 에이전트는 임의의 대상에 연결할 수 없음.
  • 호스트에서 sbx secret set으로 비밀 정보를 선언하면 프록시가 외부 요청에 해당 정보를 주입함. 키는 샌드박스 안에 존재하지 않으므로 에이전트가 키를 읽거나 유출할 수 없음.
  • 샌드박스는 자체 Docker 데몬도 제공하므로 호스트의 컨테이너를 건드리지 않고 컨테이너를 실행할 수 있음.

에이전트를 샌드박스에서 실행해야 하는 이유

  • 코드 에이전트는 실행할 명령을 스스로 결정하는 프로그램이며, 이 구성에서는 셸 도구 모음을 사용함.
  • Zed가 각 명령의 실행 전에 확인을 요청하더라도, 잠깐의 부주의나 프로젝트 파일에 삽입된 프롬프트를 통해 잘못된 rm -rf 명령이나 알 수 없는 서버로의 curl 요청이 실행될 수 있음.
  • 호스트에서 실행되는 에이전트는 환경 변수와 설정 파일에도 접근할 수 있어, env나 cat ~/.config/... 같은 명령으로 API 키가 모델의 문맥에 들어가거나 외부로 전송될 위험이 있음.
  • 샌드박스를 사용하면 피해 범위가 작업 디렉터리와 네트워크 정책이 허용하는 범위로 제한되고, 비밀 정보도 에이전트가 접근할 수 없는 곳에 유지됨.

설정

호스트에서 계속 실행하는 llmman

  • 이 구성에서도 llmman은 호스트에서 실행되므로 호스트의 GPU를 계속 사용함.
  • 서버 실행 명령은 llmman serve임.
  • 모델 설치와 다운로드는 별도의 관련 안내 및 이전 기사에서 다룸.

Docker Agent 설정 변경

  • 기존 설정 파일의 복사본으로 sbx.llmman.docker-agent.yaml을 만들고, 변경 사항은 base_url 한 줄로 제한함.
  • 엔드포인트를 http://127.0.0.1:17434/v1에서 http://host.docker.internal:17434/v1로 변경함.
  • 샌드박스 내부의 127.0.0.1은 호스트가 아니라 샌드박스 자신을 가리킴. 따라서 호스트에서 실행 중인 llmman에 접근하려면 host.docker.internal을 사용함.
  • 나머지 설정은 llmman 제공자, openai_chatcompletions API 유형, mellum 모델, 셸 도구 모음, 에이전트 지침으로 구성됨. 모델 식별자는 huggingface.co/jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M임.

샌드박스 생성

  • 프로젝트 디렉터리에서 sbx create docker-agent . --name docker-agent-acp를 실행함.
  • docker-agent는 샌드박스에서 사용할 에이전트이고, .은 현재 디렉터리를 가리키며 해당 디렉터리가 샌드박스와 공유되는 작업 공간이 됨.
  • --name docker-agent-acp는 샌드박스 이름을 지정하며, Zed 설정에서도 이 이름을 사용함.
  • 프록시가 요청을 차단해 에이전트가 llmman에 연결하지 못하면 호스트에서 sbx policy allow network localhost:17434로 포트를 허용함.
  • sbx policy log를 실행하면 무엇이 차단됐는지와 차단 이유를 확인할 수 있음.

Zed에 에이전트 등록

  • Zed의 settings.json에서 agent_servers 항목에 새 에이전트를 등록함.
  • Zed가 직접 docker-agent를 실행하는 대신 sbx를 실행하고, sbx exec -i docker-agent-acp docker-agent serve acp를 통해 샌드박스 안에서 ACP 서버를 시작함.
  • 설정에는 사용할 샌드박스 이름 docker-agent-acp와 sbx.llmman.docker-agent.yaml의 경로를 지정함. 작업 공간이 호스트와 같은 경로에 마운트되므로 설정 파일 경로도 호스트와 동일함.
  • -i는 필수 옵션임. ACP는 표준 입출력(stdio)을 통한 JSON-RPC로 통신하므로 Zed와 샌드박스 사이에서 표준 입력을 열린 상태로 유지해야 함.
  • 샌드박스 이름과 YAML 설정 파일 경로는 각 환경에 맞게 변경해야 함.

Zed에서 사용하기

  • Zed의 에이전트 패널을 열고 사용 가능한 에이전트 목록에서 🤖 docker-agent (sbx llmman)을 선택함.
  • 에이전트가 프로젝트 탐색, 파일 읽기, 셸 명령 실행을 수행하는 방식은 이전 구성과 같지만, 모든 작업은 샌드박스 안에서 이뤄짐.
  • 작업 공간은 Zed와 샌드박스가 공유하므로 에이전트가 수정한 파일은 Zed에도 바로 표시됨.

정리

  • Zed는 sbx exec -i로 샌드박스 안에서 에이전트를 실행하고, ACP를 통해 표준 입출력 기반으로 통신함.
  • Docker Agent는 프로젝트 작업 공간만 제공되는 sbx 샌드박스에서 격리 실행됨.
  • Docker Agent는 host.docker.internal을 통해 호스트의 llmman이 제공하는 OpenAI 호환 API에 연결하며, 요청은 샌드박스 프록시를 통과함.
  • 프록시는 네트워크를 필터링하고 필요할 때 API 키 같은 비밀 정보를 주입하지만, 에이전트는 해당 비밀 정보를 직접 볼 수 없음.
  • 설정 변경은 llmman 엔드포인트를 지정하는 YAML 한 줄과 Zed 설정의 에이전트 항목 하나임.
  • 이전 구성과 같은 완전 로컬 설정을 유지하면서 에이전트가 호스트 머신에서 임의의 작업을 수행하지 못하도록 제한함.