Introduction to dstack

Relevant source files

• Cargo.lock
• Cargo.toml
• README.md
• docs/deployment.md
• docs/onchain-governance.md
• kms/auth-eth/foundry-cast-cheatsheet.md
• sdk/README.md

Purpose and Scope

This document provides a high-level introduction to the dstack confidential computing framework. It covers the core concepts, system architecture, and component interactions necessary to understand how dstack enables confidential AI deployments with hardware-rooted security guarantees.

For detailed information about specific aspects of dstack:

• For usage examples and deployment instructions, see Getting Started
• For in-depth architectural details of each component, see System Architecture Overview
• For security guarantees and trust boundaries, see Security Model and Trust Boundaries
• For workspace organization and crate dependencies, see Workspace Structure and Core Dependencies

What is dstack?

dstack is an open-source framework for deploying confidential AI applications inside Trusted Execution Environments (TEEs) with cryptographic verification. It enables developers to run Docker containers inside Intel TDX Confidential Virtual Machines (CVMs) with optional NVIDIA GPU isolation, providing hardware-level privacy guarantees that are independently verifiable by end users.

Key characteristics:

Aspect	Description
Zero-friction onboarding	Standard docker-compose.yaml files work as-is with no code changes
Hardware-rooted security	Intel TDX provides memory encryption; NVIDIA H100/Blackwell GPUs provide confidential computing
Cryptographic verification	Every CVM generates TDX attestation quotes that users can verify independently
Deterministic key derivation	Keys are derived from hardware measurements and never exposed to operators
On-chain governance	Authorization policies enforced via Ethereum smart contracts

For a detailed explanation of dstack's purpose and use cases, see What is dstack?

Sources: README.md21-42 docs/deployment.md1-11

Core Concepts

Trusted Execution Environments (TEE)

A TEE is a hardware-isolated execution environment that protects code and data from external access, including the host operating system and hypervisor. dstack uses Intel TDX (Trust Domain Extensions), which provides:

• Memory encryption: All memory contents are encrypted with CPU-generated keys
• Attestation: Hardware generates cryptographic quotes proving what code is running
• Isolation: Host cannot inspect or modify CVM state

Confidential Virtual Machines (CVM)

dstack runs applications inside CVMs—virtual machines with TEE protection. Each CVM:

• Boots from a reproducible OS image with deterministic measurements
• Generates TDX attestation quotes to prove its identity
• Receives cryptographic keys only after successful attestation
• Communicates via RA-TLS (Remote Attestation TLS) for mutual verification

Attestation and Remote Attestation TLS (RA-TLS)

Attestation is the process of cryptographically proving what software is running inside a TEE. dstack implements RA-TLS, which embeds attestation quotes directly into TLS certificates:

RA-TLS implementation: ra-tls/src/lib.rs

Attestation verification: dstack-attest/src/lib.rs

Sources: docs/deployment.md162 high-level diagram 2

Key Derivation Hierarchy

dstack implements hierarchical key derivation where:

1. KMS maintains root keys inside its own TEE
2. Application-specific keys are derived using HKDF with app identity and instance ID as context
3. Keys are never transmitted—only derived deterministically by KMS
4. Multiple KMS instances can replicate root keys via attested connections

Key types:

Key Type	Derivation Context	Purpose
App CA P256	app_id + "app-ca"	Certificate authority for app's TLS certs
Disk Encryption Key	app_id + instance_id	LUKS2 disk encryption
Environment Key X25519	app_id	Decrypt Docker secrets
App K256 Key	app_id + "app-key"	Ethereum-compatible signing

Sources: kms/src/lib.rs high-level diagram 4

System Components

dstack consists of four core components that run across the host-CVM boundary:

Component Architecture Diagram

Sources: Cargo.toml16-56 high-level diagram 1

VMM (Virtual Machine Manager)

The VMM runs on the bare-metal TDX host and orchestrates CVM lifecycle:

• Binary: target/release/dstack-vmm
• Configuration: vmm.toml
• RPC Service: dstack-vmm-rpc on port 9080
• Main struct: App at vmm/src/app.rs
• VM lifecycle: VmWorkDir at vmm/src/app/vm_workdir.rs

Key responsibilities:

1. Parse docker-compose.yaml files into normalized format
2. Request boot authorization from KMS before launching CVMs
3. Generate QEMU command-line arguments with TDX configuration
4. Manage disk images, networking, and GPU passthrough
5. Monitor VM status via supervisor process manager

