---
title: 클라우드 환경 설정
url: https://platform.claude.com/docs/ko/managed-agents/environments
description: 세션에 사용할 클라우드 샌드박스를 사용자 지정합니다.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

"Environment"(환경)는 에이전트가 실행되는 샌드박스 구성을 정의합니다. 환경을 한 번 생성한 다음, 세션을 시작할 때마다 해당 ID를 참조합니다. 여러 세션이 동일한 환경을 공유할 수 있지만, 각 세션은 자체적으로 격리된 샌드박스(새로운 Linux 컨테이너)를 갖습니다.

이 페이지에서는 `type: cloud` 환경을 다룹니다. 자체 인프라에서 샌드박스를 실행하려면 [자체 호스팅 샌드박스](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes)를 참조하세요. 둘 중 하나를 선택하려면 [에이전트 환경 선택하기](https://platform.claude.com/docs/ko/managed-agents/choosing-an-environment)를 참조하세요.

## 환경 생성

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsS https://api.anthropic.com/v1/environments \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    --data '{
      "name": "python-dev",
      "config": {
        "type": "cloud",
        "networking": {"type": "limited", "allow_package_managers": true}
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply environment.yaml
    ```

    <File filename="environment.yaml">
      ```yaml
      # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
      name: python-dev
      config:
        type: cloud
        networking:
          type: limited
          allow_package_managers: true
      ```
    </File>

    [`ant apply`](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/apply)는 `environment.yaml`에서 환경을 생성하고, 해당 ID를 출력한 뒤 `claude-lock.json`에 기록합니다. 다음 `ant apply` 실행 시 환경을 다시 생성하려 하지 않고 이 환경을 업데이트하도록 `claude-lock.json`을 커밋하세요.
  </CodeGroupItem>

  ```python Python
  environment = client.beta.environments.create(
      name="python-dev",
      config={
          "type": "cloud",
          "networking": {"type": "limited", "allow_package_managers": True},
      },
  )

  print(f"Environment ID: {environment.id}")
  ```

  ```typescript TypeScript
  const environment = await client.beta.environments.create({
    name: "python-dev",
    config: {
      type: "cloud",
      networking: { type: "limited", allow_package_managers: true }
    }
  });

  console.log(`Environment ID: ${environment.id}`);
  ```

  ```csharp C#
  var environment = await client.Beta.Environments.Create(new()
  {
      Name = "python-dev",
      Config = new BetaCloudConfigParams
      {
          Networking = new BetaLimitedNetworkParams
          {
              AllowPackageManagers = true,
          },
      },
  });

  Console.WriteLine($"Environment ID: {environment.ID}");
  ```

  ```go Go
  environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
  	Name: "python-dev",
  	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
  		OfCloud: &anthropic.BetaCloudConfigParams{
  			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
  				OfLimited: &anthropic.BetaLimitedNetworkParams{
  					AllowPackageManagers: anthropic.Bool(true),
  				},
  			},
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }

  fmt.Printf("Environment ID: %s\n", environment.ID)
  ```

  ```java Java
  var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
      .name("python-dev")
      .config(BetaCloudConfigParams.builder()
          .networking(BetaLimitedNetworkParams.builder()
              .allowPackageManagers(true)
              .build())
          .build())
      .build());
  IO.println("Environment ID: " + environment.id());
  ```

  ```php PHP
  $environment = $client->beta->environments->create(
      name: 'python-dev',
      config: [
          'type' => 'cloud',
          'networking' => ['type' => 'limited', 'allow_package_managers' => true],
      ],
  );
  echo "Environment ID: {$environment->id}\n";
  ```

  ```ruby Ruby
  environment = client.beta.environments.create(
    name: "python-dev",
    config: {
      type: "cloud",
      networking: {type: "limited", allow_package_managers: true}
    }
  )

  puts "Environment ID: #{environment.id}"
  ```
</CodeGroup>

환경을 서로 구분할 수 있도록 고유하고 설명적인 `name` (csharp, go: `Name`)을 사용하세요. 이 예시는 패키지 관리자가 허용된 `limited` [네트워킹](https://platform.claude.com/docs/ko/managed-agents/environments#networking)을 사용하므로, 샌드박스가 패키지 레지스트리와 코드 호스트에 접근할 수 있습니다. 다른 호스트에 접근할 수 있도록 하려면 해당 호스트를 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)에 추가하세요.

## 세션에서 환경 사용

[세션을 생성](https://platform.claude.com/docs/ko/managed-agents/sessions)할 때 환경 ID를 문자열로 전달하세요.

<CodeGroup>
  ```bash cURL
  curl -fsS https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    --data '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENVIRONMENT_ID"
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
  )
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id
  });
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
  });
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .build());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
  );
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id
  )
  ```
</CodeGroup>

## 구성 옵션

### 패키지

`packages` (csharp, go: `Packages`) 필드는 에이전트가 시작되기 전에 샌드박스에 패키지를 미리 설치합니다. 패키지는 각각의 패키지 관리자에 의해 설치되며, 동일한 환경을 공유하는 세션 간에 캐시됩니다. 여러 패키지 관리자가 지정된 경우 알파벳 순서(apt, cargo, gem, go, npm, pip)로 실행됩니다. 선택적으로 특정 버전을 고정할 수 있습니다. 버전이 고정되지 않은 패키지는 최신 버전으로 설치됩니다. 환경이 `limited` [네트워킹](https://platform.claude.com/docs/ko/managed-agents/environments#networking)을 사용하는 경우, `networking` (csharp, go: `Networking`)에서 `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`)도 `true`로 설정하세요. 그렇지 않으면 요청이 400 오류와 함께 거부됩니다.

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsS https://api.anthropic.com/v1/environments \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    --data '{
      "name": "data-analysis",
      "config": {
        "type": "cloud",
        "packages": {
          "pip": ["pandas", "numpy", "scikit-learn"],
          "npm": ["express"]
        },
        "networking": {"type": "limited", "allow_package_managers": true}
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply environment.yaml
    ```

    <File filename="environment.yaml">
      ```yaml
      # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
      name: data-analysis
      config:
        type: cloud
        packages:
          pip:
            - pandas
            - numpy
            - scikit-learn
          npm:
            - express
        networking:
          type: limited
          allow_package_managers: true
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  environment = client.beta.environments.create(
      name="data-analysis",
      config={
          "type": "cloud",
          "packages": {
              "pip": ["pandas", "numpy", "scikit-learn"],
              "npm": ["express"],
          },
          "networking": {"type": "limited", "allow_package_managers": True},
      },
  )
  ```

  ```typescript TypeScript
  const environment = await client.beta.environments.create({
    name: "data-analysis",
    config: {
      type: "cloud",
      packages: {
        pip: ["pandas", "numpy", "scikit-learn"],
        npm: ["express"]
      },
      networking: { type: "limited", allow_package_managers: true }
    }
  });
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Environments;

  var environment = await client.Beta.Environments.Create(new()
  {
      Name = "data-analysis",
      Config = new BetaCloudConfigParams
      {
          Packages = new()
          {
              Pip = ["pandas", "numpy", "scikit-learn"],
              Npm = ["express"],
          },
          Networking = new BetaLimitedNetworkParams
          {
              AllowPackageManagers = true,
          },
      },
  });
  ```

  ```go Go
  environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
  	Name: "data-analysis",
  	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
  		OfCloud: &anthropic.BetaCloudConfigParams{
  			Packages: anthropic.BetaPackagesParams{
  				Pip: []string{"pandas", "numpy", "scikit-learn"},
  				Npm: []string{"express"},
  			},
  			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
  				OfLimited: &anthropic.BetaLimitedNetworkParams{
  					AllowPackageManagers: anthropic.Bool(true),
  				},
  			},
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  _ = environment
  ```

  ```java Java
  import com.anthropic.models.beta.environments.*;
  import java.util.List;

  var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
      .name("data-analysis")
      .config(BetaCloudConfigParams.builder()
          .packages(BetaPackagesParams.builder()
              .pip(List.of("pandas", "numpy", "scikit-learn"))
              .npm(List.of("express"))
              .build())
          .networking(BetaLimitedNetworkParams.builder()
              .allowPackageManagers(true)
              .build())
          .build())
      .build());
  ```

  ```php PHP
  $environment = $client->beta->environments->create(
      name: 'data-analysis',
      config: [
          'type' => 'cloud',
          'packages' => [
              'pip' => ['pandas', 'numpy', 'scikit-learn'],
              'npm' => ['express'],
          ],
          'networking' => ['type' => 'limited', 'allow_package_managers' => true],
      ],
  );
  ```

  ```ruby Ruby
  environment = client.beta.environments.create(
    name: "data-analysis",
    config: {
      type: "cloud",
      packages: {
        pip: %w[pandas numpy scikit-learn],
        npm: %w[express]
      },
      networking: {type: "limited", allow_package_managers: true}
    }
  )
  ```
