Sign in

v33

latestOpenAPI 3.1.0raw.githubusercontent.com2026-04-175267122.5 KB

Create and start instance

post/instances

Request body

namestring required

Human-readable name (lowercase letters, digits, and dashes only; cannot start or end with a dash)

imagestring required

OCI image reference

sizestring

Base memory size (human-readable format like "1GB", "512MB", "2G")

hotplug_sizestring

Additional memory for hotplug (human-readable format like "3GB", "1G"). Omit to disable hotplug memory.

overlay_sizestring

Writable overlay disk size (human-readable format like "10GB", "50G")

disk_io_bpsstring

Disk I/O rate limit (e.g., "100MB/s", "500MB/s"). Defaults to proportional share based on CPU allocation if configured.

vcpusinteger

Number of virtual CPUs

envobject

Environment variables

credentialsobject

Host-managed credential brokering policies keyed by guest-visible env var name. Those guest env vars receive mock placeholder values, while the real values remain host-scoped in the request env map and are only materialized on the mediated egress path according to each credential's source and inject rules.

tagsTags

User-defined key-value tags.

devicesstring[]

Device IDs or names to attach for GPU/PCI passthrough

hypervisor'cloud-hypervisor' | 'firecracker' | 'qemu' | 'vz'

Hypervisor to use for this instance. Defaults to server configuration.

skip_kernel_headersboolean

Skip kernel headers installation during boot for faster startup. When true, DKMS (Dynamic Kernel Module Support) will not work, preventing compilation of out-of-tree kernel modules (e.g., NVIDIA vGPU drivers). Recommended for workloads that don't need kernel module compilation.

skip_guest_agentboolean

Skip guest-agent installation during boot. When true, the exec and stat APIs will not work for this instance. The instance will still run, but remote command execution will be unavailable.

entrypointstring[]

Override image entrypoint (like docker run --entrypoint). Omit to use image default.

cmdstring[]

Override image CMD (like docker run <image> <command>). Omit to use image default.

Example request

{
  "name": "my-workload-1",
  "image": "docker.io/library/alpine:latest",
  "size": "2GB",
  "hotplug_size": "2GB",
  "overlay_size": "20GB",
  "disk_io_bps": "100MB/s",
  "vcpus": 2,
  "env": {
    "PORT": "3000",
    "NODE_ENV": "production"
  },
  "credentials": {
    "OUTBOUND_OPENAI_KEY": {
      "source": {
        "env": "OUTBOUND_OPENAI_KEY"
      },
      "inject": [
        {
          "hosts": [
            "api.openai.com",
            "*.openai.com"
          ],
          "as": {
            "header": "Authorization",
            "format": "Bearer ${value}"
          }
        }
      ]
    }
  },
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "network": {
    "enabled": true,
    "bandwidth_download": "1Gbps",
    "bandwidth_upload": "1Gbps",
    "egress": {
      "enabled": true,
      "enforcement": {
        "mode": "all"
      }
    }
  },
  "devices": [
    "l4-gpu"
  ],
  "gpu": {
    "profile": "L40S-1Q"
  },
  "volumes": [
    {
      "volume_id": "vol-abc123",
      "mount_path": "/mnt/data",
      "overlay_size": "1GB"
    }
  ],
  "hypervisor": "cloud-hypervisor",
  "snapshot_policy": {
    "compression": {
      "enabled": true,
      "algorithm": "zstd",
      "level": 1
    },
    "standby_compression_delay": "2m"
  },
  "auto_standby": {
    "enabled": true,
    "idle_timeout": "5m",
    "ignore_source_cidrs": [
      "10.0.0.0/8",
      "192.168.0.0/16"
    ],
    "ignore_destination_ports": [
      22,
      9000
    ]
  },
  "skip_kernel_headers": true,
  "entrypoint": [
    "/bin/sh",
    "-c"
  ],
  "cmd": [
    "echo",
    "hello"
  ]
}

Response

Instance created

idstring required

Auto-generated unique identifier (CUID2 format)

namestring required

Human-readable name

imagestring required

OCI image reference

state'Created' | 'Initializing' | 'Running' | 'Paused' | 'Shutdown' | 'Stopped' | 'Standby' | 'Unknown' required

Instance state:

  • Created: VMM created but not started (Cloud Hypervisor native)
  • Initializing: VM is running while guest init is still in progress
  • Running: Guest program has started and instance is ready
  • Paused: VM is paused (Cloud Hypervisor native)
  • Shutdown: VM shut down but VMM exists (Cloud Hypervisor native)
  • Stopped: No VMM running, no snapshot exists
  • Standby: No VMM running, snapshot exists (can be restored)
  • Unknown: Failed to determine state (see state_error for details)
state_errorstring nullable

Error message if state couldn't be determined (only set when state is Unknown)

sizestring

Base memory size (human-readable)

hotplug_sizestring

Hotplug memory size (human-readable)

overlay_sizestring

Writable overlay disk size (human-readable)

vcpusinteger

Number of virtual CPUs

disk_io_bpsstring

Disk I/O rate limit (human-readable, e.g., "100MB/s")

envobject

Environment variables

tagsTags

User-defined key-value tags.

created_atstring date-time required

Creation timestamp (RFC3339)

started_atstring date-time nullable

Start timestamp (RFC3339)

stopped_atstring date-time nullable

Stop timestamp (RFC3339)

exit_codeinteger nullable

App exit code (null if VM hasn't exited)

exit_messagestring

Human-readable description of exit (e.g., "command not found", "killed by signal 9 (SIGKILL) - OOM")

has_snapshotboolean

Whether a snapshot exists for this instance

hypervisor'cloud-hypervisor' | 'firecracker' | 'qemu' | 'vz'

Hypervisor running this instance

Example response

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "name": "my-workload-1",
  "image": "docker.io/library/alpine:latest",
  "state_error": "failed to query VMM: connection refused",
  "size": "2GB",
  "hotplug_size": "2GB",
  "overlay_size": "10GB",
  "vcpus": 2,
  "disk_io_bps": "100MB/s",
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "network": {
    "enabled": true,
    "name": "default",
    "ip": "192.168.100.10",
    "mac": "02:00:00:ab:cd:ef",
    "bandwidth_download": "125MB/s",
    "bandwidth_upload": "125MB/s"
  },
  "volumes": [
    {
      "volume_id": "vol-abc123",
      "mount_path": "/mnt/data",
      "overlay_size": "1GB"
    }
  ],
  "gpu": {
    "profile": "L40S-1Q",
    "mdev_uuid": "aa618089-8b16-4d01-a136-25a0f3c73123"
  },
  "created_at": "2025-01-15T10:30:00Z",
  "started_at": "2025-01-15T10:30:05Z",
  "stopped_at": "2025-01-15T12:30:00Z",
  "exit_code": 137,
  "exit_message": "killed by signal 9 (SIGKILL)",
  "hypervisor": "cloud-hypervisor",
  "snapshot_policy": {
    "compression": {
      "enabled": true,
      "algorithm": "zstd",
      "level": 1
    },
    "standby_compression_delay": "2m"
  },
  "auto_standby": {
    "enabled": true,
    "idle_timeout": "5m",
    "ignore_source_cidrs": [
      "10.0.0.0/8",
      "192.168.0.0/16"
    ],
    "ignore_destination_ports": [
      22,
      9000
    ]
  }
}