feat(config): add isolation.mode enum + mode-aware selector (MCP-34.2)

Introduce a three-way isolation mode (docker | sandbox | none) on both the
global DockerIsolationConfig and per-server IsolationConfig, laying the config
foundation for native (non-Docker) sandbox isolation (MCP-34).

- New `config.IsolationMode` type + constants and `IsValid()` helper.
- Global `DockerIsolationConfig.Mode` with `ResolvedMode()` back-compat mapping:
  explicit Mode wins; else legacy enabled:true ⇒ docker, enabled:false ⇒ none.
- Per-server `IsolationConfig.Mode` (*IsolationMode, nil = inherit global).
- `IsolationManager.ResolveMode()` mode resolver; `ShouldIsolate()` reimplemented
  as `ResolveMode() == docker` so existing Docker behavior is unchanged.
  Precedence: per-server explicit Mode > global gate > per-server bool opt-out;
  structural gates (HTTP / docker-command servers) apply to all modes.
- Config validation rejects unknown global/per-server mode strings.
- Per-server Mode round-trips through BBolt (UpstreamRecord) — test asserts it.
- Regenerated oas/swagger.yaml + docs.go for the new fields.

Sandbox-mode launch wiring (consuming ResolveMode==sandbox) is deferred to
MCP-34.3; no consumer acts on the sandbox value yet.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

Author: Dumbris

internal/config/config.go

@@ -399,9 +399,43 @@ type OAuthConfig struct {
 	ExtraParams  map[string]string `json:"extra_params,omitempty" mapstructure:"extra_params"` // Additional OAuth parameters (e.g., RFC 8707 resource)
 }
 
