---

name: clean description: | Development: Cleanup and maintenance for the development environment. Removes build artifacts, caches, containers, and recovers disk space. Run from repository root with 'just clean'. Use when developers need to free disk space or reset the build environment.

Clean - Cleanup & Maintenance

Overview

The clean development commands remove build artifacts, caches, containers, and other temporary files to recover disk space and reset the development environment.

Key Concept: This is a development command - run with just from the repository root, not ujust. It provides both interactive menu and non-interactive modes.

Quick Reference

Safe vs Nuclear Cleanup

Safe Cleanup (just clean all)

Safe cleanup that preserves running containers and configurations:

1. Stop GitHub runners
2. Remove runner containers
3. Remove stopped containers
4. Remove buildah working containers
5. Clean /var/tmp (buildah artifacts)
6. Podman system prune
7. Clean builder cache
8. Prune unused images
9. Remove build logs
10. Remove docs output
11. Remove build output
12. Clean all caches
13. Vacuum journal logs
14. Prune volumes
15. Restart GitHub runners

Use when: You want to free disk space but keep your pod configurations intact.

Nuclear Cleanup (just clean nuke)

DESTROYS EVERYTHING - requires typing 'NUKE' to confirm:

• Removes ALL containers (running and stopped)
• Removes ALL images
• Removes ALL volumes
• Removes ALL pod configurations
• Removes ALL cached data
• Cleans system caches

Use when: You want a completely fresh start or are troubleshooting persistent issues.

Warning: This will delete:

• All pod configurations (you'll need to reconfigure)
• All downloaded container images (will need to re-pull)
• All model data if stored in containers
• All runner configurations

Parameters

Copyjust clean [ACTION] [SUBOPTION]

Cleanup Actions

status

Show what would be cleaned (dry-run):

Copyjust clean status

Reports:

• Podman images/containers
• System files (/var/tmp, journal)
• Build artifacts (logs, docs, output)
• Caches (pixi, venv, pip, etc.)

all

Safe cleanup (15 steps):

Copyjust clean all

nuke

Nuclear option (requires NUKE confirmation):

Copyjust clean nuke
# Type 'NUKE' when prompted to confirm

podman

Full podman system prune:

Copyjust clean podman

Removes:

• All unused images
• Stopped containers
• Unused volumes
• Builder cache

images

Clean podman images:

Copyjust clean images              # Dangling only
just clean images all          # All unused
just clean images build-cache  # Builder cache

containers

Remove stopped containers:

Copyjust clean containers

runners

Manage GitHub runners:

Copyjust clean runners stop   # Stop runners
just clean runners start  # Start runners

vm

Clean VM images:

Copyjust clean vm            # Interactive
just clean vm libvirt    # Libvirt VMs
just clean vm cache      # VM cache

system

System cleanup:

Copyjust clean system        # Interactive
just clean system tmp    # Clean /var/tmp
just clean system journal # Vacuum journal logs

cache

Clean development caches:

Copyjust clean cache          # Interactive
just clean cache pixi     # .pixi/ + ~/.cache/rattler
just clean cache venv     # venv/
just clean cache chunkhound # .chunkhound/
just clean cache pip      # ~/.cache/pip/
just clean cache precommit # ~/.cache/pre-commit/
just clean cache gh       # ~/.cache/gh/

Common Workflows

Check Before Cleanup

Copy# See what would be cleaned
just clean status

# Then decide what to clean
just clean podman

Recover Disk Space

Copy# Safe cleanup
just clean all

# Or targeted cleanup
just clean images all
just clean cache pixi
just clean output

Reset Build Environment

Copy# Clean all caches and build artifacts
just clean cache all
just clean output
just clean docs

# Reinstall dependencies
just docs-install

Before Major Rebuild

Copy# Clean containers and images
just clean podman

# Then rebuild
just build os

Complete Fresh Start

Copy# Nuclear option - destroys everything
just clean nuke
# Type 'NUKE' to confirm

# Reconfigure everything from scratch
ujust jupyter config
ujust ollama config

Disk Space Targets

Troubleshooting

Cleanup Fails with Permission Error

Symptom: Cannot remove files in output/ or /var/tmp

Fix:

Copy# Fix permissions
sudo chown -R $USER:$USER output/

# For /var/tmp
sudo rm -rf /var/tmp/buildah*

Podman Prune Doesn't Free Space

Symptom: Images still present after prune

Cause: Containers referencing images

Fix:

Copy# Stop and remove all containers first
just clean containers
just clean runners stop

# Then prune
just clean podman

GitHub Runners Won't Restart

Symptom: Runners fail to start after cleanup

Cause: Configuration lost or token expired

Fix:

Copy# Re-authenticate
just gh-login

# Reconfigure runners
ujust runners config <REPO_URL> 1

Cross-References

• Related Skills: pods (build pods), vms (build VMs), docs (build docs)
• GitHub Runners: ujust runners (runner management)
• Disk Analysis: just clean status

When to Use This Skill

Use when the user asks about:

• "clean up", "cleanup", "free disk space"
• "remove containers", "prune images"
• "clean cache", "clear cache"
• "just clean", "clean podman"
• "disk full", "out of space"
• "reset environment", "fresh start"
• "nuclear cleanup", "destroy everything"