Skip to main content

provisionCvm

POST /cvms/provision Provisions a new CVM. This is the first phase of the two-phase deployment flow — call commitCvmProvision to finalize. Parameters:
FieldTypeRequiredDescription
namestringYesCVM name (5-63 chars, must start with a letter)
compose_fileobjectYesCompose file configuration (see below)
instance_typestringNoInstance type (default: "tdx.small")
node_idnumberNoDeploy to a specific node
regionstringNoRegion filter
imagestringNoOS image name
disk_sizenumberNoDisk size in GB
kmsstringNoKMS type: "PHALA" (default), "ETHEREUM", or "BASE"
kms_contractstringNoKMS contract address (on-chain KMS only)
env_keysstring[]NoAllowed environment variable keys
noncenumberNoNonce for deterministic app_id (PHALA KMS only)
app_idstringNoExpected app_id (must match nonce)
listedbooleanNoList CVM in public directory
compose_file object:
FieldTypeRequiredDescription
docker_compose_filestringYesDocker Compose YAML content
allowed_envsstring[]NoEnv var keys the CVM may receive
pre_launch_scriptstringNoScript to run before containers start
gateway_enabledbooleanNoEnable gateway/proxy
kms_enabledbooleanNoEnable KMS integration
public_logsbooleanNoMake container logs public
public_sysinfobooleanNoMake system info public
Returns: ProvisionCvm
FieldTypeDescription
compose_hashstringHash of the compose configuration — pass to commitCvmProvision
app_idstring?App ID (only for PHALA KMS)
app_env_encrypt_pubkeystring?Encryption public key (only for PHALA KMS)
kms_idstring?KMS instance ID
kms_infoKmsInfo?KMS details
device_idstring?Device ID for on-chain KMS
fmspcstring?FMSPC of the selected node
os_image_hashstring?OS image hash
instance_typestring?Selected instance type
node_idnumber?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):
const provision = await client.provisionCvm({
  name: "my-app",
  compose_file: { docker_compose_file: composeYaml },
  kms: "ETHEREUM",
});

// On-chain KMS does NOT return app_id — deploy a contract to get one
// See the on-chain KMS guide for the full flow
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);
}