feat(cli): disambiguate multiple devcontainer.json configs by config_file

A project can hold several dev container configs (the spec's
.devcontainer/<folder>/devcontainer.json), and `up` already gives each its own
container stamped with a devcontainer.config_file label. But exec /
read-configuration / stop / down resolved the target by devcontainer.local_folder
ONLY, so with two configs up at once they grabbed whichever container came first —
the wrong one half the time.

Add a shared resolveContainerID that prefers the [local_folder, config_file] label
filter (falling back to local_folder for legacy/label-less containers), mirroring
the TS CLI's old/new id-label scheme, and route exec/read-configuration/stop/down
through it. Add --config to stop/down so a specific config can be targeted.

Verified end-to-end: two configs (frontend/backend) up simultaneously; exec
--config and stop --config each hit the correct container. Unit-tested via a
narrow containerLister seam. Useful for driving several dev containers of one
project on a remote host.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: aledbf

docs/go-only-features.md

@@ -121,9 +121,15 @@ devcontainer down .    # stop AND remove the container (a later `up` builds fres
 - The target is resolved from `--workspace-folder` (or the `[path]` arg), or given
   directly with `--id-label` / `--container-id`. Idempotent: a no-op success when
   no matching container exists.
-
-Flags: `--workspace-folder`, `--id-label`, `--container-id`, `--docker-path`
-(plus `--remove-volumes` on `down`).
+- **Multiple configs in one project** (`.devcontainer/frontend/devcontainer.json`,
+  `.devcontainer/backend/devcontainer.json`, …) are disambiguated with `--config`:
+  each config produces its own container (stamped with the `config_file` label), and
+  `stop`/`down`/`exec`/`read-configuration` resolve the right one via
+  `[local_folder, config_file]` (falling back to `local_folder` for legacy
+  containers). Without `--config` on a multi-config project, the first match wins.
+
+Flags: `--workspace-folder`, `--config`, `--id-label`, `--container-id`,
+`--docker-path` (plus `--remove-volumes` on `down`).
 
 ## `up --cache-image`
 

docs/parity/cli-flags-inventory.yaml

@@ -1093,6 +1093,9 @@ commands:
       workspace-folder:
         type: string
         description: "Workspace folder path (defaults to [path] or the current directory)."
+      config:
+        type: string
+        description: "devcontainer.json path — disambiguates a project with multiple configs."
       id-label:
         type: string
         array: true
@@ -1111,6 +1114,9 @@ commands:
       workspace-folder:
         type: string
         description: "Workspace folder path (defaults to [path] or the current directory)."
+      config:
+        type: string
+        description: "devcontainer.json path — disambiguates a project with multiple configs."
       id-label:
         type: string
         array: true

internal/cli/container_lookup.go

@@ -0,0 +1,42 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+)
+
+// containerLister is the narrow seam resolveContainerID needs (satisfied by
+// *docker.EngineClient), so the lookup is unit-testable without a daemon.
+type containerLister interface {
+	ListContainers(ctx context.Context, all bool, labelFilters []string) ([]string, error)
+}
+
+// resolveContainerID finds a workspace's dev container. Explicit idLabels win.
+// Otherwise it prefers the [local_folder, config_file] label filter so that
+// multiple devcontainer.json configs in one project (e.g. .devcontainer/frontend
+// and .devcontainer/backend, each its own container) resolve to the RIGHT one,
+// and falls back to local_folder alone for a container created without a
+// config_file label (older runs / --id-label-only) — mirroring the TS CLI's
+// old/new id-label scheme. Returns "" when nothing matches.
+func resolveContainerID(ctx context.Context, engine containerLister, workspaceFolder, configFile string, idLabels []string) string {
+	if len(idLabels) > 0 {
+		if ids, _ := engine.ListContainers(ctx, true, idLabels); len(ids) > 0 {
+			return ids[0]
+		}
+		return ""
+	}
+	if workspaceFolder == "" {
+		return ""
+	}
+	local := fmt.Sprintf("devcontainer.local_folder=%s", resolvePath(workspaceFolder))
+	if configFile != "" {
+		labels := []string{local, fmt.Sprintf("devcontainer.config_file=%s", configFile)}
+		if ids, _ := engine.ListContainers(ctx, true, labels); len(ids) > 0 {
+			return ids[0]
+		}
+	}
+	if ids, _ := engine.ListContainers(ctx, true, []string{local}); len(ids) > 0 {
+		return ids[0]
+	}
+	return ""
+}

