클라우드 환경 구성

클라우드 환경은 웹 세션과 루틴이 실행될 VM의 준비 방식을 정의합니다. 환경에는 네트워크 접근 수준, 환경 변수, 설정 스크립트가 포함됩니다.

클라우드 세션에서 사용 가능한 것

각 세션은 저장소의 새 복제본에서 시작합니다. 저장소에 커밋된 프로젝트 범위 설정은 사용할 수 있고, 사용자의 로컬 머신에만 있는 설정은 사용할 수 없습니다.

클라우드에서 필요한 설정은 저장소에 커밋하거나 환경 변수와 설정 스크립트로 옮깁니다. 환경 변수와 설정 스크립트는 그 환경을 편집할 수 있는 사람에게 보이므로 비밀 값은 신중하게 다룹니다.

설치된 도구

클라우드 세션에는 일반적인 개발 도구가 사전 설치되어 있습니다.

정확한 버전은 클라우드 세션에서 Claude에게 check-tools를 실행하도록 요청해 확인합니다. 이 명령은 클라우드 세션에만 존재합니다.

PostgreSQL과 Redis는 설치되어 있지만 기본적으로 실행되지는 않습니다. 필요하면 세션 중에 시작하도록 요청합니다.

service postgresql start

service redis-server start

Docker 이미지를 매번 다시 가져오지 않으려면 설정 스크립트에 docker compose pull 또는 docker compose build를 넣어 캐시에 포함시킵니다.

GitHub 이슈와 PR 작업

클라우드 세션에는 Claude가 이슈를 읽고, pull request를 나열하고, diff를 가져오고, 댓글을 게시할 수 있는 GitHub 도구가 포함되어 있습니다. 인증은 GitHub 인증 옵션에서 구성한 방식과 GitHub 프록시를 사용하므로 토큰이 컨테이너에 직접 들어가지 않습니다.

gh CLI는 기본 설치 항목이 아닙니다. gh release, gh workflow run 같은 명령이 필요하면 설정 스크립트에 설치를 추가하고 GH_TOKEN 환경 변수를 제공합니다.

#!/bin/bash
apt update && apt install -y gh

세션 아티팩트 연결

각 클라우드 세션은 CLAUDE_CODE_REMOTE_SESSION_ID 환경 변수에서 자신의 ID를 읽을 수 있습니다. PR 본문, 커밋 메시지, Slack 게시물, 생성 보고서 등에 세션 링크를 넣어 검토자가 원본 실행을 열 수 있게 할 때 유용합니다.

echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"

리소스 제한

클라우드 세션은 대략 다음 상한으로 실행됩니다.

• 4 vCPU
• 16 GB RAM
• 30 GB 디스크

대규모 빌드나 메모리 집약적 테스트가 이 한계를 넘으면 실패할 수 있습니다. 더 큰 로컬 하드웨어나 사설 네트워크가 필요하면 Remote Control을 사용합니다.

환경 구성

환경은 웹 인터페이스 또는 Claude Code CLI에서 관리합니다.

환경 변수는 .env 형식이며 한 줄에 하나의 KEY=value 쌍을 작성합니다. 따옴표는 값의 일부로 저장되므로 값을 따옴표로 감싸지 않습니다.

NODE_ENV=development
LOG_LEVEL=debug
DATABASE_URL=postgres://localhost:5432/myapp

설정 스크립트

설정 스크립트는 새 클라우드 세션이 시작될 때 Claude Code 실행 전에 root 권한으로 실행되는 Bash 스크립트입니다. 사전 설치되지 않은 시스템 도구, 언어 패키지, Docker 이미지를 준비하는 데 사용합니다.

설정 스크립트를 추가하려면 환경 설정 대화 상자의 Setup script 필드에 스크립트를 입력합니다.

#!/bin/bash
apt update && apt install -y gh

스크립트가 0이 아닌 값으로 종료되면 세션이 시작되지 않습니다. 중요하지 않은 명령은 || true로 완화하고, 디버깅할 때는 set -x를 추가합니다.

패키지 설치에는 네트워크 접근이 필요합니다. 환경이 None이면 패키지 레지스트리에 도달할 수 없고, 기본 Trusted는 일반 패키지 레지스트리를 허용합니다.

환경 캐싱

설정 스크립트가 성공하면 Anthropic이 파일 시스템을 스냅샷하고 이후 같은 환경의 새 세션 시작점으로 재사용할 수 있습니다. 설치된 도구, 다운로드된 패키지, 가져온 Docker 이미지는 빨라지지만 실행 중인 서비스나 프로세스는 캐시되지 않습니다.

환경의 설정 스크립트나 허용 네트워크 호스트를 변경하면 캐시가 다시 빌드됩니다. 기존 세션을 재개할 때는 설정 스크립트가 다시 실행되지 않습니다.

설정 스크립트와 SessionStart hooks

클라우드 VM 자체에 필요한 도구를 설치하려면 설정 스크립트를 사용합니다. 저장소의 프로젝트 준비 작업을 로컬과 클라우드 모두에서 실행해야 한다면 SessionStart hook을 사용합니다.

클라우드에서만 hook을 실행하려면 CLAUDE_CODE_REMOTE 환경 변수를 확인합니다.

#!/bin/bash

if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
  exit 0
fi

npm install
pip install -r requirements.txt
exit 0

후속 Bash 명령에 환경 변수를 전달해야 하면 $CLAUDE_ENV_FILE에 씁니다.

네트워크 액세스

각 환경은 하나의 네트워크 접근 수준을 가집니다. 기본값인 Trusted는 일반 패키지 레지스트리와 개발 도메인을 허용하고 임의의 외부 접근을 차단합니다.

Trusted 기본 허용 목록은 GitHub, GitLab, Bitbucket, Docker와 주요 컨테이너 레지스트리, Google Cloud/AWS/Azure/Oracle 관련 도메인, npm/PyPI/RubyGems/crates.io/Go/JVM/PHP/.NET/Dart/Elixir 등 일반 패키지 레지스트리, Ubuntu 및 NixOS 배포 도메인, Kubernetes/HashiCorp/Anaconda/Apache/Eclipse/Node.js/Android/Apple 개발 도메인, Sentry/Datadog/Honeycomb 같은 모니터링 도메인, schema store, MCP 관련 도메인을 포함합니다.

Trusted 목록에 없는 도메인을 허용하려면 Custom 을 선택하고 Allowed domains에 한 줄에 하나씩 입력합니다.

api.example.com
*.internal.example.com
registry.example.com

와일드카드 하위 도메인에는 *.를 사용합니다. 기본 패키지 관리자 목록을 함께 유지하려면 Also include default list of common package managers 를 선택합니다.

GitHub clone, fetch, push, PR 작업은 별도 GitHub 프록시를 사용합니다. 이 프록시는 범위가 제한된 자격 증명을 검증하고 push를 현재 작업 브랜치로 제한합니다.

MCP 커넥터 트래픽은 Anthropic 서버를 통해 라우팅되므로 커넥터 호스트를 Allowed domains에 추가하지 않아도 작동합니다. 대신 루틴이나 세션에 포함된 커넥터 목록을 줄여 Claude가 사용할 수 있는 도구를 제한합니다.