|
| 1 | +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. |
| 2 | + |
| 3 | +import { APIResource } from '../core/resource'; |
| 4 | +import { APIPromise } from '../core/api-promise'; |
| 5 | +import { RequestOptions } from '../internal/request-options'; |
| 6 | + |
| 7 | +export class Capabilities extends APIResource { |
| 8 | + /** |
| 9 | + * Returns machine-readable host capabilities: server and API version, host |
| 10 | + * OS/architecture, every runtime available on this host with its per-runtime |
| 11 | + * feature IDs, the configured default runtime and whether it is available, guest |
| 12 | + * networking model and host gateway, supported image platforms, and stable |
| 13 | + * server-level feature IDs. |
| 14 | + * |
| 15 | + * Runtime-derived values reflect the actual host (for example, snapshot and |
| 16 | + * standby support on macOS is gated on the host OS version), so clients can gate |
| 17 | + * behavior on capabilities without hard-coding hypervisor knowledge. |
| 18 | + */ |
| 19 | + get(options?: RequestOptions): APIPromise<Capabilities> { |
| 20 | + return this._client.get('/capabilities', options); |
| 21 | + } |
| 22 | +} |
| 23 | + |
| 24 | +export interface Capabilities { |
| 25 | + default_runtime: CapabilitiesDefaultRuntime; |
| 26 | + |
| 27 | + /** |
| 28 | + * Stable server-level feature IDs: API surfaces this server exposes regardless of |
| 29 | + * which runtime backs an instance. Always present: "instances", "images", |
| 30 | + * "builds", "volumes", "ingress", "exec", "logs". Host-conditional: "devices" |
| 31 | + * (device passthrough management, Linux hosts only) and "rosetta-emulation" (Apple |
| 32 | + * Silicon macOS hosts with Rosetta currently installed, per the same availability |
| 33 | + * probe launches enforce). Per-runtime features are reported under each runtimes[] |
| 34 | + * entry. |
| 35 | + */ |
| 36 | + features: Array<string>; |
| 37 | + |
| 38 | + host: CapabilitiesHost; |
| 39 | + |
| 40 | + images: CapabilitiesImages; |
| 41 | + |
| 42 | + network: CapabilitiesNetwork; |
| 43 | + |
| 44 | + /** |
| 45 | + * Every runtime this server build supports on this host platform, each with its |
| 46 | + * own availability flag and feature IDs. Hosts commonly support several runtimes |
| 47 | + * at once (for example cloud-hypervisor, firecracker, qemu, and qemu-microvm on |
| 48 | + * linux/amd64). A listed runtime is only launchable when its "available" flag is |
| 49 | + * true. Entries are sorted by name. |
| 50 | + */ |
| 51 | + runtimes: Array<CapabilitiesRuntime>; |
| 52 | + |
| 53 | + server: CapabilitiesServer; |
| 54 | +} |
| 55 | + |
| 56 | +export interface CapabilitiesDefaultRuntime { |
| 57 | + /** |
| 58 | + * Whether the default runtime can launch on this host: it appears in runtimes and |
| 59 | + * its launch prerequisites are met (matches that entry's "available"). When false, |
| 60 | + * launches that rely on the default will fail until the server is reconfigured |
| 61 | + * with an available runtime or the missing prerequisite (for example the QEMU |
| 62 | + * system binary) is installed. |
| 63 | + */ |
| 64 | + available: boolean; |
| 65 | + |
| 66 | + /** |
| 67 | + * Runtime used for launches that do not name one |
| 68 | + */ |
| 69 | + name: string; |
| 70 | +} |
| 71 | + |
| 72 | +export interface CapabilitiesHost { |
| 73 | + /** |
| 74 | + * Host CPU architecture |
| 75 | + */ |
| 76 | + arch: string; |
| 77 | + |
| 78 | + /** |
| 79 | + * Host operating system |
| 80 | + */ |
| 81 | + os: string; |
| 82 | +} |
| 83 | + |
| 84 | +export interface CapabilitiesImages { |
| 85 | + /** |
| 86 | + * Image platform selected when a create request omits one |
| 87 | + */ |
| 88 | + default_platform: string; |
| 89 | + |
| 90 | + /** |
| 91 | + * Image platforms (os/arch) this host can run. On Apple Silicon macOS this |
| 92 | + * includes linux/amd64 only when Rosetta is currently installed — probed via the |
| 93 | + * same Virtualization.framework availability check launches enforce — so a listed |
| 94 | + * platform is launchable right now. Install Rosetta (softwareupdate |
| 95 | + * --install-rosetta) to enable it. |
| 96 | + */ |
| 97 | + platforms: Array<string>; |
| 98 | +} |
| 99 | + |
| 100 | +export interface CapabilitiesNetwork { |
| 101 | + /** |
| 102 | + * Whether direct VM-to-VM traffic is permitted on the default network |
| 103 | + */ |
| 104 | + guest_to_guest: boolean; |
| 105 | + |
| 106 | + /** |
| 107 | + * Guest networking model. "bridge" is a Linux bridge with per-VM TAP devices; |
| 108 | + * "nat" is hypervisor-provided NAT (macOS). |
| 109 | + */ |
| 110 | + model: 'bridge' | 'nat'; |
| 111 | + |
| 112 | + /** |
| 113 | + * Guest-visible host gateway IP. Guests reach host services (including host |
| 114 | + * ingress) through this address. Omitted when no default network has been resolved |
| 115 | + * on this host yet. |
| 116 | + */ |
| 117 | + gateway?: string; |
| 118 | + |
| 119 | + /** |
| 120 | + * Guest subnet CIDR |
| 121 | + */ |
| 122 | + subnet?: string; |
| 123 | +} |
| 124 | + |
| 125 | +export interface CapabilitiesRuntime { |
| 126 | + /** |
| 127 | + * Whether this runtime's launch prerequisites are currently met on this host. |
| 128 | + * Listed runtimes are supported by this server build on this platform; |
| 129 | + * available=false means a host prerequisite is missing (for example qemu requires |
| 130 | + * a runnable system-installed QEMU binary and the host vhost-vsock device) and |
| 131 | + * launches naming this runtime will fail until it is installed. |
| 132 | + */ |
| 133 | + available: boolean; |
| 134 | + |
| 135 | + /** |
| 136 | + * Stable feature IDs supported by this runtime on this host: "snapshots" |
| 137 | + * (snapshot/restore), "standby" (pause + memory snapshot, with later restore), |
| 138 | + * "fork" (clone an instance from a stopped source; forking a standby or running |
| 139 | + * source restores/creates snapshots and additionally requires "standby"), "pause" |
| 140 | + * (pause/resume), "hotplug-memory" (live memory resize), "balloon-control" |
| 141 | + * (runtime balloon target changes), "vsock" (guest vsock communication), |
| 142 | + * "gpu-passthrough" (GPU/PCI device passthrough), "disk-io-limit" (disk I/O rate |
| 143 | + * limiting), "disk-resize" (live disk resize). Values are host- and |
| 144 | + * configuration-truthful: vz omits snapshots and standby on macOS 13, which lacks |
| 145 | + * Virtualization.framework VM save/restore, while still advertising fork |
| 146 | + * (stopped-source clones need no save/restore there), and cloud-hypervisor reports |
| 147 | + * "disk-resize" only when the configured default version supports it. |
| 148 | + */ |
| 149 | + features: Array<string>; |
| 150 | + |
| 151 | + /** |
| 152 | + * Runtime identifier |
| 153 | + */ |
| 154 | + name: string; |
| 155 | +} |
| 156 | + |
| 157 | +export interface CapabilitiesServer { |
| 158 | + /** |
| 159 | + * API contract version (matches the OpenAPI document info version) |
| 160 | + */ |
| 161 | + api_version: string; |
| 162 | + |
| 163 | + /** |
| 164 | + * Server build version (short git revision, with "-dirty" suffix for uncommitted |
| 165 | + * builds, or "unknown") |
| 166 | + */ |
| 167 | + version: string; |
| 168 | +} |
| 169 | + |
| 170 | +export declare namespace Capabilities { |
| 171 | + export { |
| 172 | + type Capabilities as Capabilities, |
| 173 | + type CapabilitiesDefaultRuntime as CapabilitiesDefaultRuntime, |
| 174 | + type CapabilitiesHost as CapabilitiesHost, |
| 175 | + type CapabilitiesImages as CapabilitiesImages, |
| 176 | + type CapabilitiesNetwork as CapabilitiesNetwork, |
| 177 | + type CapabilitiesRuntime as CapabilitiesRuntime, |
| 178 | + type CapabilitiesServer as CapabilitiesServer, |
| 179 | + }; |
| 180 | +} |
0 commit comments