Phala Cloud Documentation — Confidential AI on TEE

All CVM query functions accept a CVM identifier. The SDK auto-detects the format:

Format	Example
Name	`my-app`
UUID	`550e8400-e29b-41d4-a716-446655440000`
App ID	`0x1234abcd...` (40 hex chars, optional `0x` prefix)
Instance ID	`instance-abc123`

getCvmInfo

GET /cvms/{cvmId} Returns full CVM details including configuration, status, and metadata. Parameters:

Field	Type	Required	Description
`id`	`string`	Yes	CVM identifier (any format above)

Returns: CvmInfo — version-aware response with CVM details. Example:

const cvm = await client.getCvmInfo({ id: "my-app" });
console.log(cvm.name, cvm.status);

getCvmList

GET /cvms/paginated Returns a paginated list of CVMs. Parameters:

Field	Type	Required	Description
`page`	`number`	No	Page number
`page_size`	`number`	No	Items per page
`node_id`	`number`	No	Filter by node
`user_id`	`string`	No	Filter by user

Returns: Paginated list of CVM objects. Example:

const list = await client.getCvmList({ page: 1, page_size: 10 });

getCvmState

GET /cvms/{cvmId}/state Returns the current state of a CVM (non-streaming, immediate response). Parameters:

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

Returns: CvmState

Field	Type	Description
`id`	`string`	CVM ID
`instance_id`	`string`	Instance ID
`name`	`string`	CVM name
`status`	`string`	Current status
`uptime`	`string?`	Uptime duration
`boot_progress`	`string?`	Boot progress percentage
`boot_error`	`string?`	Boot error if failed

Example:

const state = await client.getCvmState({ id: "my-app" });
console.log(state.status); // "running", "stopped", etc.

getCvmStats

GET /cvms/{cvmId}/stats Returns system information and resource usage for a CVM. Parameters:

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

Returns: CvmSystemInfo

Field	Type	Description
`is_online`	`boolean`	Whether CVM is reachable
`is_public`	`boolean`	Whether stats are public
`sysinfo`	`object?`	CPU, memory, disk usage
`status`	`string?`	Current status
`boot_progress`	`string?`	Boot progress

Example:

const stats = await client.getCvmStats({ id: "my-app" });
if (stats.sysinfo) {
  console.log(`CPU: ${stats.sysinfo.cpu_usage}%`);
}

getCvmNetwork

GET /cvms/{cvmId}/network Returns network information including public URLs and internal IP. Parameters:

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

Returns: CvmNetwork

Field	Type	Description
`is_online`	`boolean`	Whether CVM is reachable
`internal_ip`	`string?`	WireGuard internal IP
`public_urls`	`array?`	Public URL mappings

Example:

const net = await client.getCvmNetwork({ id: "my-app" });
console.log(net.public_urls);

getCvmContainersStats

GET /cvms/{cvmId}/composition Returns container-level information including running state and log endpoints. Parameters:

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

Returns: CvmContainersStats

Field	Type	Description
`is_online`	`boolean`	Whether CVM is reachable
`docker_compose_file`	`string?`	Active compose YAML
`containers`	`array?`	Container info (id, names, image, state, status, log_endpoint)

Example:

const stats = await client.getCvmContainersStats({ id: "my-app" });
stats.containers?.forEach(c => console.log(c.names, c.state));

getCvmAttestation

GET /cvms/{cvmId}/attestation Returns TEE attestation details including certificates and TCB info. Parameters:

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

Returns: CvmAttestation

Field	Type	Description
`is_online`	`boolean`	Whether CVM is reachable
`app_certificates`	`array?`	TLS certificates with attestation
`tcb_info`	`object?`	TCB measurements (mrtd, rtmr0-3, event_log, app_compose hash)

Example:

const att = await client.getCvmAttestation({ id: "my-app" });
console.log(att.tcb_info?.app_compose);

getCvmDockerCompose

GET /cvms/{cvmId}/docker-compose Returns the raw docker-compose configuration as a string. Parameters:

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

Returns: string — raw docker-compose YAML content. Example:

const compose = await client.getCvmDockerCompose({ id: "my-app" });
console.log(compose);

getCvmComposeFile

GET /cvms/{cvmId}/compose_file Returns the full compose file object with utility methods for hashing. Parameters:

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

Returns: LooseAppCompose — compose file object with getHash() and toString() methods. Example:

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

getCvmPreLaunchScript

GET /cvms/{cvmId}/pre-launch-script Returns the pre-launch script content. Parameters:

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

Returns: string — pre-launch script content.

getCvmStatusBatch

GET /cvms/status/batch Returns the status of multiple CVMs in a single request. Parameters:

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

Returns: GetCvmStatusBatchResponse

Field	Type	Description
`statuses`	`CvmStatus[]`	Status for each requested CVM

Example:

const batch = await client.getCvmStatusBatch({ ids: ["id-1", "id-2"] });
batch.statuses.forEach(s => console.log(s.id, s.status));

getCvmUserConfig

GET /cvms/{cvmId}/user-config Returns the user-level configuration for a CVM. Parameters:

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

Returns: CvmUserConfig — user configuration details.

checkCvmIsAllowed

POST /cvms/{cvmId}/is-allowed Checks whether a CVM’s current deployment is allowed by its on-chain dstack App contract. This queries the blockchain to verify that the compose hash and device ID are registered. Useful for diagnosing on-chain KMS permission issues. Parameters:

Field	Type	Required	Description
`cvmId`	`string`	Yes	CVM identifier
`compose_hash`	`string`	No	Override compose hash to check
`node_id`	`number`	No	Override node ID (resolves device ID)
`device_id`	`string`	No	Override device ID (hex)

Returns: IsAllowedResult

Field	Type	Description
`app_contract_address`	`string`	Contract address
`compose_hash`	`string`	Checked compose hash
`device_id`	`string`	Checked device ID
`compose_hash_allowed`	`boolean`	Whether compose hash is registered
`allow_any_device`	`boolean`	Whether any device is allowed
`device_id_allowed`	`boolean?`	Whether specific device is registered
`is_allowed`	`boolean`	Overall allowance result
`error`	`string?`	Error message if check failed

Example:

const result = await client.checkCvmIsAllowed({ cvmId: "my-app" });
if (!result.is_allowed) {
  console.log(`Compose hash allowed: ${result.compose_hash_allowed}`);
  console.log(`Device allowed: ${result.device_id_allowed}`);
}

​getCvmInfo

​getCvmList

​getCvmState

​getCvmStats

​getCvmNetwork

​getCvmContainersStats

​getCvmAttestation

​getCvmDockerCompose

​getCvmComposeFile

​getCvmPreLaunchScript

​getCvmStatusBatch

​getCvmUserConfig

​checkCvmIsAllowed

getCvmInfo

getCvmList

getCvmState

getCvmStats

getCvmNetwork

getCvmContainersStats

getCvmAttestation

getCvmDockerCompose

getCvmComposeFile

getCvmPreLaunchScript

getCvmStatusBatch

getCvmUserConfig

checkCvmIsAllowed