9.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. 새 그룹을 클릭합니다.

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

4. 선택적으로 설명을 추가합니다.

5. 생성을 클릭합니다.

그룹 지침 설정¶

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

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

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

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

4. 저장을 클릭합니다.

4단계: Squad 실행¶

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

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

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

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

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

컨테이너 실행 모니터링¶

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

API 참조¶