Update CVM

Unified PATCH endpoint for CVM updates. Only fields present in the request body are applied. Handles resource resize, compose configuration, visibility, environment, and OS image updates. For contract-owned KMS, compose-hash-affecting changes require two-phase flow with on-chain hash registration.

PATCH /api/v1/cvms/{cvm_id}

Update CVM

cURL

curl --request PATCH \
  --url https://cloud-api.phala.com/api/v1/cvms/{cvm_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "docker_compose_file": "<string>",
  "pre_launch_script": "<string>",
  "allowed_envs": [
    "<string>"
  ],
  "public_logs": true,
  "public_sysinfo": true,
  "public_tcbinfo": true,
  "compose": {
    "secure_time": true,
    "swap_size": "<string>",
    "storage_discard": true,
    "gateway_enabled": true,
    "port_policy": {
      "ports": [
        {
          "port": 123,
          "pp": false
        }
      ],
      "restrict_mode": false
    },
    "requirements": {
      "ephemeral_data_disk": true,
      "health_check": true,
      "health_status_file": "<string>",
      "launch_token_hash": "<string>",
      "platforms": [
        "<string>"
      ],
      "tdx_measure_acpi_tables": true
    },
    "bash_script": "<string>",
    "kms_enabled": true,
    "key_provider_id": "<string>",
    "local_key_provider_enabled": true,
    "manifest_version": 123,
    "no_instance_id": true,
    "runner": "<string>",
    "verity_volumes": [
      {
        "source": "<string>",
        "target": "<string>",
        "verity_root": "<string>"
      }
    ],
    "tproxy_enabled": true,
    "features": [
      "<string>"
    ]
  },
  "init_scripts": [],
  "confirm_data_wipe": false,
  "encrypted_env": "<string>",
  "user_config": "<string>",
  "gpus": {
    "gpus": [
      {
        "slot": "<string>",
        "product_id": "<string>"
      }
    ],
    "attach_mode": "listed"
  },
  "vcpu": 123,
  "memory": 123,
  "disk_size": 123,
  "instance_type": "<string>",
  "image": "<string>",
  "shutdown_timeout": 605,
  "allow_force_stop": false
}
'

422

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Headers

X-Compose-Hash · string | null

Compose hash from Phase 1 response (Phase 2 only)

X-Transaction-Hash · string | null

Transaction hash proving on-chain registration (Phase 2 only)

X-Prepare-Only · string | null

When 'true', generate a commit token for multisig workflows instead of expecting immediate on-chain registration

Path Parameters

cvm_id · string · required

Body

application/json

PATCH request body — all fields optional, only set fields are applied.

docker_compose_file · string | null

Docker Compose YAML content

pre_launch_script · string | null

Shell script executed before containers start

allowed_envs · string[] | null

Allowed environment variable names (env_keys)

public_logs · boolean | null

Expose container logs publicly

public_sysinfo · boolean | null

Expose system info publicly

public_tcbinfo · boolean | null

Expose TCB attestation info publicly

compose · ComposePatch · object | null

JSON Merge Patch of the app compose

Show child attributes

init_scripts · enum<string>[] | null

Platform init scripts this CVM runs, replacing the current set. Enabling docker_cleanup requires confirm_data_wipe.

Available options: docker_cleanup, env_merge

confirm_data_wipe · boolean · default: false

Confirms turning on docker_cleanup or requirements.ephemeral_data_disk, which erase data on every boot.

encrypted_env · string | null

Encrypted environment variables as hex string

user_config · string | null

User configuration string

gpus · GpuConfig · object | null

GPU configuration

Show child attributes

vcpu · integer | null

Number of vCPUs

memory · integer | null

Memory in MB

disk_size · integer | null

Disk size in GB

instance_type · string | null

Instance type identifier (e.g. tdx.medium)

image · string | null

OS image name or slug from available-os-images

shutdown_timeout · integer | null

Timeout in seconds for graceful shutdown. null uses the platform default.

Required range: 10 <= x <= 1200

allow_force_stop · boolean · default: false

When true, skips graceful shutdown and force stops the CVM immediately.

Response

202

application/json

Update initiated, track via correlation_id