</CodeGroup>

지원되는 패키지 관리자:

| 필드      | 패키지 관리자           | 예시                                          |
| ------- | ----------------- | ------------------------------------------- |
| `apt`   | 시스템 패키지 (apt-get) | `"graphviz"`                                |
| `cargo` | Rust (cargo)      | `"hyperfine@1.18.0"`                        |
| `gem`   | Ruby (gem)        | `"rails:7.1.0"`                             |
| `go`    | Go 모듈             | `"golang.org/x/tools/cmd/goimports@latest"` |
| `npm`   | Node.js (npm)     | `"express@4.18.0"`                          |
| `pip`   | Python (pip)      | `"sqlalchemy==2.0.30"`                      |

### 네트워킹

`networking` (csharp, go: `Networking`) 필드는 샌드박스의 아웃바운드 네트워크 액세스를 제어합니다.

`limited` 네트워킹에서는 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)가 Anthropic의 서버에서 실행되는 `web_search` 및 `web_fetch` 도구에도 적용됩니다. `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)와 일치하지 않는 호스트의 URL에 대한 `web_fetch` 호출은 에이전트에 오류 결과를 반환합니다. `web_search`는 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)와 일치하지 않는 호스트의 결과를 제외합니다. `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) 및 `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`)는 이러한 도구에 대해 호스트를 추가하지 않습니다. `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)에 호스트가 나열되어 있지 않으면, 어떤 `web_fetch` 또는 `web_search` 호출도 페이지나 검색 결과를 반환하지 않습니다. 이러한 도구를 위해 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)에 추가한 호스트는 샌드박스에도 개방됩니다. `unrestricted` 네트워킹과 자체 호스팅 환경은 이러한 도구를 제한하지 않습니다. 이를 더 제한하려면 에이전트 도구 세트의 해당 도구 항목에 `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) 또는 `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`)를 설정하세요. [웹 검색 및 웹 가져오기 도메인 제한](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions)을 참조하세요.

