Skip to main content

atmos devcontainer

Give your team a ready-to-use development environment with Atmos and its required tools already configured. Start an isolated container and run your project's workflows with a consistent setup across developer machines.

Experimental
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=auto, 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=auto, 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:

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

Example with geodesic:

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​