11.2. Squad 컨테이너 모드¶

Squad 컨테이너 모드는 개별 Squad 에이전트를 격리된 컨테이너 안에서 실행해 더 강력한 보안 경계와 재현 가능한 실행 환경을 제공합니다. 컨테이너 모드는 Squad 안에서 에이전트별로 켤 수 있어서, 일부 에이전트는 인프로세스로, 나머지는 컨테이너에서 실행하는 구성도 가능합니다.

사전 요구 사항¶

컨테이너 모드를 활성화하기 전에 컨테이너 실행 가이드를 완료하세요:

• 컨테이너 런타임 설치 (Docker 또는 Apple Container)
• 에이전트 러너 이미지 빌드 (aigo-agent-runner:latest)
• 마운트 허용 목록 설정
• 자격증명 프록시 실행 중 (에이전트에 외부 API 접근이 필요한 경우)

작동 방식¶

에이전트가 컨테이너 모드로 실행될 때:

sequenceDiagram
    participant Host as Backend.AI GO 호스트
    participant NS as 네임스페이스 관리자
    participant C as 컨테이너
    participant CP as 자격증명 프록시

    Host->>NS: 세션 디렉터리 생성
    NS->>C: 워크스페이스 마운트로 컨테이너 시작
    C->>CP: API 요청 (플레이스홀더 자격증명 사용)
    CP->>CP: 실제 자격증명으로 대체
    CP-->>C: 실제 자격증명으로 전달된 요청
    C->>Host: IPC: 메시지 전송 / 작업 생성
    Host-->>C: IPC: 후속 메시지
    C->>Host: IPC: 닫기 (작업 완료)
    Host->>C: 컨테이너 중지

각 컨테이너에는 다음이 제공됩니다:

• /workspace: Squad의 공유 워크스페이스 디렉터리 (메인 에이전트는 읽기-쓰기, 나머지는 읽기 전용)
• /workspace/extra/{name}: 사용자가 설정한 추가 마운트
• /workspace/ipc: 호스트-컨테이너 통신을 위한 IPC 디렉터리
• .claude/: 에이전트의 SDK 세션 상태

1단계: Squad 생성 또는 편집¶

1. 사이드바에서 Squad로 이동합니다.

2. 새 Squad를 클릭하거나 기존 Squad를 엽니다.

3. 아직 설정하지 않았다면 Squad의 워크스페이스 디렉터리를 설정합니다.

2단계: 에이전트에서 컨테이너 모드 활성화¶

1. Squad 편집기에서 컨테이너화할 에이전트를 클릭합니다.

2. 에이전트 설정 패널에서 실행 모드를 찾습니다.

3. 드롭다운에서 컨테이너를 선택합니다 (기본값은 인프로세스).

4. 컨테이너 설정 옵션이 나타납니다:

   필드	기본값	설명
   이미지	aigo-agent-runner:latest	사용할 컨테이너 이미지
   타임아웃	30분	최대 실행 시간
   유휴 타임아웃	없음	이 시간 동안 출력이 없으면 컨테이너 종료
   추가 마운트	비어 있음	마운트할 추가 호스트 경로

3단계: 추가 마운트 설정 (선택)¶

에이전트가 워크스페이스 밖의 호스트 경로에 접근해야 한다면:

1. 에이전트의 컨테이너 설정에서 마운트 추가를 클릭합니다.

2. 다음을 입력합니다:

   • 호스트 경로: 마운트할 호스트 경로 (마운트 허용 목록에 있어야 함)
   • 컨테이너 경로: 컨테이너 내부의 마운트 위치 (/workspace/extra/ 아래여야 함)
   • 읽기 전용: 에이전트가 이 경로에 쓰지 못하게 하려면 켭니다

3. 추가를 클릭합니다.

4단계: 그룹 네임스페이스 설정¶

그룹 네임스페이스는 컨테이너를 격리된 세션 그룹으로 묶습니다. 각 그룹은 고유한 세션 디렉터리와 지침 세트를 갖습니다.

그룹 네임스페이스 생성¶

1. 설정 > 컨테이너 > 그룹으로 이동합니다.

2. 새 그룹을 클릭합니다.

3. 이름을 입력합니다 (파일시스템에 안전한 이름, 예: dev-team).

4. 필요하면 설명을 추가합니다.

5. 생성을 클릭합니다.

그룹 지침 설정¶

그룹별 지침(CLAUDE.md에 해당)은 해당 그룹의 모든 컨테이너 세션에 주입됩니다:

1. 그룹 목록에서 그룹 이름을 클릭합니다.

2. 지침 편집을 클릭합니다.

3. 지침을 입력합니다 (Markdown 지원).

4. 저장을 클릭합니다.

전역 지침¶

전역 지침은 모든 그룹에 적용됩니다. 그룹별 지침과 결합되어 컨테이너마다 병합된 형태로 주입됩니다:

1. 설정 > 컨테이너 > 그룹으로 이동합니다.

2. 전역 지침 편집을 클릭합니다.

3. 전역 지시 사항을 입력합니다.

4. 저장을 클릭합니다.

5단계: Squad 실행¶

1. Squad 패널에서 실행을 클릭합니다.

2. 작업 설명을 제출합니다.

3. 플래너가 작업 그래프를 만들고 에이전트에 작업을 할당합니다.

4. 컨테이너 모드 에이전트에 작업이 할당되면:

   • DATA_DIR/sessions/{group}/ 아래에 세션 디렉터리가 생성됩니다
   • 워크스페이스와 IPC 마운트가 연결된 컨테이너가 시작됩니다
   • 에이전트가 작업을 처리하고 IPC로 결과를 전달합니다
   • 작업이 완료되거나 타임아웃되면 컨테이너가 중지됩니다

컨테이너 실행 모니터링¶

컨테이너 상태 패널¶

Squad 모니터링 대시보드에서 컨테이너별 상태를 확인할 수 있습니다:

실행 기록¶

1. 설정 > 컨테이너 > 실행 기록으로 이동합니다.

2. 시작 시각, 소요 시간, 종료 코드, 출력과 함께 지난 컨테이너 실행 내역을 확인합니다.

감사 로그¶

1. 설정 > 컨테이너 > 감사 로그로 이동합니다.

2. 보안 이벤트, 권한 검사, 마운트 검증 내역을 살펴봅니다.

컨테이너 모드 문제 해결¶

에이전트 컨테이너가 시작되지 않음¶

• 에이전트 러너 이미지가 존재하는지 확인: 설정 > 컨테이너 > 이미지 상태
• 런타임이 사용 가능한지 확인: curl http://localhost:55765/api/v1/container/runtime
• 감사 로그에서 권한 오류 검토

에이전트가 워크스페이스에 쓸 수 없음¶

• Squad 워크스페이스 디렉터리가 허용 루트 아래에 있는지 확인
• 에이전트가 메인 에이전트로 지정되어 있는지 확인 (메인 에이전트만 워크스페이스 읽기-쓰기 권한을 가집니다)

컨테이너가 타임아웃됨¶

• 에이전트의 컨테이너 설정에서 타임아웃 늘리기
• 실행 기록의 컨테이너 로그에서 느린 단계 검토
• 작업을 더 작은 하위 작업으로 나누는 것 고려

컨테이너 내부에서 API 호출 실패¶

• 자격증명 프록시가 실행 중인지 확인: 설정 > 컨테이너 > 자격증명 프록시
• 업스트림 API에 대한 올바른 자격증명 매핑이 있는지 확인
• 컨테이너 환경의 ANTHROPIC_BASE_URL이 프록시를 가리키는지 확인

API 참조¶