Phala Cloud Documentation — Private AI on TEE

Configuration methods let you modify a CVM after it has been provisioned. You can update the Docker Compose file, environment variables, resource allocation, visibility settings, and OS image independently.

Some configuration updates restart a running CVM. A change applied through PATCH /cvms/{cvmId} or the compose, environment and OS image endpoints stops the CVM, applies the change and starts it again. A stopped CVM stays stopped and runs the new configuration at its next start. A compose change that matches what the CVM already runs does not restart it: the API answers no_change and does nothing. Annotations (update_cvm_annotations) never restart the CVM, and SSH key changes without apply_now stay pending until the next power-on.

patch_cvm sends any set of changes in one request to PATCH /cvms/{cvmId}. update_cvm_resources and update_cvm_visibility send a subset of fields to the same endpoint. The other update_* methods call their own endpoints. See Update CVM Configuration for what each field does and which settings cannot change after create.

update_docker_compose

PATCH /cvms/{cvmId}/docker-compose Updates the Docker Compose configuration for a CVM. If the CVM has on-chain hash verification enabled, you need to pass compose_hash and transaction_hash. Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier
`docker_compose_file`	`str`	Yes	Docker Compose YAML content
`compose_hash`	`str`	No	On-chain compose hash (if required)
`transaction_hash`	`str`	No	On-chain transaction hash (if required)

Returns: A CloudModel with the API response when the update is accepted. For an on-chain KMS CVM whose new compose hash is not registered yet, the API answers HTTP 465 and the method returns a CloudModel with status="precondition_required" and compose_hash, app_id, device_id and kms_info, instead of raising. The sync and async clients behave the same. Example:

result = client.update_docker_compose({
    "id": "my-app",
    "docker_compose_file": """
services:
  app:
    image: nginx:latest
    ports:
      - "80:80"
""",
})

result = await client.update_docker_compose({
    "id": "my-app",
    "docker_compose_file": """
services:
  app:
    image: nginx:latest
    ports:
      - "80:80"
""",
})

update_cvm_envs

PATCH /cvms/{cvmId}/envs Updates encrypted environment variables for a CVM. Environment variables must be encrypted using the KMS public key before being sent. Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier
`encrypted_env`	`str`	Yes	Encrypted environment variable payload
`env_keys`	`list[str]`	No	List of environment variable keys
`compose_hash`	`str`	No	On-chain compose hash (if required)
`transaction_hash`	`str`	No	On-chain transaction hash (if required)

Returns: InProgressResponse on success, or precondition response if on-chain verification is needed. Example:

from phala_cloud import encrypt_env_vars

# Encrypt env vars using KMS public key
pubkey_resp = client.get_app_env_encrypt_pub_key({
    "kms": "phala",
    "app_id": "my-app-id",
})

encrypted = encrypt_env_vars(
    envs=[{"key": "SECRET", "value": "my-secret"}],
    public_key_hex=pubkey_resp.public_key,
)

client.update_cvm_envs({
    "id": "my-app",
    "encrypted_env": encrypted,
    "env_keys": ["SECRET"],
})

update_pre_launch_script

PATCH /cvms/{cvmId}/pre-launch-script Updates the pre-launch script that runs before Docker containers start. Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier
`pre_launch_script`	`str`	Yes	Script content
`compose_hash`	`str`	No	On-chain compose hash (if required)
`transaction_hash`	`str`	No	On-chain transaction hash (if required)

Returns: InProgressResponse on success.

get_cvm_docker_compose

GET /cvms/{cvmId}/docker-compose.yml Retrieves the current Docker Compose YAML for a CVM as a raw string. Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier

Returns: str — Docker Compose YAML content. Example:

yaml_content = client.get_cvm_docker_compose({"id": "my-app"})
print(yaml_content)

get_cvm_compose_file

GET /cvms/{cvmId}/compose_file Retrieves the compose file with metadata (including hash info and structure). Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier

Returns: Compose file response with metadata.

commit_cvm_update