| 모드             | 설명                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limited`      | 샌드박스 네트워크 액세스를 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)의 호스트로 제한합니다. 추가 액세스를 허용하려면 `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) 및 `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`)를 `true`로 설정하세요. 에이전트가 미리 나열할 수 없는 사이트에 접근해야 하는 경우가 아니라면 이 모드를 사용하세요. |
| `unrestricted` | 일반 안전 차단 목록을 제외한 전체 아웃바운드 네트워크 액세스입니다. 사용하기 전에 [제한 없는 네트워킹의 위험](https://platform.claude.com/docs/ko/managed-agents/environments#risks-of-unrestricted-networking)을 읽어 보세요.                                                                                                                                                                                                                                        |

<Note>
  API 요청에서 `networking` (csharp, go: `Networking`)을 명시적으로 설정하세요. 이를 생략한 생성 요청은 `unrestricted`가 됩니다. Claude Console의 환경 생성 양식은 **Limited**가 선택되고 다른 항목은 아무것도 허용되지 않은 상태로 시작합니다.
</Note>

다음 예시는 `limited` 네트워킹으로 환경을 생성합니다:

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsS https://api.anthropic.com/v1/environments \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "name": "api-access",
      "config": {
        "type": "cloud",
        "networking": {
          "type": "limited",
          "allowed_hosts": ["api.example.com"],
          "allow_mcp_servers": true,
          "allow_package_managers": true
        }
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply environment.yaml
    ```

    <File filename="environment.yaml">
      ```yaml
      # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
      name: api-access
      config:
        type: cloud
        networking:
          type: limited
          allowed_hosts:
            - api.example.com
          allow_mcp_servers: true
          allow_package_managers: true
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  environment = client.beta.environments.create(
      name="api-access",
      config={
          "type": "cloud",
          "networking": {
              "type": "limited",
              "allowed_hosts": ["api.example.com"],
              "allow_mcp_servers": True,
              "allow_package_managers": True,
          },
      },
  )
  ```

  ```typescript TypeScript
  const environment = await client.beta.environments.create({
    name: "api-access",
    config: {
      type: "cloud",
      networking: {
        type: "limited",
        allowed_hosts: ["api.example.com"],
        allow_mcp_servers: true,
        allow_package_managers: true
      }
    }
  });
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Environments;

  var environment = await client.Beta.Environments.Create(new()
  {
      Name = "api-access",
      Config = new BetaCloudConfigParams
      {
          Networking = new BetaLimitedNetworkParams
          {
              AllowedHosts = ["api.example.com"],
              AllowMcpServers = true,
              AllowPackageManagers = true,
          },
      },
  });
  ```

  ```go Go
  environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
  	Name: "api-access",
  	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
  		OfCloud: &anthropic.BetaCloudConfigParams{
  			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
  				OfLimited: &anthropic.BetaLimitedNetworkParams{
  					AllowedHosts:         []string{"api.example.com"},
  					AllowMCPServers:      anthropic.Bool(true),
  					AllowPackageManagers: anthropic.Bool(true),
  				},
  			},
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  _ = environment
  ```

  ```java Java
  import com.anthropic.models.beta.environments.*;
  import java.util.List;

  var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
      .name("api-access")
      .config(BetaCloudConfigParams.builder()
          .networking(BetaLimitedNetworkParams.builder()
              .allowedHosts(List.of("api.example.com"))
              .allowMcpServers(true)
              .allowPackageManagers(true)
              .build())
          .build())
      .build());
  ```

  ```php PHP
  $environment = $client->beta->environments->create(
      name: 'api-access',
      config: [
          'type' => 'cloud',
          'networking' => [
              'type' => 'limited',
              'allowed_hosts' => ['api.example.com'],
              'allow_mcp_servers' => true,
              'allow_package_managers' => true,
          ],
      ],
  );
  ```

  ```ruby Ruby
  environment = client.beta.environments.create(
    name: "api-access",
    config: {
      type: "cloud",
      networking: {
        type: "limited",
        allowed_hosts: %w[api.example.com],
        allow_mcp_servers: true,
        allow_package_managers: true
      }
    }
  )
  ```
</CodeGroup>

<Info>
  명시적인 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 목록과 함께 `limited` 네트워킹을 사용하세요. 에이전트에 필요한 최소한의 네트워크 액세스만 부여하여 최소 권한 원칙을 따르고, 허용된 도메인을 정기적으로 감사하세요.
</Info>

`limited` 네트워킹에서 다른 필드를 설정하지 않으면 어떤 호스트도 허용되지 않습니다. 세션에 연결한 파일, 메모리 스토어, GitHub 리포지토리는 계속 사용할 수 있습니다. 포트 80 또는 443에서 샌드박스가 보낸 요청이 호스트가 허용되지 않아 거부되면, 응답은 차단된 호스트를 명시하는 403입니다.

`limited` 네트워킹을 사용할 때:

* `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)는 샌드박스가 접근할 수 있는 도메인을 지정합니다. 순수 호스트 이름 또는 와일드카드 패턴(예: `*.example.com`)을 지정하세요. URL 스킴, 포트 또는 경로는 포함하지 마세요. 순수 호스트 이름은 정확히 해당 호스트와만 일치합니다. `example.com`은 `www.example.com`과 일치하지 않습니다. `*.example.com`은 `example.com`의 모든 하위 도메인과 일치하지만, `example.com` 자체와는 일치하지 않습니다.
* `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`)는 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 배열에 나열된 것 외에, 에이전트에 구성된 MCP 서버 엔드포인트에 대한 아웃바운드 액세스를 허용합니다. 기본값은 `false`입니다. `false`인 동안에는 에이전트가 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)에 없는 호스트의 MCP 서버를 선언하면 세션 생성이 400 오류와 함께 실패합니다. [에이전트가 위임할 수 있는 에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration)에도 동일하게 적용됩니다. 이를 해결하려면 해당 호스트를 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)에 추가하거나 `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`)를 `true`로 설정하세요.
* `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`)는 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 배열에 나열된 것 외에, 일련의 공개 패키지 레지스트리 및 코드 호스트에 대한 아웃바운드 액세스를 허용합니다. 목록은 [패키지 관리자 호스트](https://platform.claude.com/docs/ko/managed-agents/environments#package-manager-hosts)를 참조하세요. 기본값은 `false`입니다. 환경에서 `packages` (csharp, go: `Packages`)를 지정할 때는 항상 `true`로 설정하세요. 그렇지 않으면 레지스트리 호스트가 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)에 나열되어 있더라도 요청이 400 오류와 함께 거부됩니다.

#### 패키지 관리자 호스트

`allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`)가 `true`이면, 샌드박스는 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)의 호스트 외에 다음 호스트에도 접근할 수 있습니다. 이 목록은 Anthropic이 관리하며 변경될 수 있습니다.

