How to Enable or Disable Extensions Using the Dream CLI

Use dream enable <service> to activate an extension and dream disable <service> to deactivate it, which toggles the compose.yaml file and updates the internal state in .extensions.state.

The Dream CLI (dream-server/dream-cli) serves as the primary command-line interface for managing the Light-Heart-Labs/DreamServer stack. Rather than manually editing Docker Compose files, you can enable or disable extensions—such as whisper, n8n, or litellm—with simple commands that handle dependency validation and state tracking automatically.

Understanding Extension State Management

Extensions in the Dream Server are implemented as Docker Compose fragments stored in individual service directories. The CLI tracks whether an extension is enabled or disabled using a dual mechanism:

• File system state: Active extensions maintain a compose.yaml file in their service directory (extensions/services/<service>/compose.yaml), while disabled extensions have their file renamed to compose.yaml.disabled
• Registry state: A hidden state file .extensions.state records the current status of each extension

This approach allows the scripts/resolve-compose-stack.sh script to dynamically assemble the final Docker Compose configuration based on which extensions are currently active, without requiring manual YAML edits.

Enabling an Extension

The dream enable <service> command activates a disabled extension and prepares it for the next dream start or dream up operation.

Validation and Dependency Resolution

When you run the enable command, the cmd_enable function (located at line 1775 in dream-server/dream-cli) performs several validation steps:

1. Circular dependency checks ensure that enabling the requested service won't create an impossible dependency loop
2. Recursive dependency resolution (around line 1862) automatically enables any services declared as dependencies in the extension's manifest.yaml

The Enable Process

Once validation passes, the CLI executes the following actions:

• Restores the compose.yaml file from compose.yaml.disabled if it exists
• Records the enabled state by appending enabled:$sid to .extensions.state (see line 2154)
• Triggers regeneration of the .compose-flags file to include the new service in subsequent Docker Compose operations

# Enable the n8n automation extension

dream enable n8n

# → Restores extensions/services/n8n/compose.yaml from compose.yaml.disabled

# → Records "enabled:n8n" in .extensions.state

# → Recursively enables any dependencies declared in manifest.yaml

Disabling an Extension

The dream disable <service> command removes an extension from the active stack while preserving its configuration for future reactivation.

Safety Checks

The cmd_disable function implements safety guards to prevent system damage:

• Core service protection: The CLI refuses to disable essential services (enforced at line 1908)
• Dependency warnings: If other enabled extensions depend on the one being disabled, the CLI warns you (around line 1857) to prevent breaking dependent functionality

The Disable Process

When disabling a service, the CLI:

• Moves the active compose.yaml to compose.yaml.disabled (line 1937)
• Appends disabled:$sid to the state file (line 2156)
• Regenerates the compose flags to exclude the service from the next stack startup

# Disable the Whisper STT extension

dream disable whisper

# → Moves whisper/extensions/services/whisper/compose.yaml → compose.yaml.disabled

# → Records "disabled:whisper" in .extensions.state

Working with Extensions: Practical Examples

Use these commands to manage your Dream Server extensions effectively:

# List currently enabled extensions

dream extensions list

# Enable the n8n extension with its dependencies

dream enable n8n

# Disable the Whisper STT extension

dream disable whisper

# Force regeneration of compose flags (normally automatic)

dream compose-flags

Key Implementation Files

Understanding these source files helps when debugging extension issues:

• dream-server/dream-cli – Contains the cmd_enable and cmd_disable functions along with all state handling logic
• extensions/services/*/compose.yaml – Active extension Docker Compose fragments
• extensions/services/*/compose.yaml.disabled – Inactive extension fragments
• scripts/resolve-compose-stack.sh – Merges base compose, GPU overlays, and enabled extensions into the final Docker Compose configuration
• extensions/services/*/manifest.yaml – Metadata files used for dependency checks

Summary

• Enable extensions with dream enable <service>, which restores compose.yaml from .disabled status and records the state in .extensions.state
• Disable extensions with dream disable <service>, which moves compose.yaml to compose.yaml.disabled while protecting core services
• Dependency tracking is handled automatically, with circular dependency checks and recursive enabling of required services
• State regeneration happens automatically, updating .compose-flags for the next dream up or dream start command

Frequently Asked Questions

Can I manually rename the compose.yaml files instead of using the CLI?

While manually moving compose.yaml to compose.yaml.disabled (or vice versa) will technically toggle the file presence, you should use the Dream CLI commands to ensure the .extensions.state file stays synchronized and dependency checks are performed. Manual changes bypass the validation logic in cmd_enable and cmd_disable, potentially causing startup errors or broken dependency chains.

Why can't I disable certain extensions?

The CLI prevents disabling core services that are essential for the Dream Server stack to function (enforced at line 1908 in the source). If you attempt to disable a core service, the command will exit with an error. Additionally, if other enabled extensions depend on the service you're trying to disable, the CLI will warn you about the dependency conflict before proceeding.

How does the CLI handle extension dependencies?

When enabling an extension, the cmd_enable function recursively processes all dependencies declared in the extension's manifest.yaml file (around line 1862). If a required service is disabled, the CLI automatically enables it first. The system also performs circular dependency checks to prevent configuration loops that would make the stack impossible to start.

Where is the extension state stored?

Extension states are recorded in a hidden file called .extensions.state in the Dream Server directory. Each line follows the format enabled:$service_name or disabled:$service_name. The CLI appends state changes to this file (lines 2154 and 2156) to maintain a persistent record across command executions, which the resolve-compose-stack.sh script reads when building the final Docker Compose configuration.

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