From 6d23548d817a8a3a67e320692aa04c038283783b Mon Sep 17 00:00:00 2001
From: Nikolay Edigaryev <edigaryev@gmail.com>
Date: Mon, 6 Oct 2025 16:22:57 +0200
Subject: [PATCH] API spec: document VM object more thoroughly (#354)

* API spec: document VM object more thoroughly

* Describe hostDirs and signify that it's worker-local in docs
---
 api/openapi.yaml              | 91 ++++++++++++++++++++++++++++++++---
 internal/command/create/vm.go |  4 +-
 2 files changed, 85 insertions(+), 10 deletions(-)

diff --git a/api/openapi.yaml b/api/openapi.yaml
index f7eb585..b2f6c9d 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -446,19 +446,90 @@ components:
         name:
           type: string
           description: VM name
-        resources:
-          type: object
-          description: |
-            Dictionary that maps the resource name to the
-            amount of this resource required on the worker
-            for this VM to be scheduled
-          additionalProperties:
-            type: integer
+          example: macos-tahoe-base
+          readOnly: true
+        image:
+          type: string
+          description: VM image for this VM
+          example: ghcr.io/cirruslabs/macos-tahoe-base:latest
+        imagePullPolicy:
+          type: string
+          description: VM image pull policy
+          default: IfNotPresent
+          enum: [IfNotPresent, Always]
+        cpu:
+          type: number
+          description: Number of CPUs assigned to this VM
+          default: 4
+        memory:
+          type: number
+          description: Amount of RAM in megabytes assigned to this VM
+          default: 8192
+        diskSize:
+          type: number
+          description: Disk size for this VM
+          example: 100
+        net-softnet:
+          type: boolean
+          description: Whether to use Softnet network isolation
+          default: false
+        net-bridged:
+          type: string
+          description: Whether to use bridged network mode
+          example: en0
+        headless:
+          type: boolean
+          description: Whether to run without graphics
+          default: false
         nested:
           type: boolean
           description: Enable nested virtualization
+          default: false
+        status:
+          type: string
+          description: VM status
+          enum: [pending, running, failed]
+          readOnly: true
+        status_message:
+          type: string
+          description: VM status message
+          readOnly: true
+        worker:
+          type: string
+          description: Worker on which the VM was assigned to
+          readOnly: true
+        username:
+          type: string
+          description: SSH username to use when connecting to a VM
+          default: admin
+        password:
+          type: string
+          description: SSH password to use when connecting to a VM
+          default: admin
+        restart_policy:
+          type: string
+          description: |
+            VM restart policy: specify "Never" to never restart or "OnFailure" to only restart when the VM fails
+          default: Never
+          enum: [Never, OnFailure]
+        resources:
+          type: object
+          description: Resources required by this VM on the worker
+          additionalProperties:
+            type: integer
+          example:
+            org.cirruslabs.logical-cores: 4
+            org.cirruslabs.memory-mib: 8192
+        labels:
+          type: object
+          description: Labels required by this VM on the worker
+          additionalProperties:
+            type: string
+          example:
+            model: macstudio
         hostDirs:
           type: array
+          description: Directories on the Orchard Worker host to mount to a VM
           items:
             type: object
             properties:
@@ -468,6 +539,10 @@ components:
                 type: string
               ro:
                 type: boolean
+          example:
+            - path: /path/on/host/to/sources
+              ro: true
+            - path: /path/on/host/to/builds
     Events:
       title: Events
       type: object
diff --git a/internal/command/create/vm.go b/internal/command/create/vm.go
index 569ed7a..be8ec3f 100644
--- a/internal/command/create/vm.go
+++ b/internal/command/create/vm.go
@@ -67,8 +67,8 @@ func newCreateVMCommand() *cobra.Command {
 		"startup script (e.g. --startup-script=\"sync\") or a path to a script file prefixed with \"@\" "+
 			"(e.g. \"--startup-script=@script.sh\")")
 	command.Flags().StringSliceVar(&hostDirsRaw, "host-dirs", []string{},
-		"host directories to mount to the VM, can be specified multiple times and/or be comma-separated "+
-			"(see \"tart run\"'s --dir argument for syntax)")
+		"directories on the Orchard Worker host to mount to a VM, can be specified multiple times "+
+			"and/or be comma-separated (see \"tart run\"'s --dir argument for syntax)")
 	command.Flags().StringVar(&imagePullPolicy, "image-pull-policy", string(v1.ImagePullPolicyIfNotPresent),
 		fmt.Sprintf("image pull policy for this VM, by default the image is only pulled if it doesn't "+
 			"exist in the cache (%q), specify %q to always try to pull the image",