컨테이너 실행 가이드¶

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

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

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

• Apple Container: Apple Silicon Mac에서 우선 사용되며 Docker보다 가볍습니다
• Docker: 모든 플랫폼 지원 (macOS, Windows, Linux)

Apple Container (macOS Apple Silicon 전용)¶

1. Apple Container GitHub 릴리스 페이지에서 Apple Container 설치 프로그램을 다운로드합니다.

2. 다운로드한 .pkg 파일을 열고 설치 마법사를 따릅니다.

3. 설치 후 동작을 확인합니다:

   container --version
   

4. 컨테이너 시스템 서비스를 시작합니다:

   container system start
   

Docker¶

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

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

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

1. Squad > Teams를 엽니다.

2. 페이지 헤더의 컨테이너 런타임 배지를 확인합니다. 지원 런타임의 사용 가능 여부가 표시됩니다. 감지된 백엔드와 버전이 필요하면 아래 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)는 Squad 에이전트에 필요한 Claude Code SDK와 지원 도구를 미리 담아 둔 컨테이너 이미지입니다.

앱에서 빌드¶

1. Squad > Settings로 이동합니다.

2. 에이전트 이미지 빌드를 클릭합니다.

3. 빌드 프로세스는 백그라운드에서 실행되며, 진행 상황은 빌드 로그 패널에 표시됩니다.

4. 상태가 이미지 준비 완료로 표시되면 빌드가 끝난 것입니다.

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"
}

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

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

기본 차단 패턴¶

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

허용 루트 추가¶

1. Chat에서 Cowork 모드를 선택하고 Cowork 설정 drawer를 엽니다.

2. Mount Security 탭을 선택한 뒤 허용 루트 추가를 클릭합니다.

3. 호스트 디렉터리를 선택합니다 (예: /Users/you/projects).

4. 저장을 클릭합니다.

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

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단계: 자격증명 프록시 설정¶

자격증명 프록시는 API 키가 컨테이너에 들어가지 않도록 막아 줍니다. 컨테이너는 플레이스홀더 토큰을 받아 http://host-gateway:3001의 프록시와 통신하고, 프록시가 실제 자격증명으로 바꿔 업스트림 API에 요청을 전달합니다.

현재 내비게이션에는 Credential Proxy 설정 탭이 없습니다. Management API로 설정하세요.

# 설정된 포트에서 프록시 시작 (기본값: 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 문자열만 보이며, 프록시가 전달 시 실제 자격증명을 삽입합니다.

다음 단계¶

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