dstack
CLAUDE.md573 starsChanged 3 months agoApache-2.0View on GitHub
dstack is a developer-friendly, security-first framework for deploying containerized applications into Intel TDX (Trust Domain Extensions) Trusted Execution Environments (TEEs). The system provides end-to-end security through hardware-rooted attestation, automated key management, and zero-trust networking. The monorepo keeps core services and the Rust workspace in dstack/, public SDKs in sdk/, guest-OS builders in os/, documentation in docs/, and standalone utilities in tools/. dstack consists of several core components that interact to provide TEE-based container deployment: This script: 1. Builds the SDK…
- Installs packages
The file
We split this CLAUDE.md into the rules it gives an agent
8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 149
Start log messages and error messages with lowercase text
- Distinctive: line 186
Run components in separate terminals:
- Distinctive: line 203
Default: TLS termination to TCP
- Very specific: line 219
Create crate directory and Cargo.toml
- Very specific: line 220
Add to workspace members in dstack/Cargo.toml
- Distinctive: line 221
Add workspace dependency if it will be used by other crates
- Very specific: line 227
Use prpc-build in build.rs to generate Rust code
- Distinctive: line 244
When need more detailed info, try to use deepwiki mcp.
≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project Overview
dstack is a developer-friendly, security-first framework for deploying containerized applications into Intel TDX (Trust Domain Extensions) Trusted Execution Environments (TEEs). The system provides end-to-end security through hardware-rooted attestation, automated key management, and zero-trust networking.
The monorepo keeps core services and the Rust workspace in dstack/, public
SDKs in sdk/, guest-OS builders in os/, documentation in docs/, and
standalone utilities in tools/.
Architecture
dstack consists of several core components that interact to provide TEE-based container deployment:
Core Components
dstack-vmm(dstack/vmm/): Virtual Machine Manager that runs on bare-metal TDX hosts. Orchestrates CVM lifecycle, manages QEMU processes, allocates resources, parses docker-compose files, and provides a web UI (port 9080) for deployment.dstack-kms(dstack/kms/): Key Management System that handles cryptographic key provisioning after TDX quote verification. Derives keys deterministically per application identity and enforces authorization policies defined in smart contracts on Ethereum.dstack-gateway(dstack/gateway/): Reverse proxy providing zero-trust network access. Handles TLS termination, automated ACME certificate provisioning, and traffic routing via ingress mapping rules.dstack-guest-agent(dstack/guest-agent/): Runs inside each CVM to provide runtime services including Docker Compose lifecycle management, TDX quote generation, key provisioning from KMS, and log aggregation. Exposes API via Unix socket at/var/run/dstack.sock.
Communication Protocols
- RA-TLS: Remote Attestation TLS used for all inter-CVM communication, embedding TDX quotes in X.509 certificates for mutual authentication
prpc: Protocol Buffers-based RPC framework used across all service APIsvsock: Host-guest communication channel for metadata and configuration- Unix Domain Sockets: Used for local management (e.g.,
vmm.sock)
Additional Components
certbot(dstack/certbot/): Automated ACME DNS-01 certificate managementct_monitor(dstack/ct_monitor/): Certificate Transparency log monitoringverifier(dstack/verifier/): TDX quote verification service usingdcap-qvlsupervisor(dstack/supervisor/): Process supervision inside CVMs- SDKs (
sdk/): Client SDKs in Rust, Python, Go, and JavaScript for interacting with guest-agent APIs
Build Commands
Rust Components
cd dstack
# Build all components
cargo build --release
# Build specific components
cargo build --release -p dstack-vmm
cargo build --release -p dstack-kms
cargo build --release -p dstack-gateway
cargo build --release -p dstack-guest-agent
cargo build --release -p dstack-guest-agent-simulator
# Check code
cargo check --all-features
# Format code
cargo fmt --all
# Lint with Clippy
cargo clippy -- -D warnings --allow unused_variablesEthereum Smart Contracts (KMS Auth)
cd dstack/kms/auth-eth
npm install # Install Node.js dependencies for bootAuth server
forge install # Install Foundry dependencies (submodules)
# Build
forge build # Compile smart contracts
npm run build # Build TypeScript server
# Test
forge test --ffi # Run Foundry contract tests
npm test # Run TypeScript server tests
npm run test:coverage # Run TypeScript tests with coverage
# Local development
anvil # Start local Ethereum nodePython SDK
cd sdk/python
make install # Install dependencies
make test # Run testsTest Commands
Running All Tests
# Run all Rust tests (requires simulator)
./dstack/run-tests.shThis script:
- Builds the SDK simulator (
sdk/simulator/) - Starts the simulator in background
- Sets
DSTACK_SIMULATOR_ENDPOINTandTAPPD_SIMULATOR_ENDPOINT - Runs
cargo test --all-features -- --show-output
Running Specific Tests
cd dstack
# Run tests for a specific package
cargo test -p dstack-kms --all-features
# Run a specific test
cargo test --all-features test_name
# Run tests with output
cargo test --all-features -- --show-output --test-threads=1Foundry Tests (Ethereum Contracts)
cd dstack/kms/auth-eth
# Run all Foundry tests
forge test
# Run with verbosity
forge test -vv
# Run specific test contract
forge test --match-contract UpgradesWithPluginTest -vv
# Clean build artifacts
forge cleanCode Style Guidelines
Logging and Error Messages
- Start log messages and error messages with lowercase text
- Preserve the conventional capitalization of identifiers and acronyms when they
begin a message (for example,
RIM,OCSP, orHTTP) - Example:
log::info!("starting server on port {}", port); - Example:
anyhow::bail!("failed to connect to server"); - Example:
log::warn!("RIM upstream is unavailable");
Key Security Concepts
Attestation Flow
- Quote Generation: Applications request TDX quotes via
getQuote()with reportData (up to 64 bytes) - Quote Verification:
dstack-verifiervalidates quotes usingdcap-qvl, verifies OS image hash, and replays RTMRs from event logs - RTMR Replay: Compute Runtime Measurement Register values by applying SHA384 hashing to event log entries
Key Management
- Deterministic Keys:
getKey(path, purpose)derives secp256k1 keys using HKDF, with signature chains proving TEE origin - TLS Keys:
getTlsKey()generates fresh X.509 certificates with optional RA-TLS support - Environment Encryption: Client-side encryption using X25519 ECDH + AES-256-GCM, decrypted only in TEE
Smart Contract Integration
- DstackKms: Main KMS contract managing OS image whitelist and app registration
- DstackApp: Per-app authorization contract controlling device IDs and compose hash whitelist
- Deployed on Ethereum-compatible networks (Phala Network)
Development Workflow
Local Development Setup
- Build guest-OS artifacts with
make os-image, which uses the default mkosi backend (seedocs/building-guest-os.md). The Yocto backend (os/yocto/,make os-image-yocto,--backend yocto) is deprecated: never use it for new images or features. Do not deleteos/yocto/either: mkosi still reads patches, units, and scripts from it (grep -rn yocto os/mkosi) - Download or build guest OS image
- Run components in separate terminals:
- KMS:
./dstack-kms -c kms.toml - Gateway:
sudo ./dstack-gateway -c gateway.toml - VMM:
./dstack-vmm -c vmm.toml
- KMS:
Deploying Apps
- Via Web UI:
http://localhost:9080(or configured port) - Via CLI:
./vmm-cli.py(seedocs/vmm-cli-user-guide.md) - Requires:
- On-chain app registration (see
docs/onchain-governance.md) - Adding compose hash to whitelist
- Deploying via VMM with App ID
- On-chain app registration (see
Accessing Deployed Apps
Ingress mapping pattern: <id>[-[<port>][s|g]].<base_domain>
- Default: TLS termination to TCP
ssuffix: TLS passthroughgsuffix: HTTP/2 with TLS termination (gRPC)
Important Files
dstack/Cargo.toml: Workspace configuration with all Rust cratesdstack/vmm/vmm.toml: VMM configuration (CID pool, port mapping, KMS/gateway URLs)dstack/kms/kms.toml: KMS configuration (contract addresses, RPC endpoints)dstack/gateway/gateway.toml: Gateway configuration (domain, certificates, WireGuard)docker-compose.yaml: App deployment format (normalized to.app-compose.json)
Common Tasks
Adding a New Rust Crate
- Create crate directory and
Cargo.toml - Add to workspace members in
dstack/Cargo.toml - Add workspace dependency if it will be used by other crates
Modifying RPC APIs
RPC definitions use prpc framework with Protocol Buffers:
- Define
.protofiles in*/rpc/proto/ - Use
prpc-buildinbuild.rsto generate Rust code - Implement service traits in main crate
Working with TDX Quotes
- Pure Rust API:
dstack/tdx-attest/ - Verification:
dstack/verifier/usingdcap-qvl - Event log parsing:
dstack/cc-eventlog/
Documentation
- Main README:
README.md - Deployment guide:
docs/deployment.md - VMM CLI guide:
docs/vmm-cli-user-guide.md - Security guide:
docs/security-guide/security-guide.md - Design decisions:
docs/design-and-hardening-decisions.md
When need more detailed info, try to use deepwiki mcp.
Agent Resources
The .agent/ directory contains AI assistant resources:
CODING_TASTE.md— dstack code and PR conventions (API design, compat, security reasoning, code style, project structure, PR style)WRITING_GUIDE.md— Documentation and README writing guidelines (messaging, style, audiences)GPU_TEE_DEPLOYMENT.md— GPU deployment to Phala Cloud (instance types, docker-compose config, debugging)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

