CVM Configuration

Functions for updating CVM resources, visibility, OS images, and compose files

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 (updateCvmAnnotations) never restart the CVM, and SSH key changes without apply_now stay pending until the next power-on.

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

​

updateCvmResources

PATCH /cvms/{cvmId}

Updates CVM compute resources (vCPU, memory, disk, instance type). It sends only these four fields.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier
vcpu	number	No	Number of vCPUs
memory	number	No	Memory in MB
disk_size	number	No	Disk size in GB. A disk cannot shrink.
instance_type	string	No	Instance type, for example tdx.medium
allow_restart	boolean	No	Deprecated and not sent. The CVM restarts whenever a resize needs it.

Returns: { message, correlation_id, status }. correlation_id tracks the update.

Example:

await client.updateCvmResources({
  id: "my-app",
  vcpu: 4,
  memory: 8192,
  disk_size: 100,
});

---

​

updateCvmVisibility

PATCH /cvms/{cvmId}

Sets what the public can see about the CVM: system info, logs and TCB info.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier
public_sysinfo	boolean	Yes	Make system info public
public_logs	boolean	Yes	Make container logs public
public_tcbinfo	boolean	No	Make TCB info 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. Register it and call again, or use patchCvm, which returns the hash to register and supports prepareOnly.

The Trust Center listing is not a visibility setting. Change it with PATCH /cvms/{cvmId}/listed.

---

​

updatePreLaunchScript

PATCH /cvms/{cvmId}/pre-launch-script

Updates the pre-launch script for a CVM.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier
pre_launch_script	string	Yes	Script content
compose_hash	string	No	For on-chain KMS (Phase 2)
transaction_hash	string	No	For on-chain KMS (Phase 2)

Returns: Union type:

• { status: "in_progress", message, correlation_id } — update accepted
• { status: "precondition_required", message, compose_hash, app_id, device_id, kms_info } — on-chain KMS requires compose hash registration first

For CVMs using on-chain KMS, this function may return precondition_required. You must register the compose_hash on-chain using addComposeHash before retrying with the compose_hash and transaction_hash parameters.

---

​

updateOsImage

PATCH /cvms/{cvmId}/os-image

Updates the OS image for a CVM. The CVM will restart with the new image.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier
os_image_name	string	Yes	OS image name

Returns: undefined. The API answers 202 with { message, correlation_id, status }, but updateOsImage discards it.

---

​

getAvailableOsImages

GET /os-images

Returns the list of available OS images.

Parameters: None (optional filters).

Returns: GetAvailableOSImagesResponse — array of OS image variants with version info.

Example:

const images = await client.getAvailableOsImages();
images.forEach(img => console.log(img.name, img.version));

---

​

refreshCvmInstanceId

POST /cvms/{cvmId}/refresh-instance-id

Generates a new instance ID for a CVM. This invalidates the old instance ID.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier

Returns: InstanceIdRefreshResult with the new instance_id.

---

​

refreshCvmInstanceIds

POST /cvms/refresh-instance-ids

Generates new instance IDs for multiple CVMs in a single request.

Parameters:

Field	Type	Required	Description
ids	string[]	Yes	Array of CVM identifiers

Returns: RefreshCvmInstanceIdsResponse — batch results.

---

​

provisionCvmComposeFileUpdate

POST /cvms/{cvmId}/compose_file/provision

Provisions a compose file update — the first phase of a two-phase compose file change. Returns a compose_hash needed for the commit step.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier (also accepts uuid)
app_compose	object	Yes	Updated compose file object

Returns: ProvisionCvmComposeFileUpdateResult

Field	Type	Description
compose_hash	string	Hash of the provisioned compose file. Pass it to commitCvmComposeFileUpdate.
compose_hash_registered	boolean	On-chain KMS only: true if the hash is already registered on the AppAuth contract. When true, skip addComposeHash and call commitCvmComposeFileUpdate directly.
app_id	string | null	App identifier of the target CVM.
device_id	string | null	Device identifier of the target CVM.
kms_info	object | null	KMS metadata for the target CVM. Present for on-chain KMS CVMs.

