Phala Cloud Documentation — Private AI on TEE

CVM lifecycle methods control the creation and state transitions of your Confidential Virtual Machines. Provisioning is a two-step process (provision then commit), while other operations are single calls.

CVM Identifiers

Most lifecycle methods accept a CVM identifier. You can pass any of these fields — the SDK resolves them automatically:

Field	Description
`id`	CVM ID (most common)
`app_id`	App ID associated with the CVM
`uuid`	CVM UUID
`instance_id`	Instance ID
`cvm_id`	Alias for `id`

# All equivalent
client.get_cvm_info({"id": "my-app"})
client.get_cvm_info({"app_id": "my-app"})
client.get_cvm_info({"cvm_id": "my-app"})

provision_cvm

POST /cvms Creates a CVM provision request. This is step one of the two-step provisioning flow. Use the response’s token in commit_cvm_provision. Parameters: The request is a dictionary with the CVM configuration. The exact fields depend on your deployment, but typically include:

Field	Type	Required	Description
`name`	`str`	Yes	CVM display name
`compose_file`	`dict`	Yes, unless `compose_file_raw` is sent	Docker Compose configuration
`vcpu`	`int`	No	Number of vCPUs
`memory`	`int`	No	Memory in MB
`disk_size`	`int`	No	Disk size in GB
`node`	`str`	No	Physical node name for deployment
`init_scripts`	`list[str]`	No	Platform init scripts the CVM runs on every boot: `docker_cleanup` (needs dstack OS 0.6.x, `ext4` storage and the `docker-compose` runner) and `env_merge` (dstack OS 0.6.0 or newer, available on request). The list is the whole set; Phala Cloud runs them in a fixed order, `docker_cleanup` first. See Init scripts. The `{"env_merge": True}` form and `enabled_init_scripts_docker_cleanup` are deprecated.
`launch_token`	`str`	No	Launch token, at least 32 bytes, that the CVM must have on every boot. See Launch Token.
`generate_launch_token`	`bool`	No	Have Phala Cloud generate the launch token for a new app, or use the app’s existing token. A new token is returned once, as `launch_token` in the commit response.
`annotations`	`dict[str, str]`	No	Host-side settings for tools on the node, not measured. Needs a feature flag (`ERR-03-049` without it) and dstack VMM 0.6.1 or newer on the node (`ERR-03-050`). See Annotations.
`compose_file_raw`	`str`	No	A whole app-compose JSON file as one string, sent instead of `compose_file`. Needs a feature flag. Phala Cloud parses it with the same rules and writes it the same way, so the compose hash comes from that output, not from your bytes. See Raw app-compose input.

Returns: Provision response with token, compose_hash, and app_id. Example:

result = client.provision_cvm({
    "name": "my-cvm",
    "compose_file": {
        "docker_compose_file": "services:\n  app:\n    image: nginx:latest",
    },
    "vcpu": 2,
    "memory": 2048,
    "disk_size": 20,
    "node": "prod6",
})
print(result.compose_hash)

result = await client.provision_cvm({
    "name": "my-cvm",
    "compose_file": {
        "docker_compose_file": "services:\n  app:\n    image: nginx:latest",
    },
    "vcpu": 2,
    "memory": 2048,
    "disk_size": 20,
    "node": "prod6",
})
print(result.compose_hash)

commit_cvm_provision

POST /cvms Commits a provisioned CVM, creating the actual instance. Pass the token returned by provision_cvm. For the legacy flow, pass the provision response’s app_id and compose_hash instead. On-chain KMS deployments may also need a transaction hash. This endpoint is idempotent: submitting the same app_id + compose_hash again returns the existing CVM. A different compose_hash for the same app_id raises a ResourceError with error code CVM_APP_ID_CONFLICT. Parameters:

Field	Type	Required	Description
`token`	`str`	Preferred	Token from the provision response
`app_id`	`str`	Without token	App ID from the provision response
`compose_hash`	`str`	Without token	Hash from the provision response
`transaction_hash`	`str`	For on-chain KMS when needed	Transaction hash for on-chain verification

Returns: Committed CVM details. Example:

cvm = client.commit_cvm_provision({
    "token": result.token,
})

