Sign in

v33

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

Update instance properties

Update mutable properties of a running instance. Currently supports updating only the environment variables referenced by existing credential policies, enabling secret/key rotation without instance restart.

patch/instances/{id}

Path parameters

idstring required

Instance ID or name

Request body

envobject

Environment variables to update (merged with existing). Only keys referenced by the instance's existing credential source.env bindings are accepted. Use this to rotate real credential values without restarting the VM.

Example request

{
  "env": {
    "OUTBOUND_OPENAI_KEY": "new-rotated-key-456"
  },
  "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
    ]
  }
}

Response

Instance updated

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