11.3. Cowork 컨테이너 모드¶

Cowork 컨테이너 모드는 단일 Cowork(ReAct 에이전트) 세션을 격리된 컨테이너 안에서 실행합니다. 멀티 에이전트 워크플로우에서 Squad 컨테이너 모드가 제공하는 보안 이점을 개별 에이전트 작업에서도 동일하게 얻을 수 있습니다.

컨테이너 모드 사용 시기¶

다음 경우에 Cowork 컨테이너 모드를 사용하세요:

코드를 작성하거나 실행하는 작업이라 파일시스템을 확실하게 격리하고 싶은 경우
호스트 시스템 상태와 무관하게 재현 가능한 환경이 필요한 경우
컨테이너 이미지에 들어 있는 특정 도구나 의존성이 작업에 필요한 경우
워크스페이스 밖의 호스트 파일이 실수로 수정되는 것을 방지하고 싶은 경우

사전 요구 사항¶

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

컨테이너 런타임 설치 및 감지
에이전트 러너 이미지 빌드
마운트 허용 목록 설정

컨테이너 모드 활성화¶

Cowork 설정을 통해¶

사이드바에서 Cowork 패널을 엽니다.
에이전트 프로필 선택기 옆의 설정 아이콘(톱니바퀴)을 클릭합니다.
고급 설정에서 실행 모드를 찾습니다.
컨테이너를 선택합니다 (기본값은 인프로세스).

컨테이너 옵션을 설정합니다:

옵션	기본값	설명
이미지	`aigo-agent-runner:latest`	컨테이너 이미지
타임아웃	30분	최대 실행 시간
유휴 타임아웃	없음	이 시간 동안 출력이 없으면 종료

저장을 클릭합니다.

컨테이너 모드에서의 워크스페이스¶

Cowork가 컨테이너 모드로 실행되면 에이전트의 워크스페이스가 컨테이너에 마운트됩니다:

컨테이너 파일시스템:
/workspace/               ← 에이전트의 읽기-쓰기 워크스페이스 (호스트에서)
/workspace/extra/{name}/  ← 추가 마운트 (기본적으로 읽기 전용)
/workspace/ipc/           ← IPC 통신 디렉터리

워크스페이스 디렉터리는 Cowork에서 설정한 폴더 권한에 대응하며, 주 허용 폴더가 /workspace로 마운트됩니다.

폴더 권한은 여전히 적용됩니다

컨테이너 모드는 폴더 권한을 우회하지 않습니다. Cowork 설정에서 명시적으로 허용한 폴더만 컨테이너에 마운트됩니다.

추가 마운트¶

에이전트가 다른 호스트 경로에도 접근해야 한다면:

Cowork > 설정 > 컨테이너 > 추가 마운트로 이동합니다.
마운트 추가를 클릭합니다.
다음을 입력합니다:
- 호스트 경로: 호스트 머신의 경로 (허용 목록에 있어야 함)
- 컨테이너 경로: /workspace/extra/ 아래여야 함
- 읽기 전용: 참조용 데이터라면 켜두는 것을 권장

IPC 통신¶

Cowork 컨테이너 에이전트는 Squad 컨테이너 에이전트와 동일한 파일 기반 IPC 시스템으로 호스트와 통신합니다:

후속 메시지: 호스트가 ipc/input/에 기록해 스티어링 메시지를 전달합니다
발신 메시지: 컨테이너가 ipc/messages/에 기록해 메시지 전송을 요청합니다
작업 생성: 컨테이너가 ipc/tasks/에 기록해 새 작업을 만듭니다
종료 신호: 호스트가 ipc/input/_close를 기록해 정상 종료를 요청합니다

자격증명 프록시¶

에이전트가 API를 호출하면 (예: Anthropic Claude) 호출은 자격증명 프록시를 거칩니다:

컨테이너 내부에서 ANTHROPIC_API_KEY는 CREDENTIAL_PROXY_PLACEHOLDER로 설정됩니다
ANTHROPIC_BASE_URL은 자격증명 프록시인 http://host-gateway:3001을 가리킵니다
프록시가 api.anthropic.com에 전달하기 전에 실제 API 키로 대체합니다

자격증명 프록시가 실행 중이고 사용하는 API 제공자에 대한 올바른 매핑이 있는지 확인하세요. 컨테이너 실행 가이드를 참조하세요.

컨테이너 실행 모니터링¶

상태 표시¶

컨테이너 모드로 실행 중일 때 Cowork 상태 배지에 컨테이너 관련 상태가 표시됩니다:

상태	설명
`provisioning`	컨테이너 시작 중
`running`	컨테이너가 작업을 처리하는 중
`completed`	컨테이너가 성공적으로 완료됨
`failed`	컨테이너가 오류로 종료됨
`timeout`	실행이 시간 제한을 초과함

실행 기록¶

지난 컨테이너 실행 내역을 확인합니다:

curl http://localhost:55765/api/v1/container/run-history

메트릭¶

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

Squad 컨테이너 모드와의 차이점¶

기능	Cowork 컨테이너	Squad 컨테이너
에이전트 수	단일	다수
그룹 네임스페이스	세션별	그룹 네임스페이스별
워크스페이스	폴더 권한으로 결정	Squad 워크스페이스 디렉터리
IPC	예	예
자격증명 프록시	예	예
스케줄링	아니요	예 (작업 스케줄링으로)
채널 라우팅	아니요	예 (채널-Squad 매핑으로)

문제 해결¶

Cowork에서 컨테이너가 시작되지 않음¶

컨테이너 런타임이 감지되었는지 확인: 설정 > 컨테이너 > 런타임
에이전트 러너 이미지가 빌드되었는지 확인: 설정 > 컨테이너 > 이미지 상태
워크스페이스 디렉터리가 마운트 허용 목록에 있는지 확인

에이전트가 워크스페이스 파일에 접근할 수 없음¶

폴더가 Cowork의 허용된 폴더 목록에 있는지 확인
마운트 허용 목록에 폴더의 상위 디렉터리가 포함되어 있는지 확인
감사 로그 검토: 설정 > 컨테이너 > 감사 로그

스티어링 메시지가 에이전트에 도달하지 않음¶

컨테이너 모드는 IPC input/ 디렉터리를 통한 작업 중 스티어링을 지원합니다
IPC 디렉터리가 생성되었는지 확인: 세션 디렉터리에 ipc/input/이 있어야 합니다
컨테이너가 아직 실행 중인지 확인 (실행 기록 참조)

작업이 타임아웃됨¶

Cowork 설정에서 컨테이너 타임아웃 늘리기
작업을 더 작은 단계로 나누는 것 고려
컨테이너 로그에서 느리거나 멈춘 작업 확인