---
title: "Create Environment"
method: POST
path: "/v1/environments?beta=true"
---

# Create Environment

`POST /v1/environments?beta=true`

Create a new environment with the specified configuration.

## Headers

- `anthropic-beta` string — Optional header to specify the beta version(s) you want to use. To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
- `anthropic-version` string — The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).

## Request body

- BetaPublicEnvironmentCreateRequest — Public API request to create a new environment (without org/account fields).
  - `config` union — Environment configuration
    - BetaCloudConfigParams — Request params for `cloud` environment configuration. Fields default to null; on update, omitted fields preserve the existing value.
      - `networking` union — Network configuration policy. Omit on update to preserve the existing value.
        - BetaUnrestrictedNetwork — Unrestricted network access.
          - `type` 'unrestricted', required — Network policy type
        - BetaLimitedNetworkParams — Limited network request params. Fields default to null; on update, omitted fields preserve the existing value.
          - `allow_mcp_servers` boolean, nullable — Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.
          - `allow_package_managers` boolean, nullable — Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false` on creation. Must be `true` when `packages` are specified.
          - `allowed_hosts` string[], nullable — Specifies domains the container can reach.
          - `type` 'limited', required — Network policy type
      - `packages` object, nullable — Specify packages (and optionally their versions) available in this environment. When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. Under `limited` networking, requires `networking.allow_package_managers` to be `true`.
        - `apt` string[], nullable — Ubuntu/Debian packages to install
        - `cargo` string[], nullable — Rust packages to install
        - `gem` string[], nullable — Ruby packages to install
        - `go` string[], nullable — Go packages to install
        - `npm` string[], nullable — Node.js packages to install
        - `pip` string[], nullable — Python packages to install
        - `type` 'packages' — Package configuration type
      - `type` 'cloud', required — Environment type
    - BetaSelfHostedConfigParams — Request params for `self_hosted` environment configuration.
      - `type` 'self_hosted', required — Environment type
  - `description` string, nullable — Optional description of the environment
  - `metadata` object — User-provided metadata key-value pairs
  - `name` string, required — Human-readable name for the environment
  - `scope` 'organization' | 'account', nullable — The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. Only applicable for self-hosted environments. If not specified, defaults based on organization type.

## Response `200`

Successful Response

- BetaEnvironment — Unified Environment resource for both cloud and self-hosted environments.
  - `archived_at` string, nullable, required — RFC 3339 timestamp when environment was archived, or null if not archived
  - `config` union, required — Environment configuration (either Anthropic Cloud or self-hosted)
    - BetaCloudConfig — `cloud` environment configuration.
      - `networking` union, required — Network configuration policy.
        - BetaUnrestrictedNetwork — Unrestricted network access.
          - `type` 'unrestricted', required — Network policy type
        - BetaLimitedNetwork — Limited network access.
          - `allow_mcp_servers` boolean, required — Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array.
          - `allow_package_managers` boolean, required — Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array.
          - `allowed_hosts` string[], required — Specifies domains the container can reach.
          - `type` 'limited', required — Network policy type
      - `packages` BetaPackages, required — Packages (and their versions) available in this environment.
        - `apt` string[], required — Ubuntu/Debian packages to install
        - `cargo` string[], required — Rust packages to install
        - `gem` string[], required — Ruby packages to install
        - `go` string[], required — Go packages to install
        - `npm` string[], required — Node.js packages to install
        - `pip` string[], required — Python packages to install
        - `type` 'packages' — Package configuration type
      - `type` 'cloud', required — Environment type
    - BetaSelfHostedConfig — Configuration for self-hosted environments.
      - `type` 'self_hosted', required — Environment type
  - `created_at` string, required — RFC 3339 timestamp when environment was created
  - `description` string, nullable, required — User-provided description for the environment; null when unset
  - `id` string, required — Environment identifier (e.g., 'env_...')
  - `metadata` object, required — User-provided metadata key-value pairs
  - `name` string, required — Human-readable name for the environment
  - `scope` 'organization' | 'account' — The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.
  - `type` 'environment', required — The type of object (always 'environment')
  - `updated_at` string, required — RFC 3339 timestamp when environment was last updated

## Other responses

- `4XX` — Error response. See our [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details.

## Changes

- **2026-08-14** `e9d8152420c3` — 1 breaking
  - response property `description` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
- **2026-05-19** `40e330aba8bc` — 1 breaking, 5 info
  - added `#/components/schemas/BetaSelfHostedConfig` to the `config` response property `oneOf` list for the response status `200`
  - added the new optional request property `scope`
  - added `self_hosted` discriminator mapping keys to the `config/anyOf[subschema #1]/` request property
  - added `#/components/schemas/BetaSelfHostedConfigParams` to the `config/anyOf[subschema #1]/` request property `oneOf` list
  - …2 more
- **2026-04-09** `d87d3ef6f636` — 1 warning
  - deleted the `cookie` request parameter `sessionKey`
- **2026-04-08** `69486316563e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/anthropics/apis/anthropic-api/changes/v1/environments?beta=true/post.md)

---

[API](https://skmtc.dev/anthropics/apis/anthropic-api.md) · [All operations](https://skmtc.dev/anthropics/apis/anthropic-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/anthropics/anthropic-api/revisions/717ab2a5efd6/schema)