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

# Create a SandboxProfile

> Creates a workspace-scoped SandboxProfile under a logical `key` and publishes immutable revision 1 from the supplied tier, base image, packages, network policy, resource limits, and retention mode (`durable` or `ephemeral_zdr`). A package may pin a package `version` or omit it to install the latest; either way it resolves once, into this revision's derived image. Allowed hosts must be lower-case public DNS names; a host selector is not itself an enforced egress boundary. On an `allowlist` policy, `allow_package_managers` and `allow_mcp_servers` are conveniences that COMPILE into `allowed_hosts` at admission — the published revision stores the expanded hosts and records which presets produced them, so the expansion is readable and enforcement sees exact hosts only. The compiled list, not the submitted one, is what the 256-host limit applies to. Returns the SandboxProfile with 201, including the content-hashed derived image digest used for cold-start reuse. Send `Idempotency-Key` to make retries safe.

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.



## OpenAPI

````yaml /openapi.json post /v1/sandbox-profiles
openapi: 3.1.0
info:
  title: Checkfu API
  version: '2026-08-27'
  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-27); 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: harnesses
  - name: harnessRuntime
  - name: sandboxProfiles
  - name: computerProfiles
  - name: permissionAssignments
  - name: actionPolicies
  - name: files
  - name: memoryStores
  - name: dreams
  - name: modelCredentials
  - name: modelRoutingProfiles
  - name: blueprintInstallations
  - name: toolSources
  - name: skills
  - name: skillSources
  - name: agentSources
  - name: skillProposals
  - name: instructionProposals
  - name: catalog
  - name: concepts
  - name: support
  - name: connections
  - name: connectionVaults
  - name: connectionAssignments
  - name: connectedRuntimes
  - name: projects
  - name: collaboration
  - name: automationGraphs
  - name: automations
  - name: actionApprovals
  - name: standingApprovals
  - name: usage
  - name: models
  - name: outcomes
  - name: budgets
  - name: billing
  - name: sessions
  - name: audit
  - name: sessionExports
  - name: runs
  - name: runnerPools
  - name: transcripts
  - name: sessionWatches
  - name: sessionHandoffs
  - name: sessionCapsules
  - name: sessionTrajectories
  - name: webhookEndpoints
  - name: integrationGateway
  - name: agentDeployments
  - name: workEnvironments
  - name: computers
  - name: computerScreens
  - name: computerBrowserObservations
  - name: computerBrowserActions
  - name: environments
  - name: vaults
  - name: apiMcp
  - name: a2a
