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

Purpose and Scope

This document provides a high-level introduction to dstack, covering its purpose, architecture, and core components. For hands-on deployment instructions, see Getting Started. For detailed component documentation, see Core Infrastructure Services. For security details, see Security Model and Trust Boundaries.

Sources: README.md19-41

---

What is dstack?

dstack is an open framework for confidential AI that enables deploying applications with cryptographic privacy guarantees using Intel TDX (Trust Domain Extensions) and NVIDIA Confidential Computing. It provides a complete infrastructure stack for running Docker containers inside Confidential Virtual Machines (CVMs) with hardware-rooted security.

Key characteristics:

• Docker-native: Deploy existing docker-compose.yaml files without code changes
• Hardware-backed privacy: Memory encryption via Intel TDX, GPU isolation via NVIDIA Confidential Computing
• Cryptographic verification: Users can verify exactly what code is running via TDX attestation quotes
• Trustless key management: Per-app cryptographic keys isolated from operators
• Decentralized governance: Authorization policies enforced by smart contracts

Sources: README.md19-41 docs/deployment.md1-11

---

The Problem: Trust Doesn't Scale

Traditional cloud deployments require users to trust providers with:

• Sensitive data (model weights, inference inputs, training data)
• Application code and configurations
• Cryptographic keys and credentials

This trust model breaks down for:

• Confidential AI: Medical AI, financial models, private assistants need data isolation
• Multi-party computation: Parties need cryptographic guarantees about code execution
• Regulated industries: Compliance requires verifiable security properties

dstack's solution: Hardware-enforced isolation where:

1. Code runs inside encrypted memory (Intel TDX)
2. Attestation quotes prove what code is running
3. Keys are derived from hardware measurements
4. Smart contracts enforce authorization policies

Sources: README.md19-24 docs/deployment.md7-11

---

System Architecture

Architecture Analysis:

This diagram shows the complete dstack deployment topology. The dstack-vmm service runs on bare-metal TDX hardware and orchestrates multiple Confidential Virtual Machines (CVMs). Each CVM runs a guest-agent instance that provides attestation and key derivation APIs. The dstack-kms enforces authorization policies by querying either auth-simple (config-based) or auth-eth (smart contract-based) before releasing keys. The dstack-gateway handles TLS termination and routes traffic to app CVMs. All TDX quotes are verified against Intel's Provisioning Certificate Service.

Sources: Cargo.toml16-55 docs/deployment.md6-11 High-Level Diagrams (Diagram 1)

---

Core Components

Virtual Machine Manager (VMM)

The dstack-vmm service runs on bare-metal TDX hosts and manages the lifecycle of Confidential Virtual Machines.

Key responsibilities:

• Parse docker-compose.yaml files directly (no conversion needed)
• Boot QEMU-based TDX VMs with encrypted memory
• Allocate resources (vCPU, memory, GPU, network CIDs)
• Manage VM lifecycle (create, start, stop, remove)
• Expose web console for VM management at port 9080

Configuration: `vmm/vmm.toml` specifies KMS URLs, Gateway URLs, CID pool ranges, and port mappings.

Sources: docs/deployment.md119-169 Cargo.toml27

---

Key Management System (KMS)

The dstack-kms service runs inside its own CVM and provides cryptographic key management with hardware-rooted security.

Key responsibilities:

• Verify TDX attestation quotes from app CVMs
• Query authorization server (auth-eth or auth-simple) to check policies
• Derive deterministic keys using HKDF bound to app identity
• Bootstrap with self-signed RA-TLS certificates
• Support onboarding for multi-KMS deployments

Authorization flow:

1. App CVM requests key via GetAppKey() RPC
2. KMS extracts measurements from TDX quote
3. KMS calls POST /bootAuth/app on auth server with AppBootInfo
4. Auth server returns (isAllowed: bool, reason: string)
5. If allowed, KMS derives and returns encrypted key material

