Phala Cloud Documentation — Private AI on TEE

CVM configuration methods let you modify a running or stopped CVM without recreating it.

Some configuration updates restart a running CVM. A change applied through PATCH /cvms/{cvmId} or the compose, environment and OS image endpoints stops the CVM, applies the change and starts it again. A stopped CVM stays stopped and runs the new configuration at its next start. A compose change that matches what the CVM already runs does not restart it: the API answers no_change and does nothing. UpdateCVMListed and annotations (UpdateCVMAnnotations) never restart the CVM, and SSH key changes without ApplyNow stay pending until the next power-on.

PatchCVM sends any set of changes in one request to PATCH /cvms/{cvmId}. UpdateCVMResources and UpdateCVMVisibility send a subset of fields to the same endpoint. The other UpdateXxxx methods call their own endpoints. See Update CVM Configuration for what each field does and which settings cannot change after create. For CVMs using on-chain KMS, updates that affect the compose hash require an additional on-chain confirmation step.

UpdateDockerCompose

PATCH /cvms/{cvmId}/docker-compose Replaces the Docker Compose YAML for a CVM. The compose content is sent as text/yaml. For on-chain KMS CVMs, pass compose hash and transaction hash via the options parameter.

func (c *Client) UpdateDockerCompose(ctx context.Context, cvmID, compose string, opts *ComposeUpdateOptions) (*UpdateResult, error)

Parameters:

Field	Type	Required	Description
`cvmID`	`string`	Yes	CVM identifier
`compose`	`string`	Yes	Docker Compose YAML content
`opts`	`*ComposeUpdateOptions`	No	Compose hash and transaction hash headers

ComposeUpdateOptions fields:

Field	Type	Description
`ComposeHash`	`string`	Compose hash for on-chain verification (sent as `X-Compose-Hash`)
`TransactionHash`	`string`	On-chain transaction hash (sent as `X-Transaction-Hash`)

Returns: *UpdateResult when the update is accepted. For an on-chain KMS CVM whose new compose hash is not registered yet, the API answers HTTP 465 and the method returns an *APIError. Call ComposePrecondition() on it to read the compose hash to register, then call again with opts.

result, err := client.UpdateDockerCompose(ctx, "my-app", composeYAML, nil)
var apiErr *phala.APIError
if errors.As(err, &apiErr) && apiErr.IsComposePrecondition() {
    precondition, _ := apiErr.ComposePrecondition()
    fmt.Println("Register compose hash:", precondition.ComposeHash)
} else if err != nil {
    log.Fatal(err)
}

UpdatePreLaunchScript

PATCH /cvms/{cvmId}/pre-launch-script Updates the shell script that runs before CVM containers start. Sent as text/plain.

func (c *Client) UpdatePreLaunchScript(ctx context.Context, cvmID, script string, opts *ComposeUpdateOptions) (*UpdateResult, error)

Parameters:

Field	Type	Required	Description
`cvmID`	`string`	Yes	CVM identifier
`script`	`string`	Yes	Shell script content
`opts`	`*ComposeUpdateOptions`	No	Compose hash and transaction hash headers

Returns: *UpdateResult

script := "#!/bin/sh\necho 'Pre-launch setup complete'"
result, err := client.UpdatePreLaunchScript(ctx, "my-app", script, nil)

CommitCVMUpdate

POST /cvms/{cvmId}/commit-update Commit a prepared on-chain update with its token, compose hash, and transaction hash. The response contains CorrelationID and Status.

