Cloud Go SDK

Go client for the Phala Cloud API — manage CVMs, deployments, and infrastructure programmatically.

The Go SDK is currently in beta. The API surface may change between releases.

The phala Go package provides a strongly-typed client for the Phala Cloud API. It handles authentication, automatic retries with exponential backoff, and structured error responses out of the box.

Installation

Requires Go 1.25 or later.

go get github.com/Phala-Network/phala-cloud/sdks/go

Quick Start

package main

import (
	"context"
	"fmt"
	"log"

	phala "github.com/Phala-Network/phala-cloud/sdks/go"
)

func main() {
	client, err := phala.NewClient(
		phala.WithAPIKey("phak_your_api_key"),
	)
	if err != nil {
		log.Fatal(err)
	}

	user, err := client.GetCurrentUser(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Hello, %s!\n", user.User.Username)
}

Client Creation

NewClient(opts ...Option) (*Client, error)

Creates a new Phala Cloud API client. The API key is resolved from options first, then falls back to the PHALA_CLOUD_API_KEY environment variable. Returns an error if no API key is available.

// Minimal — reads API key from PHALA_CLOUD_API_KEY env var
client, err := phala.NewClient()

// Explicit configuration
client, err := phala.NewClient(
	phala.WithAPIKey("phak_your_api_key"),
	phala.WithBaseURL("https://cloud-api.phala.com/api/v1"),
	phala.WithTimeout(60 * time.Second),
	phala.WithMaxRetries(10),
)

Configuration Options

Every option is a function passed to NewClient. They follow Go’s functional options pattern, so you can combine as many as you need.

Option	Default	Description
WithAPIKey(key)	PHALA_CLOUD_API_KEY env var	API key for authentication
WithBaseURL(url)	https://cloud-api.phala.com/api/v1	API base URL (or PHALA_CLOUD_API_PREFIX env var)
WithAPIVersion(v)	"2026-06-23"	API version header value
WithTimeout(d)	no timeout	HTTP client timeout as time.Duration
WithMaxRetries(n)	30	Maximum retries for retryable errors (409/429/503)
WithHTTPClient(hc)	&http.Client{}	Custom *http.Client for full control
WithUserAgent(ua)	phala-cloud-sdk-go/0.2.0	Custom User-Agent header
WithHeader(key, val)	—	Add a custom header to all requests

Environment Variables

Variable	Description
PHALA_CLOUD_API_KEY	API key for authentication
PHALA_CLOUD_API_PREFIX	Override base URL

The client resolves environment variables automatically. If you pass an explicit option, it takes priority over the corresponding environment variable.

Pointer Helpers

Many request structs use pointer fields for optional values. The SDK provides helper functions to make this ergonomic:

phala.String("value")   // *string
phala.Int(4)            // *int
phala.Int64(100)        // *int64
phala.Float64(3.14)     // *float64
phala.Bool(true)        // *bool

These are especially useful when constructing request structs inline:

&phala.PatchCVMRequest{
	PublicSysinfo: phala.Bool(true),
	VCPU:          phala.Int(4),
	Memory:        phala.Int(8192),
}

CVM ID Resolution

The SDK automatically normalizes CVM identifiers before sending them to the API. You can pass any of the following formats to any method that accepts a cvmID string:

• UUID (with or without dashes) — dashes are stripped
• 40-char hex app ID — app_ prefix is added
• Integer ID, hashed ID, or name — used as-is

This means you never need to worry about converting between ID formats yourself.

Available Methods

Authentication & User

Method	Description
GetCurrentUser(ctx)	Get current user, workspace, and credits

CVM Lifecycle

Method	Description
ProvisionCVM(ctx, req)	Provision a new CVM
CommitCVMProvision(ctx, req)	Commit a provisioned CVM
StartCVM(ctx, id)	Start a stopped CVM
StopCVM(ctx, id)	Force-stop a CVM
ShutdownCVM(ctx, id)	Gracefully shut down a CVM
RestartCVM(ctx, id, opts)	Restart a CVM
DeleteCVM(ctx, id)	Permanently delete a CVM
ReplicateCVM(ctx, id, opts)	Replicate a CVM to another node

CVM Configuration

Method	Description
UpdateDockerCompose(ctx, id, yaml, opts)	Update Docker Compose config
UpdatePreLaunchScript(ctx, id, script, opts)	Update pre-launch script
UpdateCVMResources(ctx, id, req)	Update resource allocation
UpdateCVMVisibility(ctx, id, req)	Update visibility settings
UpdateCVMEnvs(ctx, id, req)	Update encrypted env vars
UpdateOSImage(ctx, id, req)	Update OS image
PatchCVM(ctx, id, req)	Multi-field update
ConfirmCVMPatch(ctx, id, req)	Confirm patch with on-chain hash
UpdateCVMListed(ctx, id, listed)	Update marketplace visibility in place

CVM Query

Method	Description
GetCVMList(ctx, opts)	List CVMs (paginated)
GetCVMInfo(ctx, id)	Get CVM details
GetCVMState(ctx, id)	Get CVM current state
GetCVMStats(ctx, id)	Get CVM system stats
GetCVMNetwork(ctx, id)	Get CVM network info
GetCVMContainersStats(ctx, id)	Get container stats
GetCVMAttestation(ctx, id)	Get TEE attestation
GetCVMUserConfig(ctx, id)	Get user configuration
WatchCVMState(ctx, id, opts)	Watch state changes via SSE
GetCVMStatusBatch(ctx, ids)	Get typed status and resource usage for multiple CVMs

Apps

Method	Description
GetAppList(ctx)	List applications
GetAppInfo(ctx, appID)	Get app details
GetAppCVMs(ctx, appID)	List CVMs for an app
CreateAppInstance(ctx, appID, req)	Create another instance for an app
GetAppRevisions(ctx, appID, opts)	List revision history
RedeployAppRevision(ctx, appID, revisionID, req)	Redeploy an app revision
GetAppAttestation(ctx, appID)	Get app attestation
GetAppDeviceAllowlist(ctx, appID)	Get device allowlist

Workspaces

Method	Description
ListWorkspaces(ctx)	List workspaces
GetWorkspace(ctx, slug)	Get workspace details
GetWorkspaceNodes(ctx, slug, opts)	List workspace nodes
GetWorkspaceQuotas(ctx, slug)	Get workspace quotas

Nodes, Instance Types, and OS Images

Method	Description
GetAvailableNodes(ctx)	List available TEE nodes
GetCVMCreateResources(ctx)	Get the CVM creation resource graph
ListAllInstanceTypeFamilies(ctx)	List all instance type families
ListFamilyInstanceTypes(ctx, family)	List instance types in a family
GetOSImages(ctx)	List public OS images

KMS

Method	Description
ListKMSContracts(ctx)	List KMS contracts
GetKMSContract(ctx, slug)	Get a KMS contract by slug or contract ID
ListKMSContractNodes(ctx, slug)	List node replicas under a KMS contract
GetKMSList(ctx)	List legacy node-centric KMS servers (deprecated)
GetKMSInfo(ctx, kmsID)	Get legacy node-centric KMS details
GetAppEnvEncryptPubKey(ctx, kmsType, appID)	Get env encryption public key
GetKMSOnChainDetail(ctx, chain)	Get KMS on-chain detail

SSH Keys

Method	Description
ListSSHKeys(ctx)	List SSH keys
CreateSSHKey(ctx, req)	Create an SSH key
DeleteSSHKey(ctx, keyID)	Delete an SSH key
ImportGithubProfileSSHKeys(ctx, username)	Import keys from GitHub profile
SyncGithubSSHKeys(ctx)	Sync keys from GitHub

Measurement Utilities

Function	Description
GetMrConfigId(input)	Compute V2 mr_config_id from fixed-size byte inputs
GetMrConfigIdHex(...)	Compute V2 mr_config_id from hex inputs
GetMrConfigIdV1(composeHash)	Compute the V1 compose-hash-only format
VerifyMrConfigId(...)	Verify a V2 mr_config_id

See KMS for examples.

Webhook Verification

Function	Description
VerifyWebhookSignature(secret, timestamp, body, signature)	Verify HMAC-SHA256 webhook signature
ParseWebhookEvent(headers, body, secret, tolerance...)	Verify signature and parse webhook event

event, err := phala.ParseWebhookEvent(r.Header, body, secret)
if err != nil {
    http.Error(w, "Invalid signature", http.StatusUnauthorized)
    return
}
fmt.Println(event.Event, string(event.Data))

See Webhooks for full payload format and delivery behavior.

Related

• Authentication — API key setup and custom headers
• CVM Lifecycle — provisioning, starting, stopping, deleting
• Error Handling — error types and retry logic
• Webhooks — webhook events, signatures, and delivery
• Cloud API Reference — full REST API docs