> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Hygiene

> Managing disk space with clawker's Docker resources

Clawker builds custom Docker images, creates config/history volumes, and spins up infrastructure containers (Envoy, CoreDNS, monitoring stack). Over time, these resources accumulate and can consume significant disk space — especially if you rebuild images frequently or work across many projects.

## What accumulates

| Resource               | How it grows                                                                                               | Impact                                                               |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Images**             | Each `clawker build` creates a new image. Old images are not automatically removed.                        | Largest contributor — images range from hundreds of MB to several GB |
| **Build cache**        | BuildKit caches intermediate layers to speed up rebuilds. Cache grows with each unique build.              | Can silently consume tens of GB                                      |
| **Volumes**            | Each project+agent combination gets config and history volumes. Volumes persist across container restarts. | Small individually, but accumulate across projects                   |
| **Stopped containers** | Containers created with `clawker run` or `clawker create` remain after stopping until explicitly removed.  | Minor, but reference images and volumes preventing cleanup           |

## When to clean up

* **Build failures mentioning disk space** — Docker's storage driver has a configurable cap. When reached, builds fail with `no space left on device` or similar errors.
* **Docker Desktop warnings** — Docker Desktop shows disk usage in Settings > Resources. If the virtual disk is near its limit, clawker builds will fail.
* **Slow builds** — An oversized build cache can degrade BuildKit performance.
* **General housekeeping** — periodic cleanup prevents surprise failures during time-sensitive work.

## Cleanup commands

### Clawker-managed resources

Clawker labels all its resources (`dev.clawker.*`), so its own prune commands only affect clawker resources:

```bash theme={"dark"}
# Remove dangling (untagged) clawker images
clawker image prune

# List clawker volumes and remove specific ones
clawker volume list
clawker volume remove <volume-name>

# Remove stopped clawker containers
clawker container list --all   # review first
clawker rm <container-name>
```

<Warning>
  `clawker volume prune` removes **all** unused agent volumes by default — workspace, config, and command history. Config and history volumes persist your agent's settings and shell history across sessions, so they will be lost if the matching agent container is not running at prune time. Passing `--all` widens the sweep further to infrastructure volumes (monitoring stack and any other clawker-managed volumes). Use `clawker volume list` and `clawker volume remove` for targeted cleanup instead.
</Warning>

### Docker-wide cleanup

When clawker-specific cleanup isn't enough, use Docker's built-in commands to reclaim space from all Docker resources — not just clawker's:

```bash theme={"dark"}
# Target BuildKit cache specifically (often the biggest win)
docker builder prune

# Remove all unused images, stopped containers, and networks (across all Docker workloads)
docker system prune

# Nuclear option — removes everything including all images not currently in use
docker system prune -a
```

### Checking disk usage

```bash theme={"dark"}
# Docker's built-in disk usage report
docker system df

# Detailed breakdown (slower, shows per-image and per-volume sizes)
docker system df -v
```

## Recommended routine

There's no need for a strict schedule — just prune when disk usage is becoming a problem or before it does. A reasonable habit:

1. Run `docker system df` to see where space is going
2. Start with `clawker image prune` — old images are usually the biggest win
3. If builds are still failing, run `docker builder prune` to clear the BuildKit cache
4. Use `docker system prune` as a last resort for a broader sweep