클라우드 환경 구성

• Desktop 앱
• Claude 모바일 앱
• claude.ai/code의 브라우저
• claude --cloud를 사용한 터미널
• 클라우드 예약 작업
• Claude Tag

​

Default 환경

• /web-setup과 같은 CLI 흐름: Default를 생성합니다
• Pro 및 Max의 웹 온보딩: Default를 생성합니다
• Team 및 Enterprise의 웹 온보딩: Owner가 빠른 설정을 켜지 않은 한 첫 번째 클라우드 환경 생성 양식을 표시합니다. 양식의 기본값을 유지하고 생성 및 완료를 클릭하여 동일한 Default 환경을 얻습니다

• Trusted 네트워크 액세스: 세션이 패키지 레지스트리 및 기타 허용 목록 도메인에 도달하고 세션의 네트워크를 통해 다른 것에는 도달하지 않습니다.
• 다른 구성 없음: Default는 환경 변수 또는 설정 스크립트를 정의하지 않으므로 세션은 사전 설치된 도구만으로 시작됩니다.

• Desktop 앱, 모바일 앱 및 claude.ai/code에서 직접 시작하는 세션은 선택기에 표시된 환경을 사용합니다. 선택하지 않았을 때 Owner가 설정한 조직 기본값이 선택을 채웁니다. 프로젝트의 스레드는 프로젝트 설정에서 설정된 환경을 사용합니다.
• CLI에서 Claude Code는 /remote-env 선택을 사용하거나, 목록에 하나가 있으면 Anthropic 호스팅 환경으로 폴백하고, 그렇지 않으면 브리지 환경이 아닌 목록의 첫 번째 환경으로 폴백합니다. 브리지 환경은 클라우드 환경이 아닌 자신의 머신을 나타내기 위해 Remote Control이 등록하는 항목입니다. 자체 호스팅 환경의 경우 ccpool_ ID를 사용하여 --environment <environment-id>를 전달하면 세션을 디스패치할 때 /remote-env 선택 및 해당 호출에 대한 폴백을 재정의합니다. Claude Code는 플래그에 전달된 Anthropic 호스팅 env_ ID를 거부하므로 이를 대상으로 하려면 /remote-env를 사용합니다. 플래그는 Claude Code v2.1.224 이상이 필요합니다.

​

환경 구성하기

​

환경 변수 설정하기

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

• 유휴 상태 후 VM이 복원되는 경우: 몇 분 동안 활동이 없으면 세션의 VM은 파일이 저장된 상태로 일시 중지됩니다. 다음 메시지를 보내면 동일한 VM이 복원되고 Claude Code가 다시 시작됩니다.
• VM이 회수되어 다시 빌드되는 경우: 일시 중지된 VM이 이후 회수되었다면, 세션을 다시 열 때 새 VM이 프로비저닝됩니다.

​

네트워크 시크릿 추가하기

​

요구 사항

• 역할: Pro, Max, Team 요금제에서는 역할과 관계없이 본인 환경에 시크릿을 추가하고 삭제할 수 있습니다. Team 및 Enterprise에서는 Owner가 claude.ai 조직에서 조직 관리자 역할을 보유하고 Admin은 보유하지 않으며, 이에 따라 다음 경우에 표시되는 내용이 달라집니다.
  • Enterprise의 본인 환경: 조직 관리자 역할이 있으면 시크릿을 추가하고 삭제할 수 있습니다. 역할이 없으면 Network secrets 행을 선택했을 때 “Only an organization admin can add or delete network secrets”라는 안내와 함께 시크릿 목록이 열리며, Add secret 또는 삭제 버튼은 표시되지 않습니다. Owner에게 공유 환경에 시크릿을 추가하도록 요청한 다음 해당 환경에서 세션을 실행하십시오
  • 공유 환경: Owner가 관리자 설정에서 시크릿을 추가하고 삭제합니다. 조직 관리자 역할이 없으면 환경의 대화 상자에 Network secrets 섹션이 없으므로 Owner에게 시크릿 추가를 요청하십시오
  • Team의 본인 환경: 조직 관리자 역할이 없으면 Add secret을 선택했을 때 호스트 하나를 입력하는 간소화된 양식이 열립니다
