클라우드 환경 구성

​

Default 환경

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

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

• 웹, Desktop 앱 및 모바일 앱에서 세션은 선택기에 표시된 환경을 사용합니다. 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 이상이 필요합니다.

​

환경 구성

1

환경 선택기 열기

claude.ai/code에서 메시지 상자 위의 행에 있는 현재 환경의 이름을 표시하는 클라우드 아이콘을 선택합니다. 선택기에 대한 설정 페이지 또는 직접 URL이 없습니다.

2

환경 추가 또는 편집

Add cloud environment를 선택하거나 기존 환경 위에 마우스를 가져가서 오른쪽에 나타나는 설정 아이콘을 선택합니다. 대화 상자에는 이름, 네트워크 액세스 수준, 환경 변수 및 설정 스크립트가 포함됩니다. Pro 또는 Max 플랜에서 기존 클라우드 환경을 편집할 때 대화 상자에는 API 자격 증명도 포함됩니다.

​

환경 변수 설정

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

​

API 자격 증명 추가

​

요구 사항

• 역할: claude.ai 조직의 조직 관리자 역할
  • Team 및 Enterprise에서 Owner가 보유하고 Admin은 보유하지 않습니다
  • Pro 및 Max에서 자신의 조직에서 보유합니다
  • 이를 보유하지 않으면 자신의 환경에서도 자격 증명 목록 대신 참고 사항을 봅니다. Owner에게 공유 환경에 자격 증명을 추가하고 거기에서 세션을 실행하도록 요청합니다
• 환경 유형: 이미 존재하는 Anthropic 호스팅 클라우드 환경. 자체 호스팅 환경에는 API 자격 증명이 없습니다
• API 도달 가능성: API가 인터넷에서의 연결을 수락합니다. 요청이 Anthropic의 네트워크에서 나가기 때문입니다
• 암호화 키: 조직이 고객 관리 암호화 키를 사용하는 경우 자격 증명을 저장할 수 없습니다

​

자격 증명 추가

​

자격 증명을 받는 요청

​

자격 증명을 받지 않는 요청

• GitHub: GitHub 프록시가 대신 GitHub에 대한 요청을 인증하므로 GitHub에 대한 API 자격 증명이 필요하지 않습니다
• 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는 설정 스크립트가 실행된 후 시작될 때 에이전트 프록시에 연결합니다

​

CLI에서 환경 선택

​

환경 보관

• 환경에서 이미 실행 중인 세션은 계속 작동합니다.
• 환경이 선택기 및 /remote-env에서 사라지므로 새 세션에 대해 선택할 수 없습니다.
• 환경의 API 자격 증명은 실행 중인 세션에 첨부된 상태로 유지됩니다. 보관하기 전에 더 이상 원하지 않는 것을 삭제합니다.
• 모든 표면에서 보관된 환경에서 새 세션을 시작할 수 없습니다. 환경이 저장된 CLI 기본값인 경우 Claude Code는 목록에 하나가 있으면 Anthropic 호스팅 환경에서 CLI 클라우드 세션을 시작하고, 그렇지 않으면 Remote Control 브리지 환경이 아닌 목록의 첫 번째 환경에서 시작합니다. 루틴과 같이 환경으로 명시적으로 구성된 모든 것은 새 세션을 시작할 수 없습니다. 다른 환경을 가리킵니다.

​

조직 공유 환경

​

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

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

​

네트워크 액세스

​

액세스 수준

• GitHub(별도의 프록시를 통해)
• 활성화한 MCP 커넥터(트래픽이 Anthropic의 서버를 통해 이동)
• 환경의 API 자격 증명에 나열한 호스트(에이전트 프록시가 건너뛰는 호스트 제외)
• 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에서의 요청은 실제 자격 증명이 대체되어 나갑니다.
• 푸시 보호: git push는 세션의 현재 작업 분기에 대해서만 작동합니다. 복제, 페치 및 PR 작업은 정상적으로 작동합니다.
• 리포지토리 범위: GitHub API 및 릴리스 자산 요청은 세션에 연결된 리포지토리에만 도달하므로 연결되지 않은 리포지토리에서 릴리스 자산을 다운로드하는 설정 스크립트는 403을 받습니다.
• GraphQL 제한: 프록시는 풀 요청 워크플로우에 대해서만 고정된 GraphQL 작업 세트를 제공합니다. 프록시는 GraphQL 엔드포인트의 다른 모든 것을 This GraphQL query is not enabled for this session이라고 말하는 403으로 거부하고 REST 폴백인 gh api repos/{owner}/{repo}/...의 이름을 지정합니다. 제한은 제공하는 자격 증명과 관계없이 프록시를 통한 모든 요청에 적용되므로 설정한 GH_TOKEN은 동일한 403을 받습니다. Claude는 Projects v2와 같이 GraphQL에만 존재하는 GitHub API에 프록시를 통해 도달할 수 없습니다.