Configuration: `kms/kms.toml` specifies auth webhook URL, RPC address, and onboarding settings.

Sources: docs/deployment.md172-282 Cargo.toml17-18 High-Level Diagrams (Diagram 2)

---

Gateway

The dstack-gateway service runs in its own CVM and handles TLS termination, certificate management, and traffic routing.

Key responsibilities:

• Terminate TLS connections with Let's Encrypt certificates
• Route HTTPS traffic to app CVMs based on subdomain
• Manage WireGuard VPN for inter-CVM communication
• Provision ACME certificates via DNS-01 challenge (Cloudflare)
• Set CAA DNS records to restrict certificate issuance

Certificate management: The certbot service runs inside the Gateway CVM and automatically:

• Derives ACME account keys from KMS (TEE-bound keys)
• Requests certificates via DNS-01 challenge
• Renews certificates before expiry
• Updates Gateway configuration atomically

Configuration: `gateway/gateway.toml` specifies public domain, WireGuard settings, and upstream KMS URLs.

Sources: docs/deployment.md289-373 Cargo.toml29-32 High-Level Diagrams (Diagram 6)

---

Guest Agent

The guest-agent service runs inside every CVM and provides local APIs for attestation, key derivation, and signing.

Key responsibilities:

• Generate TDX quotes on demand
• Request and cache app keys from KMS
• Derive subkeys using hierarchical key derivation
• Expose RPC services: DstackGuest, Tappd (legacy), Worker (public)
• Serve HTTP endpoints on /var/run/dstack.sock

API surfaces:

• Unix socket (primary): /var/run/dstack.sock for local app access
• HTTP endpoint (optional): Port 8090 for remote/simulator access
• RPC methods: GetKey, GetQuote, GetTlsKey, Sign, Verify

Sources: docs/deployment.md69-75 Cargo.toml25-26 High-Level Diagrams (Diagram 4)

---

Authorization Servers

Authorization servers implement the webhook interface that KMS calls to validate boot requests.

Available implementations:

Server	Type	Configuration	Use Case
auth-simple	Config-based	JSON file	Dev/testing, simple whitelists
auth-eth	Smart contract	Ethereum RPC	Production, decentralized governance

Webhook interface:

• GET / - Health check
• POST /bootAuth/app - Validate app boot with AppBootInfo
• POST /bootAuth/kms - Validate KMS boot with AppBootInfo

AppBootInfo structure:

Sources: docs/deployment.md176-217 docs/onchain-governance.md7-11 kms/auth-eth/foundry-cast-cheatsheet.md166-183

---

Security Model Overview

dstack implements a zero-trust architecture with multiple security layers:

Security guarantees:

1. Hardware isolation: Memory encrypted by Intel TDX, inaccessible to host OS or hypervisor
2. Attestation: TDX quotes prove code identity, verified against Intel PCS
3. Key isolation: Keys derived from hardware measurements, never exposed to operators
4. Authorization: Smart contracts enforce policies that operators cannot bypass
5. Reproducible builds: OS images have deterministic hashes anyone can verify

Sources: README.md31-40 docs/deployment.md96-103 High-Level Diagrams (Diagram 2)

---

Deployment Flow

Deployment stages:

1. Upload: User uploads docker-compose.yaml via VMM web console or CLI
2. Resource allocation: VMM computes compose hash, allocates CID and resources
3. Boot: VMM boots QEMU with TDX, writes VM manifest and configs
4. Stage0 (System): CVM measures app identity, generates TDX quote, requests keys from KMS
5. Authorization: KMS verifies attestation and queries auth server for approval
6. Key derivation: KMS derives keys bound to app identity using HKDF
7. Stage1 (Application): CVM sets up encrypted disk, starts Docker containers
8. Runtime: Guest agent serves key derivation APIs to application

Sources: docs/deployment.md487-511 High-Level Diagrams (Diagram 3)

---

Workspace Structure

The dstack codebase is organized as a Cargo workspace with the following major components:

