> ## 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.

# provisionCvm

> Provision a new CVM — first phase of the two-phase deployment flow

## provisionCvm

`POST /cvms/provision`

Provisions a new CVM. This is the **first phase** of the two-phase deployment flow — call [`commitCvmProvision`](/phala-cloud/references/cloud-js-sdk/commit-cvm-provision) to finalize.

**Parameters:**

| Field           | Type       | Required | Description                                              |
| --------------- | ---------- | -------- | -------------------------------------------------------- |
| `name`          | `string`   | Yes      | CVM name (5-63 chars, must start with a letter)          |
| `compose_file`  | `object`   | Yes      | Compose file configuration (see below)                   |
| `instance_type` | `string`   | No       | Instance type (default: `"tdx.small"`)                   |
| `node_id`       | `number`   | No       | Deploy to a specific node                                |
| `region`        | `string`   | No       | Region filter                                            |
| `image`         | `string`   | No       | OS image name                                            |
| `disk_size`     | `number`   | No       | Disk size in GB                                          |
| `kms`           | `string`   | No       | KMS type: `"PHALA"` (default), `"ETHEREUM"`, or `"BASE"` |
| `kms_contract`  | `string`   | No       | KMS contract address (on-chain KMS only)                 |
| `env_keys`      | `string[]` | No       | Allowed environment variable keys                        |
| `nonce`         | `number`   | No       | Nonce for deterministic `app_id` (PHALA KMS only)        |
| `app_id`        | `string`   | No       | Expected `app_id` (must match nonce)                     |
| `listed`        | `boolean`  | No       | List CVM in public directory                             |

**`compose_file` object:**

| Field                 | Type       | Required | Description                           |
| --------------------- | ---------- | -------- | ------------------------------------- |
| `docker_compose_file` | `string`   | Yes      | Docker Compose YAML content           |
| `allowed_envs`        | `string[]` | No       | Env var keys the CVM may receive      |
| `pre_launch_script`   | `string`   | No       | Script to run before containers start |
| `gateway_enabled`     | `boolean`  | No       | Enable gateway/proxy                  |
| `kms_enabled`         | `boolean`  | No       | Enable KMS integration                |
| `public_logs`         | `boolean`  | No       | Make container logs public            |
| `public_sysinfo`      | `boolean`  | No       | Make system info public               |

**Returns:** `ProvisionCvm`

| Field                    | Type       | Description                                                      |
| ------------------------ | ---------- | ---------------------------------------------------------------- |
| `compose_hash`           | `string`   | Hash of the compose configuration — pass to `commitCvmProvision` |
| `app_id`                 | `string?`  | App ID (only for PHALA KMS)                                      |
| `app_env_encrypt_pubkey` | `string?`  | Encryption public key (only for PHALA KMS)                       |
| `kms_id`                 | `string?`  | KMS instance ID                                                  |
| `kms_info`               | `KmsInfo?` | KMS details                                                      |
| `device_id`              | `string?`  | Device ID for on-chain KMS                                       |
| `fmspc`                  | `string?`  | FMSPC of the selected node                                       |
| `os_image_hash`          | `string?`  | OS image hash                                                    |
| `instance_type`          | `string?`  | Selected instance type                                           |
| `node_id`                | `number?`  | Selected node ID                                                 |

**Example — PHALA KMS (default):**

```typescript theme={"system"}
import { createClient, encryptEnvVars, parseEnvVars } from "@phala/cloud";

const client = createClient();

const provision = await client.provisionCvm({
  name: "my-app",
  instance_type: "tdx.small",
  compose_file: {
    docker_compose_file: composeYaml,
    allowed_envs: ["API_KEY", "SECRET"],
  },
});

// PHALA KMS returns app_id and pubkey directly
const encrypted = await encryptEnvVars(envVars, provision.app_env_encrypt_pubkey!);

await client.commitCvmProvision({
  app_id: provision.app_id!,
  compose_hash: provision.compose_hash,
  encrypted_env: encrypted,
  env_keys: ["API_KEY", "SECRET"],
});
```

**Example — On-chain KMS (ETHEREUM/BASE):**

```typescript theme={"system"}
import { deployAppAuth } from "@phala/cloud";

// Step 1: Provision — reserves the CVM but does not start it
const provision = await client.provisionCvm({
  name: "my-app",
  compose_file: { docker_compose_file: composeYaml },
  kms: "ETHEREUM",
});

// Step 2: Deploy an AppAuth contract to obtain an app_id
const deployed = await deployAppAuth({
  chain: provision.kms_info!.chain,
  rpcUrl: "https://...",
  kmsContractAddress: provision.kms_info!.kms_contract_address,
  privateKey: "0x...",
  deviceId: provision.device_id,
  composeHash: provision.compose_hash,
});

// Step 3: Commit — finalizes the deployment and starts the CVM
await client.commitCvmProvision({
  app_id: deployed.appId,
  compose_hash: provision.compose_hash,
  kms_id: provision.kms_id!,
  contract_address: deployed.appAuthAddress,
  deployer_address: deployed.deployer,
});
```

For the full on-chain KMS flow including environment encryption and wallet setup, see [Deploying with Onchain KMS](/phala-cloud/key-management/deploying-with-onchain-kms).

<Note>
  The combined size of `docker_compose_file` and `pre_launch_script` must not exceed 200KB.
</Note>

***

## safeProvisionCvm

Safe variant that returns a `SafeResult<ProvisionCvm>` instead of throwing on errors.

```typescript theme={"system"}
const result = await client.safeProvisionCvm({ ... });
if (result.success) {
  console.log(result.data.compose_hash);
} else {
  console.error(result.error);
}
```