# How to Enable or Disable Extensions Using the Dream CLI

> Easily enable or disable extensions in your DreamServer project using the Dream CLI. Learn the simple commands to manage your extension services with precision.

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

---

**Use `dream enable <service>` to activate an extension and `dream disable <service>` to deactivate it, which toggles the [`compose.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/manifest.yaml)

### The Enable Process

Once validation passes, the CLI executes the following actions:

- Restores the [`compose.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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

```bash

# 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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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

```bash

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

```bash

# 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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose.yaml) from `.disabled` status and records the state in `.extensions.state`
- **Disable extensions** with `dream disable <service>`, which moves [`compose.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/resolve-compose-stack.sh) script reads when building the final Docker Compose configuration.