> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phala.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CVM Query

> Functions for querying CVM information, state, and metrics

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:**

```typescript theme={"system"}
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:**

```typescript theme={"system"}
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:**

```typescript theme={"system"}
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:**

```typescript theme={"system"}
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:**

```typescript theme={"system"}
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:**

```typescript theme={"system"}
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:**

```typescript theme={"system"}
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:**

```typescript theme={"system"}
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:**

```typescript theme={"system"}
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:**

```typescript theme={"system"}
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:**

```typescript theme={"system"}
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}`);
}
```