Extend Claude Code to remote sessions on Amazon Bedrock AgentCore with security controls

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

AWS는 Claude Code를 Amazon Bedrock AgentCore의 작업별 격리 세션에서 실행하고, Amazon Bedrock의 데이터 통제와 추가 보안 장치를 적용해 사람이 검토·병합할 GitHub pull request를 생성하는 원격 코딩 에이전트 샘플을 소개한다.

📌 핵심 요약

• sample-remote-coding-agent는 사용자 AWS 계정의 AgentCore runtime에서 작업마다 독립된 microVM 세션을 실행하며, Claude Code 또는 웹 콘솔로 받은 작업을 GitHub pull request로 반환한다.
• Claude Opus가 변경 계획과 결과 검토를 맡고 Claude Sonnet이 코드를 작성하며, 저장소의 setup·test 명령으로 검증한다. 작업은 최대 3회 시도하고, 검증을 통과하지 못한 pull request는 초안으로 생성하며 에이전트는 병합하지 않는다.
• 원격 세션의 유일한 모델 공급자는 Amazon Bedrock이며, 호출에는 비공개 엔드포인트와 runtime IAM 실행 역할을 사용한다. Amazon Bedrock은 고객 콘텐츠를 모델 학습에 사용하거나 모델 공급자와 공유하지 않으며, Mantle의 운영자 접근 차단 설계인 ZOA와 설정 가능한 데이터 무보존 ZDR을 설명한다.
• Amazon Bedrock Guardrails는 제출된 작업 프롬프트를 검사하지만 저장소 파일이나 명령 출력으로 들어오는 프롬프트 주입은 검사하지 않는다. DNS Firewall의 차단 목록도 다른 HTTPS 트래픽까지 막지는 않으며, 샘플은 자체 setup·test 명령을 갖춘 신뢰할 수 있는 저장소의 범위가 명확한 작업에 적합하다.
• GitHub 접근에는 AgentCore Identity가 발급하고 자동 갱신하는 유효기간 8시간의 토큰을 사용한다. runtime IAM 권한은 해당 저장소의 작업 기록·메모리와 필요한 모델·이미지 접근으로 제한하고, 최종 변경 반영은 사람의 검토와 병합에 맡긴다.

🧩 주요 포인트

1. 작업별 독립 세션과 비동기 실행 → 노트북을 닫거나 여러 작업을 동시에 진행할 수 있지만, 실행 중 개입은 줄고 환경 설정과 비용 예측 부담이 생긴다.
2. Amazon Bedrock의 데이터 통제와 프롬프트 검사·네트워크 제한의 결합 → 원격 실행에도 보안 통제를 적용하지만, 저장소·명령 출력의 프롬프트 주입과 차단 목록 밖 HTTPS 통신에 대한 한계는 남는다.
3. 최대 3회 시도와 검증 결과를 담은 GitHub pull request → 범위가 명확한 변경의 자동화와 사람의 최종 판단을 연결하며, 신뢰할 수 없는 코드나 끝이 정해지지 않은 작업에는 적합하지 않다.

🧠 상세 정리

1. Amazon Bedrock을 사용하는 배경과 데이터 통제

글은 로컬 노트북에서 Amazon Bedrock을 모델 공급자로 사용하는 Claude Code를 원격 에이전트로 확장하는 방법을 소개하며, 먼저 기존 사용 환경의 선택 이유를 설명한다. 고객은 좌석별 라이선스 없이 기존 AWS 계정의 과금과 크레딧을 이용하고, AWS CloudTrail 감사 로그와 데이터 상주 요건을 위한 지리적 추론 프로파일을 활용할 수 있다. Amazon Bedrock은 고객 콘텐츠를 모델 학습에 사용하거나 모델 공급자와 공유하지 않으며, 공급자는 프롬프트·응답·서비스 로그에 접근할 수 없다고 설명한다. 또한 SOC·ISO·FedRAMP Moderate 적용 범위에 포함되고 HIPAA 적격성을 갖추며 GDPR을 준수하는 방식으로 사용할 수 있다고 명시한다. 임시 IAM 자격 증명, Microsoft Entra ID·Okta 등의 로그인 연계, AWS PrivateLink를 통한 비공개 연결에 더해, 차세대 추론 엔진 Mantle의 운영자 접근 차단 설계인 ZOA와 설정 가능한 데이터 무보존 ZDR도 주요 통제로 제시한다.

