CVM Lifecycle

Provision, start, stop, restart, delete, and replicate CVMs using the Python SDK.

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

Returns: Provision response with compose_hash and app_id.

Example:

Sync

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)

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,
    "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

Returns: Committed CVM details.

Example:

Sync

cvm = client.commit_cvm_provision({
    "app_id": "app-123",
    "compose_hash": "0xabc...",
    "transaction_hash": "0xdef...",
})

cvm = await 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

Returns: CVM action response with updated status.

Example:

Sync

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:

Sync

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:

Sync

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_id	int	No	Target node for the replica

Returns: Replicated CVM details.

Example:

Sync

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

replica = await 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)

Returns: CVM state object when the target state is reached.

Raises: 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"

Related

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