---
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
  - `os` 'darwin' | 'linux' — Operating system used by a VM. Set to `linux` to work around the Apple's limitation of 2 macOS VMs per host. This field cannot be changed after the VM is created.
  - `arch` 'arm64' | 'amd64' — Hardware architecture to use for a VM. This field cannot be changed after the VM is created.
  - `runtime` 'tart' | 'vetu' — Runtime to use for a VM. This field cannot be changed after the VM is created.
  - `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. Requires running Orchard Controller with `--insecure-allow-host-dirs`.
    - `name` string
    - `path` string
    - `ro` boolean
  - `powerState` 'running' | 'stopped' | 'suspended' — Desired power state of the VM. When set to `stopped` or `suspended`, the VM does not consume any `resources` and can serve as a source for creating new Orchard VMs on the same worker. See `localName` for more details. Note that you can only transition into `stopped` or `suspended` only once at the moment.
  - `localName` string — Name of the local VM backing this VM resource. `localName` is specific to a worker, whereas `name` is cluster-wide. `localName` is useful in combination with `powerState` for creating stopped or suspended VMs that can be used to start or resume new VMs on the same worker. However, with great power comes great responsibility. You need to make sure: * that these new VMs will target the same worker using `labels` or `resources`, otherwise they will fail with the "the specified VM does not exist" error * that there's only one cloned new VM for each suspended VM at a time; if you clone more new VMs from a single suspended VM, Tart will give them new MAC addresses automatically, which will stop them from booting, since the suspend‑resume machinery expects the same MAC address
  - `tartName` string — Deprecated alias for `localName`.

## 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
  - `os` 'darwin' | 'linux' — Operating system used by a VM. Set to `linux` to work around the Apple's limitation of 2 macOS VMs per host. This field cannot be changed after the VM is created.
  - `arch` 'arm64' | 'amd64' — Hardware architecture to use for a VM. This field cannot be changed after the VM is created.
  - `runtime` 'tart' | 'vetu' — Runtime to use for a VM. This field cannot be changed after the VM is created.
  - `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. Requires running Orchard Controller with `--insecure-allow-host-dirs`.
    - `name` string
    - `path` string
    - `ro` boolean
  - `powerState` 'running' | 'stopped' | 'suspended' — Desired power state of the VM. When set to `stopped` or `suspended`, the VM does not consume any `resources` and can serve as a source for creating new Orchard VMs on the same worker. See `localName` for more details. Note that you can only transition into `stopped` or `suspended` only once at the moment.
  - `localName` string — Name of the local VM backing this VM resource. `localName` is specific to a worker, whereas `name` is cluster-wide. `localName` is useful in combination with `powerState` for creating stopped or suspended VMs that can be used to start or resume new VMs on the same worker. However, with great power comes great responsibility. You need to make sure: * that these new VMs will target the same worker using `labels` or `resources`, otherwise they will fail with the "the specified VM does not exist" error * that there's only one cloned new VM for each suspended VM at a time; if you clone more new VMs from a single suspended VM, Tart will give them new MAC addresses automatically, which will stop them from booting, since the suspend‑resume machinery expects the same MAC address
  - `tartName` string — Deprecated alias for `localName`.
  - `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

- **2026-03-16** `22c44b5665e6` — 9 info
  - added the new optional request property `allOf[subschema #2: Virtual Machine Specification]/arch`
  - added the new optional request property `allOf[subschema #2: Virtual Machine Specification]/os`
  - added the new optional request property `allOf[subschema #2: Virtual Machine Specification]/runtime`
  - request property `allOf[subschema #2: Virtual Machine Specification]/tartName` deprecated
  - …5 more
- **2025-12-02** `ddc34c1a7aa4` — 3 info
  - added the new optional request property `allOf[subschema #2: Virtual Machine Specification]/powerState`
  - added the optional property `allOf[subschema #2: Virtual Machine Specification]/powerState` to the response with the `200` status
  - added the optional property `allOf[subschema #2: Virtual Machine Specification]/tartName` to the response with the `200` status
- **2025-11-11** `67700035bf96` — 2 info
  - the request optional property `allOf[subschema #1: Virtual Machine Metadata]/name` became not read-only
  - the response optional property `allOf[subschema #1: Virtual Machine Metadata]/name` became not read-only for the status `200`
- **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

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