클라우드 환경 설정

클라우드 환경 설정 (Cloud environment setup)

환경(Environment)은 에이전트가 실행되는 샌드박스 구성을 정의해요. 환경을 한 번 만들면 세션을 시작할 때마다 그 ID를 참조하면 됩니다. 여러 세션이 같은 환경을 공유할 수 있지만, 각 세션은 고유한 격리 샌드박스(새 Linux 컨테이너)를 갖게 돼요. 이 페이지는 type: cloud 환경을 다루며, 자체 인프라에서 샌드박스를 실행하려면 Self-hosted sandboxes 문서를 참고하세요.

출처: 문서

본문

환경은 에이전트가 실행되는 샌드박스 구성을 정의해요. 환경을 한 번 만든 다음 세션을 시작할 때마다 ID를 참조하면 돼요. 여러 세션이 같은 환경을 공유할 수 있지만, 각 세션은 자체 격리 샌드박스(새 Linux 컨테이너)를 갖습니다.

이 페이지는 type: cloud 환경을 다루어요. 자체 인프라에서 샌드박스를 실행하려면 Self-hosted sandboxes를 참고하세요.

Create an environment

```bash cURL curl -fsS https://api.anthropic.com/v1/environments \ -H "x-api-key: $ANTHR...KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ --data @- <<'EOF' { "name": "python-dev", "config": { "type": "cloud", "networking": {"type": "unrestricted"} } } EOF ``` ```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: unrestricted
  ```
</File>

environment = client.beta.environments.create(
    name="python-dev",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)

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

const environment = await client.beta.environments.create({
  name: "python-dev",
  config: {
    type: "cloud",
    networking: { type: "unrestricted" },
  },
});

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

var environment = await client.Beta.Environments.Create(new()
{
    Name = "python-dev",
    Config = new BetaCloudConfigParams
    {
        Networking = new BetaUnrestrictedNetwork(),
    },
});

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

environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
	Name: "python-dev",
	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
		OfCloud: &anthropic.BetaCloudConfigParams{
			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
				OfUnrestricted: &anthropic.BetaUnrestrictedNetworkParam{},
			},
		},
	},
})
if err != nil {
	panic(err)
}

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

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

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

environment = client.beta.environments.create(
  name: "python-dev",
  config: {
    type: "cloud",
    networking: {type: "unrestricted"}
  }
)

puts "Environment ID: #{environment.id}"

[`ant apply`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/apply) creates the environment from `environment.yaml`, prints its ID, and records it in `claude-lock.json`. Commit `claude-lock.json` so the next `ant apply` updates this environment instead of trying to create it again.

환경을 구분할 수 있도록 고유하고 설명적인 name을 사용하세요.

Use the environment in a session

세션을 만들 때 환경 ID를 문자열로 전달하세요.

