# Service Extension Manifest Structure in Dream Server: Complete YAML Reference

> Explore the service extension manifest structure in Dream Server. This YAML reference details Docker Compose integration, port mapping, health checks, and feature flags for seamless service extension.

- Repository: [Light Heart Labs/DreamServer](https://github.com/Light-Heart-Labs/DreamServer)
- Tags: api-reference
- Published: 2026-05-18

---

**A service extension manifest in Dream Server is a YAML configuration file that defines how services like `llama-server` or `dashboard-api` are integrated, exposing configuration fields for Docker Compose generation, port mapping, health checks, and optional feature flags.**

The **Light-Heart-Labs/DreamServer** repository uses this declarative YAML system to manage service integrations. The **service extension manifest** serves as the contract between the service code and the Dream Server installer, providing the metadata required by the compose-stack resolver to generate runtime configurations and enumerate available capabilities.

## Core Structure of a Service Extension Manifest

Every manifest file follows a strict hierarchy starting with schema declaration and compatibility constraints, followed by the mandatory `service` block and an optional `features` array.

### Schema Version and Compatibility

The manifest begins with version tracking to ensure the Dream Server installer can parse the file correctly.

- **`schema_version`**: Currently set to `dream.services.v1` to indicate the manifest format version.
- **`compatibility.dream_min`**: Specifies the minimum Dream Server version required (e.g., `"2.0.0"`) to prevent installation on incompatible hosts.

### The Service Block (Mandatory)

The `service` block is required and contains the core integration parameters used by [`scripts/resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/scripts/resolve-compose-stack.sh) to generate Docker Compose definitions. According to the source code in [`dream-server/extensions/services/llama-server/manifest.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/extensions/services/llama-server/manifest.yaml), the following fields are available:

**Identification and Naming**
- **`id`**: Unique identifier used internally and in Docker Compose network aliases (e.g., `llama-server`).
- **`name`**: Human-readable name displayed in the UI (e.g., `llama-server (LLM Inference)`).
- **`aliases`**: Alternative short names for service discovery (optional array).
- **`container_name`**: Explicit Docker container name (e.g., `dream-llama-server`).
- **`category`**: Broad grouping for UI organization (e.g., `core`, `productivity`).

**Network Configuration**
- **`port`**: Internal container port exposed by the service (e.g., `8080`).
- **`default_host`**: DNS name used by other services for internal communication (e.g., `llama-server`).
- **`host_env`**: Environment variable that can override the host address (optional).
- **`external_port_env`**: Name of the environment variable that can change the exposed host port (e.g., `OLLAMA_PORT`).
- **`external_port_default`**: Default host port if the environment variable is not set (e.g., `8080`).
- **`ui_path`**: Path that the UI should open for the service (e.g., `/`).

**Health and Runtime**
- **`health`**: HTTP endpoint path used for container health checks (e.g., `/health`).
- **`health_timeout`**: Seconds to wait before marking health checks as failed (optional).
- **`type`**: Container runtime type, usually `docker`.
- **`depends_on`**: Array of service IDs that must start before this service (optional).
- **`gpu_backends`**: List of GPU backends the service supports (e.g., `[amd, nvidia]` or `[]` for CPU-only).

## Optional Features Configuration

The `features` array defines optional capabilities that users can enable or disable through the Dream Server UI. This section powers the "Add-on" style interface where capabilities like AI chat or retrieval-augmented generation (RAG) are toggled independently of the base service.

Each feature object in the array supports these fields:

- **`id`**: Unique feature identifier (e.g., `chat`, `rag`).
- **`name`**: Human-readable feature name (e.g., `AI Chat`).
- **`description`**: Short explanation of what the feature provides.
- **`icon`**: UI icon name (e.g., `MessageSquare`, `Database`).
- **`category`**: Feature grouping for organization.
- **`setup_time`**: Approximate initialization time (e.g., `Ready`, `~2 minutes`).
- **`priority`**: Numeric ordering priority for UI display (lower numbers appear first).
- **`gpu_backends`**: GPU backends specific to this feature (optional, defaults to service-level list).

**Resource Requirements**
The `requirements` object specifies prerequisites:
- **`services`**: Array of service IDs that must be installed.
- **`services_any`**: Array where at least one service must be available.
- **`vram_gb`**: Minimum VRAM required in gigabytes.
- **`disk_gb`**: Minimum disk space required.

**Auto-Enable Conditions**
- **`enabled_services_any`**: Enables the feature if any listed service is installed.
- **`enabled_services_all`**: Enables the feature only if all listed services are installed.

## Real-World Manifest Examples

### Minimal Manifest for Static-Only Services

Services without optional features, such as the Dashboard API ([`dream-server/extensions/services/dashboard-api/manifest.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/extensions/services/dashboard-api/manifest.yaml)), define only the core service block:

```yaml
schema_version: dream.services.v1

compatibility:
  dream_min: "2.0.0"

service:
  id: static-docs
  name: Documentation (Static Site)
  container_name: dream-static-docs
  default_host: docs
  port: 80
  external_port_env: DOCS_PORT
  external_port_default: 8080
  health: /health
  ui_path: /
  type: docker
  gpu_backends: []          # No GPU needed

  category: core
  depends_on: []

```

### Feature-Rich LLM Service with GPU Requirements

The `llama-server` manifest demonstrates a complete configuration with the `features` array, including a RAG feature that requires the `qdrant` vector database:

```yaml
schema_version: dream.services.v1

compatibility:
  dream_min: "2.0.0"

service:
  id: llama-server
  name: llama-server (LLM Inference)
  aliases: [llm]
  container_name: dream-llama-server
  host_env: OLLAMA_HOST
  default_host: llama-server
  port: 8080
  external_port_env: OLLAMA_PORT
  external_port_default: 8080
  health: /health
  ui_path: /
  health_timeout: 15
  type: docker
  gpu_backends: [amd, nvidia]
  category: core
  depends_on: []

features:
  - id: chat
    name: AI Chat
    description: Chat with your local AI model
    icon: MessageSquare
    category: core
    requirements:
      services_any: [llama-server]
    enabled_services_any: [llama-server]
    setup_time: Ready
    priority: 1
  
  - id: rag
    name: Retrieval-Augmented Generation
    description: Combine LLM with vector store
    icon: Database
    category: productivity
    requirements:
      services: [qdrant]
      services_any: [llama-server]
      vram_gb: 4
    enabled_services_all: [qdrant]
    setup_time: ~2 minutes
    priority: 2
    gpu_backends: [amd, nvidia]

```

## How Manifests Drive the Dream Server Lifecycle

The Dream Server installer processes these manifests through several key components:

1. **[`scripts/resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/scripts/resolve-compose-stack.sh)** reads all manifests in `dream-server/extensions/services/` to build the final Docker Compose file, translating `port`, `depends_on`, and `container_name` fields into service definitions.

2. **[`installers/lib/tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/lib/tier-map.sh)** evaluates the `gpu_backends` arrays to determine which GPU tier configuration to apply during installation, ensuring AMD or NVIDIA runtime parameters are correctly mapped.

3. The health check system uses `health` and `health_timeout` values to determine when a service is ready to receive traffic.

## Summary

- **Every service extension manifest** starts with `schema_version: dream.services.v1` and a `compatibility` block specifying the minimum Dream Server version.
- **The `service` block is mandatory** and must include `id`, `name`, `port`, `type`, and networking fields to enable Docker Compose generation and service discovery.
- **GPU support** is declared via `gpu_backends` at both the service level and feature level, allowing the installer to select appropriate runtime configurations.
- **The `features` array is optional** but required for capabilities that users can toggle independently, supporting conditional activation through `enabled_services_any` or `enabled_services_all`.
- **Resource requirements** such as `vram_gb` and `disk_gb` in the `requirements` object prevent feature installation on under-provisioned hardware.

## Frequently Asked Questions

### What is the required schema version for Dream Server service extension manifests?

Dream Server currently requires `schema_version: dream.services.v1` at the top of every manifest file. This version string tells the [`resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/resolve-compose-stack.sh) script how to parse the remaining YAML structure and ensures backward compatibility as the platform evolves.

### How do I specify GPU requirements in a service extension manifest?

Define the `gpu_backends` field as an array of supported GPU types, such as `[amd, nvidia]`. You can set this at the service level for the entire container, or at the feature level within the `features` array if only specific capabilities require GPU acceleration. An empty array `[]` indicates CPU-only operation.

### What is the difference between `services` and `services_any` in feature requirements?

The `services` array in the `requirements` block requires every listed service to be present before the feature can be enabled, while `services_any` requires at least one service from the list to be available. Similarly, `enabled_services_all` activates a feature only when every specified service is running, whereas `enabled_services_any` activates it when any one service is detected.

### Can a service extension manifest omit the features section?

Yes. The `features` array is entirely optional. Simple services like the **Dashboard API** define only the `service` block in their manifest, making them available as soon as the container passes health checks without requiring user activation of additional capabilities.