> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phala.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CVM Configuration

> Update Docker Compose files, environment variables, resources, visibility, and OS images on running CVMs.

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.

<Warning>
  **Every configuration update triggers a CVM restart.** The CVM will be stopped, updated, and restarted automatically. Plan updates accordingly to minimize downtime.
</Warning>

Each `update_*` method targets a single aspect of the CVM and calls a dedicated API endpoint. `patch_cvm` is the unified method that can update multiple fields in a single request. Use `patch_cvm` when you need to change several settings atomically; use the individual `update_*` methods when you only need to change one thing.

## 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:** `InProgressResponse` on success, or `ComposeHashPreconditionResponse` if on-chain verification is needed.

**Example:**

<CodeGroup>
  ```python Sync theme={"system"}
  result = client.update_docker_compose({
      "id": "my-app",
      "docker_compose_file": """
  services:
    app:
      image: nginx:latest
      ports:
        - "80:80"
  """,
  })
  ```

  ```python Async theme={"system"}
  result = await client.update_docker_compose({
      "id": "my-app",
      "docker_compose_file": """
  services:
    app:
      image: nginx:latest
      ports:
        - "80:80"
  """,
  })
  ```
</CodeGroup>

***

## 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:**

```python theme={"system"}
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(
    env_vars=[{"key": "SECRET", "value": "my-secret"}],
    public_key=pubkey_resp.app_env_encrypt_pubkey,
)

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:**

```python theme={"system"}
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.

***

## update\_cvm\_resources

`PATCH /cvms/{cvmId}/resources`

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                   |
| `instance_type` | `str`   | No       | Instance type name                |
| `allow_restart` | `bool`  | No       | Allow automatic restart if needed |

**Returns:** `None`

**Example:**

<CodeGroup>
  ```python Sync theme={"system"}
  client.update_cvm_resources({
      "id": "my-app",
      "vcpu": 4,
      "memory": 4096,
      "instance_type": "tdx.medium",
  })
  ```

  ```python Async theme={"system"}
  await client.update_cvm_resources({
      "id": "my-app",
      "vcpu": 4,
      "memory": 4096,
      "instance_type": "tdx.medium",
  })
  ```
</CodeGroup>

***

## update\_cvm\_visibility

`PATCH /cvms/{cvmId}/visibility`

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:** Visibility settings response.

**Example:**

```python theme={"system"}
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:**

```python theme={"system"}
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.

**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     |
| `encrypted_env`       | `str`       | No       | Encrypted environment variables   |
| `vcpu`                | `int`       | No       | Number of vCPUs                   |
| `memory`              | `int`       | No       | Memory in MB                      |
| `disk_size`           | `int`       | No       | Disk size in GB                   |
| `image`               | `str`       | No       | OS image name                     |

**Returns:** A dict with `requires_on_chain_hash` (bool) and either `correlation_id` or on-chain hash details.

<Note>
  If the patch changes compose-hash-relevant fields, the response may include `requires_on_chain_hash: True` with hash details that need on-chain verification. Use `confirm_cvm_patch` to complete the update.
</Note>

***

## 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.

```python theme={"system"}
# 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"],
})
```

## Related

* [CVM Lifecycle](/phala-cloud/references/cloud-python-sdk/cvm-lifecycle) — provisioning and managing CVMs
* [KMS](/phala-cloud/references/cloud-python-sdk/kms) — encryption keys for environment variables