result, err := client.CommitCVMUpdate(ctx, "my-app", &phala.CommitCVMUpdateRequest{
    Token:           token,
    ComposeHash:     composeHash,
    TransactionHash: transactionHash,
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.CorrelationID, result.Status)

UpdateCVMResources

PATCH /cvms/{cvmId} Updates the resource allocation (vCPUs, memory, disk) for a CVM. All fields are optional; only the fields you include will be changed.

func (c *Client) UpdateCVMResources(ctx context.Context, cvmID string, req *UpdateResourcesRequest) (*UpdateResourcesResponse, error)

UpdateResourcesRequest fields:

Field	Type	Description
`VCPU`	`*int`	Number of vCPUs
`Memory`	`*int`	Memory in MB
`DiskSize`	`*int`	Disk size in GB. A disk cannot shrink.
`InstanceType`	`*string`	Instance type override
`AllowRestart`	`*bool`	Deprecated and not sent. The CVM restarts whenever a resize needs it.

Returns: *UpdateResourcesResponse, an alias of CVMUpdateResponse (Message, CorrelationID, Status).

resp, err := client.UpdateCVMResources(ctx, "my-app", &phala.UpdateResourcesRequest{
    VCPU:     phala.Int(4),
    Memory:   phala.Int(8192),
    DiskSize: phala.Int(50),
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.CorrelationID)

UpdateCVMVisibility

PATCH /cvms/{cvmId} Controls which information about a CVM is publicly accessible. All fields are optional.

func (c *Client) UpdateCVMVisibility(ctx context.Context, cvmID string, req *UpdateVisibilityRequest) (*CVMUpdateResponse, error)

UpdateVisibilityRequest fields:

Field	Type	Description
`PublicSysinfo`	`*bool`	Make system info public
`PublicLogs`	`*bool`	Make logs public
`PublicTcbinfo`	`*bool`	Make TCB info public

Returns: *CVMUpdateResponse (Message, CorrelationID, Status). Status is "no_change" with an empty CorrelationID when the settings already match. These settings are part of the compose hash. For a CVM on Onchain KMS, the API answers HTTP 465 until the new hash is registered on-chain. Use PatchCVM, which returns the hash to register.

resp, err := client.UpdateCVMVisibility(ctx, "my-app", &phala.UpdateVisibilityRequest{
    PublicSysinfo: phala.Bool(true),
    PublicLogs:    phala.Bool(true),
})
if err != nil {
    log.Fatal(err)
}

UpdateCVMListed

PATCH /cvms/{cvmId}/listed Sets whether the app is listed on the public Trust Center. The listing applies to every CVM of the app. It only changes a record in Phala Cloud: no compose change and no restart.

func (c *Client) UpdateCVMListed(ctx context.Context, cvmID string, listed bool) error

UpdateCVMEnvs

PATCH /cvms/{cvmId}/envs Updates the encrypted environment variables for a CVM. Environment variables are encrypted client-side before being sent to the API. ProvisionComposeUpdateRequest.EncryptedEnv has been removed; use UpdateCVMEnvs for environment changes instead.

func (c *Client) UpdateCVMEnvs(ctx context.Context, cvmID string, req *UpdateEnvsRequest) (*UpdateResult, error)

UpdateEnvsRequest fields:

Field	Type	Required	Description
`EncryptedEnv`	`string`	Yes	Hex-encoded encrypted environment variables
`EnvKeys`	`[]string`	No	List of environment variable key names
`ComposeHash`	`*string`	No	Compose hash for on-chain verification
`TransactionHash`	`*string`	No	On-chain transaction hash

Returns: *UpdateResult

result, err := client.UpdateCVMEnvs(ctx, "my-app", &phala.UpdateEnvsRequest{
    EncryptedEnv: encryptedHex,
    EnvKeys:      []string{"DATABASE_URL", "SECRET_KEY"},
})

UpdateOSImage

PATCH /cvms/{cvmId}/os-image Updates the OS image for a CVM. The CVM will need a restart to apply the new image.

func (c *Client) UpdateOSImage(ctx context.Context, cvmID string, req *UpdateOSImageRequest) error

UpdateOSImageRequest fields:

Field	Type	Required	Description
`OSImageName`	`string`	Yes	Name of the target OS image

Returns: error. The API answers with {message, correlation_id, status}, but UpdateOSImage discards it.

err := client.UpdateOSImage(ctx, "my-app", &phala.UpdateOSImageRequest{
    OSImageName: "dstack-v0.4.0",
})

PatchCVM

PATCH /cvms/{cvmId} Applies a multi-field update to a CVM in a single request. You can change compose, resources, visibility, and more in one call. Compose is a JSON Merge Patch of the app compose. Each ComposePatch key is a Patch[T]: leave it zero to keep the value, use phala.PatchValue(v) to set it, or phala.PatchNull[T]() to remove it. See How does the compose patch work? for the keys. To change a bash runner’s script, set ComposePatch.BashScript. To change the Trust Center listing, use UpdateCVMListed.

func (c *Client) PatchCVM(ctx context.Context, cvmID string, req *PatchCVMRequest) (*PatchCVMResponse, error)

PatchCVMRequest fields:

Field	Type	Description
`DockerComposeFile`	`*string`	Docker Compose YAML
`PreLaunchScript`	`*string`	Pre-launch shell script
`EncryptedEnv`	`*string`	Encrypted environment variables
`AllowedEnvs`	`[]string`	Allowed environment variable keys
`PublicSysinfo`	`*bool`	Make system info public
`PublicLogs`	`*bool`	Make logs public
`PublicTcbinfo`	`*bool`	Make TCB info public
`Compose`	`*ComposePatch`	Other compose settings as a merge patch
`InitScripts`	`[]InitScriptSlug`	Platform init scripts the CVM runs (`InitScriptDockerCleanup`, `InitScriptEnvMerge`), replacing the current set. `nil` keeps them; an empty non-nil slice removes them all.
`ConfirmDataWipe`	`bool`	Confirms turning on `docker_cleanup` or `requirements.ephemeral_data_disk`, which erase data on every boot
`UserConfig`	`*string`	User configuration string
`GPUs`	`*GPUConfig`	GPU assignment: `GPUs []GPUSpec{Slot, ProductID}` and `AttachMode`. `AttachMode` `"all"` attaches every GPU on the node.
`VCPU`	`*int`	Number of vCPUs
`Memory`	`*int`	Memory in MB
`DiskSize`	`*int`	Disk size in GB
`InstanceType`	`*string`	Instance type
`Image`	`*string`	OS image name or slug, as listed by `GetAvailableOSImages`
`OSImageName`	`*string`	Deprecated. Sent as `image`; an error if it differs from `Image`.
`ShutdownTimeout`	`*int`	Seconds to wait for a clean shutdown (10 to 1200)
`AllowForceStop`	`*bool`	Skip the clean shutdown and stop the CVM at once
`PrepareOnly`	`bool`	Sent as the `X-Prepare-Only: true` header. When the API answers 465 (the new compose hash is not on the app contract yet), the response also carries a commit token for multisig approval. It is not a dry run: if no on-chain registration is needed, the update starts.

A nil AllowedEnvs slice omits the field; an explicitly empty slice sends [] to clear it. Returns: *PatchCVMResponse. A 465 answer is not an error: RequiresOnChainHash is true and the response carries ComposeHash, AppID, DeviceID and KMSInfo, plus CommitToken, CommitURL, APICommitURL and OnchainStatus with PrepareOnly. Otherwise it carries CorrelationID and Status; Status is "no_change" with an empty CorrelationID when nothing had to change.

compose := "services:\n  app:\n    image: nginx:latest\n"
resp, err := client.PatchCVM(ctx, "my-app", &phala.PatchCVMRequest{
    DockerComposeFile: &compose,
    PublicSysinfo:     phala.Bool(true),
    VCPU:              phala.Int(4),
    Compose: &phala.ComposePatch{
        SwapSize: phala.PatchValue("2G"),
    },
})
if err != nil {
    log.Fatal(err)
}

if resp.RequiresOnChainHash {
    // Handle on-chain confirmation — see ConfirmCVMPatch
    fmt.Printf("On-chain confirmation needed. Compose hash: %s\n", resp.ComposeHash)
}

GetCVMInitScripts

GET /cvms/{cvmId}/init-scripts Lists the platform init scripts, in run order, and for each one whether the CVM runs it (Selected), whether you can pick it for this CVM (Selectable) and, if not, why (Reason). Change the selection with PatchCVM’s InitScripts. See Init scripts.

func (c *Client) GetCVMInitScripts(ctx context.Context, cvmID string) (*CVMInitScriptsResponse, error)

GetCVMAnnotations / UpdateCVMAnnotations

GET /cvms/{cvmId}/annotations / PUT /cvms/{cvmId}/annotations Reads or replaces the CVM’s annotations: key/value settings for tools on the host. They are not measured and attestation does not cover them. UpdateCVMAnnotations replaces every annotation, and an empty map clears them. It does not restart the CVM. Annotations sit behind a feature flag; without it, both calls fail with ERR-03-049. See Annotations.

func (c *Client) GetCVMAnnotations(ctx context.Context, cvmID string) (*CVMAnnotationsResponse, error)
func (c *Client) UpdateCVMAnnotations(ctx context.Context, cvmID string, annotations map[string]string) (*CVMAnnotationsResponse, error)

Returns: *CVMAnnotationsResponse with Annotations, the annotations the node now stores.

ConfirmCVMPatch

PATCH /cvms/{cvmId} Confirms a CVM patch that requires on-chain verification. Call this after PatchCVM returns RequiresOnChainHash: true and you have submitted the transaction on-chain.

func (c *Client) ConfirmCVMPatch(ctx context.Context, cvmID string, req *ConfirmCVMPatchRequest) (*CVMActionResponse, error)

ConfirmCVMPatchRequest fields:

Field	Type	Required	Description
`ComposeHash`	`string`	Yes	Compose hash from PatchCVM response
`TransactionHash`	`string`	Yes	On-chain transaction hash

The request sends an empty JSON object and supplies the hashes in the X-Compose-Hash and X-Transaction-Hash headers. The response retains the action fields and includes CorrelationID. ConfirmCVMPatchV20260121 returns the earlier ID shape. Returns: *CVMActionResponse

result, err := client.ConfirmCVMPatch(ctx, "my-app", &phala.ConfirmCVMPatchRequest{
    ComposeHash:     resp.ComposeHash,
    TransactionHash: transactionHash,
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.CorrelationID)

Compose File Operations

These methods let you provision and commit compose file updates using the two-phase flow, similar to initial CVM provisioning.

ProvisionCVMComposeFileUpdate

POST /cvms/{cvmId}/compose_file/provision Provisions a compose file update without applying it yet. Returns a compose hash for the commit step.

func (c *Client) ProvisionCVMComposeFileUpdate(ctx context.Context, cvmID string, req *ProvisionComposeUpdateRequest) (*ProvisionCVMResponse, error)

CommitCVMComposeFileUpdate

PATCH /cvms/{cvmId}/compose_file Commits a previously provisioned compose file update.

func (c *Client) CommitCVMComposeFileUpdate(ctx context.Context, cvmID string, req *CommitComposeUpdateRequest) error

Example — two-phase compose update:

// Step 1: Provision the update
provision, err := client.ProvisionCVMComposeFileUpdate(ctx, "my-app", &phala.ProvisionComposeUpdateRequest{
    DockerComposeFile: newComposeYAML,
})
if err != nil {
    log.Fatal(err)
}

// Step 2: Commit the update
err = client.CommitCVMComposeFileUpdate(ctx, "my-app", &phala.CommitComposeUpdateRequest{
    ComposeHash: provision.ComposeHash,
})
if err != nil {
    log.Fatal(err)
}

​UpdateDockerCompose

​UpdatePreLaunchScript

​CommitCVMUpdate

​UpdateCVMResources

​UpdateCVMVisibility

​UpdateCVMListed

​UpdateCVMEnvs

​UpdateOSImage

​PatchCVM

​GetCVMInitScripts

​GetCVMAnnotations / UpdateCVMAnnotations

​ConfirmCVMPatch

​Compose File Operations

​ProvisionCVMComposeFileUpdate

​CommitCVMComposeFileUpdate