---
title: "Create a VM"
method: POST
path: "/vms"
tags: ["vms"]
---

# Create a VM

`POST /vms`

## Response `200`

VM resource was successfully created

- VM
  - `name` string — VM name
  - `image` string — VM image for this VM
  - `imagePullPolicy` 'IfNotPresent' | 'Always' — VM image pull policy
  - `cpu` number — Number of CPUs assigned to this VM
  - `memory` number — Amount of RAM in megabytes assigned to this VM
  - `diskSize` number — Disk size for this VM
  - `net-softnet` boolean — Whether to use Softnet network isolation
  - `net-bridged` string — Whether to use bridged network mode
  - `headless` boolean — Whether to run without graphics
  - `nested` boolean — Enable nested virtualization
  - `status` 'pending' | 'running' | 'failed' — VM status
  - `status_message` string — VM status message
  - `worker` string — Worker on which the VM was assigned to
  - `username` string — SSH username to use when connecting to a VM
  - `password` string — SSH password to use when connecting to a VM
  - `startup_script` object — Startup script to run after the VM boots and becomes accessible via SSH
    - `script_content` string
    - `env` object
  - `restart_policy` 'Never' | 'OnFailure' — VM restart policy: specify "Never" to never restart or "OnFailure" to only restart when the VM fails
  - `resources` object — Resources required by this VM on the worker
  - `labels` object — Labels required by this VM on the worker
  - `hostDirs` object[] — Directories on the Orchard Worker host to mount to a VM
    - `name` string
    - `path` string
    - `ro` boolean

## Other responses

- `409` — VM resource with with the same name already exists

## Changes

- **2025-10-07** `fbfcc3358a84` — 1 info
  - added the optional property `startup_script` to the response with the `200` status
- **2025-10-06** `49b3b1162c55` — 17 info
  - added the optional property `cpu` to the response with the `200` status
  - added the optional property `diskSize` to the response with the `200` status
  - added the optional property `headless` to the response with the `200` status
  - added the optional property `image` to the response with the `200` status
  - …13 more
- **2025-09-26** `ece9486be282` — 1 info
  - added the optional property `nested` to the response with the `200` status
- **2023-10-09** `e0632c7e52ea` — 1 breaking, 3 info
  - the response's body type changed from no type to `object` for status `200`
  - added the optional property `hostDirs` to the response with the `200` status
  - added the optional property `name` to the response with the `200` status
  - added the optional property `resources` to the response with the `200` status
- **2023-01-26** `4b9547159dde` — 2 breaking, 1 info
  - removed the request body
  - the response's body type changed from `object` to no type for status `200`
  - removed `#/components/schemas/VMMeta, #/components/schemas/VMSpec, #/components/schemas/VMState` from the response body `allOf` list for the response status `200`

[Change history](https://skmtc.dev/openai/apis/orchard/changes/vms/post.md)

---

[API](https://skmtc.dev/openai/apis/orchard.md) · [All operations](https://skmtc.dev/openai/apis/orchard/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openai/orchard/revisions/fbfcc3358a84/schema)