# Experimental Features

Atmos introduces new capabilities as experimental features before stabilizing them. The `settings.experimental` configuration controls how these experimental features behave, letting you choose between silent operation, warnings, disabled access, or strict error handling.

> **Key points**
>
> - Control experimental feature visibility and behavior
> - Choose from five modes: silence, disable, warn, warn-daily, error
> - Commands self-register as experimental
> - Automatic notifications without manual configuration

## Configuration

**File:** `atmos.yaml`

```yaml
settings:
  # Control experimental feature handling
  # Values: "silence", "disable", "warn", "warn-daily" (default), "error"
  experimental: warn-daily
```

## Behavior Modes

The `settings.experimental` setting accepts five values that control how Atmos handles experimental commands:

- **`silence`**

  Run experimental commands without any output or notification. Use this when you've already acknowledged the experimental status and want clean output.
  ```yaml
  settings:
    experimental: silence
  ```
- **`disable`**

  Completely disable experimental commands. When a user attempts to run an experimental command, Atmos will display an error and exit. Use this in production environments where experimental features should not be accessible.
  ```yaml
  settings:
    experimental: disable
  ```
  **Example output:**
  ```
  # Error

  **Error:** experimental command is disabled

  ## Hints

  💡 Enable with settings.experimental: warn
  ```
- **`warn`**

  Show a warning notification when running experimental commands, then continue execution. Use this to retain warnings on each top-level invocation.
  ```yaml
  settings:
    experimental: warn
  ```
  **Example output:**
  ```
  🧪 `devcontainer` is an experimental feature. Learn more https://atmos.tools/experimental
  ```
- **`warn-daily` (default)**

  Show a warning at most once per experimental feature every 24 hours, then continue.
  Each feature has its own timestamp: seeing the toolchain warning does not suppress
  the first warning for devcontainers or an experimental setting. Commands within
  the same experimental command family share a timestamp.
  ```yaml
  settings:
    experimental: warn-daily
  ```
  Timestamps are stored in the shared local Atmos cache and apply across commands,
  workflows, custom commands, and projects using that cache. The interval starts
  when each warning is shown, rather than resetting at midnight. Clearing the cache
  makes warnings eligible again. If the cache cannot be read or written, Atmos
  shows the warning and continues. Concurrent suppression is best effort on Windows.

  Editions before `2026-09-14` retain `warn` as the default. An explicit
  `settings.experimental` value or `ATMOS_EXPERIMENTAL` overrides the edition default.
  The `error` and `disable` modes remain enforced on every invocation, including
  nested calls, regardless of cached warnings.
- **`error`**

  Show a warning notification and exit with an error code. Use this when you want to be notified about experimental features but prefer explicit opt-in before using them.
  ```yaml
  settings:
    experimental: error
  ```
  **Example output:**
  ```
  🧪 `devcontainer` is an experimental feature. Learn more https://atmos.tools/experimental

  # Error

  **Error:** experimental command requires explicit opt-in

  ## Hints

  💡 Enable with settings.experimental: warn
  ```

## Environment Variable

You can also control experimental feature handling via environment variable:

```bash
# Silence all experimental warnings
export ATMOS_EXPERIMENTAL=silence

# Disable experimental features
export ATMOS_EXPERIMENTAL=disable

# Enable with warnings on every top-level invocation
export ATMOS_EXPERIMENTAL=warn

# Warn once per feature every 24 hours (default)
export ATMOS_EXPERIMENTAL=warn-daily

# Require explicit opt-in
export ATMOS_EXPERIMENTAL=error
```

The environment variable takes precedence over the configuration file setting.

## Current Experimental Features

The following features are currently marked as experimental:

| Feature | Command | Description |
|---------|---------|-------------|
| AI Assistant | `atmos ai` | AI-powered assistance for infrastructure management |
| IDE Integration | `atmos lsp` | Language Server Protocol for IDE integration |
| Devcontainers | `atmos devcontainer` | Development container lifecycle management |
| Toolchain | `atmos toolchain` | Tool version management and installation |
| Backend Provisioning | `atmos terraform backend` | Terraform state backend management |
| Workdir Management | `atmos terraform workdir` | Component working directory management |
| Affected Components | `atmos list affected` | Identify changes for targeted CI/CD |

> **Note**
>
> Experimental features may change significantly or be removed in future releases. We encourage you to try them and provide feedback, but avoid relying on them in production workflows until they are stabilized.

## Use Cases

### Development Environment

For local development where you want to experiment with new features:

```yaml
settings:
  experimental: warn  # See warnings but continue working
```

### CI/CD Pipeline

For continuous integration where you want stability:

```yaml
settings:
  experimental: disable  # Block experimental commands in CI
```

Or use environment-specific configuration:

```bash
# In your CI environment
export ATMOS_EXPERIMENTAL=disable
```

### Production Environment

For production where experimental features must be explicitly enabled:

```yaml
settings:
  experimental: error  # Require explicit opt-in
```

## See Also

- [Experimental Features](/experimental) - What "experimental" means and how to provide feedback
- [Settings](/cli/configuration/settings) - Overview of all settings
- [Devcontainers](/cli/commands/devcontainer) - Experimental devcontainer support