2. 원격 코딩의 효용과 적합한 작업 범위

원격 코딩 에이전트는 코딩 요청을 맡겨 두고 다른 일을 하거나 노트북을 닫은 뒤 결과를 확인하는 작업 방식으로 소개된다. 여러 작업이 한 기기의 자원을 놓고 경쟁하지 않고 동시에 실행되며, 각각 노트북과 셸의 자격 증명에서 분리된 일회성 환경을 사용하고 결과는 동료가 검토할 수 있는 pull request로 돌아온다. 반면 실행 도중 방향을 조정하기 어렵고 환경 준비가 필요하며 비용 예측도 더 어려워진다는 절충점이 있다. 이 샘플은 사용자 AWS 계정에 속한 AgentCore runtime 세션에서 실행되고 모든 모델 호출을 Amazon Bedrock으로 보내므로, 앞서 설명한 모델 호출의 보안 특성을 이어받는다. 자체 setup·test 명령을 선언한 신뢰할 수 있는 저장소의 범위가 명확한 기능 개발·버그 수정·테스트에 적합하지만, 저장소 명령 자체를 안전하게 만들 수 없으므로 신뢰할 수 없는 코드에는 부적합하고 최대 3회 시도 제한 때문에 개방형 작업에도 맞지 않는다.

3. 작업 제출부터 격리 세션 시작까지

Claude Code에서 제출할 때는 sample-rca 플러그인이 로컬 Model Context Protocol 서버를 실행하고, 이 서버가 사용자 AWS 자격 증명으로 요청에 서명해 IAM 인증을 사용하는 Amazon API Gateway HTTP API를 호출한다. 다른 경로로는 Amazon CloudFront가 제공하는 웹 콘솔에 Amazon Cognito로 로그인하고 Cognito 인증 API를 통해 작업을 제출할 수 있다. AWS Lambda 함수는 Amazon Bedrock Guardrails로 작업 프롬프트를 검사한 다음 Amazon DynamoDB에 작업을 기록하고 Amazon SQS 대기열에 넣으며, 디스패처 함수가 해당 저장소의 runtime에서 작업용 세션 하나를 시작한다. 등록된 저장소마다 별도의 AgentCore runtime이 있고, Amazon ECR에 저장된 컨테이너 이미지에는 Claude Code CLI·Claude Agent SDK·git·make가 포함된다. 각 세션은 CPU·메모리·파일시스템이 격리된 microVM에서 실행되며, 이 환경은 Amazon Bedrock과 필요한 AWS 서비스에 대한 비공개 엔드포인트를 갖춘 VPC 안에 배치된다.

4. 계획·구현·검증과 pull request 반환

세션이 시작되면 에이전트는 AgentCore Identity에서 GitHub 접근 토큰을 받아 저장소를 복제하고, AgentCore memory에서 같은 저장소의 이전 작업이 남긴 교훈을 검색한다. 이어 Amazon Bedrock의 Claude Opus로 변경을 계획하고 Claude Sonnet으로 코드를 작성한 뒤, 같은 세션에서 저장소가 정의한 setup·test 명령을 실행한다. Claude Opus는 결과를 검토하며 필요하면 계획 단계로 되돌릴 수 있지만 전체 시도 횟수는 최대 3회이고, 각 단계의 기록은 AgentCore memory에 남아 숨겨진 빌드 선행 조건 같은 교훈을 이후 작업에 제공한다. 에이전트는 agent/<taskId> 브랜치를 푸시하고 검증 명령·종료 코드·사용한 시도 횟수를 담은 pull request를 열며, 검증을 통과하지 못했으면 초안 상태로 생성한다. 각 단계는 DynamoDB에도 상태를 보고해 Claude Code와 웹 콘솔이 진행 상황을 추적할 수 있게 하고, 최종 검토와 병합은 사람이 담당하며 에이전트는 병합하지 않는다.

