핵심 표면

클라우드 작업 순서
1. 컨테이너 생성 + 저장소 checkout
2. setup script 실행
3. 인터넷 접근 정책 적용
4. 에이전트가 명령 실행, 수정, 검증
5. 결과 diff와 답변 표시

구성 요소

setup script와 agent 단계를 분리하는 설계가 보안 경계를 만든다

Cloud Environment는 작업을 제출하면 컨테이너가 만들어지고 저장소가 체크아웃된 뒤, setup script가 실행됩니다. 이 두 단계는 단순한 순서가 아니라 보안 경계입니다. 에이전트 단계의 인터넷 접근은 기본적으로 꺼져 있지만, setup 단계는 의존성 설치를 위해 네트워크를 사용할 수 있습니다. 이 분리를 통해 에이전트가 실행 중에 외부 서버에 접근하는 것을 기본 차단하면서도 빌드 환경을 준비할 수 있습니다.

# 예시 setup script
pip install pyright
poetry install --with test
pnpm install

secrets가 setup 단계에서만 유효한 이유는 에이전트 격리 때문이다

일반 환경 변수는 setup과 agent 전체에서 유지되지만, secrets는 보안상 setup 단계에서만 풀리고 agent 단계 전에 제거됩니다. 이 설계는 에이전트가 민감한 자격증명을 직접 읽거나 외부로 전달하는 시나리오를 원천 차단합니다. 따라서 에이전트가 런타임에 직접 읽어야 하는 값으로 secrets를 설계하면 실패합니다. 런타임에 필요한 값은 일반 환경 변수로, 빌드나 설치 단계에서만 필요한 자격증명은 secrets로 구분하는 것이 올바른 설계입니다.

setup script에서 export한 값이 agent 단계로 자동 유지되지 않는 함정

setup script에서 export한 값은 agent 단계로 자동으로 이어지지 않습니다. 지속돼야 하는 값은 환경 설정에 넣거나 문서가 안내하는 방식으로 별도 구성해야 합니다. 이 동작을 모르면 setup script에서 환경 변수를 설정했는데 에이전트 실행 시 해당 값이 없다는 오류를 반복해서 만나게 됩니다. setup과 agent의 환경 범위가 다르다는 점을 전제하고 설정을 나누어야 합니다.

컨테이너 캐시가 후속 작업 속도를 높이는 조건과 무효화 시점

환경 캐시는 최대 12시간 유지될 수 있어 후속 작업이 빨라집니다. 하지만 setup script, maintenance script, 환경 변수, secrets가 바뀌면 캐시가 무효화됩니다. maintenance script는 캐시를 재사용할 때 실행되는 후속 보정 스크립트입니다. 의존성 업데이트처럼 캐시와 현재 상태 사이의 간극을 메우는 가벼운 작업에 적합합니다. 캐시를 활용하려면 setup script를 안정적으로 유지하고 불필요한 변경을 피하는 것이 중요합니다.

setup / maintenance / env / secrets를 나누는 기준
- setup script: 처음 환경을 만드는 설치와 초기화
- maintenance script: 캐시 재사용 뒤 가벼운 보정
- environment variables: agent 단계까지 유지돼야 하는 값
- secrets: setup 에서만 필요한 자격증명

어디에 둘까

주의할 점

실패 예시
- setup script 에서 export API_BASE_URL=... 을 넣고 agent 단계가 그대로 읽을 거라고 기대함
- 결과: 설치는 성공하지만 실제 작업 단계에서 환경 변수가 비어 있어 테스트와 명령이 실패함
- 대응: agent 단계까지 필요한 값은 environment variables 로 두고, setup export 는 일회성 셸 범위로만 본다