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¶

just clean [ACTION] [SUBOPTION]

Cleanup Actions¶

status¶

Show what would be cleaned (dry-run):

just 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):

just clean all

nuke¶

Nuclear option (requires NUKE confirmation):

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

podman¶

Full podman system prune:

just clean podman

Removes:

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

images¶

Clean podman images:

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

containers¶

Remove stopped containers:

just clean containers

runners¶

Manage GitHub runners:

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

vm¶

Clean VM images:

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

system¶

System cleanup:

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

cache¶

Clean development caches:

just 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¶

# See what would be cleaned
just clean status

# Then decide what to clean
just clean podman

Recover Disk Space¶

# Safe cleanup
just clean all

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

Reset Build Environment¶

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

# Reinstall dependencies
just docs-install

Before Major Rebuild¶

# Clean containers and images
just clean podman

# Then rebuild
just build os

Complete Fresh Start¶

# 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:

# 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:

# 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:

# 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