```bash cURL curl -fsS https://api.anthropic.com/v1/sessions \ -H "x-api-key: $ANTHR...KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ --data @- <

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

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

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

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

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)
}

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

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

session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id
)

Configuration options

Packages

packages 필드는 에이전트가 시작되기 전에 패키지를 샌드박스에 미리 설치해요. 패키지는 각자의 패키지 매니저로 설치되며, 같은 환경을 공유하는 세션 간에 캐시돼요. 여러 패키지 매니저를 지정하면 알파벳 순서(apt, cargo, gem, go, npm, pip)로 실행돼요. 특정 버전을 고정할 수도 있어요. 고정하지 않은 패키지는 최신 버전을 설치해요. 환경이 limited networking을 사용한다면 networking.allow_package_managers도 true로 설정하세요. 그렇지 않으면 400 에러로 요청이 거부돼요.

```bash cURL curl -fsS https://api.anthropic.com/v1/environments \ -H "x-api-key: $ANTHR...KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ --data @- <<'EOF' { "name": "data-analysis", "config": { "type": "cloud", "packages": { "pip": ["pandas", "numpy", "scikit-learn"], "npm": ["express"] }, "networking": {"type": "unrestricted"} } } EOF ``` ```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: unrestricted
  ```
</File>

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

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

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 BetaUnrestrictedNetwork(),
    },
});

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{
				OfUnrestricted: &anthropic.BetaUnrestrictedNetworkParam{},
			},
		},
	},
})
if err != nil {
	panic(err)
}
_ = environment

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(BetaUnrestrictedNetwork.builder().build())
        .build())
    .build());

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

environment = client.beta.environments.create(
  name: "data-analysis",
  config: {
    type: "cloud",
    packages: {
      pip: %w[pandas numpy scikit-learn],
      npm: %w[express]
    },
    networking: {type: "unrestricted"}
  }
)

지원되는 패키지 매니저:

Field	Package manager	Example
`apt`	System packages (apt-get)	`"graphviz"`
`cargo`	Rust (cargo)	`"[email protected]"`
`gem`	Ruby (gem)	`"rails:7.1.0"`
`go`	Go modules	`"golang.org/x/tools/cmd/goimports@latest"`
`npm`	Node.js (npm)	`"[email protected]"`
`pip`	Python (pip)	`"sqlalchemy==2.0.30"`

Networking

networking 필드는 샌드박스의 아웃바운드 네트워크 접근을 제어해요. Anthropic의 서버에서 실행되는 web_search나 web_fetch 도구에는 영향을 주지 않아요. 그 도구들이 도달할 수 있는 사이트를 제한하려면 에이전트 도구세트의 해당 도구 항목에 allowed_domains 또는 blocked_domains를 설정하세요. 자세한 내용은 Restrict web search and web fetch domains를 참고하세요.

Mode	Description
`unrestricted`	Full outbound network access, except for a general safety blocklist. This is the default.
`limited`	Restricts sandbox network access to the hosts in `allowed_hosts`. Set `allow_package_managers` and `allow_mcp_servers` to `true` to allow additional access.

다음 예시는 limited 네트워킹으로 환경을 만들어요:

```bash cURL curl -fsS https://api.anthropic.com/v1/environments \ -H "x-api-key: $ANTHR...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 } } }' ``` ```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>

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,
        },
    },
)

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
    }
  }
});

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,
        },
    },
});

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

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());

$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,
        ],
    ],
);

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
    }
  }
)

For production deployments, use `limited` networking with an explicit `allowed_hosts` list. Follow the principle of least privilege by granting only the minimum network access your agent requires, and regularly audit your allowed domains.

limited 네트워킹을 쓸 때:

allowed_hosts specifies domains the sandbox can reach. Specify bare hostnames or wildcard patterns (such as *.example.com). Do not include a URL scheme, port, or path.
allow_mcp_servers allows outbound access to MCP server endpoints configured on the agent, beyond those listed in the allowed_hosts array. Defaults to false.
allow_package_managers allows outbound access to public package registries (such as PyPI and npm) beyond those listed in the allowed_hosts array. Defaults to false. Set it to true whenever the environment specifies packages; otherwise the request is rejected with a 400 error, even if the registry hosts are listed in allowed_hosts.

Environment lifecycle

Environments persist until explicitly archived or deleted.
Each session gets its own sandbox instance, even when multiple sessions reference the same environment. Sessions do not share filesystem state.
Environments are not versioned. If you update an environment frequently, keep your own record of the changes so you can tell which configuration each session used.

Manage environments

```bash cURL # List environments curl -fsS https://api.anthropic.com/v1/environments \ -H "x-api-key: $ANTHR...KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01"

Retrieve a specific environment

curl -fsS "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID"
-H "x-api-key: $ANTHR...KEY"
-H "anthropic-version: 2023-06-01"
-H "anthropic-beta: managed-agents-2026-04-01"

Archive an environment (read-only, existing sessions continue)

curl -fsS -X POST "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive"
-H "x-api-key: $ANTHR...KEY"
-H "anthropic-version: 2023-06-01"
-H "anthropic-beta: managed-agents-2026-04-01"

Delete an environment (only if no sessions reference it)

curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID"
-H "x-api-key: $ANTHR...KEY"
-H "anthropic-version: 2023-06-01"
-H "anthropic-beta: managed-agents-2026-04-01"


```bash CLI
# List environments
ant beta:environments list

