From atmos
Orchestrates devcontainers for reproducible dev environments: start/stop/attach/shell/exec/rebuild, instance management, atmos.yaml config, VS Code integration.
npx claudepluginhub cloudposse/atmos --plugin atmosThis skill uses the workspace's default tool permissions.
Atmos provides native devcontainer management for creating standardized, reproducible development
Diagnoses devcontainer configuration problems and guides Docker-based development environment setup in VS Code and GitHub Codespaces. Addresses slow startups, config errors, parity issues, and multi-service environments.
Documents atmos.yaml structure, discovery, merging, sections (stacks, components/terraform, workflows), env overrides for configuring Atmos IaC projects.
Sets up VS Code .devcontainer with Docker, configurable Node/Bun base images, package managers (bun/npm/pnpm/yarn), ports, mounts, and Claude Code CLI support. Use for devcontainer setup requests.
Share bugs, ideas, or general feedback.
Atmos provides native devcontainer management for creating standardized, reproducible development environments. It provides built-in orchestration that integrates with Atmos authentication, toolchains, and project configuration, replacing the need for external orchestration tooling like Geodesic (though Geodesic container images remain fully supported).
Note: The devcontainer feature is currently experimental. By default (settings.experimental: warn),
Atmos displays a warning but runs the command. Set settings.experimental: silence in atmos.yaml to
suppress the warning, or disable to block experimental commands entirely.
Devcontainers are configured at the top level of atmos.yaml (not under components:).
Each named devcontainer defines container settings and a devcontainer spec:
devcontainer:
default:
settings:
runtime: docker # docker or podman (auto-detected if omitted)
spec:
name: "Atmos Default"
image: "cloudposse/geodesic:latest"
workspaceFolder: "/workspace"
workspaceMount: "type=bind,source=${WORKSPACE},target=/workspace"
mounts:
- "type=bind,source=${HOME}/.aws,target=/root/.aws,readonly"
forwardPorts:
- 8080
containerEnv:
ATMOS_BASE_PATH: "/workspace"
remoteUser: "root"
The following devcontainer spec fields are supported:
| Field | Description |
|---|---|
name | Display name for the container |
image | Container image to use |
build.dockerfile | Path to Dockerfile |
build.context | Build context directory |
build.args | Build arguments |
workspaceFolder | Path inside container for workspace |
workspaceMount | Mount specification for workspace |
mounts | Additional mount points |
forwardPorts | Ports to forward to host |
portsAttributes | Port binding configuration |
runArgs | Extra arguments passed to container runtime |
containerEnv | Environment variables set inside container |
remoteUser | User to run as inside container |
Unsupported fields (features, postCreateCommand, customizations, etc.) are silently ignored
with debug-level logging, allowing compatibility with VS Code devcontainer.json files.
Use ATMOS_LOGS_LEVEL=Debug to see which fields are being ignored.
Use !include to import existing VS Code devcontainer configurations:
devcontainer:
vscode:
settings:
runtime: docker
spec: !include .devcontainer/devcontainer.json
Containers follow the naming convention: atmos-devcontainer.{name}.{instance}
.) separator avoids parsing ambiguity with hyphenated namesdefaultAll Atmos devcontainers are labeled for management:
com.atmos.type=devcontainer
com.atmos.devcontainer.name={name}
com.atmos.devcontainer.instance={instance}
com.atmos.workspace={workspace-path}
com.atmos.created={timestamp}
Atmos automatically detects the available container runtime:
Override with settings.runtime in the devcontainer configuration.
atmos devcontainer start default # Start (create if needed)
atmos devcontainer stop default # Stop running container
atmos devcontainer remove default # Remove container and data
atmos devcontainer rebuild default # Destroy and recreate from scratch
atmos devcontainer shell # Start + attach in one command
atmos devcontainer shell default # Named devcontainer
atmos devcontainer attach default # Attach to running container
atmos devcontainer exec default -- terraform plan
atmos devcontainer exec default -- aws sts get-caller-identity
atmos devcontainer list # List all configured devcontainers
atmos devcontainer config default # Display resolved configuration
atmos devcontainer logs default # Show container logs
Multiple instances of the same devcontainer can run simultaneously:
atmos devcontainer start default --instance alice
atmos devcontainer start default --instance bob
atmos devcontainer list # Shows both instances
atmos devcontainer attach default --instance alice
Devcontainers integrate with the Atmos identity system for credential injection:
atmos devcontainer shell default --identity prod-admin
atmos devcontainer exec default --identity dev -- terraform plan
When --identity is specified, Atmos resolves the identity credentials and passes them
to the container environment.
devcontainer:
default:
spec:
name: "Infrastructure Dev"
image: "cloudposse/geodesic:latest"
workspaceFolder: "/workspace"
workspaceMount: "type=bind,source=${WORKSPACE},target=/workspace"
mounts:
- "type=bind,source=${HOME}/.aws,target=/root/.aws,readonly"
- "type=bind,source=${HOME}/.ssh,target=/root/.ssh,readonly"
containerEnv:
ATMOS_BASE_PATH: "/workspace"
AWS_PROFILE: "default"
remoteUser: "root"
devcontainer:
dev:
spec:
name: "Dev Environment"
image: "cloudposse/geodesic:latest"
containerEnv:
ATMOS_BASE_PATH: "/workspace"
ENVIRONMENT: "dev"
prod:
spec:
name: "Prod Environment"
image: "cloudposse/geodesic:latest"
containerEnv:
ATMOS_BASE_PATH: "/workspace"
ENVIRONMENT: "prod"
devcontainer:
custom:
spec:
name: "Custom Dev"
build:
dockerfile: .devcontainer/Dockerfile
context: .
args:
TERRAFORM_VERSION: "1.9.8"
workspaceFolder: "/workspace"
workspaceMount: "type=bind,source=${WORKSPACE},target=/workspace"