> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phala.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference

> Configuration reference for dstack-cloud global config, app.json, docker-compose.yaml, and CLI commands.

# 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`

```json theme={"system"}
{
  "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.

```json theme={"system"}
{
  "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):
  ```yaml theme={"system"}
  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

```yaml theme={"system"}
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
```

### Example: AI Inference with GPU

```yaml theme={"system"}
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

```yaml theme={"system"}
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.

```bash theme={"system"}
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

```bash theme={"system"}
#!/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](api-reference)** — Guest Agent and KMS APIs
* **[Glossary](glossary)** — Term definitions