feat: configurable unused images threshold with dashboard warning

- Add image_prune_threshold_mb setting (default 1024 MB)
- Add GET /api/docker/unused-images endpoint returning unused image count, size, and threshold status
- Dashboard shows amber warning banner when unused project images exceed threshold
- Banner links to settings page for pruning, shows count and human-readable size (MB/GB)
- Threshold configurable in Docker Image Cleanup section of settings
- DB migration + schema for image_prune_threshold_mb

internal/api/docker.go

@@ -150,6 +150,75 @@ func sanitizeDockerLogLine(line string) string {
 	return line
 }
 
+// unusedImageStats handles GET /api/docker/unused-images.
+// Returns the total size of unused project images and whether the threshold is exceeded.
+func (s *Server) unusedImageStats(w http.ResponseWriter, r *http.Request) {
+	if s.docker == nil {
+		respondJSON(w, http.StatusOK, map[string]any{
+			"total_size_mb": 0, "count": 0, "threshold_mb": 0, "exceeded": false,
+		})
+		return
+	}
+
+	settings, err := s.store.GetSettings()
+	if err != nil {
+		slog.Error("unused images: get settings", "error", err)
+		respondError(w, http.StatusInternalServerError, "internal server error")
+		return
+	}
+
+	projects, err := s.store.GetAllProjects()
+	if err != nil {
+		slog.Error("unused images: list projects", "error", err)
+		respondError(w, http.StatusInternalServerError, "internal server error")
+		return
+	}
+
+	// Build set of active image refs.
+	activeImages := make(map[string]bool)
+	for _, p := range projects {
+		stages, _ := s.store.GetStagesByProjectID(p.ID)
+		for _, st := range stages {
+			instances, _ := s.store.GetInstancesByStageID(st.ID)
+			for _, inst := range instances {
+				if inst.ImageTag != "" {
+					activeImages[p.Image+":"+inst.ImageTag] = true
+				}
+			}
+		}
+	}
+
+	// Sum unused image sizes.
+	ctx := r.Context()
+	var totalSize int64
+	var count int
+	for _, p := range projects {
+		if p.Image == "" {
+			continue
+		}
+		images, err := s.docker.ListImagesByRef(ctx, p.Image)
+		if err != nil {
+			continue
+		}
+		for _, img := range images {
+			if !activeImages[img.Ref] {
+				totalSize += img.Size
+				count++
+			}
+		}
+	}
+
+	totalMB := totalSize / (1024 * 1024)
+	exceeded := settings.ImagePruneThresholdMB > 0 && int(totalMB) >= settings.ImagePruneThresholdMB
+
+	respondJSON(w, http.StatusOK, map[string]any{
+		"total_size_mb": totalMB,
+		"count":         count,
+		"threshold_mb":  settings.ImagePruneThresholdMB,
+		"exceeded":      exceeded,
+	})
+}
+
 // pruneImages handles POST /api/docker/prune-images.
 // Only removes images that belong to Docker Watcher projects (not all system images).
 func (s *Server) pruneImages(w http.ResponseWriter, r *http.Request) {

internal/api/router.go

@@ -198,6 +198,7 @@ func (s *Server) Router() chi.Router {
 			r.Get("/auth/me", s.currentUser)
 			r.Post("/auth/logout", s.logout)
 			r.Get("/proxies", s.listProxyRoutes)
+			r.Get("/docker/unused-images", s.unusedImageStats)
 			r.Get("/projects", s.listProjects)
 			r.Route("/projects/{id}", func(r chi.Router) {
 				r.Get("/", s.getProject)

internal/api/settings.go

@@ -37,6 +37,7 @@ type settingsRequest struct {
 	CloudflareAPIToken   string  `json:"cloudflare_api_token"`
 	CloudflareZoneID     *string `json:"cloudflare_zone_id,omitempty"`
 	NpmAccessListID      *int    `json:"npm_access_list_id,omitempty"`
+	ImagePruneThresholdMB *int   `json:"image_prune_threshold_mb,omitempty"`
 	NpmRemote            *bool   `json:"npm_remote,omitempty"`
 	ProxyProvider        *string `json:"proxy_provider,omitempty"`
 	TraefikEntrypoint    *string `json:"traefik_entrypoint,omitempty"`
@@ -68,6 +69,7 @@ func (s *Server) getSettings(w http.ResponseWriter, r *http.Request) {
 		"npm_email":                 settings.NpmEmail,
 		"has_npm_password":          settings.NpmPassword != "",
 		"npm_remote":               settings.NpmRemote,
+		"image_prune_threshold_mb": settings.ImagePruneThresholdMB,
 		"npm_access_list_id":       settings.NpmAccessListID,
 		"polling_interval":          settings.PollingInterval,
 		"ssl_certificate_id":        settings.SSLCertificateID,
@@ -195,6 +197,9 @@ func (s *Server) updateSettings(w http.ResponseWriter, r *http.Request) {
 		}
 		updated.ProxyProvider = prov
 	}
+	if req.ImagePruneThresholdMB != nil {
+		updated.ImagePruneThresholdMB = *req.ImagePruneThresholdMB
+	}
 	if req.NpmRemote != nil {
 		updated.NpmRemote = *req.NpmRemote
 	}

internal/store/models.go

@@ -74,6 +74,7 @@ type Settings struct {
 	TraefikCertResolver string `json:"traefik_cert_resolver"`
 	TraefikNetwork      string `json:"traefik_network"`
 	TraefikAPIURL       string `json:"traefik_api_url"`
+	ImagePruneThresholdMB int  `json:"image_prune_threshold_mb"`
 	BackupEnabled       bool   `json:"backup_enabled"`
 	BackupIntervalHours  int    `json:"backup_interval_hours"`
 	BackupRetentionCount int    `json:"backup_retention_count"`

internal/store/settings.go

@@ -16,6 +16,7 @@ func (s *Store) GetSettings() (Settings, error) {
 		        cloudflare_api_token, cloudflare_zone_id,
 		        npm_remote, npm_access_list_id, proxy_provider,
 		        traefik_entrypoint, traefik_cert_resolver, traefik_network, traefik_api_url,
+		        image_prune_threshold_mb,
 		        backup_enabled, backup_interval_hours, backup_retention_count,
 		        updated_at
 		 FROM settings WHERE id = 1`,
@@ -26,6 +27,7 @@ func (s *Store) GetSettings() (Settings, error) {
 		&st.CloudflareAPIToken, &st.CloudflareZoneID,
 		&npmRemote, &st.NpmAccessListID, &st.ProxyProvider,
 		&st.TraefikEntrypoint, &st.TraefikCertResolver, &st.TraefikNetwork, &st.TraefikAPIURL,
+		&st.ImagePruneThresholdMB,
 		&backupEnabled, &st.BackupIntervalHours, &st.BackupRetentionCount,
 		&st.UpdatedAt)
 	if err != nil {
@@ -61,6 +63,7 @@ func (s *Store) UpdateSettings(st Settings) error {
 			cloudflare_api_token=?, cloudflare_zone_id=?,
 			npm_remote=?, npm_access_list_id=?, proxy_provider=?,
 			traefik_entrypoint=?, traefik_cert_resolver=?, traefik_network=?, traefik_api_url=?,
+			image_prune_threshold_mb=?,
 			backup_enabled=?, backup_interval_hours=?, backup_retention_count=?,
 			updated_at=?
 		 WHERE id = 1`,
@@ -71,6 +74,7 @@ func (s *Store) UpdateSettings(st Settings) error {
 		st.CloudflareAPIToken, st.CloudflareZoneID,
 		npmRemote, st.NpmAccessListID, st.ProxyProvider,
 		st.TraefikEntrypoint, st.TraefikCertResolver, st.TraefikNetwork, st.TraefikAPIURL,
+		st.ImagePruneThresholdMB,
 		backupEnabled, st.BackupIntervalHours, st.BackupRetentionCount,
 		st.UpdatedAt,
 	)

internal/store/store.go

@@ -121,6 +121,8 @@ func (s *Store) runMigrations() error {
 		`ALTER TABLE projects ADD COLUMN npm_access_list_id INTEGER NOT NULL DEFAULT 0`,
 		// Separate public IP for DNS A records.
 		`ALTER TABLE settings ADD COLUMN public_ip TEXT NOT NULL DEFAULT ''`,
+		// Image prune threshold (MB). Warn on dashboard when exceeded. 0 = disabled.
+		`ALTER TABLE settings ADD COLUMN image_prune_threshold_mb INTEGER NOT NULL DEFAULT 1024`,
 	}
 
 	for _, m := range migrations {
@@ -225,6 +227,7 @@ CREATE TABLE IF NOT EXISTS settings (
 	base_volume_path   TEXT NOT NULL DEFAULT '',
 	ssl_certificate_id     INTEGER NOT NULL DEFAULT 0,
 	npm_remote             INTEGER NOT NULL DEFAULT 0,
+	image_prune_threshold_mb INTEGER NOT NULL DEFAULT 1024,
 	npm_access_list_id     INTEGER NOT NULL DEFAULT 0,
 	traefik_entrypoint     TEXT NOT NULL DEFAULT 'websecure',
 	traefik_cert_resolver  TEXT NOT NULL DEFAULT 'letsencrypt',

web/src/lib/api.ts

@@ -289,6 +289,12 @@ export function listProjectImages(projectId: string): Promise<LocalImage[]> {
 	return get<LocalImage[]>(`/api/projects/${projectId}/images`);
 }
 
+export function getUnusedImageStats(): Promise<{
+	total_size_mb: number; count: number; threshold_mb: number; exceeded: boolean;
+}> {
+	return get<{ total_size_mb: number; count: number; threshold_mb: number; exceeded: boolean }>('/api/docker/unused-images');
+}
+
 export function pruneImages(): Promise<{ images_removed: number; space_reclaimed_mb: number }> {
 	return post<{ images_removed: number; space_reclaimed_mb: number }>('/api/docker/prune-images');
 }

web/src/lib/i18n/en.json

@@ -30,7 +30,9 @@
     "noProjects": "No projects yet.",
     "addFirst": "Add your first project",
     "loadFailed": "Failed to load dashboard",
-    "staleContainers": "Stale Containers"
+    "staleContainers": "Stale Containers",
+    "unusedImagesWarning": "Unused Docker images are taking up disk space",
+    "unusedImages": "unused images"
   },
   "projects": {
     "title": "Projects",
@@ -257,6 +259,8 @@
     "staleThresholdHelp": "Containers inactive for longer than this will be flagged as stale.",
     "dockerCleanup": "Docker Image Cleanup",
     "dockerCleanupHelp": "Remove unused Docker images belonging to your projects. Only images not used by active instances are removed.",
+    "pruneThreshold": "Warning Threshold (MB)",
+    "pruneThresholdHelp": "Show dashboard warning when unused project images exceed this size. 0 = disabled.",
     "pruneImages": "Prune Unused Images",
     "pruning": "Pruning...",
     "pruneResult": "Removed {count} images, reclaimed {mb} MB",

web/src/lib/i18n/ru.json

@@ -30,7 +30,9 @@
     "noProjects": "Проектов пока нет.",
     "addFirst": "Добавьте первый проект",
     "loadFailed": "Не удалось загрузить панель",
-    "staleContainers": "Устаревшие контейнеры"
+    "staleContainers": "Устаревшие контейнеры",
+    "unusedImagesWarning": "Неиспользуемые Docker-образы занимают дисковое пространство",
+    "unusedImages": "неиспользуемых образов"
   },
   "projects": {
     "title": "Проекты",
@@ -257,6 +259,8 @@
     "staleThresholdHelp": "Контейнеры, неактивные дольше этого срока, будут помечены как устаревшие.",
     "dockerCleanup": "Очистка Docker-образов",
     "dockerCleanupHelp": "Удаление неиспользуемых Docker-образов ваших проектов. Удаляются только образы, не используемые активными экземплярами.",
+    "pruneThreshold": "Порог предупреждения (МБ)",
+    "pruneThresholdHelp": "Показывать предупреждение на дашборде, когда неиспользуемые образы превышают этот размер. 0 = отключено.",
     "pruneImages": "Очистить неиспользуемые образы",
     "pruning": "Очистка...",
     "pruneResult": "Удалено {count} образов, освобождено {mb} МБ",

web/src/lib/types.ts

@@ -121,6 +121,7 @@ export interface Settings {
 	dns_provider: string;
 	has_cloudflare_api_token: boolean;
 	cloudflare_zone_id: string;
+	image_prune_threshold_mb: number;
 	proxy_provider: string;
 	traefik_entrypoint: string;
 	traefik_cert_resolver: string;

web/src/routes/+page.svelte

@@ -11,6 +11,9 @@
 	let projects = $state<Project[]>([]);
 	let instancesByProject = $state<Record<string, Instance[]>>({});
 	let staleContainers = $state<StaleContainer[]>([]);
+	let unusedImagesMB = $state(0);
+	let unusedImagesCount = $state(0);
+	let unusedImagesExceeded = $state(false);
 	let loading = $state(true);
 	let error = $state('');
 
@@ -43,6 +46,13 @@
 			}
 			instancesByProject = mapped;
 			staleContainers = staleResult;
+
+			try {
+				const imgStats = await api.getUnusedImageStats();
+				unusedImagesMB = imgStats.total_size_mb;
+				unusedImagesCount = imgStats.count;
+				unusedImagesExceeded = imgStats.exceeded;
+			} catch { /* non-critical */ }
 		} catch (e) {
 			error = e instanceof Error ? e.message : $t('dashboard.loadFailed');
 		} finally {
@@ -125,6 +135,20 @@
 		</a>
 	</div>
 
+	<!-- Unused images warning -->
+	{#if unusedImagesExceeded}
+		<a href="/settings" class="flex items-center gap-3 rounded-xl border border-amber-300 bg-amber-50 dark:border-amber-700 dark:bg-amber-950/30 p-4 transition-colors hover:bg-amber-100 dark:hover:bg-amber-950/50">
+			<div class="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-amber-100 dark:bg-amber-900/50 text-amber-600">
+				<IconAlert size={20} />
+			</div>
+			<div class="flex-1">
+				<p class="text-sm font-medium text-amber-800 dark:text-amber-300">{$t('dashboard.unusedImagesWarning')}</p>
+				<p class="text-xs text-amber-700 dark:text-amber-400">{unusedImagesCount} {$t('dashboard.unusedImages')} &middot; {unusedImagesMB >= 1024 ? (unusedImagesMB / 1024).toFixed(1) + ' GB' : unusedImagesMB + ' MB'}</p>
+			</div>
+			<span class="text-xs font-medium text-amber-600 dark:text-amber-400">{$t('settings.pruneImages')} &rarr;</span>
+		</a>
+	{/if}
+
 	<!-- System health summary -->
 	<SystemHealthCard />
 

web/src/routes/settings/+page.svelte

@@ -23,6 +23,7 @@
 	let baseVolumePath = $state('');
 	let notificationUrl = $state('');
 	let staleThresholdDays = $state('7');
+	let imagePruneThresholdMb = $state('1024');
 
 
 	// Proxy provider state.
@@ -128,6 +129,7 @@
 			baseVolumePath = settings.base_volume_path ?? '';
 			notificationUrl = settings.notification_url ?? '';
 			staleThresholdDays = String(settings.stale_threshold_days ?? 7);
+			imagePruneThresholdMb = String(settings.image_prune_threshold_mb ?? 1024);
 			proxyProvider = settings.proxy_provider ?? 'npm';
 			wildcardDns = settings.wildcard_dns ?? true;
 			dnsProvider = settings.dns_provider ?? '';
@@ -157,6 +159,7 @@
 				base_volume_path: baseVolumePath.trim(), notification_url: notificationUrl.trim(),
 				proxy_provider: proxyProvider,
 				stale_threshold_days: Math.max(1, parseInt(staleThresholdDays, 10) || 7),
+				image_prune_threshold_mb: Math.max(0, parseInt(String(imagePruneThresholdMb), 10) || 0),
 				wildcard_dns: wildcardDns,
 				dns_provider: wildcardDns ? '' : dnsProvider,
 				cloudflare_zone_id: cloudflareZoneId
@@ -363,6 +366,16 @@
 			<div class="mt-6 border-t border-[var(--border-primary)] pt-4">
 				<h3 class="mb-1 text-sm font-semibold text-[var(--text-primary)]">{$t('settings.dockerCleanup')}</h3>
 				<p class="mb-3 text-xs text-[var(--text-tertiary)]">{$t('settings.dockerCleanupHelp')}</p>
+				<div class="mb-3 max-w-xs">
+					<FormField
+						label={$t('settings.pruneThreshold')}
+						name="imagePruneThresholdMb"
+						type="number"
+						bind:value={imagePruneThresholdMb}
+						placeholder="1024"
+						helpText={$t('settings.pruneThresholdHelp')}
+					/>
+				</div>
 				<button
 					type="button"
 					onclick={() => { showPruneConfirm = true; }}