cvm = await client.commit_cvm_provision({
    "token": result.token,
})

start_cvm

POST /cvms/{cvmId}/start Starts a stopped CVM. Parameters:

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

Returns: CVM action response with updated status. Example:

result = client.start_cvm({"id": "my-app"})
print(result.status)  # "starting"

result = await client.start_cvm({"id": "my-app"})
print(result.status)

stop_cvm

POST /cvms/{cvmId}/stop Force-stops a CVM immediately. Parameters:

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

Returns: CVM action response with updated status.

shutdown_cvm

POST /cvms/{cvmId}/shutdown Gracefully shuts down a CVM, allowing containers to stop cleanly. Prefer this over stop_cvm unless you need an immediate halt. Parameters:

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

Returns: CVM action response with updated status.

restart_cvm

POST /cvms/{cvmId}/restart Restarts a CVM. Supports an optional force flag to skip graceful shutdown. Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier
`force`	`bool`	No	Force restart without graceful shutdown (default: `False`)

Returns: CVM action response with updated status. Example:

client.restart_cvm({"id": "my-app", "force": True})

await client.restart_cvm({"id": "my-app", "force": True})

delete_cvm

DELETE /cvms/{cvmId} Permanently deletes a CVM and all its data. Parameters:

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

Returns: None

This action is irreversible. All data associated with the CVM will be permanently deleted.

Example:

client.delete_cvm({"id": "my-app"})

await client.delete_cvm({"id": "my-app"})

replicate_cvm

POST /cvms/{cvmId}/replicas Creates a copy of an existing CVM. The replica shares the same compose configuration but runs as an independent instance. Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	Source CVM identifier
`node`	`str`	No	Physical node name; omit to inherit the source placement
`os_image`	`str`	No	OS image override

Returns: Replicated CVM details. Example:

replica = client.replicate_cvm({"id": "my-app", "node": "prod6"})

replica = await client.replicate_cvm({"id": "my-app", "node": "prod6"})

watch_cvm_state

GET /cvms/{cvmId}/state (SSE) Watches CVM state via Server-Sent Events. Both sync and async clients support this method. Parameters:

Field	Type	Required	Description
`id`	`str`	Yes	CVM identifier
`target`	`str`	Yes	Target state to wait for (e.g., `"running"`)
`interval`	`int`	No	Polling interval in seconds (default: `5`, range: 5-30)
`timeout`	`int`	No	Server-side timeout in seconds (default: `300`, range: 10-600)
`max_retries`	`int \| None`	No	Retries after an interrupted attempt; default `None` is unlimited, `0` disables retries
`retry_delay`	`float`	No	Delay between retries in seconds (default: `5.0`)

The SDK returns the complete event payload. A raw state status is not necessarily the derived status used by the server to determine completion, and a matching state alone does not complete the watch. A complete event whose status differs from target does not succeed; the SDK treats it as an interrupted attempt and reconnects within the retry budget. The server may emit an error event and continue. On a timeout event, an EOF without completion, or a transient transport error, the SDK reconnects within the retry budget. Exhausted retries raise RequestError, retaining the latest server error and transport diagnostics when available. HTTP errors use SDK error types and are not retried. The stream read timeout is timeout + interval + 5 seconds. Other HTTPX timeout settings remain in effect. Cancelling an async task closes the stream and propagates cancellation. maxRetries and retryDelay are also accepted as aliases. Example:

result = client.watch_cvm_state({
    "id": "my-app",
    "target": "running",
    "timeout": 120,
    "max_retries": 3,
})
print(result.status)

result = await client.watch_cvm_state({
    "id": "my-app",
    "target": "running",
    "timeout": 120,
    "max_retries": 3,
})
print(result.status)

CVM Configuration — updating compose files and resources
Error Handling — handling provisioning errors

​CVM Identifiers

​provision_cvm

​commit_cvm_provision

​start_cvm

​stop_cvm

​shutdown_cvm

​restart_cvm

​delete_cvm

​replicate_cvm

​watch_cvm_state

​Related

CVM Identifiers

provision_cvm

commit_cvm_provision

start_cvm

stop_cvm

shutdown_cvm

restart_cvm

delete_cvm

replicate_cvm

watch_cvm_state

Related