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.

You will learn

• 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

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

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.

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.

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.

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.

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:

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

settings:
  experimental: warn  # See warnings but continue working

CI/CD Pipeline

For continuous integration where you want stability:

settings:
  experimental: disable  # Block experimental commands in CI

Or use environment-specific configuration:

# In your CI environment
export ATMOS_EXPERIMENTAL=disable

Production Environment

For production where experimental features must be explicitly enabled:

settings:
  experimental: error  # Require explicit opt-in

See Also

• Experimental Features - What "experimental" means and how to provide feedback
• Settings - Overview of all settings
• Devcontainers - Experimental devcontainer support