Index your code with Devin
DeepWiki

Dstack-TEE/dstack

Menu

Introduction to dstack

Relevant source files

Purpose and Scope

This document provides a comprehensive introduction to the dstack system, explaining its purpose as a confidential computing platform, its architecture, and how its components work together to enable secure deployment of containerized applications in Trusted Execution Environments (TEEs).

For detailed information about specific subsystems:

Sources: README.md1-502

What is dstack?

dstack is a developer-friendly confidential computing platform that simplifies deploying arbitrary containerized applications into Intel TDX (Trust Domain Extensions) based Trusted Execution Environments. It provides an end-to-end security framework combining hardware-based TEE attestation with blockchain-enforced policies.

The platform enables developers to deploy Docker containers with the same familiar docker-compose.yaml workflow they already use, while automatically handling:

  • TEE attestation and verification via Intel TDX quotes
  • Cryptographic key management with hardware-rooted derivation
  • Zero-trust HTTPS with automated TLS certificate provisioning
  • Policy enforcement through Ethereum smart contracts

Sources: README.md19-29 Cargo.toml1-224

Core Problem and Solution

The Problem: Trust in Cloud Computing

Traditional cloud deployments require trusting infrastructure providers with:

  • Access to application secrets and keys
  • Visibility into runtime memory and data
  • Control over deployment configurations
  • Certificate authority operations

This trust model is incompatible with high-security use cases like:

  • Financial services handling sensitive transactions
  • Healthcare applications processing private data
  • Blockchain validators requiring key isolation
  • AI/ML workloads with proprietary models

The Solution: Hardware-Rooted Confidential Computing

dstack solves this by leveraging Intel TDX to create Confidential Virtual Machines (CVMs) where:

  1. Hardware guarantees isolation: The CPU enforces memory encryption and isolation at the hardware level
  2. Cryptographic attestation proves integrity: TDX quotes provide unforgeable evidence of what code is running
  3. Keys never leave the TEE: All cryptographic material is derived within CVMs and sealed to specific measurements
  4. Policies are immutable: Ethereum smart contracts define authorization rules that cannot be bypassed

Sources: README.md19-29 docs/deployment.md1-377

System Architecture Overview

dstack consists of four core infrastructure services running on TDX-capable bare metal hosts:

Diagram: Four Core Infrastructure Services and Their Interactions

Service Responsibilities

ServicePurposeKey Code Paths
dstack-vmmManages CVM lifecycle, allocates resources, handles QEMU/KVM configurationvmm/src/main.rs vmm/src/vm.rs
dstack-kmsGenerates and derives cryptographic keys, validates TDX attestation quotes, enforces blockchain policieskms/src/main.rs kms/src/service.rs
dstack-gatewayTerminates TLS connections, routes traffic to CVMs via WireGuard, manages Let's Encrypt certificatesgateway/src/main.rs gateway/src/proxy/
dstack-guest-agentProvides in-CVM APIs for key derivation, quote generation, and event logging via Unix socketguest-agent/src/main.rs guest-agent/src/http_server.rs

Sources: README.md63-76 Cargo.toml16-55

Key Components Deep Dive

1. dstack-vmm: Virtual Machine Monitor

The VMM is a Rust service running on the bare metal host that orchestrates all CVMs. It:

  • Spawns QEMU processes with TDX-enabled configurations
  • Manages VSOCK CID allocation for inter-CVM communication
  • Exposes HTTP management API on port 9080 for deployment
  • Handles port mapping for network access to CVMs
  • Coordinates with KMS and Gateway during CVM boot

Diagram: VMM CVM Creation Flow

Configuration: vmm/rpc/proto/vmm.proto defines the VmConfig message structure containing CPU count, memory size, OS image hash, and app configuration.

Sources: README.md71 Cargo.toml28 docs/deployment.md15-58

2. dstack-kms: Key Management System

The KMS is the trust anchor of the system, running inside a dedicated CVM. It:

  • Generates root keys on first boot, sealed to TDX measurements
  • Derives per-app keys using HKDF based on app_id and instance_id
  • Validates TDX quotes using DCAP quote verification library
  • Queries Ethereum contracts to check authorization policies
  • Provides RA-TLS endpoints for secure communication with other CVMs

Diagram: KMS Key Derivation and Authorization Flow

Key Storage: Root keys are stored in /kms/root-key.bin, encrypted with keys sealed to TDX measurements. See kms/src/root_key.rs for implementation.

Sources: README.md73 Cargo.toml17-18 docs/deployment.md88-155

3. dstack-gateway: Network Gateway

The Gateway CVM acts as a reverse proxy and TLS terminator, providing public internet access to application CVMs:

  • Terminates TLS using Let's Encrypt certificates managed by certbot
  • Routes traffic based on subdomain patterns like <app_id>[-<port>][s|g].<domain>
  • Manages WireGuard VPN connections to application CVMs
  • Load balances across multiple instances of the same app
  • Monitors Certificate Transparency logs to detect unauthorized certificates

Diagram: Gateway Request Routing and TLS Management

