컨테이너 실행 가이드¶

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

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
```

플랫폼 지원

Backend.AI GO는 Apple Silicon 기반 macOS 15(Sequoia) 이상을 지원합니다. Apple Container 자체는 macOS 26(Tahoe) 이상이 필요합니다. macOS 15부터 25까지는 Docker를 사용하세요. Intel Mac은 macOS 앱 지원 대상이 아닙니다.

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는 시작할 때 가장 적합한 컨테이너 런타임을 자동으로 감지합니다.

설정 > 스쿼드를 엽니다.
에이전트 러너 이미지 섹션의 컨테이너 런타임을 확인합니다. 지원 런타임이 있으면 사용 가능, 없으면 사용 불가로 표시됩니다. 감지된 백엔드와 버전이 필요하면 아래 Management API를 사용하세요.

Management API로 직접 조회할 수도 있습니다:

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

응답 예시:

{
  "available": true,
  "backend": "apple_container",
  "version": "0.2.0",
  "networking": {
    "hostGateway": "192.168.64.1",
    "extraRunArgs": []
  },
  "message": "Apple Container runtime detected"
}

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

에이전트 러너 이미지(aigo-agent-runner:latest)는 스쿼드 에이전트에 필요한 Claude Code SDK와 지원 도구를 미리 담아 둔 컨테이너 이미지입니다.

앱에서 빌드¶

설정 > 스쿼드로 이동합니다.
에이전트 러너 이미지 섹션에서 이미지 빌드를 클릭합니다(이미지가 이미 있으면 이미지 재빌드). 사용할 수 있는 컨테이너 런타임이 없으면 이 버튼은 비활성화됩니다.
빌드가 끝날 때까지 버튼에 빌드 중... 표시가 나타나고, 빌드가 끝나면 버튼 아래에 빌드 출력과 함께 빌드 성공 또는 빌드 실패가 나타납니다.
이미지 상태가 준비됨으로 표시되면 이미지를 사용할 수 있습니다.

Management API를 통한 빌드¶

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

이미지 상태 확인¶

curl http://localhost:8001/api/v1/container/image/status

응답:

{
  "exists": true,
  "tag": "aigo-agent-runner:latest"
}

사용자 지정 이미지

특수 용도의 에이전트에는 사용자 지정 이미지 태그를 지정할 수 있습니다. 기본 태그는 aigo-agent-runner:latest이고, 사용자 지정 이미지는 미리 빌드되어 로컬에 존재해야 합니다.

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

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

기본 차단 패턴¶

다음 경로 구성 요소 패턴은 허용 목록 설정과 무관하게 항상 차단됩니다:

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

애플리케이션 데이터 디렉토리 자체, 그 안쪽, 그 상위 디렉토리를 대상으로 하는 마운트는 허용 루트가 해당 경로를 포함하더라도 항상 거부됩니다. 이 디렉토리에는 설정 파일, API 접근 키, 저장된 자격 증명, 그리고 이 허용 목록 자체가 들어 있기 때문입니다. 레거시 ~/.backend-ai-go 디렉토리와 소켓 디렉토리에도 같은 거부 규칙이 적용되며, 스쿼드의 워크스페이스 디렉토리에도 동일하게 적용됩니다. 따라서 홈 디렉토리를 허용 루트로 추가하는 것은 여전히 유용합니다. 홈 디렉토리 자체를 마운트하는 것은 거부되지만, 그 안의 프로젝트 디렉토리는 거부되지 않습니다.

허용 루트 추가¶

코워크 대화를 열고(채팅에서 작성창의 모드를 코워크로 전환), 워크스페이스 레일의 컨텍스트 섹션에서 코워크 설정을 클릭합니다.
코워크 설정 드로어에서 마운트 보안 탭을 선택하고 허용된 루트를 찾습니다.
호스트 디렉토리 경로를 입력합니다 (예: /Users/you/projects).
추가를 클릭하거나 Enter 키를 누릅니다. 허용 목록은 바로 저장됩니다.

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

Management API를 통해¶

# Get current allowlist
curl http://localhost:8001/api/v1/container/mount/allowlist

# Set allowlist
curl -X PUT http://localhost:8001/api/v1/container/mount/allowlist \
  -H "Content-Type: application/json" \
  -d '{
    "allowedRoots": ["/Users/you/projects", "/Users/you/data"],
    "blockedPatterns": [".ssh", ".gnupg", ".env", ".aws", ".azure", ".gcloud", ".docker", ".kube"]
  }'

마운트 경로 검증¶

컨테이너를 실행하기 전에 특정 경로가 허용되는지 미리 확인할 수 있습니다:

curl -X POST http://localhost:8001/api/v1/container/mount/validate \
  -H "Content-Type: application/json" \
  -d '{"hostPath": "/Users/you/projects/myapp", "containerPath": "/workspace/extra/myapp", "readOnly": true}'

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

자격 증명 프록시는 실제 자격 증명이 컨테이너에 들어가지 않도록 막아 줍니다. 스쿼드 컨테이너 에이전트는 여기서 따로 설정할 것이 없습니다. 컨테이너 작업에 프록시가 필요하면 앱이 프록시를 시작하고, 작업은 실행되는 동안에만 유효한 토큰으로 프록시의 라우터 경로를 거쳐 모델에 연결합니다(모델 경로 참고). 아래 매핑은 선택 사항입니다. 매핑은 /{id}/... 요청을 외부 업스트림 하나로 전달하면서 플레이스홀더 CREDENTIAL_PROXY_PLACEHOLDER를 실제 자격 증명으로 바꾸며, 번들된 에이전트 러너는 매핑을 사용하지 않습니다.

현재 내비게이션에는 자격 증명 프록시 설정 탭이 없습니다. Management API로 설정하세요.

자격 증명을 shell history에 남기지 마세요

실제 자격 증명을 명령 인자나 저장된 요청 본문에 붙여넣지 마세요. 아래 예시는 값을 화면에 표시하지 않고 읽은 뒤 생성한 JSON을 표준 입력으로 전달합니다. Bash 또는 Zsh에서 실행하세요.

# 설정된 포트에서 프록시 시작 (기본값: 3001)
curl -X POST http://localhost:8001/api/v1/container/credential-proxy/start

# 자격 증명을 화면에 표시하지 않고 shell 변수로 읽기
printf "Credential: "
IFS= read -rs CREDENTIAL
printf '\n'

# 자격 증명을 프로세스 인자에 넣지 않고 메모리 내 매핑 추가
printf '%s' "$CREDENTIAL" \
  | python3 -c 'import json,sys; print(json.dumps({"id":"anthropic","upstreamUrl":"https://api.anthropic.com","authMode":"api_key","credential":sys.stdin.read()}))' \
  | curl -X POST http://localhost:8001/api/v1/container/credential-proxy/mappings \
  -H "Content-Type: application/json" \
  --data-binary @-

unset CREDENTIAL

업스트림이 OAuth bearer token을 요구하면 api_key 대신 oauth_bearer를 사용합니다. 매핑은 실행 중인 프로세스 메모리에만 있으며 상태 응답에 자격 증명이 포함되지 않습니다.

매핑을 사용하는 클라이언트는 플레이스홀더 문자열 CREDENTIAL_PROXY_PLACEHOLDER만 보내며, 프록시가 전달 시 실제 자격 증명을 삽입합니다.

다음 단계¶

스쿼드 컨테이너 모드: 스쿼드 에이전트에서 컨테이너 실행 활성화
작업 스케줄링: 컨테이너 작업 자동 실행 예약
보안 모델: 각 보안 레이어의 작동 방식