paths:
  /v1/sandbox-profiles:
    post:
      tags:
        - sandboxProfiles
      summary: Create a SandboxProfile
      description: >-
        Creates a workspace-scoped SandboxProfile under a logical `key` and
        publishes immutable revision 1 from the supplied tier, base image,
        packages, network policy, resource limits, and retention mode (`durable`
        or `ephemeral_zdr`). A package may pin a package `version` or omit it to
        install the latest; either way it resolves once, into this revision's
        derived image. Allowed hosts must be lower-case public DNS names; a host
        selector is not itself an enforced egress boundary. On an `allowlist`
        policy, `allow_package_managers` and `allow_mcp_servers` are
        conveniences that COMPILE into `allowed_hosts` at admission — the
        published revision stores the expanded hosts and records which presets
        produced them, so the expansion is readable and enforcement sees exact
        hosts only. The compiled list, not the submitted one, is what the
        256-host limit applies to. Returns the SandboxProfile with 201,
        including the content-hashed derived image digest used for cold-start
        reuse. Send `Idempotency-Key` to make retries safe.


        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: sandboxProfiles.createSandboxProfile
      parameters:
        - name: checkfu-version
          in: header
          schema:
            type: string
            enum:
              - '2026-08-27'
          required: true
        - name: idempotency-key
          in: header
          schema:
            type: string
            allOf:
              - maxLength: 255
          required: false
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  type: string
                  allOf:
                    - pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$
                tier:
                  $ref: '#/components/schemas/Union_19'
                base_image:
                  $ref: '#/components/schemas/Objects_37'
                packages:
                  $ref: '#/components/schemas/Arrays_12'
                network_policy:
                  $ref: '#/components/schemas/Union_89'
                resource_limits:
                  $ref: '#/components/schemas/Objects_10'
                retention_mode:
                  $ref: '#/components/schemas/Union_21'
              required:
                - key
                - tier
                - base_image
                - packages
                - network_policy
                - resource_limits
                - retention_mode
              additionalProperties: false
        required: true
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/SandboxProfileId'
                  workspace_id:
                    $ref: '#/components/schemas/WorkspaceId'
                  key:
                    type: string
                    allOf:
                      - pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$
                  tier:
                    $ref: '#/components/schemas/Union_19'
                  base_image:
                    $ref: '#/components/schemas/Objects_37'
                  packages:
                    $ref: '#/components/schemas/Arrays_12'
                  network_policy:
                    $ref: '#/components/schemas/Objects_38'
                  resource_limits:
                    $ref: '#/components/schemas/Objects_10'
                  retention_mode:
                    $ref: '#/components/schemas/Union_21'
                  derived_image_digest:
                    type: string
                    allOf:
                      - pattern: ^sha256:[0-9a-f]{64}$
                  current_revision_number:
                    type: integer
                    allOf:
                      - exclusiveMinimum: 0
                  resource_version:
                    type: integer
                    allOf:
                      - exclusiveMinimum: 0
                  created_at:
                    type: string
                  updated_at:
                    type: string
                required:
                  - id
                  - workspace_id
                  - key
                  - tier
                  - base_image
                  - packages
                  - network_policy
                  - resource_limits
                  - retention_mode
                  - derived_image_digest
                  - current_revision_number
                  - resource_version
                  - created_at
                  - updated_at
                additionalProperties: false
          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:
                type: object
                required:
                  - error
                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
                additionalProperties: false
        '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:
    Union_19:
      type: string
      enum:
        - container
        - microvm
    Objects_37:
      type: object
      properties:
        reference:
          type: string
          allOf:
            - minLength: 1
            - maxLength: 255
        digest:
          type: string
          allOf:
            - pattern: ^sha256:[0-9a-f]{64}$
      required:
        - reference
        - digest
      additionalProperties: false
    Arrays_12:
      type: array
      items:
        type: object
        properties:
          manager:
            type: string
            enum:
              - apt
              - cargo
              - gem
              - go
              - npm
              - pip
          name:
            $ref: '#/components/schemas/SandboxPackageCoordinate'
          version:
            $ref: '#/components/schemas/SandboxPackageCoordinate'
        required:
          - manager
          - name
        additionalProperties: false
      allOf:
        - maxItems: 256
    Union_89:
      anyOf:
        - type: object
          properties:
            mode:
              type: string
              enum:
                - none
            allowed_hosts:
              $ref: '#/components/schemas/Arrays_16'
          required:
            - mode
            - allowed_hosts
          additionalProperties: false
        - type: object
          properties:
            mode:
              type: string
              enum:
                - unrestricted
            allowed_hosts:
              $ref: '#/components/schemas/Arrays_16'
          required:
            - mode
            - allowed_hosts
          additionalProperties: false
        - $ref: '#/components/schemas/SandboxAllowlistWithinHostLimit'
    Objects_10:
      type: object
      properties:
        cpu_millis:
          type: integer
          allOf:
            - exclusiveMinimum: 0
        memory_mib:
          type: integer
          allOf:
            - exclusiveMinimum: 0
        disk_mib:
          type: integer
          allOf:
            - exclusiveMinimum: 0
        max_duration_seconds:
          type: integer
          allOf:
            - exclusiveMinimum: 0
      required:
        - cpu_millis
        - memory_mib
        - disk_mib
        - max_duration_seconds
      additionalProperties: false
    Union_21:
      type: string
      enum:
        - durable
        - ephemeral_zdr
    SandboxProfileId:
      type: string
      allOf:
        - pattern: ^sprof_[0-9a-f]{32}$
    WorkspaceId:
      type: string
      allOf:
        - pattern: ^wrkspc_[0-9a-f]{32}$
    Objects_38:
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/Union_20'
        allowed_hosts:
          type: array
          items:
            type: string
            allOf:
              - pattern: >-
                  ^(?:\*\.)?[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::[1-9][0-9]{0,4})?$
          allOf:
            - maxItems: 256
        required_egress_certification:
          type: string
          enum:
            - advisory_filter
            - security_boundary
        egress_presets:
          type: object
          properties:
            version:
              anyOf:
                - type: number
                  enum:
                    - 1
            presets:
              $ref: '#/components/schemas/UniqueSandboxEgressPresets'
          required:
            - version
            - presets
          additionalProperties: false
      required:
        - mode
        - allowed_hosts
      additionalProperties: false
    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.
    SandboxPackageCoordinate:
      type: string
      allOf:
        - minLength: 1
        - maxLength: 255
    Arrays_16:
      type: array
      items:
        $ref: '#/components/schemas/SandboxAllowedHost'
      allOf:
        - maxItems: 0
    SandboxAllowlistWithinHostLimit:
      type: object
      properties:
        mode:
          type: string
          enum:
            - allowlist
        allowed_hosts:
          type: array
          items:
            $ref: '#/components/schemas/SandboxAllowedHost'
          allOf:
            - maxItems: 256
        required_egress_certification:
          type: string
          enum:
            - advisory_filter
            - security_boundary
        allow_package_managers:
          type: boolean
        allow_mcp_servers:
          type: boolean
      required:
        - mode
        - allowed_hosts
      additionalProperties: false
    Union_20:
      type: string
      enum:
        - none
        - allowlist
        - unrestricted
    UniqueSandboxEgressPresets:
      type: array
      items:
        type: string
        enum:
          - package_managers
          - mcp_servers
      allOf:
        - minItems: 1
        - maxItems: 2
    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.
    SandboxAllowedHost:
      type: string
      description: >-
        A lower-case public DNS hostname, never localhost or an IP literal, with
        an optional leading wildcard and TCP port from 1 through 65535.
      allOf:
        - maxLength: 261
        - pattern: >-
            ^(?:\*\.)?[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+(?::[1-9][0-9]{0,4})?$
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````