5. 모델 호출·세션 격리·GitHub 자격 증명

원격 세션의 Claude Code는 Amazon Bedrock만 모델 공급자로 사용하고 비공개 엔드포인트를 통해 runtime의 IAM 실행 역할로 서명한 요청을 보내며, 컨테이너에는 다른 AWS 자격 증명을 보관하지 않는다. 각 작업의 전용 microVM은 세션 종료 시 메모리가 정리되고, 이후 작업으로 전달할 교훈은 AgentCore memory를 통해 유지된다. GitHub 접근에는 장기 자격 증명을 에이전트에 직접 보관하는 대신 Contents와 Pull requests의 읽기·쓰기 권한을 가진 GitHub App을 만들고 AgentCore Identity에 등록하며, 앱의 클라이언트 비밀값은 Identity의 토큰 보관소에 저장한다. 앱은 에이전트가 변경할 수 있는 저장소에만 설치하고 저장소마다 한 번씩 3자 OAuth인 3LO로 승인한 뒤, 각 컨테이너는 유효기간이 8시간이고 자동 갱신되는 사용자 대 서버 토큰을 받는다. 토큰의 접근 범위는 앱이 설치되어 있고 승인 사용자도 접근 권한을 가진 저장소로 제한되며, 커밋 작성자는 앱의 봇 계정으로 표시된다.

6. 제출 프롬프트 검사와 보호 범위의 한계

작업이 대기열에 들어가기 전에 API는 ApplyGuardrail API를 호출해 Amazon Bedrock Guardrails로 사용자가 제출한 프롬프트를 검사한다. 샘플은 코드를 이해하는 필터를 제공하는 Standard 등급을 사용하며, 낮은 강도로 탈옥·프롬프트 주입 시도와 악성코드 요청 같은 부정행위, AWS 접근 키 및 기타 비밀정보를 차단하도록 설정한다. 프롬프트가 차단되면 PromptBlockedByGuardrail을 반환하고 Guardrail이 응답하지 못해도 작업을 거부하므로, 검사 실패 상태에서 작업을 그대로 진행하지 않는다. 다만 검사 대상은 사용자가 입력한 작업 프롬프트이므로 실행 중 에이전트가 읽는 저장소 파일이나 명령 출력에 포함된 프롬프트 주입은 보지 못한다. 글은 모든 모델 호출을 검사하면 호출마다 전체 문맥을 다시 평가해 텍스트 양에 따른 비용이 발생하고 Claude Code 자체의 시스템 프롬프트도 주입 시도로 탐지될 수 있다고 설명하며, 제출 시점의 검사를 실행 중 모든 입력에 대한 보호로 해석하지 않도록 한계를 밝힌다.

7. 비공개 네트워크·최소 권한·사람의 승인

