Skip to content

api-reference.md

Latest commit

 

History

History
190 lines (129 loc) · 4.14 KB

api-reference.md

File metadata and controls

190 lines (129 loc) · 4.14 KB

API Reference

This document describes the APIs exposed by dstack-cloud components.

Guest Agent API (Unix Socket)

The Guest Agent runs inside each dstack CVM and provides local APIs via a Unix socket at /var/run/dstack.sock.

Get TDX Quote

Obtain a TDX attestation quote from the hardware.

GCP (TDX) only.

curl --unix-socket /var/run/dstack.sock \
  "http://localhost/GetQuote?report_data=0x1234deadbeef"

Parameters:

Parameter Type Description
report_data string (hex) Optional challenge value (32 bytes). Used to prevent replay attacks.

Response:

{
  "quote": "<base64-encoded TDX Quote>",
  "rtmr0": "...",
  "rtmr1": "...",
  "rtmr2": "...",
  "rtmr3": "..."
}

Get NSM Attestation

Obtain a Nitro Attestation Document from the NSM.

AWS Nitro only.

curl --unix-socket /var/run/dstack.sock \
  "http://localhost/GetAttestation?user_data=0x1234deadbeef"

Parameters:

Parameter Type Description
user_data string (hex) Optional challenge value.

Response:

{
  "document": "<base64-encoded NSM Attestation Document>"
}

Get Attestation (HTTP)

External attestation endpoint, accessible via HTTPS.

curl https://your-app.example.com/attestation

Response: Full attestation data (Quote or Document) for external verification.

KMS API

The KMS exposes an RPC interface for key management. All communication uses RA-TLS — the KMS verifies the workload's attestation before processing any request.

getKey(name)

Request a key from the KMS.

# Called from within the application via dstack SDK
# Not directly callable via curl (requires RA-TLS handshake)

Parameters:

Parameter Type Description
name string The name of the requested key. Keys are scoped per application.

Returns: The requested key as raw bytes.

Error Codes:

Error Description
UNAUTHORIZED Workload attestation verification failed. The workload is not running in a verified TEE.
MEASUREMENT_NOT_FOUND The workload's measurement is not registered on-chain.
KEY_NOT_FOUND No key exists for the requested name.
INTERNAL_ERROR KMS encountered an internal error.

How Applications Use getKey

Applications retrieve keys through the dstack SDK, which handles attestation and the RA-TLS connection automatically:

Python:

from dstack import DstackClient

client = DstackClient()
key = client.get_key("my-api-key")

TypeScript:

import { DstackClient } from '@dstack/sdk';

const client = new DstackClient();
const key = await client.getKey("my-api-key");

Rust:

use dstack_sdk::DstackClient;

let client = DstackClient::new()?;
let key = client.get_key("my-api-key")?;

KMS Onboard API (HTTP, Bootstrap Only)

These endpoints are only available during the first-time bootstrap (Onboard mode). After bootstrap is completed, KMS switches to RA-TLS-only mode.

Onboard.Bootstrap

Generate the KMS key pair and obtain attestation information.

curl -s "http://<KMS_URL>:12001/prpc/Onboard.Bootstrap?json" \
  -d '{"domain": "<KMS_DOMAIN>"}'

Parameters:

Parameter Type Description
domain string The domain name or IP address where KMS is accessible. Used in the attestation data.

Response:

{
  "publicKey": "...",
  "attestation": "...",
  "measurement": "..."
}

/finish

Complete the bootstrap process. KMS restarts and switches to Normal mode (HTTPS + RA-TLS).

curl "http://<KMS_URL>:12001/finish"

Response: HTTP 200 on success.

Docker Compose Volume for Guest Agent

To access the Guest Agent from within a Docker container, mount the socket:

services:
  my-app:
    image: my-app:latest
    volumes:
      - /var/run/dstack.sock:/var/run/dstack.sock

Next Steps