# Using Containers

Atmos natively supports **container components** — stack-scoped, persistent containers. One component
is one service. Atmos owns the image artifact (build/push/pull) and an optional long-running named
container lifecycle (`up`/`ps`/`logs`/`exec`/`restart`/`stop`/`rm`/`down`), discovered by labels
derived from the canonical component instance address — not from local state files.

For the complete command reference, see the [`atmos container`](/cli/commands/container/usage) documentation.

This is different from the ephemeral [`type: container` workflow step](/workflows), which is
`docker run --rm` and workflow-scoped. The component is declarative, addressable infrastructure; the
step is procedural sequencing.

## Stack Configuration

Container component config uses **first-class sections** (`image`, `build`, `run`) — consistent with
the container workflow step, NOT nested under `vars`:

```yaml
components:
  container:
    api:
      composition: storefront            # composition membership (optional)
      image: localhost:5001/api:latest
      build:                             # build the image
        context: app
        dockerfile: Dockerfile
        tags:
          - localhost:5001/api:latest
      run:                               # run configuration
        command: ./api
        ports:
          - host: 8080
            container: 80
        mounts:
          - source: .
            target: /workspace
      env:                               # component env (resolved with secrets)
        PORT: "8080"
```

Inheritance (`metadata.inherits`), catalogs, mixins, and deep-merge work exactly like other component
kinds — define abstract base components with shared `run`/`build` defaults and inherit them.

## Lifecycle

```bash
atmos container build api -s dev      # build the image from `build`
atmos container up api -s dev         # create/start the long-running container (build-on-missing)
atmos container list                  # all container components + running state
atmos container ps api -s dev         # show running state
atmos container logs api -s dev       # stream logs
atmos container exec api -s dev -- sh # run a command inside the container
atmos container down api -s dev       # stop + rm
```

Each instance is named and labeled from its canonical address `<stack>/container/<component>` (e.g.,
`atmos-dev-container-api`), so lifecycle commands discover it by label — there are no local state files.

`atmos container list` shows a running/stopped/unknown indicator for each container component.

## Compositions

A composition groups components into a system. Declare membership with the `composition` field; the
top-level `compositions` section declares the closed set of services:

```yaml
compositions:
  storefront:
    description: Storefront system
    services: [api, worker, database]
```

Run `atmos composition validate storefront -s dev` to see which services are fulfilled vs. not provided
in a stack.

## Related

- [atmos container](/cli/commands/container/usage) — Command reference