• 환경 유형: 이미 존재하는 Anthropic 호스팅 클라우드 환경이어야 합니다. 자체 호스팅 환경에는 네트워크 시크릿이 없습니다
• API 접근성: 요청이 Anthropic의 네트워크에서 나가므로 API가 인터넷으로부터의 연결을 허용해야 합니다
• 암호화 키: 조직에서 고객 관리형 암호화 키를 사용하는 경우 네트워크 시크릿을 저장할 수 없습니다

​

시크릿 추가하기

​

조직 관리자 역할 없이 Team 요금제에서 시크릿 추가하기

• Host: 시크릿을 받는 단일 호스트(예: api.example.com). 이 양식은 *. 와일드카드를 허용하지 않습니다
• Name: 시크릿의 선택적 레이블
• Secret type: 요청 헤더로 전달되는 키의 경우 Token, 또는 Username and password. 토큰의 경우 키를 Value에 붙여 넣습니다

​

시크릿이 첨부되는 요청

​

시크릿이 첨부되지 않는 요청

• GitHub: GitHub에 대한 요청은 GitHub 프록시가 대신 인증하므로 이를 위한 네트워크 시크릿은 필요하지 않습니다
• Anthropic API 및 공개 패키지 레지스트리: api.anthropic.com, registry.npmjs.org, jsr.io, npm.jsr.io, pypi.org, files.pythonhosted.org, index.crates.io, proxy.golang.org
• 설정 스크립트 요청: Claude Code는 설정 스크립트가 실행된 후 실행될 때 에이전트 프록시에 연결됩니다
• Claude Code의 텔레메트리 내보내기: Claude Code는 텔레메트리 내보내기를 실행하는 명령을 통하지 않고 직접 전송하며, 이 요청은 에이전트 프록시를 거치지 않습니다

​

CLI에서 환경 선택하기

​

환경 보관하기

• 해당 환경에서 이미 실행 중인 세션은 계속 작동합니다.
• 환경이 선택기와 /remote-env에서 사라지므로 새 세션에 선택할 수 없습니다.
• 환경의 네트워크 시크릿은 실행 중인 세션에 계속 첨부됩니다. 더 이상 필요 없는 시크릿은 보관하기 전에 삭제하십시오.
• 어떤 사용 환경에서도 보관된 환경에서는 새 세션을 시작할 수 없습니다.
  • 저장된 CLI 기본값: 해당 환경이 저장된 CLI 기본값이었다면, 목록에 Anthropic 호스팅 환경이 있을 경우 Claude Code는 CLI 클라우드 세션을 해당 환경에서 시작합니다. 그렇지 않으면 목록에서 Remote Control 브리지 환경이 아닌 첫 번째 환경에서 시작합니다.
  • 명시적으로 구성된 경우: 클라우드 예약 작업처럼 해당 환경이 명시적으로 구성된 항목은 그 환경에서 새 세션을 시작할 수 없습니다. 다른 환경을 지정하십시오.

​

조직 공유 환경

• 공유 환경 만들기: 관리자 설정의 Cloud environments 페이지를 사용합니다. 이 페이지는 Owner가 공유 환경을 편집하고 보관하는 곳이기도 합니다. 각 환경에는 이름, 네트워크 액세스 수준, .env 형식의 환경 변수, 설정 스크립트가 있습니다.
• 개인 환경 공유하기: 환경 선택기에서 본인 환경 중 하나를 편집용으로 연 다음 Who can use it 행에서 공유합니다. 환경은 ID를 유지하므로 이미 해당 환경을 사용하는 세션과 예약 작업은 영향을 받지 않으며, 이후 모든 구성원이 이를 보고 해당 환경에서 세션을 시작할 수 있습니다.

​

Claude Tag 채널이 사용하는 환경 설정하기