| 생태계          | 호스트                                                                                                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 코드 호스팅       | `github.com`, `api.github.com`, `codeload.github.com`, `raw.githubusercontent.com`, `objects.githubusercontent.com`, `release-assets.githubusercontent.com`, `gitlab.com`, `bitbucket.org` |
| Node.js      | `registry.npmjs.org`, `registry.yarnpkg.com`, `nodejs.org`                                                                                                                                 |
| Python       | `pypi.org`, `files.pythonhosted.org`                                                                                                                                                       |
| Rust         | `crates.io`, `index.crates.io`, `static.crates.io`, `static.rust-lang.org`                                                                                                                 |
| Go           | `proxy.golang.org`, `sum.golang.org`                                                                                                                                                       |
| Java         | `repo1.maven.org`, `repo.maven.apache.org`, `services.gradle.org`, `plugins.gradle.org`, `plugins-artifacts.gradle.org`                                                                    |
| Ruby         | `rubygems.org`, `index.rubygems.org`                                                                                                                                                       |
| PHP          | `packagist.org`, `repo.packagist.org`                                                                                                                                                      |
| Ubuntu (apt) | `archive.ubuntu.com`, `security.ubuntu.com`, `ppa.launchpad.net`                                                                                                                           |
| 컨테이너         | `registry-1.docker.io`, `auth.docker.io`, `production.cloudflare.docker.com`, `download.docker.com`, `ghcr.io`                                                                             |

