Docker Sandbox에서 Mistral Vibe 실행하기

Docker Sandbox에서 Mistral Vibe 실행하기

Mistral의 Vibe CLI용 고정된(pinned) 재사용 이미지를 만들고 Docker Sandbox 에이전트 킷에 연결해볼게요. Vibe는 격리된 microVM에서 실행되며 샌드박스 프록시를 통해 Mistral API에 도달하므로, 내 API 키가 VM에 들어가지 않아요.

출처: 문서

본문

Mistral Vibe는 Mistral의 오픈소스 코딩 에이전트예요. 이 가이드는 Vibe를 Docker Sandbox 에이전트로 패키징해 호스트에서 직접 실행하는 대신 격리된 microVM에서 실행되게 하는 방법을 보여줘요. 에이전트는 샌드박스 프록시를 통해 Mistral API에 도달하므로, 내 API 키는 호스트에 유지되고 VM에 절대 들어가지 않아요.

매번 실행할 때마다 에이전트를 새로 설치하는 대신, 고정된 이미지를 한 번 만들어 재사용해요. 에이전트 버전을 고정하고 전용 이미지를 빌드하면 재현 가능한 샌드박스와 더 빠른 시작을 얻을 수 있어요. 이 방식은 Docker가 나만의 에이전트를 빌드할 때 권장하는 접근법이에요.

이 가이드에서 배울 내용:

  • Mistral API 키를 샌드박스 시크릿으로 호스트에 저장하기
  • shell 템플릿 위에 Vibe를 담는 고정된 멀티 아키텍처 이미지 빌드하기
  • 프록시를 통해 Vibe를 Mistral API에 연결하는 에이전트 킷 작성하기
  • 샌드박스 검증, 실행, 반복 개선하기

이 가이드는 v2 형식을 사용해요. 참조와 마이그레이션 지침은 Kits v2 를 참고하세요.

격리가 어떻게 동작하나요

샌드박스의 모든 아웃바운드 요청은 호스트에서 실행되는 프록시를 통과해요. 프록시는 네트워크 정책을 적용하고 자격 증명을 주입하므로, VM 안의 에이전트는 실제 키를 절대 다루지 않아요.

Mistral은 내장 서비스(built-in service)예요: sbx 는 이미 mistral 서비스 이름을 MISTRAL_API_KEY 환경 변수와 api.mistral.ai 도메인에 매핑해요. VM 안에서 Vibe는 MISTRAL_API_KEY 에 대한 센티널(sentinel) 값만 보게 돼요. 프록시는 실제 키를, 그리고 오직 api.mistral.ai 로의 요청에 대해서만 교체해줘요. 에이전트가 다른 목적으로 이 변수를 읽으면 센티널을 얻어요.

내장(built-in)이 자동(automatic)을 의미하지는 않아요. 4단계 에서 작성하는 킷이 여전히 키가 어디서 오는지, 프록시가 요청에 어떻게 붙이는지를 선언해요.

사전 요구사항

시작하기 전에 다음이 갖춰져 있는지 확인해주세요:

  • Docker Desktop 또는 Docker Engine 설치
  • Docker Sandboxes( sbx ) 설치 및 로그인
  • Mistral API 키
  • 이미지를 게시할 Docker Hub 네임스페이스 또는 다른 레지스트리

1단계: 호스트에 Mistral 키 저장하기

호스트에 키를 한 번 제공해주세요. Mistral은 내장 서비스이므로 sbx 는 추가 연결 없이 mistral 이름 아래에서 이를 해석해요:

$ sbx secret set mistral

서비스 시크릿은 기본적으로 전역이므로 mistral 서비스를 선언하는 모든 샌드박스가 사용할 수 있어요. 대신 --sandbox 를 사용해 시크릿을 단일 샌드박스로 범위를 한정할 수 있어요. 프록시가 자격 증명을 어떻게 해석하고 주입하는지에 대해서는 Credentials 를 참고하세요.

2단계: 고정된 Vibe 이미지 작성하기

Vibe는 Python 어플리케이션이에요. 공식 shell 템플릿 은 이미 uv , git , ripgrep , Python을 제공하므로, 그 위에 빌드하고 uv 로 고정된 Vibe 버전을 설치해요.

Dockerfile 을 만들어주세요:

# syntax=docker/dockerfile:1
ARG BASE_IMAGE=docker/sandbox-templates:shell
FROM ${BASE_IMAGE}

# Pin the agent version for reproducible sandboxes.
# Check https://pypi.org/project/mistral-vibe/ and bump as needed.
ARG VIBE_VERSION=2.24.5

# Install Vibe as the non-root agent user. The socks extra is installed
# explicitly so the agent works through the sandbox proxy.
USER agent
RUN uv tool install "mistral-vibe==${VIBE_VERSION}" --with "httpx[socks]" \
  && vibe --version

CMD ["vibe", "--agent", "auto-approve"]

세 가지 선택이 눈에 띄어요:

  • mistral-vibe 를 명시적 버전으로 고정하면 이미지를 재현 가능하게 유지해요. 새 릴리스로 이동하려면 VIBE_VERSION 을 바꾸고 재빌드하면 돼요.
  • httpx[socks] 엑스트라를 명시적으로 설치하면 에이전트가 샌드박스 프록시 뒤에서 실행될 때 발생하는 시작 실패를 피할 수 있어요. 일부 Vibe 릴리스는 스스로 이를 가져오지 않아요.
  • CMD 는 Vibe를 --agent auto-approve 로 실행하므로 에이전트가 도구 실행을 자동 승인해요. 플래그를 이미지에 구워 넣으면 킷의 실행 동작이 한 곳에 유지되어, 킷이 엔트리포인트를 덮어쓰지 않아요.

