# atmos devcontainer start

Use this command to start a devcontainer. If the container doesn't exist, it will be created. If it exists but is stopped, it will be started.

## Usage

```shell
atmos devcontainer start <name> [flags]
```

## Arguments

- **`name`** — Name of the devcontainer to start (from `atmos.yaml` configuration)

## Flags

- **`--instance string`** — Instance name for this devcontainer (default: `default`). Use this to run multiple instances of the same devcontainer configuration.
- **`--attach`** — Attach to the container after starting it. This immediately opens an interactive shell in the container.

## Examples

```shell
# Start a devcontainer
atmos devcontainer start geodesic

# Start and immediately attach
atmos devcontainer start geodesic --attach

# Start a specific instance
atmos devcontainer start terraform --instance project-a

# Start with custom runtime (via environment variable)
export ATMOS_CONTAINER_RUNTIME=podman
atmos devcontainer start geodesic
```

## Behavior

1. **Container doesn't exist**: Creates a new container with the configured image, mounts, ports, and environment variables, then starts it
2. **Container exists but stopped**: Starts the existing container
3. **Container already running**: Reports that the container is already running

The container name follows the pattern: `atmos-devcontainer-<name>-<instance>`

## Try it out

### devcontainer

Copy the example into a new directory and make it your own:

```shell
atmos init examples/devcontainer
cd devcontainer
```

Requires a running Podman runtime (the example selects Podman) and network access for the image. The final commands clean up the local container.

```shell
atmos devcontainer start geodesic
atmos devcontainer stop geodesic
atmos devcontainer remove geodesic
```

- [Installation guide](/install)
- [Explore the example](/examples/devcontainer)
- [Initialization and repository settings](/cli/commands/init#examples-and-source-directories)

## See Also

- [Devcontainer Configuration](/cli/configuration/devcontainer) — Configure devcontainers in `atmos.yaml`
- [`atmos devcontainer attach`](/cli/commands/devcontainer/attach)
- [`atmos devcontainer stop`](/cli/commands/devcontainer/stop)
- [`atmos devcontainer list`](/cli/commands/devcontainer/list)