---
title: "Creates and starts a new SandboxEngine within a specified workspace."
method: POST
path: "/v1/{parent}/sandboxEngines"
tags: ["SandboxEngineService"]
---

# Creates and starts a new SandboxEngine within a specified workspace.

`POST /v1/{parent}/sandboxEngines`

## Request

- Base URL: `https://docs.h2o.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.h2o.ai/v1/{parent}/sandboxEngines`
- Auth: none declared
- TypeScript: <https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/docs/v1/:parent/sandboxEngines/post.ts> (a function with typed inputs; its response is checked against the schema)

Authorization may require the following permission on the engine's parent workspace:
* actions/enginemanager/sandboxEngines/CREATE

## Path parameters

- `parent` string, required

## Query parameters

- `sandboxEngineId` string, required

## Request body

- V1SandboxEngine: Message representing Sandbox Engine.
  - `name` string: Identifier. SandboxEngine resource name.
  - `displayName` string: Optional. Human-readable name of the SandboxEngine. Must contain at most 63 characters. Does not have to be unique.
  - `uid` string: Output only. Globally unique identifier of the resource.
  - `state` 'STATE_UNSPECIFIED' | 'STATE_STARTING' | 'STATE_RUNNING' | 'STATE_TERMINATING' | 'STATE_TERMINATED' | 'STATE_FAILED' | 'STATE_DELETING': All possible SandboxEngine states. - STATE_UNSPECIFIED: SandboxEngine state is unspecified or unknown. - STATE_STARTING: SandboxEngine is starting. - STATE_RUNNING: SandboxEngine is running. - STATE_TERMINATING: SandboxEngine is terminating. - STATE_TERMINATED: SandboxEngine is terminated. - STATE_FAILED: SandboxEngine has failed. - STATE_DELETING: SandboxEngine is being deleted.
  - `creator` string: Output only. Name of an entity that created the SandboxEngine.
  - `creatorDisplayName` string: Output only. Human-readable name of creator.
  - `createTime` string, date-time: Output only. Time when the SandboxEngine creation was requested.
  - `sandboxEngineImage` string, required: Required. Immutable. The resource name of the SandboxEngineImage that is assigned to this SandboxEngine. Format is `workspaces/*/sandboxEngineImages/*`.
  - `sandboxEngineImageInfo` V1SandboxEngineImageInfo: The original SandboxEngineImage data used by SandboxEngine when using the SandboxEngineImage. For more info about each field see the original SandboxEngineImage resource.
    - `image` string
    - `name` string
    - `displayName` string
    - `enabled` boolean
    - `imagePullPolicy` 'IMAGE_PULL_POLICY_UNSPECIFIED' | 'IMAGE_PULL_POLICY_ALWAYS' | 'IMAGE_PULL_POLICY_NEVER' | 'IMAGE_PULL_POLICY_IF_NOT_PRESENT': Policy for downloading an image in K8s. - IMAGE_PULL_POLICY_UNSPECIFIED: Unspecified image pull policy. - IMAGE_PULL_POLICY_ALWAYS: Every time the container is launched, the container image registry is queried to resolve the name to an image digest. - IMAGE_PULL_POLICY_NEVER: Do not try to fetch the image. If the image is already present locally, the container will start. If the image is not present, container startup will fail. - IMAGE_PULL_POLICY_IF_NOT_PRESENT: The image is pulled only if it is not already present locally.
    - `imagePullSecrets` string[]
    - `createTime` string, date-time
    - `updateTime` string, date-time, nullable
    - `creator` string
    - `updater` string
    - `creatorDisplayName` string
    - `updaterDisplayName` string
  - `sandboxEngineTemplate` string, required: Required. Immutable. The resource name of the SandboxEngineTemplate that is assigned to this SandboxEngine. Format is `workspaces/*/sandboxEngineTemplates/*`.
  - `sandboxEngineTemplateInfo` V1SandboxEngineTemplateInfo: The original SandboxEngineTemplate data used by SandboxEngine when using the SandboxEngineTemplate. For more info about each field see the original SandboxEngineTemplate resource.
    - `name` string
    - `displayName` string
    - `milliCpuRequest` integer
    - `milliCpuLimit` integer
    - `gpuResource` string
    - `gpu` integer
    - `memoryBytesRequest` string, int64
    - `memoryBytesLimit` string, int64
    - `storageBytes` string, int64
    - `storageClassName` string
    - `environmentalVariables` object
    - `yamlPodTemplateSpec` string
    - `enabled` boolean
    - `maxIdleDuration` string
    - `createTime` string, date-time
    - `updateTime` string, date-time, nullable
    - `creator` string
    - `updater` string
    - `creatorDisplayName` string
    - `updaterDisplayName` string
    - `maxRunningDuration` string
  - `currentIdleDuration` string, nullable: Output only. Current time the SandboxEngine is idle.
  - `annotations` object: Optional. Additional arbitrary metadata associated with the SandboxEngine. Annotations are key/value pairs. The key must: - be 63 characters or less - begin and end with an alphanumeric character ([a-z0-9A-Z]) - with dashes (-), underscores (_), dots (.), and alphanumerics between - regex used for validation is: ^[A-Za-z0-9]([-A-Za-z0-9_.]{0,61}[A-Za-z0-9])?$
  - `pendingReason` 'PENDING_REASON_UNSPECIFIED' | 'PENDING_REASON_CREATING_RESOURCES' | 'PENDING_REASON_SCHEDULING' | 'PENDING_REASON_PULLING_IMAGE' | 'PENDING_REASON_CONTAINER_CREATING' | 'PENDING_REASON_WAITING_READINESS' | 'PENDING_REASON_DELETING_RESOURCES': All possible reasons why a SandboxEngine is in a pending/waiting state. - PENDING_REASON_UNSPECIFIED: No pending reason - engine is in a stable state (RUNNING, TERMINATED, FAILED). - PENDING_REASON_CREATING_RESOURCES: Kubernetes resources (Pod, Service) are being created. - PENDING_REASON_SCHEDULING: Pod is waiting to be scheduled to a node. - PENDING_REASON_PULLING_IMAGE: Node is pulling the container image. - PENDING_REASON_CONTAINER_CREATING: Container is being created (init containers, volumes, network setup). - PENDING_REASON_WAITING_READINESS: Container is running but application is not ready yet. - PENDING_REASON_DELETING_RESOURCES: Kubernetes resources are being cleaned up.
  - `pendingMessage` string: Output only. Human-readable message providing details about the current pending state. Contains information from Kubernetes about what the engine is waiting for. Empty when the engine is in a stable state.