3단계: 이미지 빌드 및 게시

두 공통 아키텍처용으로 빌드하고 내 네임스페이스에 게시해주세요. 빌드는 이미지가 어떻게 빌드됐고 무엇을 포함하는지 기록하는 provenance와 SBOM 증명을 첨부해요. YOUR_NAMESPACE 를 내 Docker Hub 사용자 이름으로 바꿔주세요:

$ docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --provenance=true \
  --sbom=true \
  -t YOUR_NAMESPACE/sbx-mistral-vibe:0.1.0 \
  --push .

이동하는 태그 대신 실제 버전으로 이미지에 태그를 달아, 다음 단계의 킷이 항상 같은 빌드를 가리키도록 해주세요.

4단계: 에이전트 킷 작성하기

킷은 이미지, 네트워크 정책, 자격 증명을 하나로 묶어요. 이미지는 CMD 에서 실행 명령을 이미 설정해요. spec.yaml 이 포함된 킷용 디렉터리를 만들고 YOUR_NAMESPACE 를 게시한 네임스페이스로 바꿔주세요:

# mistral-vibe/spec.yaml
schemaVersion: "2"
kind: sandbox
name: mistral-vibe
displayName: Mistral Vibe
sandbox:
  image: docker.io/YOUR_NAMESPACE/sbx-mistral-vibe:0.1.0
  agentInstructions:
    filename: AGENTS.md
    content: |
      You are running inside an isolated Docker Sandbox microVM.
      Network access is restricted to the Mistral API. Prefer tools and
      packages already available in the workspace.
permissions:
  network:
    allow:
      - "api.mistral.ai:443"
credentials:
  - service: mistral
    apiKey:
      name: MISTRAL_API_KEY
      inject:
        - domain: api.mistral.ai
          scheme: bearer

각 필드가 하는 일:

필드 용도
kind: sandbox 샌드박스 에이전트, 즉 완전한 이미지와 그 실행 구성을 선언해요.
name 킷의 식별자. 킷 디렉터리를 sbx run 에 전달해요.
sandbox.image 3단계에서 게시한 고정 이미지. CMD 가 Vibe를 실행하므로 킷은 엔트리포인트를 설정하지 않아요.
agentInstructions.filename Vibe가 프로젝트에서 읽는 지침 파일.
agentInstructions.content 생성 시 AGENTS.md 에 추가되어 에이전트에게 환경을 알려주는 마크다운.
permissions.network.allow 샌드박스가 도달할 수 있는 호스트. 이것이 없으면 기본 거부 정책에 의해 요청이 차단돼요.
credentials[].service 키를 공급하는 내장 서비스. mistral 은 MISTRAL_API_KEY 와 api.mistral.ai 에 매핑돼요.
credentials[].apiKey.name 프록시가 관리하는 환경 변수. Vibe는 센티널 값을 보고, 프록시가 실제 키를 교체해줘요.
credentials[].apiKey.inject 프록시가 키를 붙이는 위치와 방식. scheme: bearer 는 해당 도메인에 Authorization: Bearer *** 를 설정해요.

경고: --agent auto-approve 는 Vibe를 묻지 않고 모든 도구 실행을 승인하는 모드로 실행해요. 샌드박스는 에이전트를 호스트에서 격리하지만, 민감한 워크스페이스에서 실행하기 전에 에이전트의 동작을 검토하세요.

5단계: 검증 및 실행

실행 전에 킷을 검증해주세요:

$ sbx kit validate ./mistral-vibe

이제 프로젝트 디렉터리에서 킷으로 에이전트를 실행해주세요:

$ sbx run ./mistral-vibe --name mistral-vibe .
  • ./mistral-vibe 는 spec.yaml 을 포함하는 폴더를 가리키는 샌드박스 킷 참조예요.
  • --name mistral-vibe 는 샌드박스 이름을 지어줘요. 이것이 없으면 sbx 는 에이전트와 작업 디렉터리에서 이름을 파생하며, 아래 명령들이 일치하지 않게 돼요.
  • . 은 샌드박스에 마운트할 프로젝트 디렉터리예요.

Vibe는 격리된 microVM에서 시작하고 프록시를 통해 Mistral API와 통신하며, 실제 키는 컨테이너에 절대 닿지 않아요.

킷 반복 개선

에이전트가 필요한 도메인에 도달하지 못하거나 요청이 예상과 다르게 동작하면, 프록시가 본 내용을 검사해주세요:

$ sbx policy log

각 항목은 요청, 일치한 규칙, 프록시가 어떻게 처리했는지를 보여줘요. permissions.network.allow 에 빠진 호스트를 찾는 데 사용하세요. spec.yaml 을 변경한 후에는 샌드박스를 다시 만들어 깨끗하게 시작해주세요:

$ sbx rm mistral-vibe && sbx run ./mistral-vibe --name mistral-vibe .

정리

샌드박스는 Vibe가 종료된 후에도 지속돼요. 삭제하지 않고 중지하려면:

$ sbx stop mistral-vibe

샌드박스와 그 안의 모든 것을 제거하려면:

$ sbx rm mistral-vibe

워크스페이스의 파일은 영향을 받지 않아요.

더 알아보기

  • Docker Sandboxes 시작하기
  • v3 에이전트 워크로드 빌드
  • 킷으로 샌드박스 커스터마이즈
  • 자격 증명 및 내장 서비스
  • Mistral Vibe

더 알아보기 (Learn more)

  • Docker Sandboxes
  • Docker Sandbox 킷
  • Mistral Vibe