Merge pull request #164 from mhersson/feat/env-only-backends

feat(config): allow env-only backend configuration

Author: mhersson

config.yaml.example

@@ -187,8 +187,7 @@ task_skills:
 #   agent  — contextmatrix-agent: executes cards only (no chat).
 #   chat   — contextmatrix-chat: serves global chat only (not yet released).
 #
-# Roles and callback paths are derived from the entry name — there are no
-# selector fields (default_backend / chat_backend are gone). CM picks:
+# Roles and callback paths are derived from the entry name. CM picks:
 #   task backend  → runner (if enabled) else agent (if enabled)
 #   chat backend  → runner (if enabled) else chat (if enabled)
 #
@@ -207,27 +206,17 @@ task_skills:
 #
 # RESTART REQUIRED: backends are read once at startup. Any change requires
 # a CM restart.
-#
-# MIGRATION (older configs): the old top-level `runner:` block is gone.
-# Move url/api_key into backends.runner (enabled defaults to true).
-# Rename env vars (CONTEXTMATRIX_RUNNER_* → CONTEXTMATRIX_BACKEND_RUNNER_*):
-#   CONTEXTMATRIX_RUNNER_URL                       → ..._BACKEND_RUNNER_URL
-#   CONTEXTMATRIX_RUNNER_API_KEY                   → ..._BACKEND_RUNNER_API_KEY
-#   CONTEXTMATRIX_RUNNER_ENABLED                   → ..._BACKEND_RUNNER_ENABLED
-#   CONTEXTMATRIX_RUNNER_ORCHESTRATOR_SONNET_MODEL → ..._BACKEND_RUNNER_ORCHESTRATOR_SONNET_MODEL
-#   CONTEXTMATRIX_RUNNER_ORCHESTRATOR_OPUS_MODEL   → ..._BACKEND_RUNNER_ORCHESTRATOR_OPUS_MODEL
-#   CONTEXTMATRIX_RUNNER_RECONCILE_INTERVAL        → ..._BACKEND_RUNNER_RECONCILE_INTERVAL
-# The server hard-fails if legacy CONTEXTMATRIX_RUNNER_* vars are still set.
 
 # Backend entries. Valid names: runner, agent, chat.
-# Env per-entry (NAME = RUNNER | AGENT | CHAT):
+# Every field has an env override (NAME = RUNNER | AGENT | CHAT). Env values
+# take precedence over this file, and a backend can be configured through
+# env vars alone:
 #   CONTEXTMATRIX_BACKEND_<NAME>_URL
 #   CONTEXTMATRIX_BACKEND_<NAME>_API_KEY
 #   CONTEXTMATRIX_BACKEND_<NAME>_ENABLED
 #   CONTEXTMATRIX_BACKEND_<NAME>_ORCHESTRATOR_SONNET_MODEL
 #   CONTEXTMATRIX_BACKEND_<NAME>_ORCHESTRATOR_OPUS_MODEL
 #   CONTEXTMATRIX_BACKEND_<NAME>_RECONCILE_INTERVAL
-# The backend entry must be declared in YAML before env vars for it are read.
 backends: {}
 #  runner:
 #    # Base URL of the backend. Protocol paths are appended: /trigger, /kill,

docs/remote-execution.md

@@ -1422,13 +1422,14 @@ Environment variable overrides:
 - `CONTEXTMATRIX_CHAT_IDLE_TTL`
 - `CONTEXTMATRIX_CHAT_MAX_CONCURRENT`
 
-The `CONTEXTMATRIX_BACKEND_<NAME>_*` scheme generalises to any declared backend:
+The `CONTEXTMATRIX_BACKEND_<NAME>_*` scheme generalises to any backend:
 replace `RUNNER` with the uppercased entry name (`AGENT`, `CHAT`). Supported
 suffixes are `_URL`, `_API_KEY`, `_ENABLED`, `_ORCHESTRATOR_SONNET_MODEL`,
-`_ORCHESTRATOR_OPUS_MODEL`, and `_RECONCILE_INTERVAL`. The entry must be
-declared in YAML; unrecognised names or suffixes fail loudly at startup, and
-the task-only fields are still rejected on the `chat` entry whichever channel
-sets them.
+`_ORCHESTRATOR_OPUS_MODEL`, and `_RECONCILE_INTERVAL`. Env values take
+precedence over the config file, and a backend can be configured through env
+vars alone. Unrecognised names or suffixes fail loudly at startup, and
+validation is identical whichever channel sets a field (URL required,
+≥32-char key, task-only fields rejected on the `chat` entry).
 
 **Migration from older configs:** the top-level `runner:` block and
 `CONTEXTMATRIX_RUNNER_*` env vars are gone. Move `url`/`api_key` into

