feat(config): Add a key-based config API and a default timeout fallback

Clients can now list, fetch, and update the agent's YAML configuration
through dotted keys instead of one bespoke endpoint per setting. Sensitive
keys are masked, string inputs are coerced to the field's real type, and
runtime-applicable keys take effect immediately. The new endpoints sit
behind dedicated config permissions granted only to admins, so the
discovery surface is admin-only by default.

A top-level default timeout setting is the fallback for any block that
does not specify its own, used today by the image cleanup loop. The
legacy /settings endpoints are unchanged.

Author: nfebe

internal/api/config_handlers.go

@@ -0,0 +1,86 @@
+package api
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/flatrun/agent/pkg/config"
+	"github.com/gin-gonic/gin"
+)
+
+func (s *Server) listConfig(c *gin.Context) {
+	entries := config.Walk(s.config)
+	c.JSON(http.StatusOK, gin.H{
+		"config":  entries,
+		"runtime": s.runtimeConfigKeys(),
+	})
+}
+
+func (s *Server) getConfigKey(c *gin.Context) {
+	key := normalizeConfigKey(c.Param("key"))
+	entry, err := config.Get(s.config, key)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"entry":   entry,
+		"runtime": s.runtimeConfigKeys()[key],
+	})
+}
+
+func (s *Server) updateConfigKey(c *gin.Context) {
+	key := normalizeConfigKey(c.Param("key"))
+
+	var req struct {
+		Value interface{} `json:"value"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if err := config.Set(s.config, key, req.Value); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if s.configPath != "" {
+		if err := config.Save(s.config, s.configPath); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "value updated in memory but not persisted: " + err.Error()})
+			return
+		}
+	}
+
+	applied := false
+	if apply, ok := s.runtimeAppliers()[key]; ok {
+		apply(s)
+		applied = true
+	}
+
+	entry, _ := config.Get(s.config, key)
+	c.JSON(http.StatusOK, gin.H{
+		"entry":   entry,
+		"applied": applied,
+	})
+}
+
+func (s *Server) runtimeAppliers() map[string]func(*Server) {
+	return map[string]func(*Server){
+		"cleanup.timeout": func(srv *Server) {
+			srv.manager.SetCleanupTimeout(srv.config.Cleanup.Timeout)
+		},
+	}
+}
+
+func (s *Server) runtimeConfigKeys() map[string]bool {
+	keys := make(map[string]bool)
+	for k := range s.runtimeAppliers() {
+		keys[k] = true
+	}
+	return keys
+}
+
+func normalizeConfigKey(raw string) string {
+	return strings.Trim(raw, "/")
+}

internal/api/server.go

@@ -127,6 +127,7 @@ func New(cfg *config.Config, configPath string) *Server {
 	}
 
 	manager := docker.NewManager(cfg.DeploymentsPath)
+	manager.SetCleanupTimeout(cfg.Cleanup.Timeout)
 	certsDiscovery := certs.NewDiscovery(cfg.DeploymentsPath)
 	networksManager := networks.NewManager()
 	pluginsDir := filepath.Join(cfg.DeploymentsPath, ".flatrun", "plugins")
@@ -375,6 +376,9 @@ func (s *Server) setupRoutes() {
 			protected.GET("/settings", s.authMiddleware.RequirePermission(auth.PermSettingsRead), s.getSettings)
 			protected.PUT("/settings", s.authMiddleware.RequirePermission(auth.PermSettingsWrite), s.updateSettings)
 			protected.PUT("/settings/security", s.authMiddleware.RequirePermission(auth.PermSettingsWrite), s.updateSecuritySettings)
+			protected.GET("/config", s.authMiddleware.RequirePermission(auth.PermConfigRead), s.listConfig)
+			protected.GET("/config/*key", s.authMiddleware.RequirePermission(auth.PermConfigRead), s.getConfigKey)
+			protected.PUT("/config/*key", s.authMiddleware.RequirePermission(auth.PermConfigWrite), s.updateConfigKey)
 
 			// Compose, stats, subdomain (deployment-scoped)
 			protected.GET("/subdomain/generate", s.authMiddleware.RequirePermission(auth.PermDeploymentsRead), s.generateSubdomain)

internal/auth/permissions.go

@@ -33,6 +33,9 @@ const (
 	PermSettingsRead  Permission = "settings:read"
 	PermSettingsWrite Permission = "settings:write"
 
+	PermConfigRead  Permission = "config:read"
+	PermConfigWrite Permission = "config:write"
+
 	PermAuditRead Permission = "audit:read"
 
 	PermContainersRead   Permission = "containers:read"
@@ -88,6 +91,7 @@ var adminPermissions = []Permission{
 	PermUsersRead, PermUsersWrite, PermUsersDelete,
 	PermAPIKeysRead, PermAPIKeysWrite, PermAPIKeysDelete,
 	PermSettingsRead, PermSettingsWrite,
+	PermConfigRead, PermConfigWrite,
 	PermAuditRead,
 	PermContainersRead, PermContainersWrite, PermContainersDelete,
 	PermImagesRead, PermImagesWrite, PermImagesDelete,

internal/docker/cleanup.go

@@ -2,8 +2,8 @@ package docker
 
 import (
 	"context"
+	"log"
 	"strings"
-	"time"
 
 	"github.com/docker/docker/api/types/container"
 	"github.com/docker/docker/api/types/filters"
@@ -48,7 +48,7 @@ func (m *Manager) CleanupDeploymentImages(name string, dryRun bool) (CleanupResu
 		return CleanupResult{}, nil
 	}
 
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	ctx, cancel := context.WithTimeout(context.Background(), m.CleanupTimeout())
 	defer cancel()
 
 	hostImages, err := m.apiClient.listImageRecords(ctx)
@@ -73,6 +73,7 @@ func (m *Manager) CleanupDeploymentImages(name string, dryRun bool) (CleanupResu
 		}
 		if !dryRun {
 			if _, err := m.apiClient.cli.ImageRemove(ctx, img.id, image.RemoveOptions{}); err != nil {
+				log.Printf("cleanup: failed to remove image %s (%s) for deployment %s: %v", img.id, tagLabel, name, err)
 				continue
 			}
 		}
@@ -92,7 +93,7 @@ func (m *Manager) PruneDanglingImages(dryRun bool) (CleanupResult, error) {
 		return CleanupResult{}, nil
 	}
 
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	ctx, cancel := context.WithTimeout(context.Background(), m.CleanupTimeout())
 	defer cancel()
 
 	if dryRun {

internal/docker/manager.go

@@ -23,11 +23,25 @@ type composeContainer struct {
 }
 
 type Manager struct {
-	discovery *Discovery
-	executor  *ComposeExecutor
-	apiClient *APIClient
-	basePath  string
-	mu        sync.RWMutex
+	discovery      *Discovery
+	executor       *ComposeExecutor
+	apiClient      *APIClient
+	basePath       string
+	cleanupTimeout time.Duration
+	mu             sync.RWMutex
+}
+
+func (m *Manager) SetCleanupTimeout(d time.Duration) {
+	if d > 0 {
+		m.cleanupTimeout = d
+	}
+}
+
+func (m *Manager) CleanupTimeout() time.Duration {
+	if m.cleanupTimeout > 0 {
+		return m.cleanupTimeout
+	}
+	return 2 * time.Minute
 }
 
 func NewManager(deploymentsPath string) *Manager {

pkg/config/config.go

@@ -25,6 +25,7 @@ type Config struct {
 	DeploymentsPath string               `yaml:"deployments_path"`
 	SystemFilesRoot string               `yaml:"system_files_root"`
 	DockerSocket    string               `yaml:"docker_socket"`
+	DefaultTimeout  time.Duration        `yaml:"default_timeout"`
 	API             APIConfig            `yaml:"api"`
 	Auth            AuthConfig           `yaml:"auth"`
 	Domain          DomainConfig         `yaml:"domain"`
@@ -37,6 +38,7 @@ type Config struct {
 	Audit           AuditConfig          `yaml:"audit"`
 	Cluster         ClusterConfig        `yaml:"cluster"`
 	SystemTerminal  SystemTerminalConfig `yaml:"system_terminal"`
+	Cleanup         CleanupConfig        `yaml:"cleanup"`
 }
 
 type DomainConfig struct {
@@ -179,6 +181,10 @@ type SystemTerminalConfig struct {
 	ProtectedMode models.ProtectedModeConfig `yaml:"protected_mode" json:"protected_mode"`
 }
 
+type CleanupConfig struct {
+	Timeout time.Duration `yaml:"timeout" json:"timeout"`
+}
+
 func FindConfigPath(providedPath string) string {
 	if providedPath != "" && providedPath != "config.yml" {
 		return providedPath
@@ -265,6 +271,12 @@ func setDefaults(cfg *Config) {
 	if cfg.Health.MetricsRetention == 0 {
 		cfg.Health.MetricsRetention = 24 * time.Hour
 	}
+	if cfg.DefaultTimeout == 0 {
+		cfg.DefaultTimeout = 2 * time.Minute
+	}
+	if cfg.Cleanup.Timeout == 0 {
+		cfg.Cleanup.Timeout = cfg.DefaultTimeout
+	}
 	if cfg.Auth.JWTSecret == "" {
 		cfg.Auth.JWTSecret = "default-secret-change-me"
 	}