​

보안 프록시

• 악의적인 요청으로부터의 보호
• 속도 제한 및 남용 방지
• 향상된 보안을 위한 콘텐츠 필터링
• 요청된 호스트 이름의 DNS 수준 감사 추적

​

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

​

설정에서 전달되는 항목

​

설치된 도구

​

GitHub 이슈 및 풀 요청 작업

• 토큰을 설정하면 컨테이너에 변경되지 않고 전달되므로 스크립트 및 GitHub의 gh CLI가 직접 사용합니다.
• 둘 다 설정하지 않고 GitHub 프록시가 세션에 대한 인증을 처리하는 경우 두 변수 모두 Claude가 실행하는 명령에서 자리 표시자 문자열 proxy-injected로 읽으며, 프록시는 아웃바운드 GitHub 요청에서 실제 자격 증명을 대체합니다. gh는 자신의 토큰 없이 작동하지만 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의 디스크

​

설정 스크립트

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

​

스크립트 요구 사항

• 0으로 종료: 스크립트가 0이 아닌 값으로 종료되면 세션이 시작되지 않습니다. 간헐적인 설치 실패가 세션을 차단하지 않도록 중요하지 않은 명령에 || true를 추가합니다.
• 5분 이내에 완료: 환경 캐시를 빌드할 수 있도록 스크립트의 총 런타임을 대략 5분 이내로 유지합니다. & 및 wait로 독립적인 설치를 병렬로 실행하고 맞지 않는 단일 다운로드를 SessionStart 훅으로 이동하여 백그라운드에서 시작합니다.
• 설치를 위한 네트워크 액세스: 패키지 설치는 레지스트리에 도달해야 합니다. 기본 Trusted 수준은 npm, PyPI, RubyGems 및 crates.io를 포함한 일반적인 패키지 레지스트리를 다룹니다. None 네트워크 액세스를 사용하면 설치가 실패합니다.

​

환경 캐싱

​

설정 스크립트 대 SessionStart 훅

• Anthropic 호스팅 환경: Claude Code는 리포지토리 및 조직의 서버 관리 설정에서 훅을 실행합니다.
• 자체 호스팅 환경: Claude Code는 또한 러너 호스트의 ~/.claude/에서 운영자가 시드한 훅과 Claude Code가 적용하는 관리 소스 중 하나인 경우 러너 이미지의 관리 설정 파일의 훅을 실행합니다.

​

SessionStart 훅으로 종속성 설치

{
  "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

npm install
pip install -r requirements.txt
exit 0

​

클라우드 세션의 제한 사항

• 클라우드 전용 범위 없음: 훅은 로컬 및 클라우드 세션 모두에서 실행됩니다. 로컬 실행을 건너뛰려면 위에 표시된 대로 CLAUDE_CODE_REMOTE 환경 변수를 확인합니다.
• 네트워크 액세스 필요: 설치 명령은 패키지 레지스트리에 도달해야 합니다. 환경이 None 네트워크 액세스를 사용하면 이러한 훅이 실패합니다. Trusted 아래의 기본 허용 목록은 npm, PyPI, RubyGems 및 crates.io를 다룹니다.
• 프록시 호환성: Anthropic 호스팅 환경에서 모든 아웃바운드 트래픽은 보안 프록시를 통과하고, 일부 패키지 관리자는 이 프록시에서 올바르게 작동하지 않습니다. Bun은 알려진 예입니다. 자체 호스팅 환경에서 아웃바운드 트래픽은 자신의 네트워크 경계를 통해 나갑니다.
• 시작 지연 추가: 훅은 환경 캐싱의 이점을 누리는 설정 스크립트와 달리 세션이 시작되거나 재개될 때마다 실행됩니다. 다시 설치하기 전에 종속성이 이미 있는지 확인하여 설치 스크립트를 빠르게 유지합니다.

​

기본 허용 도메인

​

관련 리소스

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