The Python SDK (dstack-sdk) provides a Python interface for applications running inside dstack CVMs to interact with the Guest Agent. It enables cryptographic key derivation, attestation quote generation, TLS certificate management, and other secure operations through a simple, Pythonic API.
For information about SDK design principles shared across all languages, see 9.1. SDK Architecture and Design Principles For core operations available in all SDKs, see 9.2. Core SDK Operations For cryptographic details, see 9.7. Cryptographic Operations and Algorithms
Sources: sdk/python/src/dstack_sdk/__init__.py1-53 sdk/python/pyproject.toml5-18
The Python SDK provides two main client classes:
DstackClient: Synchronous client for blocking operations sdk/python/tests/test_client.py28-29AsyncDstackClient: Asynchronous client for use with asyncio sdk/python/tests/test_client.py89-90Both clients communicate with the Guest Agent via Unix domain socket (defaulting to /var/run/dstack.sock) or HTTP, sending requests to the Guest Agent's RPC endpoints.
The SDK is built with modern Python practices, utilizing httpx for both sync and async transports, pydantic for robust data modeling, and comprehensive type stubs for IDE support sdk/python/pyproject.toml13-18
The following diagram illustrates the interaction between the Python SDK and the Guest Agent within the CVM environment.
SDK Communication Flow
Sources: sdk/python/pyproject.toml13-18 sdk/python/tests/test_client.py28-31 sdk/python/tests/test_client.py89-92
get_key)The get_key() method derives deterministic keys bound to the application's identity (app_id). The same path will always produce the same key for a specific application sdk/python/README.md35-37
client.get_key(path="wallet/eth", algorithm="secp256k1") sdk/python/tests/test_client.py28-31await client.get_key(path="wallet/eth", algorithm="ed25519") sdk/python/tests/test_client.py89-99Sources: sdk/python/tests/test_client.py28-42 sdk/python/README.md35-60
get_quote & attest)Generates a TDX quote proving the code is running in a genuine TEE. The attest method is a convenience wrapper that provides the full attestation object sdk/python/tests/test_client.py44-55
ValueError sdk/python/tests/test_client.py161-171 sdk/python/tests/test_client.py173-180GetQuoteResponse includes a replay_rtmrs() method to compute RTMR values from the event log for verification sdk/python/tests/test_client.py148-158Sources: sdk/python/tests/test_client.py44-55 sdk/python/tests/test_client.py148-158 sdk/python/tests/test_client.py161-180 sdk/python/README.md61-80
get_tls_key)Creates fresh TLS credentials. Unlike get_key, this generates a new random key for each call sdk/python/tests/test_client.py138-145
Sources: sdk/python/tests/test_client.py57-64 sdk/python/tests/test_client.py138-145 sdk/python/tests/test_client.py216-220 sdk/python/README.md98-123
The SDK uses Pydantic models to ensure type safety for all RPC responses. Key models include:
| Model | Purpose | Key Attributes |
|---|---|---|
GetKeyResponse | Result of key derivation | key, signature_chain sdk/python/src/dstack_sdk/__init__.py10 |
GetQuoteResponse | TDX quote data | quote, event_log sdk/python/src/dstack_sdk/__init__.py11 |
GetTlsKeyResponse | TLS credentials | key, certificate_chain sdk/python/src/dstack_sdk/__init__.py12 |
InfoResponse | Instance metadata | app_id, instance_id, tcb_info sdk/python/src/dstack_sdk/__init__.py13 |
TcbInfo | TEE measurements | mrtd, rtmr0-3, compose_hash sdk/python/src/dstack_sdk/__init__.py16 |
Sources: sdk/python/src/dstack_sdk/__init__.py1-53 sdk/python/tests/test_client.py15-25 sdk/python/tests/test_client.py72-86
The SDK includes specific modules for integrating derived keys with popular blockchain libraries. These are available via optional dependencies dstack-sdk[eth] and dstack-sdk[sol] sdk/python/pyproject.toml23-28
to_account_secure converts a GetKeyResponse into a LocalAccount using SHA256 hashing of the key material for enhanced security sdk/python/src/dstack_sdk/ethereum.py46-66to_keypair_secure converts the response into a solders.Keypair sdk/python/src/dstack_sdk/solana.py46-64Sources: sdk/python/src/dstack_sdk/ethereum.py1-67 sdk/python/src/dstack_sdk/solana.py1-65 sdk/python/pyproject.toml23-28
The Python SDK also provides utilities for deployment-time operations, such as encrypting environment variables for the KMS and calculating compose hashes.
encrypt_env_vars: Encrypts sensitive variables using the KMS public key sdk/python/src/dstack_sdk/encrypt_env_vars.py41-74get_compose_hash: Computes the deterministic hash of an AppCompose configuration sdk/python/src/dstack_sdk/get_compose_hash.py202-219verify_env_encrypt_public_key: Verifies the authenticity of the public key used for environment encryption sdk/python/src/dstack_sdk/verify_env_encrypt_public_key.py15-78Sources: sdk/python/src/dstack_sdk/__init__.py19-27 sdk/python/src/dstack_sdk/get_compose_hash.py1-219 sdk/python/src/dstack_sdk/encrypt_env_vars.py1-104
Entity Mapping: Python Code to System Roles
Sources: sdk/python/src/dstack_sdk/ethereum.py46-49 sdk/python/src/dstack_sdk/solana.py46-49 sdk/python/src/dstack_sdk/get_compose_hash.py202-219 sdk/python/src/dstack_sdk/encrypt_env_vars.py41-74
The SDK is managed using pdm sdk/python/pyproject.toml31-32
ruff for linting and formatting, and mypy for static type checking sdk/python/pyproject.toml61-109pytest and pytest-asyncio for verification sdk/python/pyproject.toml118-123Sources: sdk/python/pyproject.toml1-137 sdk/python/tests/test_client.py1-215
Refresh this wiki