Configuration Reference

dstack-cloud uses three layers of configuration: a global CLI config, a per-project app.json, and a standard docker-compose.yaml for your application. This page documents every field and available option.

dstack-cloud Global Configuration

Location: ~/.config/dstack-cloud/config.json

{
  "image_search_paths": ["/path/to/your/images"],
  "gcp": {
    "project": "your-gcp-project-id",
    "zone": "us-central1-a",
    "bucket": "gs://your-bucket-name"
  },
  "nitro": {
    "region": "us-east-1"
  }
}

Fields

Field	Type	Description
`image_search_paths`	array of string	Local paths where dstack-cloud looks for OS images
`gcp.project`	string	GCP project ID
`gcp.zone`	string	GCP zone for VM deployment
`gcp.bucket`	string	GCS bucket for storing CVM images
`nitro.region`	string	AWS region for Nitro Enclave deployment

app.json (Project Configuration)

Location: <project-dir>/app.json Generated by dstack-cloud new and edited manually for advanced configuration.

{
  "os_image": "dstack-cloud-0.6.0",
  "key_provider": "local",
  "instance_name": "my-app",
  "platform": "nitro"
}

Fields

Field	Type	Description
`os_image`	string	The dstack OS image version to use
`key_provider`	string	Key provider mode: `local` (default), `tpm`, or `kms`
`instance_name`	string	Human-readable name for the instance
`platform`	string	Target platform: `gcp` or `nitro`

key_provider Values

Value	Description	Use Case
`local`	Keys generated locally within the CVM	Development, testing, single-node
`tpm`	Use the platform TPM as root of trust	KMS instances on GCP
`kms`	Use an external dstack-kms for key delivery	Production workloads that need attested key delivery

docker-compose.yaml

The standard Docker Compose file defines your application. dstack-cloud reads this file and packages all containers into the CVM.

dstack-specific Extensions

dstack-cloud reads the standard docker-compose.yaml format. No special extensions are required. Important notes:

All images must be pullable by the build system (use public registries or pre-pull images)
Use SHA256 digests for pinned images (recommended for reproducible measurements):
```
services:
  web:
    image: nginx:latest@sha256:abc123...
```
The runtime: nvidia field is supported for GPU workloads on compatible instances
volumes that reference /var/run/dstack.sock are automatically mounted for Guest Agent access

Example: Web Application

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"

Example: AI Inference with GPU

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    command: --model Qwen/Qwen2.5-7B-Instruct
    ports:
      - "8000:8000"
    volumes:
      - /var/run/dstack.sock:/var/run/dstack.sock

Example: KMS Instance

services:
  dstack-kms:
    image: phalanetwork/dstack-kms:latest
    environment:
      - KMS_HTTPS_PORT=12001
      - ETH_RPC_URL=https://sepolia.base.org
      - KMS_CONTRACT_ADDR=0x...
      - APP_CONTRACT_ADDR=0x...
    ports:
      - "12001:12001"

.env (Environment Variables)

Location: <project-dir>/.env Standard dotenv format. Used for environment variables that are injected into the CVM.

API_KEY=your-api-key-here
DATABASE_URL=postgres://user:pass@host:5432/db

KMS Environment Variables

Variable	Description	Example
`KMS_HTTPS_PORT`	Port for KMS HTTPS/RA-TLS service	`12001`
`ETH_RPC_URL`	Ethereum RPC endpoint URL	`https://sepolia.base.org`
`KMS_CONTRACT_ADDR`	DstackKms contract address	`0x1234...abcd`
`APP_CONTRACT_ADDR`	DstackApp contract address	`0x5678...efgh`
`USE_LIGHT_CLIENT`	Use helios light client instead of direct RPC	`true` or `false`

Security of Environment Variables

Environment variables are encrypted before leaving your machine
They are decrypted only inside the CVM/TEE
The cloud provider and host OS cannot read them in plaintext

prelaunch.sh (Pre-launch Script)

Location: <project-dir>/prelaunch.sh An optional shell script that runs before the CVM/Enclave launches. Common uses:

Start the VSOCK proxy (Nitro)
Inject environment variables
Generate dynamic configuration

#!/bin/bash
# prelaunch.sh — runs before CVM launch

# Start VSOCK proxy (Nitro only)
socat VSOCK-LISTEN:8000,reuseaddr,fork TCP:localhost:8000 &

# Inject environment variables
export KMS_HTTPS_PORT=12001
export ETH_RPC_URL=https://sepolia.base.org

echo "Prelaunch complete"

dstack-cloud CLI Commands

Command	Description
`dstack-cloud new <name>`	Create a new project directory
`dstack-cloud deploy`	Build and deploy the CVM/Enclave
`dstack-cloud status`	Show deployment status and measurements
`dstack-cloud logs [--follow]`	View container logs
`dstack-cloud stop`	Stop the running CVM/Enclave
`dstack-cloud start`	Start a stopped CVM/Enclave
`dstack-cloud remove`	Remove the deployment and clean up resources
`dstack-cloud fw allow <port>`	Allow inbound traffic on a port
`dstack-cloud fw deny <port>`	Deny inbound traffic on a port
`dstack-cloud pull --os-image <version>`	Download an OS image
`dstack-cloud config-edit`	Edit the global configuration

Next Steps

API Reference — Guest Agent and KMS APIs
Glossary — Term definitions

​Configuration Reference

​dstack-cloud Global Configuration

​Fields

​app.json (Project Configuration)

​Fields

​key_provider Values

​docker-compose.yaml

​dstack-specific Extensions

​Example: Web Application

​Example: AI Inference with GPU

​Example: KMS Instance

​.env (Environment Variables)

​KMS Environment Variables

​Security of Environment Variables

​prelaunch.sh (Pre-launch Script)

​dstack-cloud CLI Commands

​Next Steps

Configuration Reference

dstack-cloud Global Configuration

Fields

app.json (Project Configuration)

Fields

key_provider Values

docker-compose.yaml

dstack-specific Extensions

Example: Web Application

Example: AI Inference with GPU

Example: KMS Instance

.env (Environment Variables)

KMS Environment Variables

Security of Environment Variables

prelaunch.sh (Pre-launch Script)

dstack-cloud CLI Commands

Next Steps