harbor cache

Manage Harbor cache and clean up resources

The harbor cache command group provides utilities for managing Harbor’s cache, including downloaded datasets, Docker images, and temporary files.

Commands

harbor cache clean

Clean Harbor cache by removing Docker images and the cache directory.

harbor cache clean [OPTIONS]

Options

-f, --force · boolean

Skip confirmation prompt and clean immediately. Default: false

--dry · boolean

Show what would be cleaned without actually cleaning. Default: false

--no-docker · boolean

Skip Docker image cleanup. Default: false

--no-cache-dir · boolean

Skip cache directory cleanup. Default: false

Examples

Clean cache with confirmation:

harbor cache clean

Clean without confirmation:

harbor cache clean --force

Dry run to see what would be cleaned:

harbor cache clean --dry

Clean only Docker images:

harbor cache clean --no-cache-dir

Clean only cache directory:

harbor cache clean --no-docker

What Gets Cleaned

Cache Directory

Location: ~/.cache/harbor/

Contains:

• tasks/: Downloaded datasets and tasks
• jobs/: Job results (only if inside cache)
• registry/: Cached registry metadata
• environments/: Environment build caches

Example structure:

~/.cache/harbor/
├── tasks/
│   ├── terminal-bench@2.0/
│   ├── swe-bench@lite/
│   └── ...
├── jobs/
│   ├── my-job-20260303-120000/
│   └── ...
└── registry/
    └── cache.json

Docker Images

The command removes Docker images matching these patterns:

• alexgshaw/* - Harbor base images
• hb__* - Harbor environment images (prefix: “harbor build”)
• sb__* - Sandbox environment images (prefix: “sandbox build”)

Example images:

alexgshaw/harbor-base:latest
hb__task-001:latest
hb__terminal-bench-task-123:latest
sb__custom-env:latest

Usage Examples

Basic Cleanup

Clean everything with confirmation:

harbor cache clean

Output:

Harbor Cache Cleanup

Cache directory: /home/user/.cache/harbor
Cache size: 2048.50 MB

Docker images to remove: 15 image(s)
  • alexgshaw/harbor-base:latest
  • hb__task-001:latest
  • hb__task-002:latest
  ...

Proceed with cleanup? (y/N): y

✓ Removed cache directory: /home/user/.cache/harbor
✓ Removed 15 Docker image(s)

✓ Cache cleanup completed

Check Before Cleaning

Use dry run to see what would be removed:

harbor cache clean --dry

Output:

Harbor Cache Cleanup

DRY RUN - No changes will be made

Cache directory: /home/user/.cache/harbor
Cache size: 2048.50 MB

Docker images to remove: 15 image(s)
  • alexgshaw/harbor-base:latest
  • hb__task-001:latest
  ...

✓ Dry run completed (no changes made)

Automated Cleanup

Clean without prompts (useful for scripts):

harbor cache clean --force

Selective Cleanup

Clean only Docker images (preserve downloaded tasks):

harbor cache clean --no-cache-dir

Clean only cache directory (preserve Docker images):

harbor cache clean --no-docker

When to Clean Cache

Free Up Disk Space

Docker images and cached tasks can consume significant storage:

# Check disk usage
du -sh ~/.cache/harbor
docker images | grep -E "alexgshaw|hb__|sb__" | wc -l

# Clean up
harbor cache clean

After Evaluations

Clean up after completing evaluations:

# Run evaluation
harbor run --dataset terminal-bench@2.0 --agent claude-code

# Clean up (keep results)
mv ~/.cache/harbor/jobs/my-job-20260303-120000 ./results/
harbor cache clean

Before Major Updates

Clean cache before updating Harbor:

# Clean old cache
harbor cache clean --force

# Update Harbor
uv tool upgrade harbor

# Re-download needed datasets
harbor datasets download terminal-bench@2.0

Development Workflow

Clean frequently during development:

# After testing
harbor cache clean --force

# Or just Docker images
harbor cache clean --no-cache-dir --force

Advanced Usage

Preserve Specific Jobs

Move important job results before cleaning:

# Move important results
mkdir -p ./important-results
cp -r ~/.cache/harbor/jobs/critical-eval-* ./important-results/

# Clean cache
harbor cache clean --force

# Results preserved in ./important-results

Scheduled Cleanup

Automate cache cleanup with cron:

# Add to crontab (clean weekly on Sunday at 2am)
0 2 * * 0 /usr/local/bin/harbor cache clean --force

Selective Docker Cleanup

Clean only old Docker images:

# Remove images older than 7 days
docker image prune --all --filter "until=168h" --filter "label=harbor=true"

# Or use Harbor's cleanup
harbor cache clean --no-cache-dir

Monitor Cache Size

Check cache size before and after:

# Before
du -sh ~/.cache/harbor
docker images | grep -E "alexgshaw|hb__|sb__"

# Clean
harbor cache clean --dry

# After
du -sh ~/.cache/harbor
docker images | grep -E "alexgshaw|hb__|sb__"

Troubleshooting

Docker Cleanup Fails

If Docker cleanup fails:

# Check Docker is running
docker ps

# Manually remove images
docker rmi $(docker images | grep -E "alexgshaw|hb__|sb__" | awk '{print $3}')

# Or force remove
docker rmi -f $(docker images | grep -E "alexgshaw|hb__|sb__" | awk '{print $3}')

Permission Issues

If cache directory cleanup fails:

# Check permissions
ls -la ~/.cache/harbor

# Fix permissions
sudo chown -R $USER:$USER ~/.cache/harbor

# Try again
harbor cache clean

Partial Cleanup

If cleanup is interrupted:

# Check what remains
ls -la ~/.cache/harbor
docker images | grep -E "alexgshaw|hb__|sb__"

# Clean again
harbor cache clean --force

Best Practices

Regular Cleanup

Clean cache periodically:

# Weekly cleanup (keep important results)
harbor cache clean --force

Before Long-Running Jobs

Clean cache to ensure enough disk space:

# Check available space
df -h

# Clean if needed
harbor cache clean --force

# Run job
harbor run --dataset large-benchmark --agent claude-code

Development Iterations

Clean frequently during development:

# After each test iteration
harbor cache clean --no-cache-dir --force  # Keep datasets

CI/CD Integration

Clean cache in CI/CD pipelines:

# .github/workflows/test.yml
steps:
  - name: Clean Harbor cache
    run: harbor cache clean --force
    
  - name: Run tests
    run: harbor run --config test-config.yaml

See Also

• harbor datasets - Download datasets
• harbor run - Run evaluations
• harbor jobs - Manage jobs