Instances
Choose a TEE, location, size and image; create, wait for, rename, extend and delete confidential VMs.
An instance is one confidential VM. You choose its shape when you create it, and the shape is fixed for its life: to change the size, image, disks or network, create a new instance.
What you choose
TEE: Intel TDX or AMD SEV-SNP
tee | Hardware | What the quote measures |
|---|---|---|
tdx | Intel Xeon with Trust Domain Extensions | MRTD and RTMR[1] and RTMR[2] for the image, RTMR[3] for your keys |
sev-snp | AMD EPYC with Secure Nested Paging | the launch digest for the image, HOST_DATA for your keys |
Both encrypt the guest's memory and registers so that the host, its operators and other tenants cannot read them. tee is optional: without it the platform picks one TEE that runs your image and size, and the response's tee names the choice, which holds for the instance's life. Pin tee when you need a particular verifier or hardware.
Location
GET /v1/locations lists where instances run, which TEEs each location offers, and which location is the default for each TEE:
{
"items": [
{ "id": "us-west-1", "displayName": "US West (Hillsboro, Oregon)", "country": "US", "tees": ["sev-snp", "tdx"], "defaultFor": ["sev-snp", "tdx"],
"publicIpModes": ["shared", "dedicated"], "hostnameDomain": "hil1.compute.confidential.ai", "ipv6": false, "privateNetworks": false },
{ "id": "ca-east-1", "displayName": "Canada East (Beauharnois, Quebec)", "country": "CA", "tees": ["sev-snp"], "defaultFor": [],
"publicIpModes": ["shared", "dedicated"], "hostnameDomain": "bhs1.compute.confidential.ai", "ipv6": false, "privateNetworks": false }
]
}A location's id names its area, a direction and a number, such as us-west-1; a second site in the same area takes the next number. displayName says where it is. Pass the id as location in a create or a list filter.
Every create names its location: the platform never picks one for you. When the instances don't fit there, the 409 insufficient_capacity problem lists in details.alternatives the other locations where they would fit now.
Size
Sizes are a fixed catalog. Read ids from GET /v1/sizes rather than building them:
| Family | Shape | Ids |
|---|---|---|
c1 | 2 GiB per vCPU | c1.2x, c1.4x, c1.8x, c1.16x |
s1 | 4 GiB per vCPU | s1.2x, s1.4x, s1.8x, s1.16x |
m1 | 8 GiB per vCPU | m1.2x, m1.4x, m1.8x |
g1-b300 | NVIDIA B300 GPUs, 8 vCPUs and 64 GiB per GPU | g1-b300.1x, .2x, .4x, .8x |
Each size lists its tees and its purchaseOptions. CPU sizes are on-demand. GPU sizes come by reservation or as spot; see GPUs. A size whose locations is empty is not offered in any region yet.
Each size lists the regions that offer it in locations, with the TEEs it runs on in each, so name one of those in location. For a CPU size, each of them carries onDemandAvailable: whether one instance of the size had room there as the API answered, counted as a create counts it. The size's own onDemandAvailable is true when any region's is. It is a look, not a hold: a create can still be refused with insufficient_capacity, and false turns true as instances are deleted. GET /v1/capacity says how many one create could get in each region and TEE, within your quotas, as maxCount, with the same caveat. The console greys out a size that has no room in the region you picked, and marks the regions that do not have the size.
Image
GET /v1/images lists the image versions your organization can launch. Name an image by family, such as confos-cpu, to get its newest active version, or pin one as confos-cpu@2026.10.17. A new version takes creates on a TEE only once it has passed the platform's boot test there; until then the family's name gives you the newest active version that has, or if none has, the newest deprecated version still accepting creates that has. Where the newest version does not sell the size you ask for yet, the name gives you the newest one that does. The response always says which version and digest boots.
Each image has a launch contract in launch. Read it before you create:
| Field | Meaning |
|---|---|
access | sshKeys: send access.sshKeys. launchKey: send trust.launchKey and the listed signed trust.initData format. launchFile: send only trust.initData, containing the measured configuration. |
disks | The disks you may list, which are required, their minSizeGiB, and their encryption. |
attestationPort, attestationPublic | Where the image serves quotes, and whether that port is published as the endpoint named attest. |
readiness.tcpPorts | The guest ports the platform dials before it reports the instance Reachable. |
minMemoryGiB | The smallest memory the image runs in. |
Each of the image's artifacts is one build for one TEE, with the sizes it runs on and its signed referenceManifest. An image runs every size with the memory its launch contract needs (minMemoryGiB), and GPU sizes only if it runs GPUs, so a new size is offered on each image it fits.
The image families you are most likely to see (GET /v1/images lists the ones open to your organization):
confos-cpu, the general-purpose image: you log in over SSH with your own keys, and itsattestendpoint returns a quote that also covers the SSH host keys, so you can pin them. It needs auser-datadisk.c8s-node, a node of a confidential Kubernetes cluster: it takes a launch key and a signed launch document instead of SSH keys.confos-gpu, the general-purpose image with NVIDIA's GPU stack (the CC driver, CUDA, NCCL and Docker) and the same SSH keys,user-datadisk andattestendpoint asconfos-cpu. It is TDX only, and lists its GPU sizes once they are offered; see GPUs.c8s-pod, the c8s node image booted as a single confidential pod with no Kubernetes cluster around it. It takes a launch key and a signed launch document asc8s-nodedoes, and needs no disk and less memory than a node; read itslaunchfor the exact floor. Without a disk, the pod's container image layers and writable state live in guest memory: pick a size with room for them, or add the optionalcontainerddisk for large images.
A c8s pod
Read the selected version's launch.initDataFormats first. Historical images such as 2026.10.30-1 take c8s-launch/v1 and need the CLI from their release. A version listing c8s-launch/v2 requires a separate measured CDS VM and a matching v2 CLI. Its Pod launch carries the CDS endpoint and the policy that binds the CDS image to its exact configuration.
For a v2 image, prepare CDS as described below, then create the Pod bundle from a Kubernetes v1 Pod manifest with metadata.uid set:
c8s node launch-config new-pod --out ./my-pod --cluster-id my-pod \
--image-manifest pod-manifest.json \
--server-address <cluster-server-ip> --server-public-key server.pub \
--cds-address <cds-host:port> --cds-image-policy-file cds-pin.json \
--pod-manifest pod.yaml --workloads workloads.jsonpod-manifest.json is the reference manifest published with the exact c8s-pod version. The server fields identify the cluster; the separate CDS fields select and authenticate CDS. The generated Pod key must differ from the server key. Send my-pod/pod/pubkey as trust.launchKey, and my-pod/pod/launch.yaml and launch.yaml.sig, base64-encoded, as trust.initData with format: c8s-launch/v2. Keep my-pod/pod.key private. Pod CVMs currently require TDX.
The create checks the two against the document. A trust.launchKey the document does not name for its role, or a signature that does not verify over the document's exact bytes, returns 422; a document with YAML anchors or aliases, more than one document, or an unknown role returns 400. The same checks apply to c8s-node.
The pod serves its status and attestation on private port 8443, with no automatic attest endpoint. Open 8443 as an ingress rule, then verify the pod and read its status, with --node set to that endpoint. Applications communicate through the c8s mesh and can reach the internet; host ports are not required for Pod readiness.
c8s pod-attest --node <host:port> --launch-key-pub my-pod/pod/pubkey --image-manifest pod-manifest.json
c8s pod-status get --node <host:port> --launch-key-pub my-pod/pod/pubkey --image-manifest pod-manifest.jsonpod-attest prints the image, the launch key's SHA-256 and the container image digests the pod measured; --expect-digest, repeated, fails unless the measured set is exactly the one you give. pod-status get verifies the pod the same way and prints the pod as v1 Pod JSON. See Attestation for what the quote binds.
A measured CDS
A catalog version with launch contract c8s-cds/1 uses a dedicated CDS image, separate from the Pod image. Generate its configuration and cds-pin.json with the matching c8s cds config new command, using that CDS version's reference manifest and the Pod image/key authority the CDS should admit. Follow the C8s launch guide for the policy inputs.
Send only the generated configuration through trust.initData:
{
"trust": {
"initData": {
"format": "c8s-cds/v1",
"document": "<base64 of the exact cds-config.yaml bytes>"
}
}
}The image advertises access: launchFile. No launch key or signature accompanies this document. The API accepts at most 64 KiB of UTF-8 and writes those exact decoded bytes as the sole pubkey file on the measured launch disk. Do not change whitespace or line endings after generating its pin. The document is host-visible, must contain no secrets, and is never returned by the API. It is sealed in storage until the cluster owns its immutable launch Secret; afterward the database retains only its launch-binding hashes.
CDS needs no scratch disk and has no SSH service or automatic TCP readiness probe. Open an ingress named cds to guest port 8443, then authenticate it with c8s cds ca --url https://<host:port> --image-policy-file cds-pin.json. Cloud's Reachable status does not prove CDS identity or readiness. The Pod launch must name the same endpoint and pin. CDS currently holds its CA and policy changes in memory: restarting it creates a new CA and requires recreating members and restoring policy, as described in the C8s guide.
The c8s-cds-ha image is the CDS of C8s main, built from 173b9d467 for 2026.11.10-1. It certifies c8s nodes, and Pod CVMs only under a podImagePolicy its configuration names. In Cloud it can run as a one-replica cluster. That cluster cannot gain a replica, because instances cannot reach each other, and a restart loses its state. To run one:
- Generate the configuration with the same build's
c8s cds config new, adding--replica 10.0.2.2 --voters 1. 10.0.2.2 is the guest's own address in Cloud. Give each such cluster its ownclusterID. - Create the instance with that configuration and the ingress to 8443 above.
- Start the cluster with the Genesis runbook, adding
--aloneso it starts without other replicas, and--target <host:port>naming the endpoint. - Read it with
c8s cds ha status --config cds-config.yaml --cds-pin cds-pin.json --url <host:port>.
A public container image
image can instead name a public OCI container image, by a reference with a / as docker pull takes it: ghcr.io/org/app:1.2, ghcr.io/org/app@sha256:… or docker.io/library/nginx:1.29. This is open to internal organizations for now: it needs an image version whose launch.containers is true, and the current one, confos-cpu@2026.10.29, is internal.
{
"name": "app",
"location": "us-west-1",
"size": "s1.2x",
"image": "ghcr.io/org/app:1.2",
"container": { "command": [ "serve", "--port", "8080" ], "env": { "LOG_LEVEL": "info" } },
"network": { "ingress": [ { "name": "http", "port": 8080 } ] },
"readiness": { "tcpPorts": [ 8080 ] }
}- The API resolves a tag to its digest at create, without credentials. An image the registry does not serve anonymously returns
400with violationnot_found. - The instance boots the newest image version your organization can use that runs containers and the size, and the response's
imagenames it. That image pulls the container by digest at every boot and runs it as the instance's only workload. - The container runs on the instance's own network, so it listens on guest ports: open them with
network.ingress, and name one inreadinessto haveReachablewait for it. container.commandreplaces the image's default command, andcontainer.envsets its environment. Both are bound into the measurement and are visible to the host: never put a secret in them.access.sshKeysis optional. Withoutdisks, the instance gets the disks its image requires at their smallest size and a 20 GiB encrypted scratch disk for the container's state.- The response's
containergives the reference, the digest every boot pulls, andlaunchLine, the line the measurement binds: a quote whose launch binding matches it proves the instance was launched to run exactly this image, command and environment.
Without an image version that runs containers, the create returns 422 unsupported_combination with violation incompatible on /image. container with a catalog image is also a 422.
Disks
The root disk is a read-only, measured image. You add writable disks from the launch contract:
encryption | Behaviour |
|---|---|
guest | Encrypted inside the guest under a key made at each boot. It reads as empty after every boot. Use it for anything secret. |
none | Survives reboots until the instance is deleted, and the host can read and change it. confos-cpu's user-data is one: never keep a secret there unencrypted. |
boot.count goes up at every boot, so you can tell when guest-encrypted disks were wiped.
Create
curl https://api.cloud.confidential.ai/v1/instances \
-H "Authorization: Bearer $CC_API_KEY" \
-H "Api-Version: 2026-10-15" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "web",
"count": 1,
"size": "s1.4x",
"image": "confos-cpu",
"tee": "sev-snp",
"location": "us-west-1",
"disks": [
{ "name": "user-data", "type": "scratch", "sizeGiB": 20 },
{ "name": "data", "type": "scratch", "sizeGiB": 100 }
],
"network": { "ingress": [ { "name": "ssh", "port": 22 }, { "name": "https", "port": 443 } ] },
"access": { "sshKeys": [ "ssh-ed25519 AAAA… you@laptop" ] },
"labels": { "app": "web", "env": "prod" },
"expiresAt": "2026-11-01T00:00:00Z"
}'countcreates 1 to 16 identical instances, all or none. With aname, they are namedweb-0,web-1and so on.labelsare Kubernetes-style key/value pairs you can filter on. They are not secret.expiresAtdeletes the instances at that time. Without it they run until you delete them.placementwith policycolocateputs instances that name the same group on one host.
The create returns 202 with every instance provisioning and its endpoints already assigned: the platform chooses each instance's host before it answers, and endpoints never change.
Statuses
| Status | Meaning |
|---|---|
provisioning | Accepted and placed; its host has not started the guest yet. |
running | The host started the guest and keeps it running, starting it again at once whenever it exits, with the reason restarting until the next boot runs. Whether the guest answers is the Reachable condition. |
failed | The platform stopped trying (launch_failed, host_lost, image_unavailable). It stays until you delete it. |
stopped | The guest is stopped (a preempted spot GPU instance). Disks, addresses and endpoints stay; POST /v1/instances/{id}/start starts it again. |
terminating | Delete requested; the guest or its disks may still exist. |
terminated | Gone. The tombstone stays for 90 days. |
unknown | The host has not reported for 60 seconds. Leave the instance alone: it is probably still running. |
statusReason says why, and conditions carries signals such as Reachable, with a reason like TcpDialSucceeded or TcpDialTimedOut. No condition ever says whether the instance can be trusted: verify it yourself.
Confidential VMs cannot migrate, so an instance never moves. If its host is lost, the instance becomes failed with host_lost, and the platform never re-creates it elsewhere for you.
Wait
curl "https://api.cloud.confidential.ai/v1/instances/$ID?waitFor=reachable&timeoutSeconds=60" \
-H "Authorization: Bearer $CC_API_KEY" -H "Api-Version: 2026-10-15"waitFor is running, reachable or terminated. The call returns as soon as the instance reaches the target or failed, stopped, terminated or unknown, and returns the current state with 200 when the time runs out. Loop on bounded waits; there is no unbounded one. While the instance is unknown the wait returns at once, so pause about 30 seconds between calls.
List and get
curl "https://api.cloud.confidential.ai/v1/instances?label=app=web&status=running&pageSize=50" \
-H "Authorization: Bearer $CC_API_KEY" -H "Api-Version: 2026-10-15"Filter by label, status, tee, location, project, reservation or idempotencyKey. Lists return {items, nextPageToken}; pass pageToken back with the same filters for the next page. Without status, terminated tombstones are left out.
Rename
curl -X PATCH https://api.cloud.confidential.ai/v1/instances/$ID \
-H "Authorization: Bearer $CC_API_KEY" -H "Api-Version: 2026-10-15" \
-H "Content-Type: application/json" -d '{ "name": "web-prod" }'Only the name changes: the id, hostnames, endpoints and guest stay. A name another live instance has returns 409 name_conflict. The same call turns a GPU instance's GPU metrics on or off with gpuMetrics.
Extend
curl -X POST https://api.cloud.confidential.ai/v1/instances/$ID/extend \
-H "Authorization: Bearer $CC_API_KEY" -H "Api-Version: 2026-10-15" \
-H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
-d '{ "expiresAt": "2026-12-01T00:00:00Z" }'extend moves expiresAt later; nothing moves it earlier or removes it, and an instance created without an expiry cannot be given one. In its last ten minutes a running instance has reason expiring, and once deleted its tombstone has reason expired.
Delete
curl -X DELETE https://api.cloud.confidential.ai/v1/instances/$ID \
-H "Authorization: Bearer $CC_API_KEY" -H "Api-Version: 2026-10-15"Deleting returns 202 with the instance terminating, then 200 with its tombstone once the guest and disks are gone; repeating it is safe. A delete always wins, even while the host is unknown: the instance then stays terminating until its host reports or is retired.
Deleting destroys every disk of the instance. It cannot be undone.