Sign in
vms

List VMs

get/vms

Query parameters

filterstring

Filter VMs using path=value syntax; currently only worker=<name> is supported to return VMs assigned to the given worker

Response

OK

namestring

VM name

generationnumber

Incremented by the controller each time a VM's specification changes

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 tartName for more details.

Note that you can only transition into stopped or suspended only once at the moment.

tartNamestring

Name of the Tart VM backing this VM resource.

tartName is specific to a worker, whereas name is cluster-wide.

tartName 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

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"
      }
    ]
  }
]

Changes