# CreateSandboxRequest


[API catalog](/reference/api/) · [Docker Sandboxes overview](/reference/api/sandboxes/latest/) · [Product manual](https://docs.docker.com/ai/sandboxes-api/) · [OpenAPI specification](/reference/api/sandboxes/api.yaml)

API version: v1


> This API is experimental. Features, interfaces,
> and behavior may change.




Schema constraints and annotations:

```json
{
  "allOf": [
    {
      "properties": {
        "agent": {
          "description": "agent names an optional agent profile; unsupported profiles fail explicitly.",
          "type": "string"
        },
        "displayName": {
          "description": "(OPTIONAL) display_name is a scoped label; the backend assigns the immutable resource ID.",
          "maxLength": 64,
          "pattern": "^[a-zA-Z0-9_-]*$",
          "type": "string"
        },
        "displayNamePrefix": {
          "description": "(OPTIONAL) display_name_prefix requests a generated label and excludes display_name.",
          "type": "string"
        },
        "environment": {
          "additionalProperties": {
            "title": "value",
            "type": "string"
          },
          "description": "environment is non-secret environment metadata.",
          "type": "object"
        },
        "features": {
          "$ref": "#/components/schemas/FeatureOptions",
          "description": "features carries typed inputs validated before admission can have effects."
        },
        "kits": {
          "description": "kits are the kit inputs to apply before readiness, in composition order.",
          "items": {
            "$ref": "#/components/schemas/KitInput"
          },
          "type": "array"
        },
        "labels": {
          "additionalProperties": {
            "description": "",
            "title": "value",
            "type": "string"
          },
          "description": "labels are non-secret caller-assigned key/value metadata recorded at admission.\nThis contract has no verb that changes labels afterwards.",
          "maxProperties": 64,
          "type": "object"
        },
        "mcp": {
          "$ref": "#/components/schemas/McpCreateSpec",
          "description": "mcp requests an MCP gateway wired before the workload starts."
        },
        "networkPolicies": {
          "description": "network_policies are inline policies materialized in governance and enforced before the first guest process.\nOmission or an empty list requests no inline policies; unsupported policies fail before create effects.",
          "items": {
            "$ref": "#/components/schemas/NetworkPolicy"
          },
          "type": "array"
        },
        "platform": {
          "$ref": "#/components/schemas/Platform",
          "description": "platform selects an exact supported, image-compatible tuple when present.\nexplicit platform requires OS and architecture"
        },
        "policyIds": {
          "description": "policy_ids names existing governance policies, never raw policy content.",
          "items": {
            "minLength": 1,
            "type": "string"
          },
          "type": "array"
        },
        "pullPolicy": {
          "description": "pull_policy retains shared image-pull semantics and explicit support errors.",
          "enum": [
            "unspecified",
            "always"
          ],
          "title": "CreateSandboxRequestPullPolicy",
          "type": "string"
        },
        "resources": {
          "$ref": "#/components/schemas/Resources",
          "description": "resources requests CPU and memory within the selected placement's limits."
        },
        "startupExecution": {
          "$ref": "#/components/schemas/StartupExecution",
          "description": "startup_execution is ordinary create input and persists for\nthe sandbox lifetime."
        }
      }
    },
    {
      "dependentSchemas": {
        "image": {
          "not": {
            "anyOf": [
              {
                "required": [
                  "imageRef"
                ]
              }
            ]
          }
        },
        "imageRef": {
          "not": {
            "anyOf": [
              {
                "required": [
                  "image"
                ]
              }
            ]
          }
        }
      },
      "properties": {
        "image": {
          "description": "image is the managed Image resource name.",
          "pattern": "^images/[^/]+$",
          "type": "string"
        },
        "imageRef": {
          "description": "image_ref is an external OCI reference, with the existing backend validation.",
          "type": "string"
        }
      }
    }
  ],
  "description": "CreateSandboxRequest validates typed composition intent before replay and\npersists accepted guarantees, distinct enough from legacy create that old\nservers cannot silently drop it.\ndisplay_name and display_name_prefix are mutually exclusive At most one of image, imageRef is set.",
  "title": "CreateSandboxRequest",
  "type": "object",
  "unevaluatedProperties": false
}
```