• claude.ai/admin-settings/claude-code에서 공유 또는 자체 호스팅 환경을 조직의 기본 환경으로 설정합니다.
• Claude Tag 관리자 설정에서 채널에 환경을 고정합니다.

​

네트워크 액세스

​

액세스 수준

• GitHub(별도의 프록시를 통해)
• 활성화한 MCP 커넥터(트래픽이 Anthropic의 서버를 통해 이동)
• 환경의 네트워크 시크릿에 나열한 호스트(시크릿을 받지 않는 호스트 제외)
• Anthropic API(Claude Code의 자체 요청의 경우, 보안 및 격리 아래에 언급된 대로 None에서도)

​

특정 도메인 허용

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

• 이 환경의 세션이 다른 조직의 공개 아티팩트를 열기: Claude Code는 호스트에서 직접 이를 가져오므로 이 목록에 추가합니다.
• 로컬 CLI 또는 자체 호스팅 러너를 구성하는 경우: 호스트를 해당 허용 목록에 유지합니다. 네트워크 액세스 요구 사항 및 자체 호스팅 네트워크 요구 사항을 참조합니다.

​

GitHub 프록시

• Git 자격 증명: VM 내부의 git 클라이언트는 범위가 지정된 자격 증명을 사용하며, 프록시는 이를 확인하고 실제 GitHub 토큰으로 교환합니다.
• API 요청: 기본 제공 GitHub 도구의 요청 및 proxy-injected 자리 표시자 아래의 gh에서의 요청은 실제 자격 증명이 대체되어 나갑니다.
• 푸시 제한: 프록시는 브랜치 삭제 및 태그와 같이 브랜치가 아닌 항목의 푸시를 거부합니다. 푸시가 업데이트할 수 있는 브랜치는 제한하지 않습니다. 이를 제한하려면 GitHub에서 브랜치 보호 규칙 또는 규칙 세트를 사용합니다.
• 저장소 범위: 프록시는 세션에 연결된 저장소에 대한 GitHub API 요청을 처리합니다. 다른 저장소에 대한 API 요청은 GitHub access to로 시작하고 is not enabled for this session을 포함하는 메시지와 함께 403을 받습니다. github.com/{owner}/{repo}/archive/ 또는 codeload.github.com URL을 통해 가져오는 소스 아카이브도 저장소가 연결되어 있지 않으면 공개 저장소라도 동일한 403을 받습니다.
• GraphQL 제한: 프록시는 GitHub의 GraphQL 엔드포인트에 대한 요청을 GitHub GraphQL is not available from Claude Code sessions로 시작하는 메시지와 함께 403으로 거부하며, 이 메시지는 REST 폴백인 gh api repos/{owner}/{repo}/...를 안내합니다. gh pr 및 gh issue와 같이 GraphQL을 사용하는 gh 하위 명령도 동일한 403을 받습니다. 제한은 제공하는 자격 증명과 관계없이 프록시를 통한 모든 요청에 적용되므로 설정한 GH_TOKEN은 동일한 403을 받습니다. Claude는 Projects v2와 같이 GraphQL에만 존재하는 GitHub API에 프록시를 통해 도달할 수 없습니다.

​

보안 프록시

• 악의적인 요청으로부터의 보호
• 속도 제한 및 남용 방지

​

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

​

설정에서 전달되는 항목

​

저장소에 커밋하지 않고 개인 기본 설정 추가

#!/bin/bash
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md <<'EOF'
Use conventional commit messages.
EOF

​

설치된 도구

​

GitHub 이슈 및 풀 리퀘스트 작업

• 토큰을 설정하면 컨테이너에 변경되지 않고 전달되므로 스크립트 및 GitHub의 gh CLI가 직접 사용합니다.
• 둘 다 설정하지 않고 GitHub 프록시가 세션에 대한 인증을 처리하는 경우 두 변수 모두 Claude가 실행하는 명령에서 자리 표시자 문자열 proxy-injected로 읽히며, 프록시는 아웃바운드 GitHub 요청에서 실제 자격 증명으로 대체합니다. 연결된 저장소에 대한 gh api 호출은 자신의 토큰 없이 작동하지만 GITHUB_TOKEN을 직접 읽는 스크립트는 사용 가능한 토큰이 아닌 자리 표시자를 받습니다.

