Create Environment

POST /v1/environments

Create a new environment with the specified configuration.

Headers

• "anthropic-beta": optional array of AnthropicBeta

  Optional header to specify the beta version(s) you want to use.

  • string

  • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more

    • "message-batches-2024-09-24"

    • "prompt-caching-2024-07-31"

    • "computer-use-2024-10-22"

    • "computer-use-2025-01-24"

    • "pdfs-2024-09-25"

    • "token-counting-2024-11-01"

    • "token-efficient-tools-2025-02-19"

    • "output-128k-2025-02-19"

    • "files-api-2025-04-14"

    • "mcp-client-2025-04-04"

    • "mcp-client-2025-11-20"

    • "dev-full-thinking-2025-05-14"

    • "interleaved-thinking-2025-05-14"

    • "code-execution-2025-05-22"

    • "extended-cache-ttl-2025-04-11"

    • "context-1m-2025-08-07"

    • "context-management-2025-06-27"

    • "model-context-window-exceeded-2025-08-26"

    • "skills-2025-10-02"

    • "fast-mode-2026-02-01"

    • "output-300k-2026-03-24"

    • "user-profiles-2026-03-24"

    • "user-profiles-2026-08-18"

    • "user-profiles-2026-09-04"

    • "advisor-tool-2026-03-01"

    • "managed-agents-2026-04-01"

    • "cache-diagnosis-2026-04-07"

    • "dreaming-2026-04-21"

    • "thinking-token-count-2026-05-13"

    • "server-side-fallback-2026-06-01"

    • "server-side-fallback-2026-07-01"

    • "fallback-credit-2026-06-01"

    • "fallback-credit-2026-07-01"

    • "agent-memory-2026-07-22"

    • "mid-conversation-tool-changes-2026-07-01"

    • "compact-2026-01-12"

    • "computer-use-2025-11-24"

    • "mcp-tunnels-2026-06-22"

    • "structured-outputs-2025-11-13"

    • "task-budgets-2026-03-13"

    • "thinking-display-updates-2026-08-18"

    • "ce-user-management-2026-07-13"

    • "mid-conversation-output-config-2026-07-01"

    • "thinking-binding-controls-2026-08-01"

    • "mid-conversation-system-clear-at-2026-08-21"

• "anthropic-workspace-id": optional string

Body parameters

• name: string

  Human-readable name for the environment

  maxLength: 256, minLength: 1

• config: optional BetaCloudConfigParams or BetaSelfHostedConfigParams or null

  Environment configuration

  • BetaCloudConfigParams object

    Request params for cloud environment configuration.

    Fields default to null; on update, omitted fields preserve the existing value.

    • type: "cloud"

      Environment type

    • networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams or null

      Network configuration policy. Omit on update to preserve the existing value.

      • BetaUnrestrictedNetwork object

        Unrestricted network access.

        • type: "unrestricted"

          Network policy type

      • BetaLimitedNetworkParams object

        Limited network request params.

        Fields default to null; on update, omitted fields preserve the existing value.

        • type: "limited"

          Network policy type

        • allow_mcp_servers: optional boolean or null

          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: optional boolean or null

          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: optional array of string or null

          Specifies domains the container can reach.

    • packages: optional BetaPackagesParams or null

      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.

      • type: optional "packages"

        Package configuration type

        default: packages

      • apt: optional array of string or null

        Ubuntu/Debian packages to install

      • cargo: optional array of string or null

        Rust packages to install

      • gem: optional array of string or null

        Ruby packages to install

      • go: optional array of string or null

        Go packages to install

      • npm: optional array of string or null

        Node.js packages to install

      • pip: optional array of string or null

        Python packages to install

  • BetaSelfHostedConfigParams object

    Request params for self_hosted environment configuration.

    • type: "self_hosted"

      Environment type

• description: optional string or null

  Optional description of the environment

  maxLength: 1024

• metadata: optional map[string]

  User-provided metadata key-value pairs

• scope: optional "organization" or "account" or null

  The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. API organizations support only 'organization'; 'account' is rejected. If not specified, defaults based on organization type.

  • "organization"

  • "account"

Returns

• BetaEnvironment object

  Unified Environment resource for both cloud and self-hosted environments.

  • type: "environment"

    The type of object (always 'environment')

    default: environment

  • id: string

    Environment identifier (e.g., 'env_...')

  • archived_at: string or null

    RFC 3339 timestamp when environment was archived, or null if not archived

  • config: BetaCloudConfig or BetaSelfHostedConfig

    Environment configuration (either Anthropic Cloud or self-hosted)

    • BetaCloudConfig object

      cloud environment configuration.

      • type: "cloud"

        Environment type

      • networking: BetaUnrestrictedNetwork or BetaLimitedNetwork

        Network configuration policy.

        • BetaUnrestrictedNetwork object

          Unrestricted network access.

          • type: "unrestricted"

            Network policy type

        • BetaLimitedNetwork object

          Limited network access.

          • type: "limited"

            Network policy type

          • allow_mcp_servers: boolean

            Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the allowed_hosts array.

          • allow_package_managers: boolean

            Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the allowed_hosts array.

          • allowed_hosts: array of string

            Specifies domains the container can reach.

      • packages: BetaPackages

        Package manager configuration.

        • type: optional "packages"

          Package configuration type

          default: packages

        • apt: array of string

          Ubuntu/Debian packages to install

        • cargo: array of string

          Rust packages to install

        • gem: array of string

          Ruby packages to install

        • go: array of string

          Go packages to install

        • npm: array of string

          Node.js packages to install

        • pip: array of string

          Python packages to install

    • BetaSelfHostedConfig object

      Configuration for self-hosted environments.

      • type: "self_hosted"

        Environment type

  • created_at: string

    RFC 3339 timestamp when environment was created

  • description: string or null

    User-provided description for the environment; null when unset

  • metadata: map[string]

    User-provided metadata key-value pairs

  • name: string

    Human-readable name for the environment

  • updated_at: string

    RFC 3339 timestamp when environment was last updated

  • scope: optional "organization" or "account"

    The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

    • "organization"

    • "account"

Example

curl https://api.anthropic.com/v1/environments \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "name": "python-data-analysis",
          "config": {
            "type": "cloud",
            "networking": {
              "type": "limited",
              "allow_package_managers": true,
              "allowed_hosts": [
                "api.example.com"
              ]
            },
            "packages": {
              "pip": [
                "pandas",
                "numpy"
              ]
            }
          },
          "description": "Python environment with data-analysis packages."
        }'

Response (200)

{
  "id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "archived_at": null,
  "config": {
    "networking": {
      "allow_mcp_servers": false,
      "allow_package_managers": true,
      "allowed_hosts": [
        "api.example.com"
      ],
      "type": "limited"
    },
    "packages": {
      "apt": [
        "string"
      ],
      "cargo": [
        "string"
      ],
      "gem": [
        "string"
      ],
      "go": [
        "string"
      ],
      "npm": [
        "string"
      ],
      "pip": [
        "pandas",
        "numpy"
      ],
      "type": "packages"
    },
    "type": "cloud"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "description": "Python environment with data-analysis packages.",
  "metadata": {},
  "name": "python-data-analysis",
  "type": "environment",
  "updated_at": "2026-03-15T10:00:00Z",
  "scope": "organization"
}