Ingress Patterns: See README.md210-221 for complete routing rules. The suffix s enables TLS passthrough (see gateway/src/proxy/tls_passthough.rs74-87), while g enables gRPC/HTTP2.

Sources: README.md72-221 Cargo.toml29-30 docs/deployment.md156-281

4. dstack-guest-agent: In-CVM Service

The guest agent runs inside every CVM and provides the Unix socket API at /var/run/dstack.sock that containerized applications use to access TEE functionality:

Diagram: Guest Agent API Endpoints and Their Implementations

API Methods: See sdk/rust/types/src/lib.rs for the complete API schema exposed to applications. The agent implements three API surfaces: Host API (VSOCK to host), Guest API (VSOCK from host), and Public API (HTTP on :8090).

Sources: README.md74 Cargo.toml25-26 README.md230-254

Security Architecture

dstack's security model is built on three pillars:

1. Hardware-Based Attestation (Intel TDX)

Every CVM generates TDX quotes that cryptographically prove:

  • The exact code running in the TEE (via MRTD measurement)
  • The boot configuration and loaded modules (via RTMR registers)
  • The platform's TCB (Trusted Computing Base) status

Diagram: TDX Attestation Flow from Boot to Key Derivation

Sources: Cargo.toml70-71 README.md230-254

2. Blockchain-Based Authorization

Ethereum smart contracts define immutable policies that the KMS enforces:

  • DstackKms.sol: Main contract managing allowed KMS instances, OS images, and app registry
  • DstackApp.sol: Per-app contract controlling allowed compose hashes and device IDs

Diagram: Smart Contract Authorization Flow

Sources: kms/auth-eth/foundry-cast-cheatsheet.md1-523 docs/deployment.md60-377

3. Cryptographic Key Hierarchy

All keys are derived from a root key generated inside the KMS CVM, creating a hierarchical structure:

Root Key (sealed to TDX measurements) ├─> Per-App CA Key (derived via HKDF with app_id) │ └─> TLS Certificates for instances ├─> Per-Instance Disk Key (app_id + instance_id + "disk") ├─> Per-Instance Env Key (app_id + instance_id + "env") └─> Per-Instance k256 Key (app_id + instance_id + "k256") └─> Ethereum/Blockchain signing keys

Key Derivation: Implemented in kms/src/service.rs using HKDF-SHA256 with domain separation.

Sources: README.md195-206

Developer Workflow

The typical workflow for deploying an application on dstack:

1. On-Chain Registration

Deploy a DstackApp contract to define authorization policies:

Sources: docs/deployment.md300-352

2. Compose File Preparation

Write a standard docker-compose.yaml and optionally encrypt environment variables:

Sources: README.md174-246

3. Whitelist Compose Hash

Calculate the SHA256 hash of the compose configuration and add it to the smart contract:

Sources: docs/deployment.md354-363

4. Deploy to VMM

Use the Web UI at :9080 or CLI to deploy:

  • Select OS image (e.g., dstack-0.5.2)
  • Provide App ID from step 1
  • Upload compose file
  • Configure resources (CPU, RAM, disk)
  • Optionally add encrypted environment variables

Sources: README.md174-193 docs/deployment.md365-377

5. Access Application

Once deployed, the application is accessible via dstack-gateway:

https://<app_id>-<port>.domain.com

Or retrieve TDX quotes from inside the container:

Sources: README.md207-254

Key Concepts

Confidential VM (CVM)

A virtual machine running with Intel TDX protection, where memory is encrypted and isolated from the host. The VMM can create CVMs but cannot inspect their runtime state or memory contents.

Code: CVM creation in vmm/src/vm.rs TDX configuration via QEMU parameters.

App ID vs Instance ID

  • App ID: The Ethereum address of the DstackApp contract (proxy address), representing the application across all instances
  • Instance ID: Unique identifier for a specific running VM instance of the app

Relationship: Multiple instances can share the same App ID but have different Instance IDs. Keys are derived per-instance, but authorization policies apply per-app.

RA-TLS (Remote Attestation TLS)

A TLS extension that embeds a TDX quote in the certificate, allowing peers to verify the TEE authenticity during the handshake. Used for secure communication between KMS and guest agents.

Implementation: ra-tls/src/lib.rs

RTMR (Runtime Measurement Register)

TDX provides 4 RTMRs that accumulate measurements during boot:

  • RTMR0: OS image hash
  • RTMR1: Reserved
  • RTMR2: Reserved
  • RTMR3: Application-specific events (compose hash, app ID, custom events)

Extension: Applications can extend RTMR3 via the emitEvent API.

Sources: cc-eventlog/src/lib.rs

Compose Hash

The SHA256 hash of the app-compose.json file, which includes:

  • Docker compose configuration
  • App ID
  • Network settings
  • Resource allocations

This hash must be whitelisted in the DstackApp contract before deployment.

OS Image Hash

The hash of the entire guest OS filesystem image. The KMS maintains a whitelist of approved OS image hashes to prevent running unauthorized or compromised guest images.

Verification: verifier/dstack-verifier.toml9-13 shows configuration for OS image verification service.

Sources: README.md1-502 Cargo.toml1-224 docs/deployment.md1-377 verifier/dstack-verifier.toml1-19