​

출력을 세션에 다시 연결

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

​

테스트 실행, 서비스 시작 및 패키지 추가

​

테스트 실행

​

서비스 시작

service postgresql start

service redis-server start

​

패키지 추가

​

리소스 제한

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

​

시간 제한

• Claude가 실행하는 명령: 클라우드 환경은 자체 명령 타임아웃을 설정하지 않으므로 Bash 도구의 기본값이 적용됩니다. Claude는 기본적으로 포그라운드 명령을 2분 동안 기다리며 최대 10분까지 요청할 수 있습니다. 명령이 타임아웃에 도달하면 Claude Code는 명령이 sleep으로 시작하지 않는 한 명령을 중지하는 대신 백그라운드로 이동합니다. 이런 방식으로 이동된 명령은 Claude Code가 백그라운드 시간 제한에서 중지하기 전에 최대 30분 더 실행될 수 있습니다. BASH_DEFAULT_TIMEOUT_MS를 1800000 밀리초 이상으로 설정하면 해당 제한과 포그라운드 기본값이 모두 길어집니다.
• SessionStart 훅: Claude Code는 훅 항목에 timeout을 초 단위로 설정하지 않으면 600초 후 command 훅을 취소합니다. Claude Code는 async: true로 실행하는 훅에 타임아웃을 적용하지 않습니다.
• 설정 스크립트: 대략 5분 이상 걸리는 스크립트는 캐시되지 않습니다. 스크립트 요구 사항은 그 이하로 유지하는 방법을 다룹니다.
• 유휴 세션: 몇 분 동안 활동이 없으면 세션의 VM이 파일이 저장된 상태로 일시 중지되고, 일시 중지된 VM은 나중에 회수될 수 있습니다. 환경 변수 설정은 각 경우에 세션이 반영하는 항목을 설명하고, Environment expired는 VM이 회수된 세션을 다시 여는 방법을 다룹니다.

​

설정 스크립트

​

설정 스크립트 추가

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

​

스크립트 요구사항

• 종료 코드 0: 스크립트가 0이 아닌 코드로 종료되면 세션이 시작되지 않습니다. 중요하지 않은 명령에 || true를 추가하여 일시적인 설치 실패가 세션을 차단하지 않도록 합니다.
• 5분 이내에 완료: 스크립트의 총 실행 시간을 약 5분 이내로 유지하여 환경 캐시를 구축할 수 있도록 합니다. 설정이 그보다 오래 걸리면 환경이 캐시되지 않습니다. &와 wait를 사용하여 독립적인 설치를 병렬로 실행하고, 맞지 않는 단일 다운로드는 백그라운드에서 실행하는 SessionStart hook으로 이동합니다. 새 세션이 설정 중에 정지되거나 실패하면 새 세션이 설정 중에 정지되거나 시간 초과됨을 참조합니다.
• 설치를 위한 네트워크 액세스: 패키지 설치는 레지스트리에 도달해야 합니다. 기본 신뢰됨 수준은 npm, PyPI, RubyGems 및 crates.io를 포함한 일반적인 패키지 레지스트리를 포함합니다. 없음 네트워크 액세스를 사용하면 설치가 실패합니다.
• 환경의 변수가 아직 설정되지 않음: 스크립트는 세션이 환경의 환경 변수를 설정하기 전에 실행됩니다. 스크립트에 필요한 값은 스크립트 자체에서 설정합니다.

​

환경 캐싱

​

설정 스크립트 vs. SessionStart hook

• Anthropic 호스팅 환경: Claude Code는 조직의 서버 관리형 설정의 훅을 실행하고, 프로젝트 스레드 외부에서는 저장소의 훅도 실행합니다. Claude Tag 세션은 서버 관리형 설정을 받지 않으므로 서버 관리형 설정의 훅은 그곳에서 실행되지 않습니다.
• 자체 호스팅 환경: Claude Code는 또한 운영자가 실행기 호스트의 ~/.claude/에서 시드한 hook과 실행기 이미지의 관리 설정 파일의 hook을 실행합니다. 해당 파일이 Claude Code가 적용하는 관리 소스 중 하나인 경우입니다.

