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

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

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.

The combined size of docker_compose_file and pre_launch_script must not exceed 200KB.

---

safeProvisionCvm

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

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