9.3. Cowork 컨테이너 모드¶

Cowork 컨테이너 모드는 단일 Cowork(ReAct 에이전트) 세션을 격리된 컨테이너 내에서 실행합니다. 이는 멀티 에이전트 워크플로우를 위한 Squad 컨테이너 모드와 동일한 보안 이점을 단일 에이전트 작업에 제공합니다.

컨테이너 모드 사용 시기¶

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

코드 작성 또는 실행이 포함된 작업에서 강력한 파일시스템 격리가 필요한 경우
호스트 시스템 상태에 관계없이 재현 가능한 환경이 필요한 경우
컨테이너 이미지에서 사용 가능한 특정 도구나 의존성이 작업에 필요한 경우
워크스페이스 외부의 호스트 파일이 실수로 수정되는 것을 방지하고자 하는 경우

사전 요구 사항¶

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

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

컨테이너 모드 활성화¶

Cowork 설정을 통해¶

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

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

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

저장을 클릭합니다.

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

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

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

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

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

자격증명 프록시¶

에이전트가 API를 호출할 때 (예: Anthropic Claude), 호출은 자격증명 프록시를 통해 이루어집니다:

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

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

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

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

문제 해결¶

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

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

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

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

작업이 타임아웃됨¶

Cowork 설정에서 컨테이너 타임아웃 늘리기
작업을 더 작은 단계로 나누는 것을 고려하세요
느리거나 막힌 작업을 위해 컨테이너 로그 확인