POST /cvms/{cvmId}/commit-update Commit a prepared update using its token. compose_hash and transaction_hash are optional request fields. The returned CommitCvmUpdateResult contains correlation_id and status.

result = client.commit_cvm_update({
    "cvm_id": "my-app",
    "token": token,
})
print(result.correlation_id, result.status)

The async client supports await client.commit_cvm_update(...). A safe_commit_cvm_update variant is also available.

update_cvm_resources

PATCH /cvms/{cvmId} Changes the resource allocation (CPU, memory, disk, instance type) for a CVM. Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier
`vcpu`	`float`	No	Number of vCPUs
`memory`	`float`	No	Memory in MB
`disk_size`	`float`	No	Disk size in GB. A disk cannot shrink.
`instance_type`	`str`	No	Instance type name
`allow_restart`	`bool`	No	Deprecated and not sent. The CVM restarts whenever a resize needs it.

Returns: The API response, {"message", "correlation_id", "status"}. Example:

client.update_cvm_resources({
    "id": "my-app",
    "vcpu": 4,
    "memory": 4096,
    "instance_type": "tdx.medium",
})

await client.update_cvm_resources({
    "id": "my-app",
    "vcpu": 4,
    "memory": 4096,
    "instance_type": "tdx.medium",
})

update_cvm_visibility

PATCH /cvms/{cvmId} Controls which CVM information is publicly accessible. Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier
`public_sysinfo`	`bool`	Yes	Whether system info is public
`public_logs`	`bool`	Yes	Whether logs are public
`public_tcbinfo`	`bool`	No	Whether TCB info is public

Returns: {"message", "correlation_id", "status"}. status is "in_progress", or "no_change" with an empty correlation_id when the settings already match. These settings are part of the compose hash. For a CVM on Onchain KMS, the request fails with HTTP 465 until the new hash is registered on-chain. Use patch_cvm, which returns the hash to register. The Trust Center listing is not a visibility setting; it has its own endpoint, PATCH /cvms/{cvmId}/listed. Example:

client.update_cvm_visibility({
    "id": "my-app",
    "public_sysinfo": True,
    "public_logs": False,
})

update_os_image

PATCH /cvms/{cvmId}/os-image Changes the OS image for a CVM. Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier
`os_image_name`	`str`	Yes	Name of the target OS image

Returns: None Example:

client.update_os_image({
    "id": "my-app",
    "os_image_name": "ubuntu-24.04-tee",
})

get_available_os_images

GET /cvms/{cvmId}/available-os-images Lists OS images available for a specific CVM. The available images depend on the CVM’s node and configuration. Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier

Returns: List of available OS image objects.

patch_cvm

PATCH /cvms/{cvmId} A batch update method that can modify multiple CVM fields in a single request. This is useful when you need to change several settings atomically. compose is a JSON Merge Patch of the app compose, typed as ComposePatch. Only the keys you set are sent, and a key set to None is sent as null, which removes it. See How does the compose patch work? for the keys. To change a bash runner’s script, set ComposePatch(bash_script=...). Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier
`docker_compose_file`	`str`	No	Docker Compose YAML
`pre_launch_script`	`str`	No	Pre-launch script content
`allowed_envs`	`list[str]`	No	Allowed environment variable keys
`public_logs`	`bool`	No	Whether logs are public
`public_sysinfo`	`bool`	No	Whether system info is public
`public_tcbinfo`	`bool`	No	Whether TCB info is public
`compose`	`ComposePatch`	No	Other compose settings as a merge patch, for example `{"swap_size": "2G", "requirements": {"health_check": True}}`
`init_scripts`	`list[str]`	No	Platform init scripts the CVM runs (`"docker_cleanup"`, `"env_merge"`), replacing the current set. `[]` removes them all.
`confirm_data_wipe`	`bool`	No	Confirms turning on `docker_cleanup` or `requirements.ephemeral_data_disk`, which erase data on every boot
`encrypted_env`	`str`	No	Encrypted environment variables
`user_config`	`str`	No	User configuration string
`gpus`	`dict`	No	GPU assignment: `{"gpus": [{"slot": ..., "product_id": ...}], "attach_mode": ...}`. `attach_mode: "all"` attaches every GPU on the node. Other shapes fail validation.
`vcpu`	`int`	No	Number of vCPUs
`memory`	`int`	No	Memory in MB
`disk_size`	`int`	No	Disk size in GB
`instance_type`	`str`	No	Instance type, for example `tdx.medium`
`image`	`str`	No	OS image name
`shutdown_timeout`	`int`	No	Seconds to wait for a clean shutdown (10 to 1200)
`allow_force_stop`	`bool`	No	Skip the clean shutdown and stop the CVM at once
`prepare_only`	`bool`	No	Sent as the `X-Prepare-Only: true` header, not in the body. Also accepted as `prepareOnly`.