internal/config/config.go

@@ -5,10 +5,8 @@ import (
 	"fmt"
 	"io"
 	"log/slog"
-	"maps"
 	"os"
 	"path/filepath"
-	"slices"
 	"strconv"
 	"strings"
 	"time"
@@ -38,6 +36,18 @@ const (
 // allowlisting. Order is stable (runner, agent, chat) for error messages.
 var allowedBackendNames = []string{BackendNameRunner, BackendNameAgent, BackendNameChat}
 
+// backendEnvSuffixes are the per-entry CONTEXTMATRIX_BACKEND_<NAME>_* env
+// var suffixes. applyEnvOverrides reads each one; checkBackendEnvKeys
+// allowlists the same set — keep the two in sync via this list.
+var backendEnvSuffixes = []string{
+	"_URL",
+	"_API_KEY",
+	"_ENABLED",
+	"_ORCHESTRATOR_SONNET_MODEL",
+	"_ORCHESTRATOR_OPUS_MODEL",
+	"_RECONCILE_INTERVAL",
+}
+
 // BackendConfig is one entry in the backends map: an execution backend CM
 // can drive over the contextmatrix-protocol webhook contract. Read once at
 // startup — changing backends requires a CM restart.
@@ -581,7 +591,7 @@ func Load(path string) (*Config, error) {
 				return nil, err
 			}
 
-			if err := checkBackendEnvKeys(cfg); err != nil {
+			if err := checkBackendEnvKeys(); err != nil {
 				return nil, err
 			}
 
@@ -618,7 +628,7 @@ func Load(path string) (*Config, error) {
 		return nil, err
 	}
 
-	if err := checkBackendEnvKeys(cfg); err != nil {
+	if err := checkBackendEnvKeys(); err != nil {
 		return nil, err
 	}
 
@@ -950,9 +960,27 @@ func applyEnvOverrides(cfg *Config) error {
 		}
 	}
 
-	for name, b := range cfg.Backends {
+	// Backend entries can be configured entirely via env: a variable for one
+	// of the allowed names creates the entry when YAML does not declare it,
+	// so pure-env deployments need no backends stub in the config file.
+	for _, name := range allowedBackendNames {
 		prefix := "CONTEXTMATRIX_BACKEND_" + strings.ToUpper(name)
 
+		anySet := false
+
+		for _, suffix := range backendEnvSuffixes {
+			if os.Getenv(prefix+suffix) != "" {
+				anySet = true
+
+				break
+			}
+		}
+
+		b, declared := cfg.Backends[name]
+		if !declared && !anySet {
+			continue
+		}
+
 		if v := os.Getenv(prefix + "_URL"); v != "" {
 			b.URL = v
 		}
@@ -985,29 +1013,29 @@ func applyEnvOverrides(cfg *Config) error {
 			b.ReconcileInterval = v
 		}
 
+		if cfg.Backends == nil {
+			cfg.Backends = map[string]BackendConfig{}
+		}
+
 		cfg.Backends[name] = b
 	}
 
 	return nil
 }
 
 // checkBackendEnvKeys rejects CONTEXTMATRIX_BACKEND_<NAME>_* variables that
-// do not map to a known (name, suffix) pair. The backend name must be in the
-// closed set (runner, agent, chat) AND be declared in cfg.Backends; the suffix
-// must be one of the per-entry fields below. A typo'd or stale variable must
-// fail loudly, not silently configure nothing. NOTE: when adding a new
-// per-backend env field to applyEnvOverrides, add it to the known set here too.
-func checkBackendEnvKeys(cfg *Config) error {
+// do not map to a known (name, suffix) pair: the name must be in the closed
+// set (runner, agent, chat) and the suffix in backendEnvSuffixes. A typo'd
+// or stale variable must fail loudly, not silently configure nothing. The
+// entry does not need to be declared in YAML — applyEnvOverrides creates it.
+func checkBackendEnvKeys() error {
 	known := map[string]bool{}
 
-	for name := range cfg.Backends {
+	for _, name := range allowedBackendNames {
 		pfx := "CONTEXTMATRIX_BACKEND_" + strings.ToUpper(name)
-		known[pfx+"_URL"] = true
-		known[pfx+"_API_KEY"] = true
-		known[pfx+"_ENABLED"] = true
-		known[pfx+"_ORCHESTRATOR_SONNET_MODEL"] = true
-		known[pfx+"_ORCHESTRATOR_OPUS_MODEL"] = true
-		known[pfx+"_RECONCILE_INTERVAL"] = true
+		for _, suffix := range backendEnvSuffixes {
+			known[pfx+suffix] = true
+		}
 	}
 
 	for _, kv := range os.Environ() {
@@ -1017,11 +1045,11 @@ func checkBackendEnvKeys(cfg *Config) error {
 		}
 
 		if !known[key] {
-			return fmt.Errorf("%s references no configured backend "+
-				"(allowed names: %s; declared: %v) — fix the variable name or add the backends entry",
+			return fmt.Errorf("%s is not a recognised backend env var "+
+				"(names: %s; suffixes: %s) — fix the variable name",
 				key,
 				strings.Join(allowedBackendNames, ", "),
-				slices.Sorted(maps.Keys(cfg.Backends)))
+				strings.Join(backendEnvSuffixes, ", "))
 		}
 	}
 

internal/config/config_test.go

@@ -2498,6 +2498,63 @@ backends:
 	assert.Equal(t, "http://override:9993", cb.URL)
 }
 
+func TestBackendEnvOnlyConfiguration(t *testing.T) {
+	// No backends block in YAML at all: env vars for a valid name create
+	// the entry, so pure-env deployments need no YAML stub.
+	dir := t.TempDir()
+	boardsDir := t.TempDir()
+	path := writeConfigFile(t, dir, minValidBase(boardsDir))
+
+	t.Setenv("CONTEXTMATRIX_BACKEND_RUNNER_URL", "http://env-only:9090")
+	t.Setenv("CONTEXTMATRIX_BACKEND_RUNNER_API_KEY", strings.Repeat("e", 32))
+	t.Setenv("CONTEXTMATRIX_BACKEND_RUNNER_ENABLED", "true")
+
+	cfg, err := Load(path)
+	require.NoError(t, err)
+
+	tb, ok := cfg.TaskBackendConfig()
+	require.True(t, ok, "env-only runner must resolve as task backend")
+	assert.Equal(t, "runner", tb.Name)
+	assert.Equal(t, "http://env-only:9090", tb.URL)
+	// The env-created entry gets the task defaults like a YAML-declared one.
+	assert.Equal(t, "claude-sonnet-4-6", tb.OrchestratorSonnetModel)
+	assert.Equal(t, "claude-opus-4-8", tb.OrchestratorOpusModel)
+	assert.Equal(t, "60s", tb.ReconcileInterval)
+}
+
+func TestBackendEnvOnlyChatConfiguration(t *testing.T) {
+	dir := t.TempDir()
+	boardsDir := t.TempDir()
+	path := writeConfigFile(t, dir, minValidBase(boardsDir))
+
+	t.Setenv("CONTEXTMATRIX_BACKEND_CHAT_URL", "http://env-only:9092")
+	t.Setenv("CONTEXTMATRIX_BACKEND_CHAT_API_KEY", strings.Repeat("e", 32))
+
+	cfg, err := Load(path)
+	require.NoError(t, err)
+
+	cb, ok := cfg.ChatBackendConfig()
+	require.True(t, ok, "env-only chat must resolve as chat backend")
+	assert.Equal(t, "chat", cb.Name)
+
+	_, ok = cfg.TaskBackendConfig()
+	assert.False(t, ok, "chat-only config must not resolve a task backend")
+}
+
+func TestBackendEnvOnlyIncompleteErrors(t *testing.T) {
+	// An env-created entry goes through full validation: enabling a backend
+	// via env without a URL fails loudly instead of half-configuring.
+	dir := t.TempDir()
+	boardsDir := t.TempDir()
+	path := writeConfigFile(t, dir, minValidBase(boardsDir))
+
+	t.Setenv("CONTEXTMATRIX_BACKEND_RUNNER_ENABLED", "true")
+
+	_, err := Load(path)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "url")
+}
+
 func TestBackendEnvUnknownNameErrors(t *testing.T) {
 	cases := []struct {
 		name   string