v1

latestOpenAPI 3.0.02026-07-17212535.2 KB

vms

Create a VM

post/vms

Request body

namestring

VM name

generationnumber

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.

imagestring

VM image for this VM

imagePullPolicy'IfNotPresent' | 'Always'

VM image pull policy

cpunumber

Number of CPUs assigned to this VM

memorynumber

Amount of RAM in megabytes assigned to this VM

diskSizenumber

Disk size for this VM

net-softnetboolean

Please use netSoftnet instead

netSoftnetboolean

Whether to use Softnet network isolation.

See tart run's help for --net-softnet for more details.

netSoftnetAllowstring[]

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.

netSoftnetBlockstring[]

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.

suspendableboolean

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-bridgedstring

Whether to use bridged network mode

headlessboolean

Whether to run without graphics

nestedboolean

Enable nested virtualization

usernamestring

SSH username to use when connecting to a VM

passwordstring

SSH password to use when connecting to a VM

restart_policy'Never' | 'OnFailure'

VM restart policy: specify "Never" to never restart or "OnFailure" to only restart when the VM fails

resourcesobject

Resources required by this VM on the worker

labelsobject

Labels required by this VM on the worker

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.

localNamestring

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

tartNamestring

Deprecated alias for localName.

Example request

{
  "name": "macos-tahoe-base",
  "image": "ghcr.io/cirruslabs/macos-tahoe-base:latest",
  "diskSize": 100,
  "netSoftnetAllow": [
    "192.168.0.0/24"
  ],
  "netSoftnetBlock": [
    "66.66.0.0/16"
  ],
  "net-bridged": "en0",
  "startup_script": {
    "script_content": "#!/bin/zsh\n\necho $GREETING\n",
    "env": {
      "GREETING": "Hello, World!"
    }
  },
  "resources": {
    "org.cirruslabs.logical-cores": 4,
    "org.cirruslabs.memory-mib": 8192
  },
  "labels": {
    "model": "macstudio"
  },
  "hostDirs": [
    {
      "path": "/path/on/host/to/sources",
      "ro": true
    },
    {
      "path": "/path/on/host/to/builds"
    }
  ]
}

Response

VM resource was successfully created

namestring

VM name

generationnumber

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.

imagestring

VM image for this VM

imagePullPolicy'IfNotPresent' | 'Always'

VM image pull policy

cpunumber

Number of CPUs assigned to this VM

memorynumber

Amount of RAM in megabytes assigned to this VM

diskSizenumber

Disk size for this VM

net-softnetboolean

Please use netSoftnet instead

netSoftnetboolean

Whether to use Softnet network isolation.

See tart run's help for --net-softnet for more details.

netSoftnetAllowstring[]

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.

netSoftnetBlockstring[]

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.

suspendableboolean

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-bridgedstring

Whether to use bridged network mode

headlessboolean

Whether to run without graphics

nestedboolean

Enable nested virtualization

usernamestring

SSH username to use when connecting to a VM

passwordstring

SSH password to use when connecting to a VM

restart_policy'Never' | 'OnFailure'

VM restart policy: specify "Never" to never restart or "OnFailure" to only restart when the VM fails

resourcesobject

Resources required by this VM on the worker

labelsobject

Labels required by this VM on the worker

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.

localNamestring

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

tartNamestring

Deprecated alias for localName.

status'pending' | 'running' | 'failed'

VM status

status_messagestring

VM status message

workerstring

Worker on which the VM was assigned to

observedGenerationnumber

Corresponds to the Generation value on which the worker had acted upon

Example response

{
  "name": "macos-tahoe-base",
  "image": "ghcr.io/cirruslabs/macos-tahoe-base:latest",
  "diskSize": 100,
  "netSoftnetAllow": [
    "192.168.0.0/24"
  ],
  "netSoftnetBlock": [
    "66.66.0.0/16"
  ],
  "net-bridged": "en0",
  "startup_script": {
    "script_content": "#!/bin/zsh\n\necho $GREETING\n",
    "env": {
      "GREETING": "Hello, World!"
    }
  },
  "resources": {
    "org.cirruslabs.logical-cores": 4,
    "org.cirruslabs.memory-mib": 8192
  },
  "labels": {
    "model": "macstudio"
  },
  "hostDirs": [
    {
      "path": "/path/on/host/to/sources",
      "ro": true
    },
    {
      "path": "/path/on/host/to/builds"
    }
  ]
}