​

SessionStart hook으로 종속성 설치

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash

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

cd "$CLAUDE_PROJECT_DIR" || exit 1
hashes=node_modules/.install_pkgs.sha256

if ! sha256sum --check --status "$hashes" 2>/dev/null; then
  # Delete the old hashes first, so a failed install runs again next time
  rm -f "$hashes"
  if npm install; then
    sha256sum scripts/install_pkgs.sh package.json package-lock.json > "$hashes" || rm -f "$hashes"
  fi
fi

# pip skips requirements that are already satisfied
pip install -r requirements.txt
exit 0

​

클라우드 세션의 제한사항

• 세션당 하나의 저장소: Anthropic 호스팅 환경에서 여러 저장소가 있는 세션은 어떤 저장소의 .claude/settings.json에서도 훅을 로드하지 않으므로 그곳에 정의한 SessionStart 훅이 실행되지 않습니다. 이러한 세션의 의존성은 대신 설정 스크립트로 설치합니다. 자체 호스팅 환경의 경우 어떤 저장소의 설정이 적용되는지를 참조합니다.
• 프로젝트의 클라우드 스레드에서는 실행되지 않음: 프로젝트의 클라우드 스레드는 저장소 수와 관계없이 저장소의 .claude/settings.json에 있는 훅을 실행하지 않습니다. Anthropic 호스팅 환경에서는 설정 스크립트로 스레드의 의존성을 설치합니다. 자체 호스팅 환경에서는 대신 실행기 호스트의 설정에 있는 훅을 사용합니다.
• 클라우드 전용 범위 없음: hook은 로컬 및 클라우드 세션 모두에서 실행됩니다. 로컬 실행을 건너뛰려면 CLAUDE_CODE_REMOTE 환경 변수가 true가 아닌 한 조기에 종료합니다. 종속성 설치 스크립트가 수행하는 방식입니다.
• 네트워크 액세스 필요: 설치 명령은 패키지 레지스트리에 도달해야 합니다. 환경이 없음 네트워크 액세스를 사용하면 이러한 hook이 실패합니다. 신뢰됨 아래의 기본 허용 목록은 npm, PyPI, RubyGems 및 crates.io를 포함합니다.
• 프록시 호환성: Anthropic 호스팅 환경에서 모든 아웃바운드 트래픽은 보안 프록시를 통과하고, 일부 패키지 관리자는 이와 올바르게 작동하지 않습니다. Bun은 알려진 예입니다. 자체 호스팅 환경에서 아웃바운드 트래픽은 대신 자신의 네트워크 경계를 통과합니다.
• 시작 지연 추가: 훅은 환경 캐싱의 이점을 받는 설정 스크립트와 달리 세션이 시작되거나 재개될 때마다 실행됩니다. 의존성 설치 스크립트처럼 이미 완료된 작업을 건너뛰어 설치 스크립트를 빠르게 유지합니다.

​

기본 허용 도메인

​

관련 리소스

• 클라우드 세션 참조: 클라우드 세션 시작, 관리 및 공유
• 클라우드 세션 빠른 시작: GitHub 연결 및 첫 번째 클라우드 세션 시작
• Claude Tag: Claude가 Slack에서 시작하는 세션은 동일한 환경에서 실행됩니다
• 클라우드 예약 작업: 예약된 실행은 동일한 환경 및 네트워크 액세스 수준을 사용합니다
• Remote Control: 자신의 머신의 네트워크 및 파일에서 세션 실행
• 자체 호스팅 환경: 조직의 자체 인프라에서 클라우드 세션 실행
• SessionStart 훅: 로컬 및 클라우드 세션에서 실행되는 리포지토리 커밋 설정
• 서버 관리 설정: 관리 콘솔에서 전달되는 조직 정책