fix: make service config optional in API design

api/apiv1/design/database.go

@@ -199,7 +199,7 @@ var ServiceSpec = g.Type("ServiceSpec", func() {
 			"llm_model":      "gpt-4",
 			"openai_api_key": "sk-...",
 		})
-		g.Meta("struct:tag:json", "config")
+		g.Meta("struct:tag:json", "config,omitempty")
 	})
 	g.Attribute("cpus", g.String, func() {
 		g.Description("The number of CPUs to allocate for this service. It can include the SI suffix 'm', e.g. '500m' for 500 millicpus. Defaults to container defaults if unspecified.")
@@ -225,7 +225,7 @@ var ServiceSpec = g.Type("ServiceSpec", func() {
 		g.Meta("struct:tag:json", "database_connection,omitempty")
 	})
 
-	g.Required("service_id", "service_type", "version", "host_ids", "config")
+	g.Required("service_id", "service_type", "version", "host_ids")
 })
 
 var BackupRepositorySpec = g.Type("BackupRepositorySpec", func() {

docs/services/managing.md

@@ -16,7 +16,7 @@ The following table describes the fields in a service spec:
 | `service_type` | string | Yes | The type of service to run. One of: `mcp`, `rag`, `postgrest`.                                                                                                   |
 | `version` | string | Yes | The service version in semver format (e.g., `1.0.0`) or the literal `latest`.                                                                                   |
 | `host_ids` | array | Yes | The IDs of the hosts to run this service on. One instance is created per host.                                                                                  |
-| `config` | object | Yes | Service-type-specific configuration. See the page for your service type for valid fields.                                                                       |
+| `config` | object | No | Service-type-specific configuration. See the page for your service type for valid fields. When omitted, the service uses sensible defaults.                     |
 | `port` | integer | No | Host port to publish the service on. Set to `0` to let Docker assign a random port. When omitted, the service is not reachable from outside the Docker network. |
 | `cpus` | string | No | CPU limit for the service container. Accepts a decimal (e.g., `"0.5"`) or millicpu suffix (e.g., `"500m"`). Defaults to container defaults if unspecified.      |
 | `memory` | string | No | Memory limit for the service container in SI or IEC notation (e.g., `"512M"`, `"1GiB"`). Defaults to container defaults if unspecified.                        |

server/internal/api/apiv1/convert.go

@@ -44,6 +44,15 @@ func isSensitiveConfigKey(key string) bool {
 	return false
 }
 
+// normalizeConfig ensures a nil config map is converted to an empty map so
+// downstream code never has to nil-check.
+func normalizeConfig(config map[string]any) map[string]any {
+	if config == nil {
+		return map[string]any{}
+	}
+	return config
+}
+
 // scrubSensitiveConfig returns a copy of config with sensitive keys removed,
 // recursively descending into nested maps and slices.
 func scrubSensitiveConfig(config map[string]any) map[string]any {
@@ -685,7 +694,7 @@ func apiToServiceSpec(apiSvc *api.ServiceSpec) (*database.ServiceSpec, error) {
 		Version:            apiSvc.Version,
 		HostIDs:            hostIDs,
 		Port:               apiSvc.Port,
-		Config:             apiSvc.Config,
+		Config:             normalizeConfig(apiSvc.Config),
 		CPUs:               cpus,
 		MemoryBytes:        memory,
 		OrchestratorOpts:   orchestratorOptsToDatabase(apiSvc.OrchestratorOpts),

server/internal/api/apiv1/convert_test.go

@@ -31,3 +31,23 @@ func TestIsSensitiveConfigKey(t *testing.T) {
 		}
 	}
 }
+
+func TestNormalizeConfig(t *testing.T) {
+	t.Run("nil becomes empty map", func(t *testing.T) {
+		result := normalizeConfig(nil)
+		if result == nil {
+			t.Fatal("normalizeConfig(nil) returned nil, want empty map")
+		}
+		if len(result) != 0 {
+			t.Errorf("normalizeConfig(nil) returned map with %d entries, want 0", len(result))
+		}
+	})
+
+	t.Run("non-nil map is returned as-is", func(t *testing.T) {
+		input := map[string]any{"key": "value"}
+		result := normalizeConfig(input)
+		if result["key"] != "value" {
+			t.Errorf("normalizeConfig did not preserve existing entries")
+		}
+	})
+}