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

# updateDockerCompose

> Update the Docker Compose configuration for a CVM

## updateDockerCompose

`PATCH /cvms/{cvmId}/docker-compose`

Updates the Docker Compose file for a running CVM. The request body is sent as `text/yaml`.

This function uses a **two-phase flow** for CVMs with on-chain KMS:

1. **Phase 1:** Call with the new `docker_compose_file`. If the CVM uses on-chain KMS, the API returns `precondition_required` with a `compose_hash`.
2. **Register on-chain:** Call [`addComposeHash`](/phala-cloud/references/cloud-js-sdk/add-compose-hash) to register the new compose hash on the blockchain.
3. **Phase 2:** Retry the call with the original YAML plus `compose_hash` and `transaction_hash`.

**Parameters:**

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | CVM identifier |
| `docker_compose_file` | `string` | Yes | New Docker Compose YAML content |
| `compose_hash` | `string` | No | Compose hash (Phase 2, sent via `X-Compose-Hash` header) |
| `transaction_hash` | `string` | No | On-chain transaction hash (Phase 2, sent via `X-Transaction-Hash` header) |

**Returns:** Union of two possible responses:

**Success (`in_progress`):**

| Field | Type | Description |
| - | - | - |
| `status` | `"in_progress"` | Update accepted |
| `message` | `string` | Status message |
| `correlation_id` | `string` | Tracking ID |

**Precondition required (`precondition_required`):**

| Field | Type | Description |
| - | - | - |
| `status` | `"precondition_required"` | On-chain registration needed |
| `message` | `string` | Instructions |
| `compose_hash` | `string` | Hash to register on-chain |
| `app_id` | `string` | App ID for contract interaction |
| `device_id` | `string` | Device ID |
| `kms_info` | `KmsInfo` | KMS details for chain interaction |

**Example — PHALA KMS:**

```typescript theme={"system"}
const result = await client.updateDockerCompose({
  id: "my-app",
  docker_compose_file: newComposeYaml,
});
// result.status === "in_progress"
```

**Example — On-chain KMS (two phases):**

```typescript theme={"system"}
import { addComposeHash } from "@phala/cloud";

// Phase 1
const result = await client.updateDockerCompose({
  id: "my-app",
  docker_compose_file: newComposeYaml,
});

if (result.status === "precondition_required") {
  // Register on-chain
  const receipt = await addComposeHash({
    chain: result.kms_info.chain,
    kmsContractAddress: result.kms_info.kms_contract_address,
    appId: result.app_id as `0x${string}`,
    composeHash: result.compose_hash,
    privateKey: privateKey,
  });

  // Phase 2
  await client.updateDockerCompose({
    id: "my-app",
    docker_compose_file: newComposeYaml,
    compose_hash: result.compose_hash,
    transaction_hash: receipt.transactionHash,
  });
}
```

***

## safeUpdateDockerCompose

Safe variant that returns a `SafeResult` instead of throwing on errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.