This document provides a technical introduction to the dstack confidential computing framework. It explains the core architecture, key components, and how they work together to enable running Docker-based applications inside Trusted Execution Environments (TEEs).
This page covers the high-level system design and component interactions. For detailed information on specific subsystems:
dstack is an open framework that enables confidential computing for containerized applications. It allows Docker Compose applications to run inside Confidential Virtual Machines (CVMs) with hardware-based memory encryption, without requiring code changes or custom SDKs.
The framework provides:
| Feature | Implementation |
|---|---|
| Docker-native deployment | Parse docker-compose.yaml files directly via VMM |
| Hardware-rooted security | Intel TDX for CPU/memory, NVIDIA Confidential Computing for GPU |
| Attestation-based identity | TDX quotes prove what code is running |
| Isolated key management | Per-app keys derived in TEE, never exposed to operators |
| Transparent governance | Authorization policies enforced via smart contracts |
Applications communicate with the Guest Agent running inside the CVM through a Unix socket at /var/run/dstack.sock to access cryptographic primitives (keys, quotes, signatures) without leaving the TEE boundary.
Sources: README.md19-40 docs/confidential-ai.md1-26
dstack consists of four primary services that operate across different security domains:
Sources: README.md62-77 docs/deployment.md6-10
The VMM runs on bare-metal TDX-capable hosts and orchestrates CVM lifecycle. It parses Docker Compose files, allocates resources, and spawns QEMU processes with TDX enabled.
| Responsibility | Implementation |
|---|---|
| Parse docker-compose.yaml | vmm/src/docker_compose.rs |
| Manage VM lifecycle | vmm/src/vmm_service.rs App and AppState structures |
| Generate QEMU command-line | vmm/src/qemu_args.rs |
| Allocate CID pool | Configuration via cid_start and cid_pool_size in vmm.toml |
| Serve web dashboard | HTTP API on port 9080 by default |
Configuration file: vmm.toml
Sources: README.md76-77 docs/deployment.md131-169
The KMS runs inside its own CVM and manages cryptographic keys. It verifies TDX attestation quotes before releasing keys and enforces authorization policies.
| Responsibility | Implementation |
|---|---|
| Verify attestation quotes | kms/src/service/quote_verification.rs |
| Derive per-app keys | Hierarchical key derivation from root keys |
| Enforce authorization | Query auth API (webhook or smart contract) |
| Sign certificates | Issue per-app CA certificates |
RPC endpoints exposed on port 9201:
GetAppKey - Request application keys with TDX quoteGetAppEnvEncryptPubKey - Get public key for environment encryptionGetTempCaCert - Temporary CA for onboardingConfiguration file: kms.toml
Sources: README.md72-73 docs/deployment.md172-287
The Gateway runs in a CVM and handles TLS termination, certificate management, and routing to application CVMs. It maintains a WireGuard mesh network for internal communication.
| Responsibility | Implementation |
|---|---|
| TLS termination | RA-TLS certificates with embedded attestation |
| ACME certificate provisioning | Certbot integration with DNS-01 challenge |
| Route to CVMs | HTTP reverse proxy based on subdomain |
| WireGuard mesh | VPN tunnel between Gateway and CVMs |
RPC endpoints on port 9202:
Configuration file: gateway.toml
Sources: README.md74-75 docs/deployment.md289-373
The Guest Agent runs inside each CVM and acts as the trusted bootstrap component. It generates attestation quotes, requests keys from KMS, manages disk encryption, and provides SDK APIs to applications.
| Responsibility | Implementation |
|---|---|
| Generate TDX quotes | guest/dstack-guest-agent/src/tdx_attest.rs |
| Request app keys | RPC call to KMS with quote |
| Mount encrypted disk | LUKS with KMS-provided key |
| Expose SDK API | Unix socket at /var/run/dstack.sock |
| Manage containers | Start/stop Docker Compose services |
RPC services exposed:
WorkerRpc - External API on port 8090DstackGuestRpc - Internal SDK API on port 8000TappdRpc - Legacy compatibility APISources: README.md70-71 README.md82-89
Sources: Diagram 2 from high-level system architecture, docs/deployment.md1-534
Applications often require sensitive configuration (API keys, credentials). dstack encrypts these client-side before deployment, and only the Guest Agent inside the TEE can decrypt them.
This ensures secrets never exist unencrypted outside the TEE. Even the infrastructure operator cannot access plaintext credentials.
Sources: Diagram 5 from high-level system architecture, docs/deployment.md489-513
A TEE is a hardware-isolated execution environment where code and data are protected from the host operating system, hypervisor, and even physical access. dstack uses Intel TDX (Trust Domain Extensions) to create CVMs.
| Property | Implementation |
|---|---|
| Memory encryption | Hardware-accelerated encryption of all DRAM |
| Measured boot | Boot sequence recorded in RTMR (Runtime Measurement Registers) |
| Attestation | TDX quotes prove code identity and hardware authenticity |
| Isolation | Hypervisor cannot read or modify CVM memory |
Sources: README.md23-24 docs/confidential-ai.md13-25
A CVM is a virtual machine running inside a TEE. In dstack, each application deployment creates a CVM booted with a reproducible OS image.
The OS image hash is measured during boot and included in the attestation quote. Users can verify they're interacting with the expected software stack.
Sources: README.md66-67 docs/deployment.md79-83
Attestation is the process of cryptographically proving what code is running and that it's executing in genuine TEE hardware.
The quote contains:
Applications expose quotes via SDK:
Sources: Diagram 3 from high-level system architecture, README.md173-175 docs/confidential-ai.md213-244
Before releasing keys, the KMS queries an authorization API to check if the deployment is allowed. Policies can be enforced via:
| Mode | Implementation | Use Case |
|---|---|---|
| auth-simple | Local JSON config file | Development, single-operator deployments |
| auth-eth | Ethereum smart contracts | Production, decentralized governance |
Authorization checks include:
Sources: docs/deployment.md176-213 docs/onchain-governance.md1-190
All components run directly on the host without TEE isolation. Used for local development and testing.
Warning: Dev mode provides no security guarantees. The KMS flag --dev disables attestation verification.
Sources: docs/deployment.md27-93
KMS and Gateway run as CVMs with full attestation and authorization enforcement. Requires:
Sources: docs/deployment.md95-373
All major components communicate via a custom RPC framework called pRPC (Protocol Buffers RPC). Critical security paths use RA-TLS (Remote Attestation TLS) where TDX quotes are embedded in X.509 certificates for mutual attestation.
| Service | Port | Protocol | Purpose |
|---|---|---|---|
| VMM RPC | 9080 | HTTP | VM management API |
| KMS RPC | 9201 | RA-TLS | Key provisioning |
| Gateway RPC | 9202 | RA-TLS | CVM registration |
| Guest Agent (external) | 8090 | HTTP | Public API |
| Guest Agent (internal) | 8000 | Unix socket | SDK API |
The RA-TLS handshake verifies that both endpoints are running in genuine TEEs with expected measurements.
Sources: README.md74-75 Diagram 1 from high-level system architecture
For on-chain governance, policies are defined in Ethereum smart contracts:
| Contract | Purpose | Owner |
|---|---|---|
| DstackKms | Global policies (OS whitelist, Gateway ID, KMS devices) | Admin/DAO |
| DstackApp | Per-app policies (compose hashes, device whitelist) | App owner |
During boot, KMS calls isAppAllowed(AppBootInfo) on the smart contract to check if the deployment is authorized.
Sources: docs/onchain-governance.md1-190 kms/auth-eth/foundry-cast-cheatsheet.md166-183
Applications interact with the Guest Agent through SDKs in multiple languages. All SDKs communicate via HTTP over /var/run/dstack.sock.
| Language | Package | Protocol |
|---|---|---|
| JavaScript/TypeScript | @phala/dstack-sdk | HTTP POST to Unix socket |
| Python | dstack_sdk | HTTP POST to Unix socket |
| Rust | dstack-sdk | HTTP POST to Unix socket |
| Go | github.com/Dstack-TEE/dstack/sdk/go | HTTP POST to Unix socket |
Core operations available via SDK:
| Operation | Purpose | Return Value |
|---|---|---|
info() | Get app metadata and TCB info | App ID, compose hash, measurements |
getKey(path, purpose) | Derive deterministic key | Cryptographic key bytes |
getQuote(reportData) | Generate TDX attestation | Quote + event log |
getTlsKey(options) | Get random TLS certificate | X.509 cert + private key |
sign(algorithm, data) | Sign with derived key | Signature bytes |
emitEvent(event, payload) | Extend RTMR3 | Success/failure |
Sources: README.md82-89 Diagram 4 from high-level system architecture
Each component has a TOML configuration file:
Sources: docs/deployment.md133-158 docs/deployment.md234-265 docs/deployment.md308-333
For detailed information on specific aspects of dstack:
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.
