Service Extension Manifest Structure in Dream Server: Complete YAML Reference

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 to generate Docker Compose definitions. According to the source code in 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), define only the core service block:

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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}