+// IsolationMode selects how an stdio MCP server's process is isolated (MCP-34.2).
+//
+//   - "docker"  — run the server inside a Docker container (the original behavior).
+//   - "sandbox" — run under a native OS sandbox (Landlock LSM + rlimits on Linux;
+//     see MCP-34). No daemon required.
+//   - "none"    — no isolation; the server process runs directly on the host.
+//
+// The empty string means "unset": back-compat code falls back to the legacy
+// boolean Enabled flag (enabled:true ⇒ docker, enabled:false ⇒ none).
+type IsolationMode string
+
+const (
+	// IsolationModeDocker runs the server inside a Docker container.
+	IsolationModeDocker IsolationMode = "docker"
+	// IsolationModeSandbox runs the server under a native OS sandbox (Landlock/rlimits).
+	IsolationModeSandbox IsolationMode = "sandbox"
+	// IsolationModeNone disables isolation; the process runs directly.
+	IsolationModeNone IsolationMode = "none"
+)
+
+// IsValid reports whether the mode is a recognized value. The empty string
+// ("unset") is treated as valid because the global config falls back to the
+// legacy Enabled bool; callers that require an explicit mode should check for
+// emptiness separately.
+func (m IsolationMode) IsValid() bool {
+	switch m {
+	case IsolationModeDocker, IsolationModeSandbox, IsolationModeNone, "":
+		return true
+	default:
+		return false
+	}
+}
+
 // DockerIsolationConfig represents global Docker isolation settings
 type DockerIsolationConfig struct {
-	Enabled           bool              `json:"enabled" mapstructure:"enabled"`                                // Global enable/disable for Docker isolation
+	Enabled           bool              `json:"enabled" mapstructure:"enabled"`                                // Global enable/disable for Docker isolation (legacy; superseded by Mode)
+	Mode              IsolationMode     `json:"mode,omitempty" mapstructure:"mode"`                            // Isolation mode: "docker" | "sandbox" | "none". Empty falls back to Enabled (MCP-34.2)
 	EnableCacheVolume bool              `json:"enable_cache_volume" mapstructure:"enable_cache_volume"`        // Mount shared cache volumes for faster restarts (default: true)
 	DefaultImages     map[string]string `json:"default_images" mapstructure:"default_images"`                  // Map of runtime type to Docker image
 	Registry          string            `json:"registry,omitempty" mapstructure:"registry"`                    // Custom registry (defaults to docker.io)
@@ -417,14 +451,34 @@ type DockerIsolationConfig struct {
 
 // IsolationConfig represents per-server isolation settings
 type IsolationConfig struct {
-	Enabled     *bool    `json:"enabled,omitempty" mapstructure:"enabled"`             // Enable Docker isolation for this server (nil = inherit global)
-	Image       string   `json:"image,omitempty" mapstructure:"image"`                 // Custom Docker image (overrides default)
-	NetworkMode string   `json:"network_mode,omitempty" mapstructure:"network_mode"`   // Custom network mode for this server
-	ExtraArgs   []string `json:"extra_args,omitempty" mapstructure:"extra_args"`       // Additional docker run arguments for this server
-	WorkingDir  string   `json:"working_dir,omitempty" mapstructure:"working_dir"`     // Custom working directory in container
-	LogDriver   string   `json:"log_driver,omitempty" mapstructure:"log_driver"`       // Docker log driver override for this server
-	LogMaxSize  string   `json:"log_max_size,omitempty" mapstructure:"log_max_size"`   // Maximum size of log files override
-	LogMaxFiles string   `json:"log_max_files,omitempty" mapstructure:"log_max_files"` // Maximum number of log files override
+	Enabled     *bool          `json:"enabled,omitempty" mapstructure:"enabled"`             // Enable Docker isolation for this server (nil = inherit global; legacy, superseded by Mode)
+	Mode        *IsolationMode `json:"mode,omitempty" mapstructure:"mode"`                   // Per-server isolation mode override: "docker" | "sandbox" | "none" (nil = inherit global; MCP-34.2)
+	Image       string         `json:"image,omitempty" mapstructure:"image"`                 // Custom Docker image (overrides default)
+	NetworkMode string         `json:"network_mode,omitempty" mapstructure:"network_mode"`   // Custom network mode for this server
+	ExtraArgs   []string       `json:"extra_args,omitempty" mapstructure:"extra_args"`       // Additional docker run arguments for this server
+	WorkingDir  string         `json:"working_dir,omitempty" mapstructure:"working_dir"`     // Custom working directory in container
+	LogDriver   string         `json:"log_driver,omitempty" mapstructure:"log_driver"`       // Docker log driver override for this server
+	LogMaxSize  string         `json:"log_max_size,omitempty" mapstructure:"log_max_size"`   // Maximum size of log files override
+	LogMaxFiles string         `json:"log_max_files,omitempty" mapstructure:"log_max_files"` // Maximum number of log files override
+}
+
+// ResolvedMode returns the effective global isolation mode, applying back-compat
+// mapping from the legacy Enabled bool (MCP-34.2):
+//
+//   - an explicit Mode always wins;
+//   - otherwise enabled:true ⇒ docker, enabled:false ⇒ none;
+//   - a nil config resolves to none.
+func (dic *DockerIsolationConfig) ResolvedMode() IsolationMode {
+	if dic == nil {
+		return IsolationModeNone
+	}
+	if dic.Mode != "" {
+		return dic.Mode
+	}
+	if dic.Enabled {
+		return IsolationModeDocker
+	}
+	return IsolationModeNone
 }
 
 // IsEnabled returns true if isolation is explicitly enabled, false otherwise.
@@ -1499,11 +1553,28 @@ func (c *Config) ValidateDetailed() []ValidationError {
 		}
 	}
 
+	// Validate global isolation mode (MCP-34.2). Empty is allowed (back-compat
+	// fallback to the Enabled bool); only a non-empty unknown value is invalid.
+	if c.DockerIsolation != nil && !c.DockerIsolation.Mode.IsValid() {
+		errors = append(errors, ValidationError{
+			Field:   "docker_isolation.mode",
+			Message: fmt.Sprintf("invalid isolation mode: %s (must be docker, sandbox, or none)", c.DockerIsolation.Mode),
+		})
+	}
+
 	// Validate server configurations
 	serverNames := make(map[string]bool)
 	for i, server := range c.Servers {
 		fieldPrefix := fmt.Sprintf("mcpServers[%d]", i)
 
+		// Validate per-server isolation mode override (MCP-34.2).
+		if server.Isolation != nil && server.Isolation.Mode != nil && !server.Isolation.Mode.IsValid() {
+			errors = append(errors, ValidationError{
+				Field:   fmt.Sprintf("%s.isolation.mode", fieldPrefix),
+				Message: fmt.Sprintf("invalid isolation mode: %s (must be docker, sandbox, or none)", *server.Isolation.Mode),
+			})
+		}
+
 		// Validate server name
 		if server.Name == "" {
 			errors = append(errors, ValidationError{

internal/config/isolation_mode_test.go

@@ -0,0 +1,95 @@
+package config
+
+import "testing"
+
+// TestDockerIsolationConfig_ResolvedMode_BackCompat verifies the back-compat
+// mapping from the legacy global Enabled bool to the new isolation.mode enum
+// (MCP-34.2): old enabled:true ⇒ mode:docker, enabled:false ⇒ mode:none, and
+// an explicit Mode always wins over the legacy bool.
+func TestDockerIsolationConfig_ResolvedMode_BackCompat(t *testing.T) {
+	tests := []struct {
+		name string
+		cfg  *DockerIsolationConfig
+		want IsolationMode
+	}{
+		{"nil config resolves to none", nil, IsolationModeNone},
+		{"legacy enabled:true ⇒ docker", &DockerIsolationConfig{Enabled: true}, IsolationModeDocker},
+		{"legacy enabled:false ⇒ none", &DockerIsolationConfig{Enabled: false}, IsolationModeNone},
+		{"explicit mode:docker", &DockerIsolationConfig{Mode: IsolationModeDocker}, IsolationModeDocker},
+		{"explicit mode:sandbox", &DockerIsolationConfig{Mode: IsolationModeSandbox}, IsolationModeSandbox},
+		{"explicit mode:none", &DockerIsolationConfig{Mode: IsolationModeNone}, IsolationModeNone},
+		{"explicit mode wins over legacy enabled:false", &DockerIsolationConfig{Enabled: false, Mode: IsolationModeSandbox}, IsolationModeSandbox},
+		{"explicit mode:none wins over legacy enabled:true", &DockerIsolationConfig{Enabled: true, Mode: IsolationModeNone}, IsolationModeNone},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.cfg.ResolvedMode(); got != tt.want {
+				t.Errorf("ResolvedMode() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+// TestIsolationMode_IsValid checks the enum validation helper.
+func TestIsolationMode_IsValid(t *testing.T) {
+	valid := []IsolationMode{IsolationModeDocker, IsolationModeSandbox, IsolationModeNone}
+	for _, m := range valid {
+		if !m.IsValid() {
+			t.Errorf("IsValid(%q) = false, want true", m)
+		}
+	}
+	// Empty string is treated as "unset" (back-compat) and is considered valid
+	// at the global level; only a non-empty unknown value is invalid.
+	if !IsolationMode("").IsValid() {
+		t.Errorf("IsValid(\"\") = false, want true (unset is valid)")
+	}
+	for _, m := range []IsolationMode{"vm", "gvisor", "DOCKER"} {
+		if m.IsValid() {
+			t.Errorf("IsValid(%q) = true, want false", m)
+		}
+	}
+}
+
+// TestConfig_Validate_InvalidIsolationMode ensures an unknown global isolation
+// mode is rejected by config validation.
+func TestConfig_Validate_InvalidIsolationMode(t *testing.T) {
+	c := &Config{
+		DockerIsolation: &DockerIsolationConfig{Mode: IsolationMode("gvisor")},
+	}
+	errs := c.ValidateDetailed()
+	found := false
+	for _, e := range errs {
+		if e.Field == "docker_isolation.mode" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("expected validation error for docker_isolation.mode, got %+v", errs)
+	}
+}
+
+// TestConfig_Validate_InvalidPerServerIsolationMode ensures an unknown
+// per-server isolation mode is rejected by config validation.
+func TestConfig_Validate_InvalidPerServerIsolationMode(t *testing.T) {
+	bad := IsolationMode("vm")
+	c := &Config{
+		Servers: []*ServerConfig{
+			{
+				Name:      "srv",
+				Command:   "npx",
+				Protocol:  "stdio",
+				Isolation: &IsolationConfig{Mode: &bad},
+			},
+		},
+	}
+	errs := c.ValidateDetailed()
+	found := false
+	for _, e := range errs {
+		if e.Field == "mcpServers[0].isolation.mode" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("expected validation error for per-server isolation.mode, got %+v", errs)
+	}
+}

internal/storage/async_ops_test.go

@@ -51,6 +51,7 @@ func TestSaveServerSyncPreservesAllFields(t *testing.T) {
 		Updated:     time.Now(),
 		Isolation: &config.IsolationConfig{
 			Enabled:     config.BoolPtr(true),
+			Mode:        func() *config.IsolationMode { m := config.IsolationModeSandbox; return &m }(),
 			Image:       "python:3.11",
 			NetworkMode: "bridge",
 			ExtraArgs:   []string{"-v", "/host:/container"},
@@ -120,6 +121,10 @@ func TestSaveServerSyncPreservesAllFields(t *testing.T) {
 	if record.Isolation.IsEnabled() != serverConfig.Isolation.IsEnabled() {
 		t.Errorf("Isolation.Enabled mismatch: got %v, want %v", record.Isolation.IsEnabled(), serverConfig.Isolation.IsEnabled())
 	}
+	// MCP-34.2: per-server isolation.mode must survive the BBolt round-trip.
+	if !reflect.DeepEqual(record.Isolation.Mode, serverConfig.Isolation.Mode) {
+		t.Errorf("Isolation.Mode mismatch: got %v, want %v", record.Isolation.Mode, serverConfig.Isolation.Mode)
+	}
 	if record.Isolation.Image != serverConfig.Isolation.Image {
 		t.Errorf("Isolation.Image mismatch: got %s, want %s", record.Isolation.Image, serverConfig.Isolation.Image)
 	}

internal/upstream/core/isolation.go

@@ -153,41 +153,75 @@ func (im *IsolationManager) GetDockerIsolationWarning(serverConfig *config.Serve
 	return ""
 }
 
-// ShouldIsolate determines if a server should be isolated based on global and server config
+// ShouldIsolate determines if a server should be isolated via Docker, based on
+// global and server config. It is the legacy boolean view of ResolveMode and
+// stays in lockstep with it: it returns true iff the resolved mode is "docker".
+// Callers that need to distinguish sandbox/none should call ResolveMode.
 func (im *IsolationManager) ShouldIsolate(serverConfig *config.ServerConfig) bool {
-	// Check if global isolation is disabled
-	if im.globalConfig == nil || !im.globalConfig.Enabled {
-		// If the user explicitly opted THIS server into isolation (via
-		// isolation.enabled: true), warn them once that the per-server
-		// setting is being ignored because the global flag is off. Silent
-		// short-circuits here are a common cause of confusion — telemetry
-		// shows many users configure per-server opt-ins and then wonder why
-		// nothing runs in a container.
-		if im.hasExplicitPerServerOptIn(serverConfig) {
-			im.warnPerServerIgnoredOnce(serverConfig.Name)
-		}
-		return false
-	}
+	return im.ResolveMode(serverConfig) == config.IsolationModeDocker
+}
 
-	// Check if server has isolation config and it's explicitly disabled
-	// With *bool: nil means "inherit global", explicit false means "disabled"
-	if serverConfig.Isolation != nil && serverConfig.Isolation.Enabled != nil && !*serverConfig.Isolation.Enabled {
-		return false
+// ResolveMode resolves the effective isolation mode for a server (MCP-34.2),
+// combining the global config (with legacy Enabled⇒docker back-compat), an
+// optional per-server override, and structural gates.
+//
+// Precedence:
+//  1. A per-server explicit Mode wins outright (even over a disabled global) —
+//     mirroring how other per-server overrides (image, network) take priority.
+//  2. Otherwise, when the global mode resolves to none, per-server bool opt-ins
+//     are ignored (and warned about once), preserving the pre-mode behavior.
+//  3. When the global mode is active, a per-server bool opt-out (enabled:false)
+//     downgrades the server to none.
+//
+// Structural gates then apply to ALL non-none modes: HTTP servers (no command)
+// and servers that already invoke docker are never isolated.
+func (im *IsolationManager) ResolveMode(serverConfig *config.ServerConfig) config.IsolationMode {
+	mode := im.resolveConfiguredMode(serverConfig)
+	if mode == config.IsolationModeNone {
+		return config.IsolationModeNone
 	}
 
-	// Only isolate stdio servers (HTTP servers don't need Docker isolation)
-	if serverConfig.Command == "" {
-		return false
+	// Only isolate stdio servers (HTTP servers don't need a sandbox/container).
+	if serverConfig == nil || serverConfig.Command == "" {
+		return config.IsolationModeNone
 	}
 
-	// Skip isolation for servers that are already using Docker
-	// These are typically pre-configured Docker containers that don't need additional isolation
+	// Skip isolation for servers that already invoke Docker — these are
+	// typically pre-configured containers, and wrapping them (in a container
+	// or a Landlock sandbox) would break their access to the Docker socket.
 	cmdName := filepath.Base(serverConfig.Command)
 	if cmdName == "docker" || strings.Contains(serverConfig.Command, "docker") {
-		return false
+		return config.IsolationModeNone
+	}
+
+	return mode
+}
+
+// resolveConfiguredMode applies the global + per-server config precedence to
+// produce the desired mode, before the structural gates in ResolveMode.
+func (im *IsolationManager) resolveConfiguredMode(serverConfig *config.ServerConfig) config.IsolationMode {
+	globalMode := im.globalConfig.ResolvedMode() // nil-safe; returns none for nil
+
+	// (1) A per-server explicit Mode override wins outright.
+	if serverConfig != nil && serverConfig.Isolation != nil && serverConfig.Isolation.Mode != nil {
+		return *serverConfig.Isolation.Mode
+	}
+
+	// (2) Global isolation off: per-server bool opt-ins are ignored (warn once).
+	if globalMode == config.IsolationModeNone {
+		if im.hasExplicitPerServerOptIn(serverConfig) {
+			im.warnPerServerIgnoredOnce(serverConfig.Name)
+		}
+		return config.IsolationModeNone
+	}
+
+	// (3) Global isolation active: honor a per-server bool opt-out.
+	if serverConfig != nil && serverConfig.Isolation != nil &&
+		serverConfig.Isolation.Enabled != nil && !*serverConfig.Isolation.Enabled {
+		return config.IsolationModeNone
 	}
 
-	return true
+	return globalMode
 }
 
 // hasExplicitPerServerOptIn returns true when the server config explicitly