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/provision
Creates a CVM provision request. This is step one of the two-step provisioning flow. The response includes a compose_hash that you use 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 | Docker Compose configuration |
vcpu | int | No | Number of vCPUs |
memory | int | No | Memory in MB |
disk_size | int | No | Disk size in GB |
teepod_id | int | No | Target node ID |
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,
"teepod_id": 3,
})
print(result.compose_hash)
commit_cvm_provision
POST /cvms
Commits a provisioned CVM, creating the actual instance. This is step two of the provisioning flow. Pass the compose_hash from the provision step along with on-chain transaction details.
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 |
|---|
app_id | str | Yes | App ID from provision step |
compose_hash | str | Yes | Hash from provision step |
transaction_hash | str | Yes | On-chain transaction hash |
cvm = client.commit_cvm_provision({
"app_id": "app-123",
"compose_hash": "0xabc...",
"transaction_hash": "0xdef...",
})
start_cvm
POST /cvms/{cvmId}/start
Starts a stopped CVM.
Parameters:
| Field | Type | Required | Description |
|---|
id | str | Yes | CVM identifier |
result = client.start_cvm({"id": "my-app"})
print(result.status) # "starting"
stop_cvm
POST /cvms/{cvmId}/stop
Force-stops a CVM immediately.
Parameters:
| Field | Type | Required | Description |
|---|
id | str | Yes | CVM identifier |
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 |
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) |
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 |
None
This action is irreversible. All data associated with the CVM will be permanently deleted.
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_id | int | No | Target node for the replica |
replica = client.replicate_cvm({"id": "my-app", "node_id": 5})
watch_cvm_state
GET /cvms/{cvmId}/state (SSE)
Polls the CVM state via Server-Sent Events until it reaches a target status. This is useful for waiting until a CVM finishes starting or stopping. Only available on the sync client.
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 | No | Maximum retry attempts |
retry_delay | float | No | Delay between retries in seconds (default: 5.0) |
TimeoutError if max retries exceeded.
Example:
# Start a CVM and wait for it to be running
client.start_cvm({"id": "my-app"})
state = client.watch_cvm_state({
"id": "my-app",
"target": "Running",
"timeout": 120,
"max_retries": 3,
})
print(state.status) # "Running"
