> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an Environment

> Creates a CMA-compatible cloud or self-hosted Environment.



## OpenAPI

````yaml /openapi.json post /v1/environments
openapi: 3.1.0
info:
  title: Checkfu API
  version: '2026-08-31'
  description: >-
    Authentication is declared per operation: API-key, runtime, or connector
    bearer; Automation signature; or credential-free pairing redemption. Every
    general Checkfu REST request requires the dated `Checkfu-Version` header
    (one of: 2026-08-31); the three MCP JSON-RPC transports use
    `MCP-Protocol-Version`, A2A uses `A2A-Version`, and the provider OAuth
    callback carries neither Checkfu header. API keys resolve one Workspace
    without a request selector; authenticated responses identify it with
    `Checkfu-Workspace-Id`.
servers:
  - url: https://api.checkfu.com
security:
  - bearerAuth: []
tags:
  - name: organizations
  - name: sourceRepositories
  - name: tenants
  - name: workspaces
  - name: principals
  - name: principalGroups
  - name: principalAccessCredentials
  - name: apiKeys
  - name: agents
  - name: harnessRuntime
  - name: permissionAssignments
  - name: actionPolicies
  - name: files
  - name: memoryStores
  - name: modelCredentials
  - name: modelRoutingProfiles
  - name: toolSources
  - name: skills
  - name: skillSources
  - name: agentBlueprints
  - name: skillProposals
  - name: instructionProposals
  - name: catalog
  - name: concepts
  - name: support
  - name: connections
  - name: connectionVaults
  - name: connectionAssignments
  - name: connectedRuntimes
  - name: fileTrees
  - name: collaboration
  - name: automationGraphs
  - name: automations
  - name: actionApprovals
  - name: standingApprovals
  - name: workloadReviewPolicies
  - name: usage
  - name: models
  - name: budgets
  - name: billing
  - name: sessions
  - name: audit
  - name: sessionExports
  - name: runs
  - name: runnerPools
  - name: transcripts
  - name: sessionWatches
  - name: sessionCapsules
  - name: sessionTrajectories
  - name: webhookEndpoints
  - name: integrationGateway
  - name: workEnvironments
  - name: computers
  - name: computerScreens
  - name: computerBrowserObservations
  - name: computerBrowserActions
  - name: environments
  - name: computerHeadlessOperations
  - name: vaults
  - name: apiMcp
  - name: a2a
paths:
  /v1/environments:
    post:
      tags:
        - environments
      summary: Create an Environment
      description: >-
        Creates a CMA-compatible cloud or self-hosted Environment. New cloud
        Environments default to limited networking with no allowed hosts or
        optional network access, and empty package lists. Existing networking is
        preserved on partial updates. Workload execution requires current
        placement authority; unrestricted networking is refused for adversarial
        workloads. Self-hosted scope accepts the exact organization or account
        literals and defaults to account for Checkfu's Tenant isolation
        boundary.


        Checkfu support posture: alpha; hosted. Required evidence journey:
        sandbox-conformance. Deployment-specific readiness and the latest proven
        release are available from GET /v1/support/capabilities.
      operationId: environments.createEnvironment
      parameters:
        - name: checkfu-version
          in: header
          schema:
            type: string
            enum:
              - '2026-08-31'
          required: true
        - name: idempotency-key
          in: header
          schema:
            type: string
            allOf:
              - maxLength: 255
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentCreateParams'
        required: true
      responses:
        '201':
          description: Environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment_1'
          headers:
            checkfu-workspace-id:
              description: The Workspace resolved from the authenticated bearer credential.
              required: true
              schema:
                $ref: '#/components/schemas/WorkspaceId'
        '400':
          description: Typed Checkfu wire error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationMalformedError'
        '401':
          description: Typed Checkfu wire error
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - type
                      - message
                      - more
                    properties:
                      type:
                        type: string
                        enum:
                          - auth.invalid_key
                      message:
                        type: string
                      more:
                        type: string
                        enum:
                          - >-
                            https://docs.checkfu.com/reference/errors#auth-invalid-key
                        description: >-
                          Stable public documentation and remedy for this error
                          type.
                    additionalProperties: false
                additionalProperties: false
        '403':
          description: >-
            The organization, tenant, or workspace backing this key is
            administratively disabled. | Deployment governance or retention
            policy denied the request.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    required:
                      - error
                    properties:
                      error:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - auth.disabled_tenancy
                          message:
                            type: string
                          more:
                            type: string
                            enum:
                              - >-
                                https://docs.checkfu.com/reference/errors#auth-disabled-tenancy
                            description: >-
                              Stable public documentation and remedy for this
                              error type.
                        required:
                          - type
                          - message
                          - more
                        additionalProperties: false
                    additionalProperties: false
                  - $ref: '#/components/schemas/PolicyDeniedError'
        '409':
          description: >-
            The request conflicts with the resource's current state. | An
            idempotent mutation conflicts with a completed or in-progress
            request for the same key.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationConflictError'
                  - $ref: '#/components/schemas/IdempotencyConflictError'
        '429':
          description: Typed Checkfu wire error
          headers:
            retry-after:
              description: >-
                Delay in seconds for rate limits or deployment quotas with a
                known release or UTC reset boundary
              required: false
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - type
                      - message
                      - more
                    properties:
                      type:
                        type: string
                        enum:
                          - budget.exceeded
                      message:
                        type: string
                      more:
                        type: string
                        enum:
                          - >-
                            https://docs.checkfu.com/reference/errors#budget-exceeded
                        description: >-
                          Stable public documentation and remedy for this error
                          type.
                    additionalProperties: false
                additionalProperties: false
        '500':
          description: >-
            An unexpected internal failure occurred; the message contains an
            opaque incident reference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeInternalError'
      security:
        - bearerAuth: []