<Warning>
  네트워크 액세스는 작업 단위가 아니라 호스트 단위로 부여됩니다. 샌드박스는 명령이 제공하는 모든 자격 증명을 사용하여, `git push` 및 패키지 게시와 같은 업로드를 포함해 허용된 호스트에 어떤 요청이든 보낼 수 있습니다. 에이전트가 신뢰할 수 없는 입력(리포지토리 파일, 가져온 웹 콘텐츠 또는 서드파티 도구 출력)을 처리하는 경우, 성공한 "prompt injection"(프롬프트 인젝션)이 허용된 호스트를 이용해 샌드박스 밖으로 파일을 복사할 수 있습니다. 이 위험을 줄이려면 `bash` 도구의 [권한 정책](https://platform.claude.com/docs/ko/managed-agents/permission-policies)을 `always_ask` 또는 `auto`로 설정하세요. 환경에서 `packages` (csharp, go: `Packages`)를 지정하지 않는 경우, 대신 `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`)를 `false`로 두고 에이전트에 필요한 호스트만 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)에 나열할 수 있습니다.
</Warning>

#### 제한 없는 네트워킹의 위험

`unrestricted` 네트워킹에서는 샌드박스의 코드가 일반 안전 차단 목록에 있는 호스트를 제외한 인터넷상의 모든 호스트에 요청을 보낼 수 있습니다. 이 모드를 선택하기 전에 에이전트가 그러한 접근 권한으로 무엇을 할 수 있는지 고려하세요:

* **에이전트는 외부 사이트를 읽기만 하는 것이 아니라 변경할 수도 있습니다:** `bash` 도구는 어떤 요청이든 보낼 수 있습니다. 에이전트는 데이터를 게시하고, 양식을 제출하고, API를 호출하고, 외부 사이트의 데이터를 변경하는 스크립트를 실행할 수 있습니다. URL을 가져오기만 하는 요청도 일부 사이트에서는 데이터를 변경할 수 있습니다.
* **기본적으로 이러한 요청을 일시 중지하는 장치가 없습니다:** 에이전트 도구 세트의 기본 [권한 정책](https://platform.claude.com/docs/ko/managed-agents/permission-policies)은 `always_allow`이므로 `bash` 명령은 승인 없이 실행됩니다.
* **샌드박스에 있는 모든 것이 외부로 나갈 수 있습니다:** 여기에는 파일, 도구 출력, 그리고 샌드박스에 넣은 모든 자격 증명이나 시크릿이 포함됩니다.
* **가져온 콘텐츠가 에이전트를 조종할 수 있습니다:** 웹 페이지, API 응답 및 에이전트가 읽는 기타 콘텐츠에는 에이전트의 다음 행동을 바꾸는 지시(프롬프트 인젝션)가 포함될 수 있습니다.
* **에이전트는 사용자를 대신하여 행동합니다:** 에이전트의 행동은 사이트의 서비스 약관을 위반하거나, 해당 사이트에 계정과 기록을 생성할 수 있습니다.
* **모델 동작은 보안 통제 수단이 아닙니다:** 에이전트는 사이트가 요청을 차단한 후 다른 방식으로 재시도하는 것을 포함하여, 요청하지 않은 방식으로 외부 사이트에서 행동할 수 있습니다. 네트워크 설정과 권한 정책을 사용하여 에이전트가 할 수 있는 일을 제한하세요.
* **안전 차단 목록은 허용 목록이 아닙니다:** 이 목록은 에이전트가 접근하는 다른 사이트나 해당 사이트에서 에이전트가 하는 일을 제한하지 않습니다.

이러한 위험을 줄이려면 명시적인 호스트 목록과 함께 `limited` 네트워킹을 사용하세요. 다음 `networking` 값은 `api.example.com`과 함께, 패키지를 설치하는 에이전트를 위한 [패키지 관리자 호스트](https://platform.claude.com/docs/ko/managed-agents/environments#package-manager-hosts)를 허용합니다:

```json
{
  "type": "limited",
  "allowed_hosts": ["api.example.com"],
  "allow_package_managers": true
}
```

`web_search` 및 `web_fetch` 도구만 사용하는 에이전트는 필요한 사이트를 나열할 수 있다면 `unrestricted` 네트워킹이 필요하지 않습니다. `limited` 네트워킹에서는 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)가 해당 도구에도 적용되므로([네트워킹](https://platform.claude.com/docs/ko/managed-agents/environments#networking) 참조), 해당 사이트를 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)에 나열하세요. 이를 `web_search`의 `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`)에도 나열하면 해당 사이트를 검색하게 됩니다. `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)에 추가한 호스트는 샌드박스에도 개방됩니다. 도구를 더 제한하려면 [웹 검색 및 웹 가져오기 도메인 제한](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions)을 참조하세요.

에이전트가 미리 나열할 수 없는 사이트에 접근해야 하는 경우에만 `unrestricted`를 사용하세요. 이 경우 시크릿과 민감한 파일을 샌드박스에 두지 말고, 작업에 필요한 자격 증명만 에이전트에 제공하세요. `bash` 도구의 권한 정책을 `always_ask` 또는 `auto`로 설정하는 것을 고려하고, [세션의 이벤트를 모니터링](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming)하세요.

## 환경 수명 주기

* 환경은 명시적으로 보관되거나 삭제될 때까지 유지됩니다.
* 여러 세션이 동일한 환경을 참조하더라도 각 세션은 자체 샌드박스 인스턴스를 갖습니다. 세션은 파일 시스템 상태를 공유하지 않습니다.
* 환경은 버전 관리되지 않습니다. 환경을 자주 업데이트하는 경우, 각 세션이 어떤 구성을 사용했는지 알 수 있도록 변경 사항을 직접 기록해 두세요.

## 환경 관리

<CodeGroup>
  ```bash cURL
  # 환경 목록 조회
  curl -fsS https://api.anthropic.com/v1/environments \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"

  # 특정 환경 조회
  curl -fsS "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"

  # 환경 보관 처리(읽기 전용, 기존 세션은 계속 유지됨)
  curl -fsS -X POST "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"

  # 환경 삭제(참조하는 세션이 없는 경우에만 가능)
  curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  # environment 목록 조회
  ant beta:environments list

  # 특정 environment 조회
  ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"

  # environment 보관(읽기 전용, 기존 세션은 계속 유지됨)
  ant beta:environments archive --environment-id "$ENVIRONMENT_ID"

  # environment 삭제(참조하는 세션이 없는 경우에만)
  ant beta:environments delete --environment-id "$ENVIRONMENT_ID"
  ```

  ```python Python
  # 환경 목록 조회
  environments = client.beta.environments.list()

  # 특정 환경 조회
  env = client.beta.environments.retrieve(environment.id)

  # 환경 보관 (읽기 전용, 기존 세션은 계속 유지됨)
  client.beta.environments.archive(environment.id)

  # 환경 삭제 (참조하는 세션이 없는 경우에만 가능)
  client.beta.environments.delete(environment.id)
  ```

  ```typescript TypeScript
  // 환경 목록 조회
  const environments = await client.beta.environments.list();

  // 특정 환경 조회
  const env = await client.beta.environments.retrieve(environment.id);

  // 환경 보관 (읽기 전용, 기존 세션은 계속됨)
  await client.beta.environments.archive(environment.id);

  // 환경 삭제 (참조하는 세션이 없는 경우에만)
  await client.beta.environments.delete(environment.id);
  ```

  ```csharp C#
  // 환경 목록 조회
  var environments = await client.Beta.Environments.List();

  // 특정 환경 조회
  var env = await client.Beta.Environments.Retrieve(environment.ID);

  // 환경 보관 (읽기 전용, 기존 세션은 계속 유지됨)
  await client.Beta.Environments.Archive(environment.ID);

  // 환경 삭제 (참조하는 세션이 없는 경우에만 가능)
  await client.Beta.Environments.Delete(environment.ID);
  ```

  ```go Go
  // 환경 목록 조회
  environments, err := client.Beta.Environments.List(ctx, anthropic.BetaEnvironmentListParams{})
  // ...

  // 특정 환경 조회
  env, err := client.Beta.Environments.Get(ctx, environment.ID, anthropic.BetaEnvironmentGetParams{})
  // ...

  // 환경 보관 (읽기 전용, 기존 세션은 계속 유지됨)
  _, err = client.Beta.Environments.Archive(ctx, environment.ID, anthropic.BetaEnvironmentArchiveParams{})
  // ...

  // 환경 삭제 (참조하는 세션이 없는 경우에만 가능)
  _, err = client.Beta.Environments.Delete(ctx, environment.ID, anthropic.BetaEnvironmentDeleteParams{})
  ```

  ```java Java
  // 환경 목록 조회
  var environments = client.beta().environments().list();
  // 특정 환경 조회
  var env = client.beta().environments().retrieve(environment.id());
  // 환경 보관 (읽기 전용, 기존 세션은 계속 유지됨)
  client.beta().environments().archive(environment.id());
  // 환경 삭제 (참조하는 세션이 없는 경우에만 가능)
  client.beta().environments().delete(environment.id());
  ```

  ```php PHP
  // 환경 목록 조회
  $environments = $client->beta->environments->list();
  // 특정 환경 조회
  $env = $client->beta->environments->retrieve($environment->id);
  // 환경 보관 (읽기 전용, 기존 세션은 계속 유지됨)
  $client->beta->environments->archive($environment->id);
  // 환경 삭제 (참조하는 세션이 없는 경우에만 가능)
  $client->beta->environments->delete($environment->id);
  ```

  ```ruby Ruby
  # 환경 목록 조회
  environments = client.beta.environments.list

  # 특정 환경 조회
  env = client.beta.environments.retrieve(environment.id)

  # 환경 보관 (읽기 전용, 기존 세션은 계속 유지됨)
  client.beta.environments.archive(environment.id)

  # 환경 삭제 (참조하는 세션이 없는 경우에만 가능)
  client.beta.environments.delete(environment.id)
  ```
</CodeGroup>

## 사전 설치된 런타임

클라우드 샌드박스에는 일반적인 언어 런타임, 데이터베이스 및 명령줄 도구가 기본으로 포함되어 있습니다. 전체 목록은 [클라우드 샌드박스 참조](https://platform.claude.com/docs/ko/managed-agents/cloud-sandboxes-reference)를 참조하세요.

## 다음 단계

<CardGroup cols={2}>
  <Card title="클라우드 샌드박스 참조" icon="book" href="https://platform.claude.com/docs/ko/managed-agents/cloud-sandboxes-reference">
    클라우드 샌드박스에서 사용할 수 있는 사전 설치된 패키지, 데이터베이스 및 유틸리티입니다.
  </Card>

  <Card title="세션 시작" icon="play" href="https://platform.claude.com/docs/ko/managed-agents/sessions">
    세션을 생성하여 에이전트를 실행하고 작업 실행을 시작하세요.
  </Card>
</CardGroup>