Example:

import { addComposeHash } from "@phala/cloud";

const compose = await client.getCvmComposeFile({ id: "my-app" });
compose.docker_compose_file = newYaml;

const provision = await client.provisionCvmComposeFileUpdate({
  uuid: "my-app",
  app_compose: compose,
});

if (provision.kms_info && !provision.compose_hash_registered) {
  // On-chain KMS: register the new hash before commit.
  // See addComposeHash docs for the full parameter set.
  await addComposeHash({
    chain: provision.kms_info.chain,
    kmsContractAddress: provision.kms_info.kms_contract_address,
    appId: provision.app_id as `0x${string}`,
    composeHash: provision.compose_hash,
    privateKey: process.env.ETH_PRIVATE_KEY as `0x${string}`,
  });
}

await client.commitCvmComposeFileUpdate({
  id: "my-app",
  compose_hash: provision.compose_hash,
});

---

​

commitCvmComposeFileUpdate

POST /cvms/{cvmId}/compose_file/commit

Commits a compose file update — the second phase. For on-chain KMS, the compose_hash must be registered on-chain before calling this.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier
compose_hash	string	Yes	From provisionCvmComposeFileUpdate
encrypted_env	string	No	Hex-encoded encrypted env vars
env_keys	string[]	No	Allowed env variable keys
transaction_hash	string	No	On-chain transaction hash

Returns: CommitCvmComposeFileUpdate — update details.

---

​

patchCvm

PATCH /cvms/{cvmId}

Applies partial updates to a CVM via the unified PATCH endpoint. Only fields present in the request body are applied. You can update compose files, environment variables, resources, visibility, and OS images all in a single call.

compose is a JSON Merge Patch of the app compose: a key you set changes that value, null removes the key, and a key you leave out stays as it is. See How does the compose patch work? for the keys and the settings that cannot change after create.

For CVMs with on-chain KMS (ETHEREUM/BASE), a change to the compose needs a second step only when the new compose hash is not on the app contract yet. The API then answers HTTP 465, and patchCvm returns { requiresOnChainHash: true, composeHash, ... } with the hash to register. After registration, call confirmCvmPatch with the transaction proof. 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 correlationId. prepareOnly is not a dry run: an update that needs no registration starts right away.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier
docker_compose_file	string	No	New Docker Compose YAML
pre_launch_script	string	No	New pre-launch script
allowed_envs	string[]	No	Allowed env variable keys
public_logs	boolean	No	Make logs publicly accessible
public_sysinfo	boolean	No	Make system info public
public_tcbinfo	boolean	No	Make TCB info public
compose	ComposePatch	No	Other compose settings as a merge patch, for example { swap_size: "2G", requirements: { health_check: true } }
init_scripts	("docker_cleanup" | "env_merge")[]	No	Platform init scripts the CVM runs, replacing the current set. [] removes them all.
confirm_data_wipe	boolean	No	Confirms turning on docker_cleanup or requirements.ephemeral_data_disk, which erase data on every boot
encrypted_env	string	No	Hex-encoded encrypted env vars
user_config	string	No	User configuration string
gpus	object	No	GPU assignment: { gpus: [{ slot, product_id? }], attach_mode? }. attach_mode: "all" attaches every GPU on the node instead of the listed slots.
vcpu	number	No	Number of vCPUs
memory	number	No	Memory in MB
disk_size	number	No	Disk size in GB
instance_type	string	No	Instance type, for example tdx.medium
image	string	No	OS image name
shutdown_timeout	number	No	Seconds to wait for a clean shutdown (10 to 1200)
allow_force_stop	boolean	No	Skip the clean shutdown and stop the CVM at once
prepareOnly	boolean	No	Sent as the X-Prepare-Only: true header. On Onchain KMS, the hash-required result then carries a commit token for multisig approval.