internal/cli/container_lookup_test.go

@@ -0,0 +1,63 @@
+package cli
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+// fakeLister answers ListContainers from a map of "sorted,label,filter" -> ids.
+type fakeLister struct{ byFilter map[string][]string }
+
+func (f *fakeLister) ListContainers(_ context.Context, _ bool, labels []string) ([]string, error) {
+	return f.byFilter[strings.Join(labels, "|")], nil
+}
+
+func TestResolveContainerID(t *testing.T) {
+	const (
+		ws    = "/proj"
+		cfgA  = "/proj/.devcontainer/a/devcontainer.json"
+		cfgB  = "/proj/.devcontainer/b/devcontainer.json"
+		local = "devcontainer.local_folder=/proj"
+	)
+	key := func(labels ...string) string { return strings.Join(labels, "|") }
+
+	t.Run("config_file disambiguates multiple configs", func(t *testing.T) {
+		f := &fakeLister{byFilter: map[string][]string{
+			key(local, "devcontainer.config_file="+cfgA): {"idA"},
+			key(local, "devcontainer.config_file="+cfgB): {"idB"},
+			key(local): {"idA", "idB"}, // both share local_folder
+		}}
+		if got := resolveContainerID(context.Background(), f, ws, cfgB, nil); got != "idB" {
+			t.Errorf("cfgB -> %q, want idB", got)
+		}
+		if got := resolveContainerID(context.Background(), f, ws, cfgA, nil); got != "idA" {
+			t.Errorf("cfgA -> %q, want idA", got)
+		}
+	})
+
+	t.Run("falls back to local_folder for legacy container (no config_file match)", func(t *testing.T) {
+		f := &fakeLister{byFilter: map[string][]string{
+			key(local): {"legacy"}, // no config_file-filtered entry
+		}}
+		if got := resolveContainerID(context.Background(), f, ws, cfgA, nil); got != "legacy" {
+			t.Errorf("-> %q, want legacy (fallback)", got)
+		}
+	})
+
+	t.Run("explicit id-labels win", func(t *testing.T) {
+		f := &fakeLister{byFilter: map[string][]string{
+			key("x=y"): {"bylabel"},
+			key(local): {"byfolder"},
+		}}
+		if got := resolveContainerID(context.Background(), f, ws, cfgA, []string{"x=y"}); got != "bylabel" {
+			t.Errorf("-> %q, want bylabel", got)
+		}
+	})
+
+	t.Run("no match", func(t *testing.T) {
+		if got := resolveContainerID(context.Background(), &fakeLister{}, ws, cfgA, nil); got != "" {
+			t.Errorf("-> %q, want empty", got)
+		}
+	})
+}

internal/cli/exec.go