Workspace organization:

• Infrastructure: Core services (vmm, kms, gateway, guest-agent)
• Security: Attestation libraries (tdx-attest, ra-tls, ra-rpc, cc-eventlog)
• Support: Utilities (certbot, ct_monitor, supervisor, dstack-util)
• SDKs: Client libraries (sdk/rust, Python/JS/Go are external)
• RPC: Protocol definitions (kms/rpc, guest-agent/rpc, gateway/rpc, vmm/rpc)

Sources: Cargo.toml15-55

---

SDK Architecture

Applications interact with the guest agent through multi-language SDKs:

SDK features:

Language	Package	Unix Socket	HTTP	Blockchain Helpers
Python	dstack-sdk	✓	✓	Ethereum, Solana
TypeScript	@phala/dstack-sdk	✓	✓	-
Rust	dstack-sdk	✓	✓	-
Go	github.com/Dstack-TEE/dstack/sdk/go	✓	✓	-

RPC services:

• DstackGuest: Full internal API with all methods
• Tappd: Legacy API for backward compatibility
• Worker: Public API with filtered information

Sources: README.md80-89 Cargo.toml46-47 High-Level Diagrams (Diagram 4)

---

Smart Contract Governance

For production deployments, authorization policies are enforced by Ethereum smart contracts:

Contract hierarchy:

1. DstackKms (main contract): Maintains global whitelists (OS images, KMS devices) and app registry
2. DstackApp (per-app): Controls allowed compose hashes and device IDs for specific apps

Authorization flow:

1. KMS calls POST /bootAuth/app on auth-eth webhook server
2. auth-eth calls isAppAllowed(AppBootInfo) on DstackKms contract
3. DstackKms checks OS image whitelist
4. DstackKms delegates to specific DstackApp contract
5. DstackApp checks compose hash and device whitelist
6. Result bubbles back to KMS

Sources: docs/onchain-governance.md1-58 kms/auth-eth/foundry-cast-cheatsheet.md1-50 High-Level Diagrams (Diagram 5)

---

Deployment Models

dstack supports two deployment modes:

Development Deployment

All components run directly on the host for local testing:

• KMS: Dev mode, no security guarantees
• Gateway: Host process
• Apps: Standard VMs (not TDX)
• Authorization: None or simple config file

Use case: Local development, testing, debugging

Sources: docs/deployment.md27-92

---

Production Deployment

Security-hardened deployment with all guarantees enabled:

• KMS: Runs in dedicated CVM with TDX attestation
• Gateway: Runs in dedicated CVM
• Apps: Run in individual CVMs with TDX
• Authorization: auth-eth with smart contract governance OR auth-simple with config

Requirements:

1. Bare-metal TDX host (Intel 4th/5th Gen Xeon)
2. Auth server (auth-eth or auth-simple) configured and running
3. OS image hash whitelisted in auth server
4. Apps registered with compose hashes whitelisted

Sources: docs/deployment.md95-373

---

Next Steps

For hands-on deployment:

• Quick start: See Getting Started
• Architecture details: See System Architecture Overview
• Security details: See Security Model and Trust Boundaries

For component documentation:

• VMM: See dstack-vmm: Virtual Machine Manager
• KMS: See dstack-kms: Key Management System
• Gateway: See dstack-gateway: Network Gateway
• Guest Agent: See dstack-guest-agent: In-VM Services

For security topics:

• Attestation: See Remote Attestation and RA-TLS
• Key derivation: See Key Derivation and Cryptographic Primitives
• Authorization: See Boot Authorization and Policy Enforcement

For smart contract governance:

• On-chain policies: See Smart Contract Architecture
• Contract deployment: See Contract Deployment and Configuration

For application development:

• SDK usage: See Core SDK Operations
• Python SDK: See Python SDK Reference
• TypeScript SDK: See JavaScript/TypeScript SDK Reference

Sources: Table of Contents JSON structure