For detailed VMM documentation, see Virtual Machine Manager (VMM)

Sources: vmm/src/main.rs vmm/src/app.rs Cargo.toml27

KMS (Key Management System)

The KMS runs inside its own CVM and acts as the trust anchor:

• Binary: target/release/dstack-kms
• Configuration: kms.toml
• RPC Service: dstack-kms-rpc on port 9201 (RA-TLS)
• Main struct: KmsState at kms/src/lib.rs
• RPC handler: RpcHandler at kms/src/rpc_impl.rs

Key responsibilities:

1. Verify TDX attestation quotes from CVMs requesting keys
2. Query authorization policies from auth-api (blockchain or config-based)
3. Derive application-specific keys using HKDF
4. Sign certificate signing requests (CSRs) with embedded attestation
5. Replicate root keys to other KMS instances via onboarding

For detailed KMS documentation, see Key Management System (KMS)

Sources: kms/src/main.rs kms/src/lib.rs Cargo.toml17

Gateway

The Gateway runs inside a CVM and provides external-facing ingress:

• Binary: target/release/dstack-gateway
• Configuration: gateway.toml
• RPC Service: dstack-gateway-rpc on port 9202 (HTTPS + RA-TLS)
• Main struct: Proxy at gateway/src/lib.rs
• State: ProxyState and ProxyInner at gateway/src/state.rs

Key responsibilities:

1. Terminate HTTPS traffic and extract SNI for routing
2. Register CVMs and allocate WireGuard tunnel IPs
3. Route traffic to application CVMs via WireGuard VPN mesh
4. Synchronize state across Gateway nodes using wavekv::KvStore
5. Obtain and renew ACME certificates via certbot::DistributedCertBot

For detailed Gateway documentation, see dstack Gateway

Sources: gateway/src/main.rs gateway/src/lib.rs Cargo.toml29

Guest Agent

The guest agent runs inside every CVM (KMS, Gateway, and application CVMs):

• Binary: target/release/dstack-guest-agent
• Configuration: guest-agent.toml
• RPC Service: dstack-guest-agent-rpc on port 9205
• Main service: DstackGuestRpc at guest-agent/rpc/proto/dstack_guest.proto
• Socket: /var/run/dstack.sock

Key responsibilities:

1. Generate TDX attestation quotes via tdx-attest crate
2. Request keys from KMS with quote-authenticated RPC
3. Manage LUKS2 encrypted disks
4. Decrypt environment variables for Docker containers
5. Expose SDK API via Unix socket for application access

For detailed guest agent documentation, see Guest Agent

Sources: guest-agent/src/main.rs guest-agent/rpc/proto/dstack_guest.proto Cargo.toml25-26

Communication Protocols and Ports

dstack components communicate using multiple protocols optimized for different use cases:

Protocol Mapping

Sources: Cargo.toml89 Cargo.toml172 high-level diagram 3

Port Assignments

Service	Port	Protocol	Purpose
dstack-vmm	9080	HTTP	VM management API
dstack-kms	9201	RA-TLS	Key provisioning with attestation
dstack-gateway	9202	HTTPS + RA-TLS	Public ingress + internal mesh
dstack-gateway	8000	HTTP	Admin/debug interface
dstack-guest-agent	9205	HTTP	Guest RPC service
host-api	VSOCK 2:10000	VSOCK	Host-to-guest API

Sources: vmm/src/main.rs kms/src/main.rs gateway/src/main.rs guest-agent/src/main.rs

RPC Framework (PRPC)

All internal RPC communication uses prpc (Protocol Buffers RPC):

• RPC definitions: .proto files in */rpc/proto/ directories
• Build step: prpc-build generates Rust code at compile time
• Transport: HTTP/1.1 with JSON or binary encoding
• Service trait: prpc::server::RpcService

Example RPC services:

Crate	Proto File	Generated Trait
dstack-vmm-rpc	vmm/rpc/proto/vmm.proto	VmmRpc
dstack-kms-rpc	kms/rpc/proto/kms.proto	KmsRpc
dstack-gateway-rpc	gateway/rpc/proto/gateway.proto	GatewayRpc
dstack-guest-agent-rpc	guest-agent/rpc/proto/dstack_guest.proto	DstackGuestRpc

Sources: Cargo.toml215-216 vmm/rpc/build.rs kms/rpc/build.rs

Workspace Organization