# Retrieve a specific environment
ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"

# Archive an environment (read-only, existing sessions continue)
ant beta:environments archive --environment-id "$ENVIRONMENT_ID"

# Delete an environment (only if no sessions reference it)
ant beta:environments delete --environment-id "$ENVIRONMENT_ID"

# List environments
environments = client.beta.environments.list()

# Retrieve a specific environment
env = client.beta.environments.retrieve(environment.id)

# Archive an environment (read-only, existing sessions continue)
client.beta.environments.archive(environment.id)

# Delete an environment (only if no sessions reference it)
client.beta.environments.delete(environment.id)

// List environments
const environments = await client.beta.environments.list();

// Retrieve a specific environment
const env = await client.beta.environments.retrieve(environment.id);

// Archive an environment (read-only, existing sessions continue)
await client.beta.environments.archive(environment.id);

// Delete an environment (only if no sessions reference it)
await client.beta.environments.delete(environment.id);

// List environments
var environments = await client.Beta.Environments.List();

// Retrieve a specific environment
var env = await client.Beta.Environments.Retrieve(environment.ID);

// Archive an environment (read-only, existing sessions continue)
await client.Beta.Environments.Archive(environment.ID);

// Delete an environment (only if no sessions reference it)
await client.Beta.Environments.Delete(environment.ID);

// List environments
environments, err := client.Beta.Environments.List(ctx, anthropic.BetaEnvironmentListParams{})
// ...

// Retrieve a specific environment
env, err := client.Beta.Environments.Get(ctx, environment.ID, anthropic.BetaEnvironmentGetParams{})
// ...

// Archive an environment (read-only, existing sessions continue)
_, err = client.Beta.Environments.Archive(ctx, environment.ID, anthropic.BetaEnvironmentArchiveParams{})
// ...

// Delete an environment (only if no sessions reference it)
_, err = client.Beta.Environments.Delete(ctx, environment.ID, anthropic.BetaEnvironmentDeleteParams{})

// List environments
var environments = client.beta().environments().list();
// Retrieve a specific environment
var env = client.beta().environments().retrieve(environment.id());
// Archive an environment (read-only, existing sessions continue)
client.beta().environments().archive(environment.id());
// Delete an environment (only if no sessions reference it)
client.beta().environments().delete(environment.id());

// List environments
$environments = $client->beta->environments->list();
// Retrieve a specific environment
$env = $client->beta->environments->retrieve($environment->id);
// Archive an environment (read-only, existing sessions continue)
$client->beta->environments->archive($environment->id);
// Delete an environment (only if no sessions reference it)
$client->beta->environments->delete($environment->id);

# List environments
environments = client.beta.environments.list

# Retrieve a specific environment
env = client.beta.environments.retrieve(environment.id)

# Archive an environment (read-only, existing sessions continue)
client.beta.environments.archive(environment.id)

# Delete an environment (only if no sessions reference it)
client.beta.environments.delete(environment.id)

Pre-installed runtimes

클라우드 샌드박스에는 일반적인 언어 런타임, 데이터베이스, 명령줄 도구가 기본 제공돼요. 전체 목록은 Cloud sandbox reference를 참고하세요.

Next steps

Pre-installed packages, databases, and utilities available in cloud sandboxes. Create a session to run your agent and start running tasks.

더 알아보기 (Learn more)

Cloud sandbox reference — 클라우드 샌드박스의 미리 설치된 패키지·데이터베이스·유틸리티
Start a session — 에이전트 실행할 세션 만들기
Self-hosted sandboxes — 자체 인프라에서 샌드박스 실행하기