--- title: "Stage CVM changes" method: PATCH path: "/api/v1/cvms/{cvm_id}/draft" tags: ["CVMs", "cvms-draft"] --- # Stage CVM changes `PATCH /api/v1/cvms/{cvm_id}/draft` ## Request - Base URL: `https://cloud-api.phala.com` - URL: `https://cloud-api.phala.com/api/v1/cvms/{cvm_id}/draft` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Adds an update to the CVM's staged changes without restarting it. The body is the PATCH /cvms/{cvm_id} body. Applying runs the staged compose changes in order on the CVM's compose; other fields take the last staged value. Scripts this change sends are reviewed as the draft would leave them. The first staged change records the CVM's compose hash. ## Path parameters - `cvm_id` string, required ## 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 - `compose` ComposePatch: JSON Merge Patch of the CVM's app compose. A sent key sets the value, a sent null removes the key, an unsent key is unchanged. ``requirements`` merges per key. - `secure_time` boolean, nullable - `swap_size` string, nullable: Swap size, e.g. "2G" - `storage_discard` boolean, nullable - `snapshotter` 'overlayfs' | 'stargz', nullable: Only with the nerdctl-compose runner - `gateway_enabled` boolean, nullable: Route the CVM through dstack-gateway. Enabling needs a gateway for the CVM's node; disabling removes the instance from the gateway after the update. - `port_policy` PortPolicy: Per-instance port policy declared in app-compose. >= v0.5.9. ``restrict_mode=True`` with an empty ``ports`` list is a valid lockdown. Field order is alphabetical for compose_hash stability. - `ports` PortAttrs[] - `port` integer, required - `pp` boolean - `restrict_mode` boolean - `event_log_version` 1 | 2, nullable - `requirements` RequirementsPatch: ``requirements`` keys a PATCH may set; null removes the key. ``gpu_policy`` is not patchable: the stored value is kept as it is. - `ephemeral_data_disk` boolean, nullable: Format the data disk on every boot (OS 0.6.3 or newer). Turning it on requires confirm_data_wipe. - `health_check` boolean, nullable - `health_status_file` string, nullable - `launch_token_hash` string, nullable: Must be the hash of the app's launch token - `platforms` string[], nullable - `tdx_measure_acpi_tables` boolean, nullable - `bash_script` string, nullable: Script run by the bash runner - `kms_enabled` boolean, nullable - `key_provider` 'none' | 'kms' | 'local' | 'tpm', nullable - `key_provider_id` string, nullable - `local_key_provider_enabled` boolean, nullable - `manifest_version` union - integer - string - `no_instance_id` boolean, nullable - `runner` string, nullable - `storage_fs` 'ext4' | 'zfs', nullable - `verity_volumes` VerityVolume[], nullable - `source` string, required - `target` string, required - `verity_root` string, required - `tproxy_enabled` boolean, nullable - `features` string[], nullable - `init_scripts` string[], nullable: Platform init scripts this CVM runs, replacing the current set. Enabling docker_cleanup requires confirm_data_wipe. - `confirm_data_wipe` boolean: Confirms turning on docker_cleanup or requirements.ephemeral_data_disk, which erase data on every boot. - `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 GB - `instance_type` string, nullable: Instance type identifier (e.g. tdx.medium) - `image` string, nullable: OS image name or slug from available-os-images - `shutdown_timeout` integer, nullable: Timeout in seconds for graceful shutdown. null uses the platform default. - `allow_force_stop` boolean: When true, skips graceful shutdown and force stops the CVM immediately. ## Response `200` Successful Response - CvmDraftResponse: The CVM's staged changes and the compose hash applying them produces. - `base_compose_hash` string, nullable, required: The CVM's compose hash when the first change was staged - `current_compose_hash` string, nullable, required: The CVM's compose hash now; apply is rejected while it differs from the base - `preview_compose_hash` string, required: The compose hash the CVM runs after apply. For contract-owned KMS, register it on-chain before applying. - `patch` object, required: The one PATCH /cvms/{cvm_id} body the apply sends: the entries applied in order to the CVM's current compose - `entries` CvmDraftEntry[], required: The staged patches, oldest first - `user_id` string, hashid, required: A hashed identifier that maps to an internal database ID - `username` string, required - `staged_at` string, date-time, required - `patch` object, required ## Other responses - `409`: ERR-03-054: another request changed the staged changes at the same time - `422`: Validation Error ## Changes - **2026-11-07** `c71a8dc90391`: 1 info - endpoint added [Operation history](https://skmtc.dev/phala/apis/phala-cloud-api/changes/api/v1/cvms/:cvm_id/draft/patch.md) --- [API](https://skmtc.dev/phala/apis/phala-cloud-api.md) - [All operations](https://skmtc.dev/phala/apis/phala-cloud-api/llms.txt) - [OpenAPI document](https://skmtc.dev/phala/apis/phala-cloud-api/revisions/c71a8dc90391?raw)