@@ -174,7 +174,11 @@ func runExec(ctx context.Context, opts *execOpts, cmdArgs []string) error {
 	// 2. Find the container
 	containerID := opts.containerID
 	if containerID == "" {
-		containerID = findContainerByOpts(ctx, engine, opts, logger)
+		configFile := ""
+		if loadResult != nil {
+			configFile = loadResult.Config.ConfigFilePath
+		}
+		containerID = findContainerByOpts(ctx, engine, opts, configFile, logger)
 	}
 
 	if containerID == "" {
@@ -369,27 +373,13 @@ func (w *rawLogWriter) Write(p []byte) (int, error) {
 	return len(p), nil
 }
 
-func findContainerByOpts(ctx context.Context, engine *docker.EngineClient, opts *execOpts, logger log.Logger) string {
-	labels := opts.idLabels
-	if len(labels) == 0 && opts.workspaceFolder != "" {
-		labels = []string{
-			fmt.Sprintf("devcontainer.local_folder=%s", resolvePath(opts.workspaceFolder)),
-		}
-	}
-
-	if len(labels) == 0 {
-		return ""
+func findContainerByOpts(ctx context.Context, engine *docker.EngineClient, opts *execOpts, configFile string, logger log.Logger) string {
+	// [local_folder, config_file] disambiguates when a project has multiple
+	// devcontainer.json configs; falls back to local_folder for legacy containers.
+	if id := resolveContainerID(ctx, engine, opts.workspaceFolder, configFile, opts.idLabels); id != "" {
+		return id
 	}
-
-	ids, err := engine.ListContainers(ctx, false, labels)
-	if err != nil || len(ids) == 0 {
-		ids, err = engine.ListContainers(ctx, true, labels)
-		if err != nil || len(ids) == 0 {
-			return findComposeContainer(ctx, engine, opts, logger)
-		}
-	}
-
-	return ids[0]
+	return findComposeContainer(ctx, engine, opts, logger)
 }
 
 func findComposeContainer(ctx context.Context, engine *docker.EngineClient, opts *execOpts, logger log.Logger) string {

internal/cli/read_configuration.go

@@ -214,18 +214,14 @@ func runReadConfiguration(ctx context.Context, out Output, opts *readConfigOpts)
 	}
 
 	containerID := opts.containerID
-	if containerID == "" && engine != nil && len(opts.idLabels) > 0 {
-		ids, _ := engine.ListContainers(ctx, true, opts.idLabels)
-		if len(ids) > 0 {
-			containerID = ids[0]
-		}
-	}
-	if containerID == "" && engine != nil && workspaceFolder != "" {
-		labels := []string{fmt.Sprintf("devcontainer.local_folder=%s", workspaceFolder)}
-		ids, _ := engine.ListContainers(ctx, false, labels)
-		if len(ids) > 0 {
-			containerID = ids[0]
+	if containerID == "" && engine != nil {
+		configFile := ""
+		if result != nil {
+			configFile = result.Config.ConfigFilePath
 		}
+		// [local_folder, config_file] so multiple configs in one project resolve
+		// to the right container (fallback to local_folder for legacy ones).
+		containerID = resolveContainerID(ctx, engine, workspaceFolder, configFile, opts.idLabels)
 	}
 
 	if containerID != "" && engine != nil {

internal/cli/stop.go

@@ -12,6 +12,7 @@ import (
 
 type stopOpts struct {
 	workspaceFolder string
+	configPath      string
 	idLabels        []string
 	containerID     string
 	dockerPath      string
@@ -68,6 +69,7 @@ Go-only command; not part of the upstream @devcontainers/cli.`,
 func addStopFlags(cmd *cobra.Command, opts *stopOpts) {
 	f := cmd.Flags()
 	f.StringVar(&opts.workspaceFolder, "workspace-folder", "", "Workspace folder path (defaults to [path] or the current directory).")
+	f.StringVar(&opts.configPath, "config", "", "devcontainer.json path — disambiguates a project with multiple configs.")
 	f.StringArrayVar(&opts.idLabels, "id-label", nil, "id label(s) of the target container (name=value); repeatable.")
 	f.StringVar(&opts.containerID, "container-id", "", "Target container id directly.")
 	f.StringVar(&opts.dockerPath, "docker-path", "", "Docker CLI path.")
@@ -131,23 +133,17 @@ func runStopOrDown(ctx context.Context, out Output, opts stopOpts, remove bool)
 }
 
 // resolveWorkspaceContainer finds the dev container for a workspace: a directly
-// given --container-id, else the first container matching --id-label or the
-// workspace's devcontainer.local_folder label. all=true so a stopped container
-// is still found (down after a prior stop).
+// given --container-id, else --id-label, else the workspace's container —
+// disambiguated by --config (config_file label) when a project has multiple
+// devcontainer.json configs, falling back to local_folder. all=true so a stopped
+// container is still found (down after a prior stop).
 func resolveWorkspaceContainer(ctx context.Context, engine *docker.EngineClient, opts stopOpts) string {
 	if opts.containerID != "" {
 		return opts.containerID
 	}
-	labels := opts.idLabels
-	if len(labels) == 0 && opts.workspaceFolder != "" {
-		labels = []string{fmt.Sprintf("devcontainer.local_folder=%s", resolvePath(opts.workspaceFolder))}
+	configFile := ""
+	if opts.configPath != "" {
+		configFile = resolvePath(opts.configPath)
 	}
-	if len(labels) == 0 {
-		return ""
-	}
-	ids, err := engine.ListContainers(ctx, true, labels)
-	if err != nil || len(ids) == 0 {
-		return ""
-	}
-	return ids[0]
+	return resolveContainerID(ctx, engine, opts.workspaceFolder, configFile, opts.idLabels)
 }