각 AgentCore runtime은 사용자 AWS 계정의 VPC 내 비공개 서브넷에서 실행되고 필요한 AWS 서비스에 VPC 엔드포인트로 연결하므로, 해당 서비스로 보내는 프롬프트·작업 상태·로그는 인터넷을 통과하지 않는다. 인터넷으로 나가는 경로는 GitHub와 패키지 레지스트리를 위한 NAT gateway이며 보안 그룹은 아웃바운드 HTTPS만 허용하고, Amazon Route 53 Resolver DNS Firewall은 api.anthropic.com 같은 모델 공급자의 자체 도메인을 차단한다. 다만 이 DNS 통제는 차단 목록 방식이어서 다른 HTTPS 트래픽까지 막지는 못하므로, 글은 운영 환경에서 AWS Network Firewall의 도메인 허용 목록을 고려하도록 제안한다. runtime IAM 역할은 Amazon Bedrock의 Anthropic 모델 호출, 해당 저장소의 작업 기록·메모리 읽기와 쓰기, 에이전트 이미지 가져오기로 권한을 제한하고, 여러 저장소가 공유하는 GitHub 자격 증명 공급자를 작업이 변경하지 못하도록 AgentCore Identity 제어 영역 접근을 명시적으로 거부한다. 최종 변경 반영은 사람이 결정하며, 기본 브랜치에 브랜치 보호를 켜 모든 변경이 검토를 받도록 권고한다.

8. 배포 시간과 제공된 사전 요구사항

이후 안내는 사용자 AWS 계정에 스택을 배포하고 GitHub를 연결해 저장소를 등록한 다음, 웹 콘솔이나 Claude Code로 작업을 실행하고 생성된 pull request를 검토하는 흐름을 예고한다. 배포에는 15~25분, 저장소 등록에는 추가로 8~12분이 걸린다고 설명하며, 가능하면 전용 AWS 계정을 사용하고 AgentCore runtime V2가 제공되는 리전을 선택하도록 한다. 열거된 리전은 버지니아 북부 us-east-1, 오하이오 us-east-2, 오리건 us-west-2, 도쿄 ap-northeast-1, 아일랜드 eu-west-1이고, 본문 예시는 us-west-2를 사용하며 모델 가용성은 리전별 안내를 참조하도록 한다. 준비 도구는 해당 계정의 자격 증명을 설정한 AWS CLI, 실행 중인 Docker, Python 3.11 이상, uv, Node.js 22.12 이상이며, 배포 과정에서 로컬 기기에 약 1.3GB의 ARM64 이미지를 빌드한다. 제공된 source_body는 작고 신뢰할 수 있는 GitHub 저장소를 언급하는 사전 요구사항 도중에 끝나므로, 이후의 구체적인 배포 명령이나 실행 결과는 확인할 수 없다.

🧾 핵심 주장 / 시사점

• 작업별 microVM 격리와 AgentCore memory의 교훈 전달을 결합해 실행 환경은 분리하면서 같은 저장소에서 얻은 경험은 후속 작업에 활용한다.
• Amazon Bedrock의 데이터 보호와 제출 프롬프트 검사는 서로 다른 범위를 다루며, 어느 쪽도 저장소 파일·명령 출력의 프롬프트 주입이나 모든 외부 HTTPS 통신을 포괄하는 통제로 설명되지는 않는다.
• 최대 3회의 반복, 저장소 명령에 의한 검증, 초안 pull request, 사람의 병합을 연결해 자동화의 종료 조건과 최종 변경 반영 권한을 구분한다.

✅ 액션 아이템

• 원격 실행 후보를 신뢰할 수 있는 저장소의 범위가 명확한 작업으로 한정하고 setup·test 명령 제공 여부 확인.
• Amazon Bedrock Guardrails의 검사 범위와 저장소·명령 출력의 프롬프트 주입, 차단 목록 밖 HTTPS 통신에 대한 한계 검토.
• GitHub pull request의 검증 결과와 최대 3회 시도 내역을 확인하고 사람의 검토 후 병합 여부 결정.

❓ 열린 질문

• 대상 저장소는 신뢰할 수 있는 저장소이며, 범위가 명확한 작업을 검증할 setup·test 명령을 제공하는가?
• Amazon Bedrock Guardrails가 검사하지 않는 저장소·명령 출력의 프롬프트 주입과 차단 목록 밖 HTTPS 통신의 한계를 어떻게 다룰 것인가?
• 최대 3회 시도 후에도 검증을 통과하지 못해 초안으로 생성된 GitHub pull request는 어떤 기준으로 후속 처리할 것인가?