Skip to main content

atmos devcontainer

Use this command to manage development containers (devcontainers) for your Atmos workflows.

Devcontainers provide isolated, reproducible development environments with all required tools and dependencies pre-configured.

Configure Devcontainers

Learn how to configure devcontainers in your atmos.yaml, including runtime selection, mounts, environment variables, and container specifications.

atmos devcontainer --help

Prerequisites​

Container Runtime Required​

Atmos devcontainers require either Docker or Podman to be installed and running on your system.

Installation​

Install Docker Desktop for Mac

# Or via Homebrew
brew install --cask docker

Start Docker Desktop from Applications or Launchpad.

Verification​

docker --version
docker ps

Runtime Selection​

Atmos automatically detects the available container runtime:

  1. Checks for Docker first
  2. Falls back to Podman if Docker is unavailable
  3. You can override with ATMOS_CONTAINER_RUNTIME=docker or ATMOS_CONTAINER_RUNTIME=podman

Usage​

atmos devcontainer <subcommand> [options]

Subcommands​

Container Runtimes​

Atmos supports both Docker and Podman as container runtimes:

  • Auto-detection: Atmos automatically detects the available runtime (Docker first, then Podman)
  • Explicit selection: Set ATMOS_CONTAINER_RUNTIME=docker or ATMOS_CONTAINER_RUNTIME=podman
  • Per-devcontainer: Configure runtime in atmos.yaml under devcontainer.<name>.settings.runtime

Configuration​

Devcontainers are configured in atmos.yaml under the devcontainer section:

components:
  devcontainer:
    <name>:  # Choose any name for your devcontainer (e.g., geodesic, terraform, python)
      settings:
        runtime: podman  # Optional: docker, podman, or omit for auto-detect
      spec: !include devcontainer.json

Example with geodesic:

components:
  devcontainer:
    geodesic:
      spec: !include devcontainer.json

The <name> is a user-defined identifier you choose for your devcontainer. Use it with commands like atmos devcontainer start <name>.

The spec field follows the VS Code Dev Container specification.

Output Masking​

Devcontainer commands support Atmos's automatic secret masking system with some limitations:

Masking Support:

  • ✅ logs - Masking enabled by default
  • ✅ exec - Masking enabled by default for non-interactive commands
  • ⚠️ attach/shell - Masking requires experimental --pty flag (macOS/Linux only)

Interactive Sessions:

Interactive TTY sessions (attach, shell) cannot mask output in standard mode due to TTY limitations. To enable masking in interactive sessions:

# Enable masking in interactive sessions (experimental, macOS/Linux only)
atmos devcontainer attach geodesic --pty
atmos devcontainer shell geodesic --pty
warning

The --pty flag is experimental and not available on Windows. Standard attach/shell mode works on all platforms but cannot mask output in interactive TTY sessions.

For complete masking configuration (patterns, options, use cases), see the Secret Masking Configuration documentation.

Examples​

# List all devcontainers
atmos devcontainer list

# Start a devcontainer
atmos devcontainer start geodesic

# Start and attach in one command
atmos devcontainer start geodesic --attach

# Attach to a running devcontainer
atmos devcontainer attach geodesic

# Show logs
atmos devcontainer logs geodesic

# Rebuild a devcontainer
atmos devcontainer rebuild geodesic

# Stop a devcontainer
atmos devcontainer stop geodesic

# Remove a devcontainer
atmos devcontainer remove geodesic

See Also​