Returns: Discriminated union on requiresOnChainHash:

Accepted (requiresOnChainHash: false):

Field	Type	Description
requiresOnChainHash	false	Update accepted directly
correlationId	string	Tracking ID. Empty when the API answers no_change.

Hash required (requiresOnChainHash: true):

Field	Type	Description
requiresOnChainHash	true	On-chain registration needed
composeHash	string	Hash to register on-chain
appId	string	App ID for contract interaction
deviceId	string	Device ID
kmsInfo	KmsInfo	KMS details for chain interaction
commitToken	string?	One-time token for multisig commit
commitUrl	string?	Dashboard page where the update can be committed
apiCommitUrl	string?	API URL for commitCvmUpdate
onchainStatus	object?	Current on-chain allowance status

Example — simple update (PHALA KMS):

const result = await client.patchCvm({
  id: "my-app",
  vcpu: 4,
  memory: 8192,
});
console.log(result.correlationId);

Example — on-chain KMS compose update (two-phase):

import { addComposeHash } from "@phala/cloud";

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

if (result.requiresOnChainHash) {
  const tx = await addComposeHash({
    chain: result.kmsInfo.chain,
    kmsContractAddress: result.kmsInfo.kms_contract_address,
    appId: result.appId as `0x${string}`,
    composeHash: result.composeHash,
    privateKey: privateKey,
  });

  await client.confirmCvmPatch({
    id: "my-app",
    composeHash: result.composeHash,
    transactionHash: tx.transactionHash,
  });
}

---

​

getCvmInitScripts

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 patchCvm’s init_scripts. See Init scripts.

Parameters: id (CVM identifier).

Returns: { items: [{ slug, selected, selectable, reason }] }

---

​

getCvmAnnotations / updateCvmAnnotations

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. updateCvmAnnotations 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 (Record<string, string>) for updateCvmAnnotations.

Returns: { annotations }, the annotations the node now stores.

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

---

​

confirmCvmPatch

PATCH /cvms/{cvmId} (with X-Compose-Hash and X-Transaction-Hash headers)

Completes the second phase of an on-chain KMS CVM update. Call this after patchCvm returns { requiresOnChainHash: true } and you have registered the compose hash on-chain via addComposeHash.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier
composeHash	string	Yes	Compose hash from patchCvm Phase 1 response
transactionHash	string	Yes	Transaction hash proving on-chain registration

Returns: ConfirmCvmPatchResult

Field	Type	Description
correlationId	string	Tracking ID

Example:

const confirmed = await client.confirmCvmPatch({
  id: "my-app",
  composeHash: patchResult.composeHash,
  transactionHash: txReceipt.transactionHash,
});
console.log(`Update started: ${confirmed.correlationId}`);

---

​

commitCvmUpdate

POST /cvms/{cvmId}/commit-update

Completes a two-phase CVM update using a one-time commit token. This enables multisig workflows where the on-chain signer is different from the original API caller. The token is generated when you call patchCvm with prepareOnly: true.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier
token	string	Yes	One-time commit token from prepare-only flow
composeHash	string	Yes	Compose hash from Phase 1 response
transactionHash	string	Yes	Transaction hash proving on-chain registration

Returns: CommitCvmUpdateResult

Field	Type	Description
correlationId	string	Tracking ID
status	string	Update status

Example:

// Phase 1: prepare-only
const result = await client.patchCvm({
  id: "my-app",
  docker_compose_file: newComposeYaml,
  prepareOnly: true,
});

if (result.requiresOnChainHash && result.commitToken) {
  // ... multisig approval and on-chain registration happen externally ...

  // Phase 2: commit with token
  const committed = await client.commitCvmUpdate({
    id: "my-app",
    token: result.commitToken,
    composeHash: result.composeHash,
    transactionHash: "0x...",
  });
  console.log(`Update started: ${committed.correlationId}`);
}