Sign in

v41

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-055374134.9 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

platformstring

Target platform as os/arch[/variant] (e.g. "linux/amd64"), matching Docker --platform. Omit for the host platform. Not a fixed enum: the os/arch[/variant] grammar is validated server-side and invalid values return 400 invalid_platform. Only os "linux" with arch amd64 or arm64 is accepted today.

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",
  "platform": "linux/amd64",
  "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
    ]
  },
  "health_check": {
    "interval": "10s",
    "timeout": "2s",
    "start_period": "30s",
    "failure_threshold": 3,
    "success_threshold": 1,
    "http": {
      "port": 8080,
      "path": "/healthz",
      "scheme": "http",
      "expected_status": 200
    },
    "tcp": {
      "port": 5432
    },
    "exec": {
      "command": [
        "curl",
        "-f",
        "http://localhost:4318/"
      ],
      "working_dir": "/app"
    }
  },
  "restart_policy": {
    "policy": "on_failure",
    "backoff": "5s",
    "max_attempts": 10,
    "stable_after": "10m"
  },
  "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

platformstring

Resolved image platform as os/arch[/variant] (e.g. "linux/amd64"). amd64 images on an arm64 host run under Rosetta emulation.

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

phase_durations_msobject

Cumulative milliseconds the instance has spent in each lifecycle phase, including time accrued in the current phase up to the response time. Keys mirror instance states lowercased (running, standby, paused, stopped, created, initializing, shutdown). Consumers (e.g. billing) sum the phases they consider billable.

current_phasestring

The lifecycle phase the instance is currently in.

current_phase_sincestring date-time

When the instance entered current_phase.

Example response

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "name": "my-workload-1",
  "image": "docker.io/library/alpine:latest",
  "platform": "linux/amd64",
  "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
    ]
  },
  "health_check": {
    "interval": "10s",
    "timeout": "2s",
    "start_period": "30s",
    "failure_threshold": 3,
    "success_threshold": 1,
    "http": {
      "port": 8080,
      "path": "/healthz",
      "scheme": "http",
      "expected_status": 200
    },
    "tcp": {
      "port": 5432
    },
    "exec": {
      "command": [
        "curl",
        "-f",
        "http://localhost:4318/"
      ],
      "working_dir": "/app"
    }
  },
  "health_status": {
    "status": "healthy",
    "consecutive_successes": 4,
    "last_checked_at": "2026-05-16T01:00:00Z",
    "last_success_at": "2026-05-16T01:00:00Z",
    "last_failure_at": "2026-05-16T00:59:50Z",
    "last_error": "connection refused"
  },
  "restart_policy": {
    "policy": "on_failure",
    "backoff": "5s",
    "max_attempts": 10,
    "stable_after": "10m"
  },
  "restart_status": {
    "attempts": 3,
    "last_attempt_at": "2025-01-15T12:30:00Z",
    "next_attempt_at": "2025-01-15T12:30:05Z",
    "blocked_reason": "max_attempts_exceeded",
    "last_reason": "health_check_failed"
  },
  "phase_durations_ms": {
    "running": 60000,
    "standby": 300000
  },
  "current_phase": "running",
  "current_phase_since": "2026-05-11T14:00:00Z"
}