Sign in

v41

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-055374134.9 KB

Attach volume to instance

post/instances/{id}/volumes/{volumeId}

Path parameters

idstring required

Instance ID or name

volumeIdstring required

Volume ID or name

Request body

mount_pathstring required

Path where volume should be mounted

readonlyboolean

Mount as read-only

Example request

{
  "mount_path": "/mnt/data"
}

Response

Volume attached

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