## Response `200`

A successful response.

- V1CreateSandboxEngineResponse: Response message for SandboxEngineService.CreateSandboxEngine.
  - `sandboxEngine` V1SandboxEngine: Message representing Sandbox Engine.
    - `name` string: Identifier. SandboxEngine resource name.
    - `displayName` string: Optional. Human-readable name of the SandboxEngine. Must contain at most 63 characters. Does not have to be unique.
    - `uid` string: Output only. Globally unique identifier of the resource.
    - `state` 'STATE_UNSPECIFIED' | 'STATE_STARTING' | 'STATE_RUNNING' | 'STATE_TERMINATING' | 'STATE_TERMINATED' | 'STATE_FAILED' | 'STATE_DELETING': All possible SandboxEngine states. - STATE_UNSPECIFIED: SandboxEngine state is unspecified or unknown. - STATE_STARTING: SandboxEngine is starting. - STATE_RUNNING: SandboxEngine is running. - STATE_TERMINATING: SandboxEngine is terminating. - STATE_TERMINATED: SandboxEngine is terminated. - STATE_FAILED: SandboxEngine has failed. - STATE_DELETING: SandboxEngine is being deleted.
    - `creator` string: Output only. Name of an entity that created the SandboxEngine.
    - `creatorDisplayName` string: Output only. Human-readable name of creator.
    - `createTime` string, date-time: Output only. Time when the SandboxEngine creation was requested.
    - `sandboxEngineImage` string, required: Required. Immutable. The resource name of the SandboxEngineImage that is assigned to this SandboxEngine. Format is `workspaces/*/sandboxEngineImages/*`.
    - `sandboxEngineImageInfo` V1SandboxEngineImageInfo: The original SandboxEngineImage data used by SandboxEngine when using the SandboxEngineImage. For more info about each field see the original SandboxEngineImage resource.
      - `image` string
      - `name` string
      - `displayName` string
      - `enabled` boolean
      - `imagePullPolicy` 'IMAGE_PULL_POLICY_UNSPECIFIED' | 'IMAGE_PULL_POLICY_ALWAYS' | 'IMAGE_PULL_POLICY_NEVER' | 'IMAGE_PULL_POLICY_IF_NOT_PRESENT': Policy for downloading an image in K8s. - IMAGE_PULL_POLICY_UNSPECIFIED: Unspecified image pull policy. - IMAGE_PULL_POLICY_ALWAYS: Every time the container is launched, the container image registry is queried to resolve the name to an image digest. - IMAGE_PULL_POLICY_NEVER: Do not try to fetch the image. If the image is already present locally, the container will start. If the image is not present, container startup will fail. - IMAGE_PULL_POLICY_IF_NOT_PRESENT: The image is pulled only if it is not already present locally.
      - `imagePullSecrets` string[]
      - `createTime` string, date-time
      - `updateTime` string, date-time, nullable
      - `creator` string
      - `updater` string
      - `creatorDisplayName` string
      - `updaterDisplayName` string
    - `sandboxEngineTemplate` string, required: Required. Immutable. The resource name of the SandboxEngineTemplate that is assigned to this SandboxEngine. Format is `workspaces/*/sandboxEngineTemplates/*`.
    - `sandboxEngineTemplateInfo` V1SandboxEngineTemplateInfo: The original SandboxEngineTemplate data used by SandboxEngine when using the SandboxEngineTemplate. For more info about each field see the original SandboxEngineTemplate resource.
      - `name` string
      - `displayName` string
      - `milliCpuRequest` integer
      - `milliCpuLimit` integer
      - `gpuResource` string
      - `gpu` integer
      - `memoryBytesRequest` string, int64
      - `memoryBytesLimit` string, int64
      - `storageBytes` string, int64
      - `storageClassName` string
      - `environmentalVariables` object
      - `yamlPodTemplateSpec` string
      - `enabled` boolean
      - `maxIdleDuration` string
      - `createTime` string, date-time
      - `updateTime` string, date-time, nullable
      - `creator` string
      - `updater` string
      - `creatorDisplayName` string
      - `updaterDisplayName` string
      - `maxRunningDuration` string
    - `currentIdleDuration` string, nullable: Output only. Current time the SandboxEngine is idle.
    - `annotations` object: Optional. Additional arbitrary metadata associated with the SandboxEngine. Annotations are key/value pairs. The key must: - be 63 characters or less - begin and end with an alphanumeric character ([a-z0-9A-Z]) - with dashes (-), underscores (_), dots (.), and alphanumerics between - regex used for validation is: ^[A-Za-z0-9]([-A-Za-z0-9_.]{0,61}[A-Za-z0-9])?$
    - `pendingReason` 'PENDING_REASON_UNSPECIFIED' | 'PENDING_REASON_CREATING_RESOURCES' | 'PENDING_REASON_SCHEDULING' | 'PENDING_REASON_PULLING_IMAGE' | 'PENDING_REASON_CONTAINER_CREATING' | 'PENDING_REASON_WAITING_READINESS' | 'PENDING_REASON_DELETING_RESOURCES': All possible reasons why a SandboxEngine is in a pending/waiting state. - PENDING_REASON_UNSPECIFIED: No pending reason - engine is in a stable state (RUNNING, TERMINATED, FAILED). - PENDING_REASON_CREATING_RESOURCES: Kubernetes resources (Pod, Service) are being created. - PENDING_REASON_SCHEDULING: Pod is waiting to be scheduled to a node. - PENDING_REASON_PULLING_IMAGE: Node is pulling the container image. - PENDING_REASON_CONTAINER_CREATING: Container is being created (init containers, volumes, network setup). - PENDING_REASON_WAITING_READINESS: Container is running but application is not ready yet. - PENDING_REASON_DELETING_RESOURCES: Kubernetes resources are being cleaned up.
    - `pendingMessage` string: Output only. Human-readable message providing details about the current pending state. Contains information from Kubernetes about what the engine is waiting for. Empty when the engine is in a stable state.

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto.md) - [All operations](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/llms.txt) - [OpenAPI document](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/revisions/297cfadc1d39?raw)