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

# Create a VM

`POST /vms`

## Request body

- object
  - `name` string — VM name
  - `generation` number — Incremented by the controller each time a VM's specification changes
  - `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 — Please use `netSoftnet` instead
  - `netSoftnet` boolean — Whether to use Softnet network isolation. See `tart run`'s help for `--net-softnet` for more details.
  - `netSoftnetAllow` string[] — List of CIDRs to allow the traffic to when using Softnet isolation. See `tart run`'s help for `--net-softnet-allow` for more details. Enables `netSoftnet`.
  - `netSoftnetBlock` string[] — List of CIDRs to block the traffic to when using Softnet isolation. See `tart run`'s help for `--net-softnet-block` for more details. Enables `netSoftnet`.
  - `suspendable` boolean — When set, a VM will be started with an additional `--suspendable` command-line argument to `tart run`, which allows suspending it. Further generations of the VM will be `tart suspend`'ed instead of `tart stopped`. For example, this allows you to prepare a VM with loose Softnet settings and then move to the next generation by tightening the settings while preserving the VM's state.
  - `net-bridged` string — Whether to use bridged network mode
  - `headless` boolean — Whether to run without graphics
  - `nested` boolean — Enable nested virtualization
  - `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

## Response `200`

VM resource was successfully created

- VM
  - `name` string — VM name
  - `generation` number — Incremented by the controller each time a VM's specification changes
  - `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 — Please use `netSoftnet` instead
  - `netSoftnet` boolean — Whether to use Softnet network isolation. See `tart run`'s help for `--net-softnet` for more details.
  - `netSoftnetAllow` string[] — List of CIDRs to allow the traffic to when using Softnet isolation. See `tart run`'s help for `--net-softnet-allow` for more details. Enables `netSoftnet`.
  - `netSoftnetBlock` string[] — List of CIDRs to block the traffic to when using Softnet isolation. See `tart run`'s help for `--net-softnet-block` for more details. Enables `netSoftnet`.
  - `suspendable` boolean — When set, a VM will be started with an additional `--suspendable` command-line argument to `tart run`, which allows suspending it. Further generations of the VM will be `tart suspend`'ed instead of `tart stopped`. For example, this allows you to prepare a VM with loose Softnet settings and then move to the next generation by tightening the settings while preserving the VM's state.
  - `net-bridged` string — Whether to use bridged network mode
  - `headless` boolean — Whether to run without graphics
  - `nested` boolean — Enable nested virtualization
  - `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
  - `status` 'pending' | 'running' | 'failed' — VM status
  - `status_message` string — VM status message
  - `worker` string — Worker on which the VM was assigned to
  - `observedGeneration` number — Corresponds to the `Generation` value on which the worker had acted upon

## Other responses

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

## Changes

- **2025-11-11** `cd959a44c8d1` — 1 breaking
  - added required request body
- **2025-11-11** `266972c74d44` — 1 info
  - added the optional property `allOf[subschema #2: Virtual Machine Specification]/suspendable` to the response with the `200` status
- **2025-11-06** `eb0a5b3ac3ed` — 23 warning, 1 info
  - removed the optional property `cpu` from the response with the `200` status
  - removed the optional property `diskSize` from the response with the `200` status
  - removed the optional property `headless` from the response with the `200` status
  - removed the optional property `hostDirs` from the response with the `200` status
  - …20 more
- **2025-10-27** `349c4709fa60` — 4 info
  - added the optional property `netSoftnet` to the response with the `200` status
  - added the optional property `netSoftnetAllow` to the response with the `200` status
  - added the optional property `netSoftnetBlock` to the response with the `200` status
  - response property `net-softnet` deprecated
- **2025-10-07** `fbfcc3358a84` — 1 info
  - added the optional property `startup_script` to the response with the `200` status

[Full 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/cd959a44c8d1/schema)