---
name: container-management
description: Use when the user wants to create, manage, or work with containers, VMs, or isolated development environments. Applies when discussing Docker, systemd-nspawn, libvirt, or container orchestration in projects using gaol.
---

# Container Management with Gaol

Gaol is a cross-platform container and VM management tool. Use the `gaol` CLI for all container operations.

## Quick Reference

### Container Lifecycle
```bash
gaol create <name> --profile base --start    # Create and start
gaol start <name>                            # Start existing
gaol stop <name>                             # Stop container
gaol destroy <name> --force                  # Remove container
gaol list --all-runtimes                     # List all containers
gaol status <name>                           # Show status
```

### Execution
```bash
gaol exec <name> -- <command>                # Run command
gaol shell <name>                            # Interactive shell
gaol logs <name> --follow                    # View logs
```

### Profiles
Common profiles to use with `--profile`:
- `base` - Essential tools (curl, git, vim)
- `dev-python` - Python development (python3, pip, uv)
- `dev-node` - Node.js development (nodejs, npm, pnpm)
- `dev-rust` - Rust development (rustc, cargo)
- `gui` - GUI application support
- `docker-in-docker` - Docker inside containers

### GPU Support
```bash
gaol gpu check                               # Check GPU availability
gaol create <name> --gpu --start             # Create with GPU
gaol exec <name> -- nvidia-smi               # Verify GPU access
```

### Spec Files
Create containers from YAML specs:
```yaml
name: my-dev
runtime: docker
profiles:
  - base
  - dev-python
volumes:
  - .:/workspace
network:
  ports:
    - 8000:8000
```

Apply with: `gaol apply spec.yaml --start`

## Available Runtimes

| Runtime | Use Case |
|---------|----------|
| `docker` | General purpose, wide compatibility |
| `nspawn` | Lightweight, systemd integration (Linux) |
| `libvirt` | Full VM isolation |
| `apple` | Native macOS (Apple Silicon) |

## When to Use

- User mentions "container", "docker", "VM", or "isolated environment"
- User wants to set up a development environment
- User needs to run commands in isolation
- User is working on a project and needs environment setup