The dstack codebase is organized as a Cargo workspace with 42 member crates:

Core Service Crates

Sources: Cargo.toml16-56

Dependency Categories

The workspace dependencies are organized in Cargo.toml59-248:

Category	Key Dependencies	Purpose
Internal	ra-rpc, ra-tls, dstack-attest, tdx-attest	Core functionality
Networking	tokio, hyper, reqwest, bollard	Async I/O and HTTP
Cryptography	p256, k256, ed25519-dalek, rustls, ring	Key operations and TLS
Serialization	serde, prost, bincode, toml	Data encoding
RPC	prpc, prpc-build	Protocol Buffers RPC

Sources: Cargo.toml59-248

SDK Integration

Applications inside CVMs interact with the guest agent via language-specific SDKs:

SDK Architecture

Available SDKs:

Language	Package	Location
JavaScript/TypeScript	@phala/dstack-sdk	sdk/js/
Python	dstack-sdk	sdk/python/
Rust	dstack-sdk	sdk/rust/
Go	github.com/Dstack-TEE/dstack/sdk/go	sdk/go/

For SDK documentation, see SDK and Client Libraries

Sources: sdk/README.md guest-agent/rpc/proto/dstack_guest.proto high-level diagram 6

Deployment Models

dstack supports two deployment modes with different security guarantees:

Development Deployment

Characteristics:

• All components run directly on the host (no CVMs)
• KMS operates in dev mode with simulated attestation
• No hardware security guarantees
• Fast iteration for development

Use case: Local development and testing only

Configuration: docs/deployment.md27-93

Production Deployment

Characteristics:

• KMS and Gateway run as CVMs with TDX attestation
• Authorization via auth-api webhook (blockchain or config-based)
• All keys derived inside TEE
• Full hardware-rooted security guarantees

Architecture:

Use case: Production deployments with verifiable security

Configuration: docs/deployment.md95-486

For complete deployment instructions, see Getting Started and Deployment and Operations

Sources: docs/deployment.md1-564 high-level diagram 5

Authorization and Governance

dstack supports multiple authorization backends for boot approval:

Authorization Flow

When a CVM requests boot, the following sequence occurs:

1. VMM calls KMS RequestBootAuthorization with AppBootInfo
2. KMS calls auth-api webhook (e.g., POST /bootAuth/app)
3. Auth server validates against policies (smart contract or config file)
4. If approved, KMS returns authorization; VMM boots CVM
5. CVM requests keys from KMS with TDX attestation quote
6. KMS verifies quote and releases derived keys

Authorization Backends

Backend	Description	Configuration
auth-simple	Config file-based whitelisting	JSON file with MRs, devices, compose hashes
auth-eth	Ethereum smart contract governance	DstackKms and DstackApp contracts
Custom	Implement webhook interface	POST /bootAuth/app and POST /bootAuth/kms

Smart contracts:

• DstackKms: kms/auth-eth/contracts/DstackKms.sol
• DstackApp: kms/auth-eth/contracts/DstackApp.sol

For on-chain governance setup, see On-Chain Governance and docs/onchain-governance.md

Sources: docs/deployment.md178-264 docs/onchain-governance.md1-190 kms/auth-eth/

Security Model Overview

dstack implements a defense-in-depth security model with multiple verification layers:

Trust Boundaries

Key security properties:

1. Hardware isolation: TDX encrypts CVM memory; host cannot access
2. Attestation verification: Every CVM proves its identity via TDX quotes
3. Deterministic builds: Reproducible OS images enable verification
4. Key non-exposure: Keys derived inside TEE based on attestation
5. Policy enforcement: Smart contracts or config files control authorization

For detailed security analysis, see Security Model and Trust Boundaries and docs/security/security-model.md

Sources: README.md78-80 docs/security/security-model.md high-level diagram 2

Next Steps

To continue learning about dstack:

• What is dstack? - Detailed explanation of confidential AI and use cases
• System Architecture Overview - Deep dive into component interactions
• Security Model and Trust Boundaries - Threat model and cryptographic guarantees
• Getting Started - Deploy your first application in a TEE

For developers:

• SDK and Client Libraries - Language-specific SDK documentation
• Guest Agent - Guest agent API and cryptographic operations

For operators:

• Deployment and Operations - Production deployment guide
• VMM CLI Guide - Command-line reference

For contributors:

• Workspace Structure and Core Dependencies - Codebase organization