---
title: "Update CVM"
method: PATCH
path: "/api/v1/cvms/{cvm_id}"
tags: ["CVMs"]
---

# Update CVM

`PATCH /api/v1/cvms/{cvm_id}`

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.

## Path parameters

- `cvm_id` string, required

## Headers

- `X-Compose-Hash` string, nullable — Compose hash from Phase 1 response (Phase 2 only)
- `X-Transaction-Hash` string, nullable — Transaction hash proving on-chain registration (Phase 2 only)
- `X-Prepare-Only` string, nullable — When 'true', generate a commit token for multisig workflows instead of expecting immediate on-chain registration

## Request body

- UpdateCvmRequest — PATCH request body — all fields optional, only set fields are applied.
  - `docker_compose_file` string, nullable — Docker Compose YAML content
  - `pre_launch_script` string, nullable — Shell script executed before containers start
  - `allowed_envs` string[], nullable — Allowed environment variable names (env_keys)
  - `public_logs` boolean, nullable — Expose container logs publicly
  - `public_sysinfo` boolean, nullable — Expose system info publicly
  - `public_tcbinfo` boolean, nullable — Expose TCB attestation info publicly
  - `encrypted_env` string, nullable — Encrypted environment variables as hex string
  - `user_config` string, nullable — User configuration string
  - `gpus` GpuConfig
    - `gpus` GpuSpec[], required
      - `slot` string, required
      - `product_id` string, nullable
    - `attach_mode` union
      - 'listed' | 'all'
      - string
  - `vcpu` integer, nullable — Number of vCPUs
  - `memory` integer, nullable — Memory in MB
  - `disk_size` integer, nullable — Disk size in MB
  - `image` string, nullable — OS image name or slug from available-os-images
  - `shutdown_timeout` integer, nullable — Timeout in seconds for graceful shutdown. null means no timeout.
  - `allow_force_stop` boolean — When true, falls back to hard stop if graceful shutdown times out. Use for zombie CVMs that are unresponsive to shutdown signals.

## Response `202`

Update initiated, track via correlation_id

- unknown

## Other responses

- `400` — Invalid request or terms violation
- `401` — Authentication required
- `403` — CVM not in workspace or GPU rental managed
- `404` — CVM not found
- `409` — Another operation in progress
- `422` — Validation Error
- `465` — Compose hash registration required (Phase 1)
- `466` — Compose hash invalid or expired
- `467` — Transaction verification failed
- `468` — Compose hash not allowed on-chain

---

[API](https://skmtc.net/phala/apis/phala-cloud-api.md) · [All operations](https://skmtc.net/phala/apis/phala-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/phala/phala-cloud-api/versions/83c6ae62e860/schema)