Skip to main content
CVM configuration methods let you modify a running or stopped CVM without recreating it.
Every configuration update triggers a CVM restart. The CVM will be stopped, updated, and restarted automatically. Plan updates accordingly to minimize downtime.
Each UpdateXxxx method targets a single aspect of the CVM (compose file, resources, visibility, etc.) and calls a dedicated API endpoint. PatchCVM is the unified method that can update multiple fields in a single request — internally it calls PATCH /cvms/{cvmId}. Use PatchCVM when you need to change several settings atomically; use the individual UpdateXxxx methods when you only need to change one thing. 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:
FieldTypeRequiredDescription
cvmIDstringYesCVM identifier
composestringYesDocker Compose YAML content
opts*ComposeUpdateOptionsNoCompose hash and transaction hash headers
ComposeUpdateOptions fields:
FieldTypeDescription
ComposeHashstringCompose hash for on-chain verification (sent as X-Compose-Hash)
TransactionHashstringOn-chain transaction hash (sent as X-Transaction-Hash)
Returns: *UpdateResult which may indicate that on-chain confirmation is needed. 
result, err := client.UpdateDockerCompose(ctx, "my-app", composeYAML, nil)
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:
FieldTypeRequiredDescription
cvmIDstringYesCVM identifier
scriptstringYesShell script content
opts*ComposeUpdateOptionsNoCompose hash and transaction hash headers
Returns: *UpdateResult 
script := "#!/bin/sh\necho 'Pre-launch setup complete'"
result, err := client.UpdatePreLaunchScript(ctx, "my-app", script, nil)

​
UpdateCVMResources

PATCH /cvms/{cvmId}/resources 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) error
UpdateResourcesRequest fields:
FieldTypeDescription
VCPU*intNumber of vCPUs
Memory*intMemory in MB
DiskSize*intDisk size in GB
InstanceType*stringInstance type override
AllowRestart*boolAllow automatic restart if needed
Returns: error (no response body on success) 
err := client.UpdateCVMResources(ctx, "my-app", &phala.UpdateResourcesRequest{
	VCPU:         phala.Int(4),
	Memory:       phala.Int(8192),
	DiskSize:     phala.Int(50),
	AllowRestart: phala.Bool(true),
})
Resource changes may require a CVM restart. Set AllowRestart to true if you want the restart to happen automatically.

​
UpdateCVMVisibility

PATCH /cvms/{cvmId}/visibility Controls which information about a CVM is publicly accessible. All fields are optional. 
func (c *Client) UpdateCVMVisibility(ctx context.Context, cvmID string, req *UpdateVisibilityRequest) (*CVMVisibility, error)
UpdateVisibilityRequest fields:
FieldTypeDescription
PublicSysinfo*boolMake system info public
PublicLogs*boolMake logs public
PublicTcbinfo*boolMake TCB info public
Returns: *CVMVisibility with the updated visibility settings. 
visibility, err := client.UpdateCVMVisibility(ctx, "my-app", &phala.UpdateVisibilityRequest{
	PublicSysinfo: phala.Bool(true),
	PublicLogs:    phala.Bool(true),
})
if err != nil {
	log.Fatal(err)
}

​
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. 
func (c *Client) UpdateCVMEnvs(ctx context.Context, cvmID string, req *UpdateEnvsRequest) (*UpdateResult, error)
UpdateEnvsRequest fields:
FieldTypeRequiredDescription
EncryptedEnvstringYesHex-encoded encrypted environment variables
EnvKeys[]stringNoList of environment variable key names
ComposeHash*stringNoCompose hash for on-chain verification
TransactionHash*stringNoOn-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:
FieldTypeRequiredDescription
OSImageNamestringYesName of the target OS image
Returns: error (no response body on success) 
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. This is the most flexible update method — you can change compose, resources, visibility, and more in one call. 
func (c *Client) PatchCVM(ctx context.Context, cvmID string, req *PatchCVMRequest) (*PatchCVMResponse, error)
PatchCVMRequest fields:
FieldTypeDescription
DockerComposeFile*stringDocker Compose YAML
PreLaunchScript*stringPre-launch shell script
EncryptedEnv*stringEncrypted environment variables
AllowedEnvs[]stringAllowed environment variable keys
PublicSysinfo*boolMake system info public
PublicLogs*boolMake logs public
PublicTcbinfo*boolMake TCB info public
SecureTime*boolEnable/disable secure time
Listed*boolPublicly listed
VCPU*intNumber of vCPUs
Memory*intMemory in MB
DiskSize*intDisk size in GB
InstanceType*stringInstance type
OSImageName*stringOS image name
AllowRestart*boolAllow automatic restart
Returns: *PatchCVMResponse — check RequiresOnChainHash to see if on-chain confirmation is needed. 
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),
})
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)
}

​
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:
FieldTypeRequiredDescription
ComposeHashstringYesCompose hash from PatchCVM response
TransactionHashstringYesOn-chain transaction hash
Returns: *CVMActionResponse 
_, err := client.ConfirmCVMPatch(ctx, "my-app", &phala.ConfirmCVMPatchRequest{
	ComposeHash:     resp.ComposeHash,
	TransactionHash: "0xabc123...",
})

​
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)
}