agentleFS
Dstack-TEEDstack-TEE/dstack/CLAUDE.md

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
  1. Distinctive:

    Start log messages and error messages with lowercase text

    line 149
  2. Distinctive:

    Run components in separate terminals:

    line 186
  3. Distinctive:

    Default: TLS termination to TCP

    line 203
  4. Very specific:

    Create crate directory and Cargo.toml

    line 219
  5. Very specific:

    Add to workspace members in dstack/Cargo.toml

    line 220
  6. Distinctive:

    Add workspace dependency if it will be used by other crates

    line 221
  7. Very specific:

    Use prpc-build in build.rs to generate Rust code

    line 227
  8. Distinctive:

    When need more detailed info, try to use deepwiki mcp.

    line 244

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 APIs
  • vsock: 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 management
  • ct_monitor (dstack/ct_monitor/): Certificate Transparency log monitoring
  • verifier (dstack/verifier/): TDX quote verification service using dcap-qvl
  • supervisor (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_variables

Ethereum 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 node

Python SDK

cd sdk/python
make install  # Install dependencies
make test     # Run tests

Test Commands

Running All Tests

# Run all Rust tests (requires simulator)
./dstack/run-tests.sh

This script:

  1. Builds the SDK simulator (sdk/simulator/)
  2. Starts the simulator in background
  3. Sets DSTACK_SIMULATOR_ENDPOINT and TAPPD_SIMULATOR_ENDPOINT
  4. 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=1

Foundry 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 clean

Code 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, or HTTP)
  • 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

  1. Quote Generation: Applications request TDX quotes via getQuote() with reportData (up to 64 bytes)
  2. Quote Verification: dstack-verifier validates quotes using dcap-qvl, verifies OS image hash, and replays RTMRs from event logs
  3. 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

  1. Build guest-OS artifacts with make os-image, which uses the default mkosi backend (see docs/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 delete os/yocto/ either: mkosi still reads patches, units, and scripts from it (grep -rn yocto os/mkosi)
  2. Download or build guest OS image
  3. Run components in separate terminals:
    • KMS: ./dstack-kms -c kms.toml
    • Gateway: sudo ./dstack-gateway -c gateway.toml
    • VMM: ./dstack-vmm -c vmm.toml

Deploying Apps

  • Via Web UI: http://localhost:9080 (or configured port)
  • Via CLI: ./vmm-cli.py (see docs/vmm-cli-user-guide.md)
  • Requires:
    1. On-chain app registration (see docs/onchain-governance.md)
    2. Adding compose hash to whitelist
    3. Deploying via VMM with App ID

Accessing Deployed Apps

Ingress mapping pattern: <id>[-[<port>][s|g]].<base_domain>

  • Default: TLS termination to TCP
  • s suffix: TLS passthrough
  • g suffix: HTTP/2 with TLS termination (gRPC)

Important Files

  • dstack/Cargo.toml: Workspace configuration with all Rust crates
  • dstack/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

  1. Create crate directory and Cargo.toml
  2. Add to workspace members in dstack/Cargo.toml
  3. Add workspace dependency if it will be used by other crates

Modifying RPC APIs

RPC definitions use prpc framework with Protocol Buffers:

  • Define .proto files in */rpc/proto/
  • Use prpc-build in build.rs to generate Rust code
  • Implement service traits in main crate

Working with TDX Quotes

  • Pure Rust API: dstack/tdx-attest/
  • Verification: dstack/verifier/ using dcap-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)

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.