components:
  schemas:
    EnvironmentCreateParams:
      type: object
      properties:
        name:
          type: string
        config:
          anyOf:
            - $ref: '#/components/schemas/EnvironmentConfigParams'
            - type: 'null'
        description:
          anyOf:
            - type: string
            - type: 'null'
        metadata:
          $ref: '#/components/schemas/ResourceMetadata'
        scope:
          anyOf:
            - $ref: '#/components/schemas/EnvironmentScope'
            - type: 'null'
      required:
        - name
      additionalProperties: false
    Environment_1:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/EnvironmentId'
        archived_at:
          anyOf:
            - type: string
            - type: 'null'
        config:
          $ref: '#/components/schemas/EnvironmentConfig'
        created_at:
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
        metadata:
          $ref: '#/components/schemas/ResourceMetadata'
        name:
          type: string
        type:
          type: string
          enum:
            - environment
        updated_at:
          type: string
        scope:
          $ref: '#/components/schemas/EnvironmentScope'
      required:
        - id
        - archived_at
        - config
        - created_at
        - description
        - metadata
        - name
        - type
        - updated_at
      additionalProperties: false
    WorkspaceId:
      type: string
      pattern: ^wrkspc_[0-9a-f]{32}$
    ValidationMalformedError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.malformed
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#validation-malformed
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        The request could not be decoded or violated a declared input
        constraint.
    PolicyDeniedError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - policy.denied
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#policy-denied
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: Deployment governance or retention policy denied the request.
    ValidationConflictError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.conflict
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#validation-conflict
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: The request conflicts with the resource's current state.
    IdempotencyConflictError:
      anyOf:
        - $ref: '#/components/schemas/ValidationIdempotencyConflictError'
        - $ref: '#/components/schemas/ValidationIdempotencyInProgressError'
      description: >-
        An idempotent mutation conflicts with a completed or in-progress request
        for the same key.
    RuntimeInternalError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - runtime.internal
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#runtime-internal
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        An unexpected internal failure occurred; the message contains an opaque
        incident reference.
    EnvironmentConfigParams:
      anyOf:
        - $ref: '#/components/schemas/CloudConfigParams'
        - $ref: '#/components/schemas/SelfHostedConfigParams'
    ResourceMetadata:
      type: object
      additionalProperties:
        type: string
        allOf:
          - maxLength: 512
      allOf:
        - propertyNames:
            type: string
            allOf:
              - minLength: 1
              - maxLength: 64
        - maxProperties: 16
          description: at most 16 correlation pairs with keys of 1 to 64 characters
    EnvironmentScope:
      type: string
      enum:
        - organization
        - account
    EnvironmentId:
      type: string
      pattern: ^env_[0-9a-f]{32}$
    EnvironmentConfig:
      anyOf:
        - $ref: '#/components/schemas/CloudConfig'
        - $ref: '#/components/schemas/SelfHostedConfig'
    ValidationIdempotencyConflictError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.idempotency_conflict
            message:
              type: string
            more:
              type: string
              enum:
                - >-
                  https://docs.checkfu.com/reference/errors#validation-idempotency-conflict
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: The Idempotency-Key is already bound to a different request.
    ValidationIdempotencyInProgressError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.idempotency_in_progress
            message:
              type: string
            more:
              type: string
              enum:
                - >-
                  https://docs.checkfu.com/reference/errors#validation-idempotency-in-progress
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        An identical idempotent request is still in progress and may be retried
        later.
    CloudConfigParams:
      type: object
      properties:
        type:
          type: string
          enum:
            - cloud
        networking:
          anyOf:
            - anyOf:
                - $ref: '#/components/schemas/UnrestrictedNetwork'
                - $ref: '#/components/schemas/LimitedNetworkParams'
            - type: 'null'
        packages:
          anyOf:
            - $ref: '#/components/schemas/PackagesParams'
            - type: 'null'
      required:
        - type
      additionalProperties: false
    SelfHostedConfigParams:
      type: object
      properties:
        type:
          type: string
          enum:
            - self_hosted
        networking:
          anyOf:
            - anyOf:
                - $ref: '#/components/schemas/UnrestrictedNetwork'
                - $ref: '#/components/schemas/LimitedNetworkParams'
            - type: 'null'
      required:
        - type
      additionalProperties: false
    CloudConfig:
      type: object
      properties:
        type:
          type: string
          enum:
            - cloud
        networking:
          anyOf:
            - $ref: '#/components/schemas/UnrestrictedNetwork'
            - $ref: '#/components/schemas/LimitedNetwork'
        packages:
          $ref: '#/components/schemas/Packages'
      required:
        - type
        - networking
        - packages
      additionalProperties: false
    SelfHostedConfig:
      type: object
      properties:
        type:
          type: string
          enum:
            - self_hosted
        networking:
          anyOf:
            - $ref: '#/components/schemas/UnrestrictedNetwork'
            - $ref: '#/components/schemas/LimitedNetwork'
      required:
        - type
      additionalProperties: false
    UnrestrictedNetwork:
      type: object
      properties:
        type:
          type: string
          enum:
            - unrestricted
      required:
        - type
      additionalProperties: false
    LimitedNetworkParams:
      type: object
      properties:
        type:
          type: string
          enum:
            - limited
        allow_mcp_servers:
          anyOf:
            - type: boolean
            - type: 'null'
        allow_package_managers:
          anyOf:
            - type: boolean
            - type: 'null'
        allowed_hosts:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
      required:
        - type
      additionalProperties: false
    PackagesParams:
      type: object
      properties:
        type:
          type: string
          enum:
            - packages
        apt:
          anyOf:
            - $ref: '#/components/schemas/Arrays_45'
            - type: 'null'
        cargo:
          anyOf:
            - $ref: '#/components/schemas/Arrays_45'
            - type: 'null'
        gem:
          anyOf:
            - $ref: '#/components/schemas/Arrays_45'
            - type: 'null'
        go:
          anyOf:
            - $ref: '#/components/schemas/Arrays_45'
            - type: 'null'
        npm:
          anyOf:
            - $ref: '#/components/schemas/Arrays_45'
            - type: 'null'
        pip:
          anyOf:
            - $ref: '#/components/schemas/Arrays_45'
            - type: 'null'
      additionalProperties: false
    LimitedNetwork:
      type: object
      properties:
        type:
          type: string
          enum:
            - limited
        allow_mcp_servers:
          type: boolean
        allow_package_managers:
          type: boolean
        allowed_hosts:
          type: array
          items:
            type: string
      required:
        - type
        - allow_mcp_servers
        - allow_package_managers
        - allowed_hosts
      additionalProperties: false
    Packages:
      type: object
      properties:
        type:
          type: string
          enum:
            - packages
        apt:
          $ref: '#/components/schemas/Arrays_45'
        cargo:
          $ref: '#/components/schemas/Arrays_45'
        gem:
          $ref: '#/components/schemas/Arrays_45'
        go:
          $ref: '#/components/schemas/Arrays_45'
        npm:
          $ref: '#/components/schemas/Arrays_45'
        pip:
          $ref: '#/components/schemas/Arrays_45'
      required:
        - apt
        - cargo
        - gem
        - go
        - npm
        - pip
      additionalProperties: false
    Arrays_45:
      type: array
      items:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.