9.1. 컨테이너 실행 가이드¶

이 가이드는 컨테이너 런타임 설정, 에이전트 러너 이미지 빌드, 컨테이너에서 에이전트를 실행하기 전 마운트 보안 설정 방법을 안내합니다.

1단계: 컨테이너 런타임 설치¶

Backend.AI GO는 두 가지 컨테이너 런타임을 지원합니다:

Apple Container — Apple Silicon Mac에서 선호되며 Docker보다 경량
Docker — 모든 플랫폼 지원 (macOS, Windows, Linux)

Apple Container (macOS Apple Silicon 전용)¶

Apple Container GitHub 릴리스 페이지에서 Apple Container 설치 프로그램을 다운로드합니다.
다운로드한 .pkg 파일을 열고 설치 마법사를 따릅니다.
설치 후 동작을 확인합니다:
```
container --version
```
컨테이너 시스템 서비스를 시작합니다:
```
container system start
```

플랫폼 지원

Apple Container는 Apple Silicon에서 실행되는 macOS 15(Sequoia) 이상에서만 사용할 수 있습니다. Intel Mac에서는 Backend.AI GO가 자동으로 Docker를 사용합니다.

Docker¶

macOSWindowsLinux

Docker Desktop for Mac을 다운로드하여 설치합니다.
Applications 폴더에서 Docker Desktop을 시작합니다.
Docker가 실행 중인지 확인합니다:
```
docker version
```

Docker Desktop for Windows를 다운로드하여 설치합니다.
설치 중 백엔드로 WSL 2를 선택합니다.
시작 메뉴에서 Docker Desktop을 시작합니다.
PowerShell에서 Docker가 실행 중인지 확인합니다:
```
docker version
```

공식 편의 스크립트를 사용하여 Docker Engine을 설치합니다:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
docker version

2단계: 런타임 감지 확인¶

Backend.AI GO는 시작 시 가장 적합한 컨테이너 런타임을 자동으로 감지합니다.

설정 > 컨테이너를 엽니다.
런타임 필드에 감지된 백엔드가 표시됩니다:
- Apple Container — Apple Container 감지 및 선호
- Docker — Docker 사용 가능
- 사용 불가 — 런타임 없음 (설치 재확인 필요)

Management API를 통해 직접 확인할 수도 있습니다:

curl http://localhost:55765/api/v1/container/runtime

3단계: 에이전트 러너 이미지 빌드¶

에이전트 러너 이미지(aigo-agent-runner:latest)는 Squad 에이전트에 필요한 Claude Code SDK 및 지원 도구가 포함된 사전 구성된 컨테이너 이미지입니다.

앱에서 빌드¶

설정 > 컨테이너로 이동합니다.
에이전트 이미지 빌드를 클릭합니다.
빌드 프로세스가 백그라운드에서 실행됩니다.
상태가 이미지 준비 완료로 표시되면 빌드가 완료된 것입니다.

CLI를 통한 빌드¶

aigo container build-image

Management API를 통한 빌드¶

curl -X POST http://localhost:55765/api/v1/container/image/build \
  -H "Content-Type: application/json" \
  -d '{"imageTag": "aigo-agent-runner:latest"}'

4단계: 마운트 허용 목록 설정¶

마운트 허용 목록은 컨테이너가 접근할 수 있는 호스트 디렉터리를 제어합니다. 허용된 루트 하의 경로만 마운트될 수 있으며, 그 외 모든 경로는 거부됩니다.

기본 차단 패턴¶

다음 경로 구성 요소 패턴은 허용 목록 설정에 관계없이 항상 차단됩니다:

패턴	이유
`.ssh`	SSH 키
`.gnupg`	GPG 키
`.env`	환경 파일
`.aws`	AWS 자격증명
`.azure`	Azure 자격증명
`.gcloud`	Google Cloud 자격증명
`.docker`	Docker 자격증명
`.kube`	Kubernetes 설정

허용 루트 추가¶

설정 > 컨테이너 > 마운트 보안으로 이동합니다.
허용 루트 추가를 클릭합니다.
호스트 디렉터리를 선택합니다 (예: /Users/사용자명/projects).
저장을 클릭합니다.

추가된 루트의 하위 디렉터리만 컨테이너에 마운트될 수 있습니다.

5단계: 자격증명 프록시 설정¶

자격증명 프록시는 API 키가 컨테이너에 노출되지 않도록 보장합니다. 컨테이너는 플레이스홀더 토큰을 받고 http://host-gateway:3001의 프록시와 통신하며, 프록시는 실제 자격증명으로 대체한 후 업스트림 API에 요청을 전달합니다.

프록시 시작¶

설정 > 컨테이너 > 자격증명 프록시로 이동합니다.
자격증명 프록시 활성화 토글을 켭니다.
프록시가 포트 3001에서 자동으로 시작됩니다 (설정 가능).

자격증명 매핑 추가¶

자격증명 프록시 설정에서 매핑 추가를 클릭합니다.
다음을 입력합니다:
- 이름: 사람이 읽기 쉬운 레이블 (예: "Anthropic API")
- 업스트림 URL: 실제 API 엔드포인트 (예: https://api.anthropic.com)
- 자격증명 유형: API 키 또는 OAuth Bearer
- 실제 자격증명: 실제 API 키 (호스트에 암호화되어 저장됨)
저장을 클릭합니다.

보안 참고

실제 자격증명은 앱의 암호화된 키스토어에 저장되며 평문으로 디스크에 기록되지 않습니다. 컨테이너는 플레이스홀더 문자열 CREDENTIAL_PROXY_PLACEHOLDER만 볼 수 있습니다.

다음 단계¶

Squad 컨테이너 모드 — Squad 에이전트에서 컨테이너 실행 활성화
작업 스케줄링 — 컨테이너 작업 자동 스케줄링
보안 모델 — 보안 레이어 심층 분석