Returns: A dict with requires_on_chain_hash (bool). When it is False, the dict has correlation_id, which is empty when the API answers no_change. When it is True, it has compose_hash, app_id, device_id and kms_info, plus commit_token, commit_url, api_commit_url and onchain_status for a prepare_only call.

On Onchain KMS, a change to the compose returns requires_on_chain_hash: True only when the new compose hash is not on the app contract yet (HTTP 465). If the hash is already allowed, or the patch does not change the compose (for example a resize), the update starts at once and you get correlation_id. After a 465, register compose_hash on-chain, then call confirm_cvm_patch with the compose hash and transaction hash. With prepare_only, the 465 result also carries commit_token, and anyone holding it can finish the update. prepare_only is not a dry run: an update that needs no registration starts right away. See Multisig and Governance.

get_cvm_init_scripts

GET /cvms/{cvmId}/init-scripts Lists the platform init scripts, in run order, and for each one whether the CVM runs it (selected), whether you can pick it for this CVM (selectable) and, if not, why (reason). Change the selection with patch_cvm’s init_scripts. See Init scripts. Parameters: id (CVM identifier). Returns: CvmInitScriptsResponse with items.

get_cvm_annotations / update_cvm_annotations

GET /cvms/{cvmId}/annotations / PUT /cvms/{cvmId}/annotations Reads or replaces the CVM’s annotations: key/value settings for tools on the host. They are not measured and attestation does not cover them. update_cvm_annotations replaces every annotation, and {} clears them. It does not restart the CVM. Annotations sit behind a feature flag; without it, both calls fail with ERR-03-049. See Annotations. Parameters: id (CVM identifier), plus annotations (dict[str, str]) for update_cvm_annotations. Returns: CvmAnnotationsResponse with annotations, the annotations the node now stores.

client.update_cvm_annotations({"id": "my-app", "annotations": {"memory_tier": "fast"}})

Compose File Update Flow

For updates that require on-chain hash verification, the SDK provides a two-step flow similar to CVM provisioning:

provision_cvm_compose_file_update

POST /cvms/{cvmId}/compose_file/provision Provisions a compose file update and returns the new compose hash.

commit_cvm_compose_file_update

PATCH /cvms/{cvmId}/compose_file Commits the compose file update with the verified hash.

# Step 1: Provision the update
provision = client.provision_cvm_compose_file_update({
    "id": "my-app",
    "app_compose": {
        "docker_compose_file": "services:\n  app:\n    image: nginx:latest",
    },
})

# Step 2: After on-chain verification, commit the update
client.commit_cvm_compose_file_update({
    "id": "my-app",
    "compose_hash": provision.compose_hash,
    "encrypted_env": "...",
    "env_keys": ["KEY1", "KEY2"],
})

CVM Lifecycle — provisioning and managing CVMs
KMS — encryption keys for environment variables

​update_docker_compose

​update_cvm_envs

​update_pre_launch_script

​get_cvm_docker_compose

​get_cvm_compose_file

​commit_cvm_update

​update_cvm_resources

​update_cvm_visibility

​update_os_image

​get_available_os_images

​patch_cvm

​get_cvm_init_scripts

​get_cvm_annotations / update_cvm_annotations

​Compose File Update Flow

​provision_cvm_compose_file_update

​commit_cvm_compose_file_update

​Related