diff --git a/.xcli.example.yaml b/.xcli.example.yaml
index 554c001..721afcd 100644
--- a/.xcli.example.yaml
+++ b/.xcli.example.yaml
@@ -1,5 +1,5 @@
-# lab-dev configuration example
-# This file is generated by 'lab-dev init' and can be customized for your environment
+# xcli lab configuration example
+# This file is generated by 'xcli lab init' and can be customized for your environment
 
 # Repository paths (auto-discovered or manually specified)
 repos:
@@ -9,6 +9,11 @@ repos:
   labBackend: ../lab-backend
   lab: ../lab
 
+# Optional stable instance id. If omitted, xcli derives one from the config
+# root and config path. With the wrapped config format this is lab.instance.id.
+instance:
+  id: ""
+
 # Operating mode: "local" or "hybrid"
 # - local: All services run locally including Xatu ClickHouse cluster
 # - hybrid: External Xatu data source, local transformations and APIs
@@ -67,7 +72,7 @@ infrastructure:
 
   volumes:
     persist: true  # Use named volumes (data survives down/up cycles)
-                  # Set to false for clean slate every restart
+                  # Use 'xcli lab destroy --instance <id>' for an intentional clean slate
 
   # Observability stack (Prometheus + Grafana)
   # When enabled, starts Prometheus to scrape all lab service metrics
diff --git a/README.md b/README.md
index 8a2c35b..9be958a 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,10 @@ xcli cc           # Launch web dashboard (Command Center)
 xcli lab status   # Check status (CLI)
 ```
 
+Each checkout is a distinct lab instance. A single instance uses the familiar
+default ports when they are free. Additional worktrees get isolated Docker
+resources, generated configs, state, and a non-overlapping port slot.
+
 Services:
 
 - Lab Frontend: <http://localhost:5173>
@@ -160,11 +164,31 @@ Keyboard shortcuts:
 xcli lab init                    # Initialize configuration
 xcli lab check                   # Verify environment (repos, Docker, config)
 xcli lab up                      # Start all services (always rebuilds)
-xcli lab down                    # Stop and remove containers/volumes
-xcli lab clean                   # Remove all containers, volumes, and build artifacts
+xcli lab down                    # Stop the selected instance, preserve data
+xcli lab stop                    # Same safe stop as down
+xcli lab clean                   # Safe alias for down
 xcli lab status                  # Show service status
+xcli lab status --all            # Show all known instances
+xcli lab list                    # List persisted instances
+xcli lab show <instance-id>      # Show one instance manifest and live state
+xcli lab destroy --instance <id> # Delete one instance's data and generated state
+xcli lab reset redis --instance <id> # Intentionally clear Redis for one instance
 ```
 
+`down`, `stop`, and `clean` preserve ClickHouse, Redis, Prometheus, and Grafana
+data. `destroy` and `reset redis` are the destructive paths.
+
+Use `--instance <id>` from any directory to target a specific persisted
+instance:
+
+```bash
+xcli lab --instance worktree-a stop
+xcli lab --instance worktree-a destroy --yes
+```
+
+By default, xcli derives the instance id from the config root and config path.
+You can set a stable id with `lab.instance.id` in `.xcli.yaml`.
+
 ### Build & Rebuild
 
 ```bash
@@ -197,6 +221,9 @@ xcli lab logs -f <service>       # Follow logs
 
 Services: `lab-backend`, `lab-frontend`, `cbt-mainnet`, `cbt-api-mainnet`, etc.
 
+Service commands target the selected instance. Use `xcli lab --instance <id>
+logs lab-backend` to inspect another worktree's stack.
+
 ### Configuration
 
 ```bash
@@ -243,8 +270,11 @@ xcli lab status
 # View logs
 xcli lab logs lab-backend -f
 
-# Complete cleanup (removes all containers, volumes, build artifacts)
-xcli lab clean
+# Diagnose instance paths, ports, traps, and latest rebuild failure
+xcli lab diagnose
+
+# Remove all generated state and data for one instance
+xcli lab destroy --instance <id>
 ```
 
 ### Getting Help
@@ -263,19 +293,23 @@ xcli lab mode --help         # Understand local vs hybrid modes
 `.xcli.yaml` is created by `xcli lab init`. Key settings:
 
 ```yaml
-mode: local  # "local" or "hybrid"
-
-networks:
-  - name: mainnet
-    enabled: true
-    portOffset: 0
-
-infrastructure:
-  clickhouse:
-    xatu:
-      mode: local  # "local" or "external"
-  volumes:
-    persist: true  # Keep data between restarts
+lab:
+  instance:
+    id: worktree-a  # Optional stable id; otherwise xcli derives one
+
+  mode: local  # "local" or "hybrid"
+
+  networks:
+    - name: mainnet
+      enabled: true
+      portOffset: 0
+
+  infrastructure:
+    clickhouse:
+      xatu:
+        mode: local  # "local" or "external"
+    volumes:
+      persist: true  # Keep data between restarts
 ```
 
 **Modes:**
diff --git a/cmd/xcli/main.go b/cmd/xcli/main.go
index 63047a9..1196c6e 100644
--- a/cmd/xcli/main.go
+++ b/cmd/xcli/main.go
@@ -88,6 +88,7 @@ func main() {
 		}
 
 		log.SetLevel(level)
+		config.SetRuntimeConfigPath(configPath)
 
 		// Enable log writer based on verbose flag
 		logWriter.SetEnabled(verbose)
diff --git a/go.mod b/go.mod
index 2ea286e..7a2db20 100644
--- a/go.mod
+++ b/go.mod
@@ -11,6 +11,7 @@ require (
 	github.com/aws/smithy-go v1.26.0
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/containerd/errdefs v1.0.0
 	github.com/docker/docker v28.5.2+incompatible
 	github.com/docker/go-connections v0.7.0
 	github.com/pterm/pterm v0.12.83
@@ -53,7 +54,6 @@ require (
 	github.com/clipperhouse/displaywidth v0.11.0 // indirect
 	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
 	github.com/containerd/console v1.0.5 // indirect
-	github.com/containerd/errdefs v1.0.0 // indirect
 	github.com/containerd/errdefs/pkg v0.3.0 // indirect
 	github.com/containerd/log v0.1.0 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
diff --git a/pkg/cc/backend_lab.go b/pkg/cc/backend_lab.go
index e535c7e..a1e5bd6 100644
--- a/pkg/cc/backend_lab.go
+++ b/pkg/cc/backend_lab.go
@@ -13,6 +13,7 @@ import (
 	"github.com/ethpandaops/xcli/pkg/configtui"
 	"github.com/ethpandaops/xcli/pkg/constants"
 	"github.com/ethpandaops/xcli/pkg/git"
+	"github.com/ethpandaops/xcli/pkg/instance"
 	"github.com/ethpandaops/xcli/pkg/orchestrator"
 	"github.com/ethpandaops/xcli/pkg/seeddata"
 	"github.com/ethpandaops/xcli/pkg/tui"
@@ -27,6 +28,7 @@ type labBackend struct {
 	orch    *orchestrator.Orchestrator
 	labCfg  *config.LabConfig
 	cfgPath string
+	runtime *instance.Runtime
 	gitChk  *git.Checker
 }
 
@@ -39,6 +41,7 @@ func newLabBackend(
 	orch *orchestrator.Orchestrator,
 	labCfg *config.LabConfig,
 	cfgPath string,
+	runtime *instance.Runtime,
 	gitChk *git.Checker,
 ) *labBackend {
 	return &labBackend{
@@ -47,6 +50,7 @@ func newLabBackend(
 		orch:    orch,
 		labCfg:  labCfg,
 		cfgPath: cfgPath,
+		runtime: runtime,
 		gitChk:  gitChk,
 	}
 }
@@ -120,16 +124,16 @@ func (b *labBackend) GetConfigSummary() any {
 		Mode:     b.labCfg.Mode,
 		Networks: networks,
 		Ports: portsInfo{
-			LabBackend:      b.labCfg.Ports.LabBackend,
-			LabFrontend:     b.labCfg.Ports.LabFrontend,
-			CBTBase:         b.labCfg.Ports.CBTBase,
-			CBTAPIBase:      b.labCfg.Ports.CBTAPIBase,
-			CBTFrontendBase: b.labCfg.Ports.CBTFrontendBase,
-			ClickHouseCBT:   b.labCfg.Infrastructure.ClickHouseCBTPort,
-			ClickHouseXatu:  b.labCfg.Infrastructure.ClickHouseXatuPort,
-			Redis:           b.labCfg.Infrastructure.RedisPort,
-			Prometheus:      b.labCfg.Infrastructure.Observability.PrometheusPort,
-			Grafana:         b.labCfg.Infrastructure.Observability.GrafanaPort,
+			LabBackend:      b.portPlan().LabBackend,
+			LabFrontend:     b.portPlan().LabFrontend,
+			CBTBase:         b.portPlan().CBTBase,
+			CBTAPIBase:      b.portPlan().CBTAPIBase,
+			CBTFrontendBase: b.portPlan().CBTFrontendBase,
+			ClickHouseCBT:   b.portPlan().ClickHouseCBT01HTTP,
+			ClickHouseXatu:  b.portPlan().ClickHouseXatu01HTTP,
+			Redis:           b.portPlan().Redis,
+			Prometheus:      b.portPlan().Prometheus,
+			Grafana:         b.portPlan().Grafana,
 		},
 		CfgPath: b.cfgPath,
 	}
@@ -179,7 +183,7 @@ func (b *labBackend) RebuildService(ctx context.Context, name string) error {
 
 // LogSource returns how to stream logs for a given service.
 func (b *labBackend) LogSource(name string) LogSourceInfo {
-	if container, ok := dockerContainerNames[name]; ok {
+	if container, ok := b.orch.InfrastructureManager().DockerContainerName(name); ok {
 		return LogSourceInfo{Type: cmdDocker, Container: container}
 	}
 
@@ -193,13 +197,7 @@ func (b *labBackend) LogFilePath(name string) string {
 
 // GitRepos returns the lab repositories for git status checking.
 func (b *labBackend) GitRepos() map[string]string {
-	return map[string]string{
-		"cbt":         b.labCfg.Repos.CBT,
-		"xatu-cbt":    b.labCfg.Repos.XatuCBT,
-		"cbt-api":     b.labCfg.Repos.CBTAPI,
-		"lab-backend": b.labCfg.Repos.LabBackend,
-		"lab":         b.labCfg.Repos.Lab,
-	}
+	return b.labCfg.Repos.Map()
 }
 
 // GetEditableConfig returns the lab config with passwords masked.
@@ -279,11 +277,7 @@ func (b *labBackend) PutEditableConfig(data json.RawMessage) error {
 // GetOverrides returns the CBT overrides state.
 func (b *labBackend) GetOverrides() (any, error) {
 	xatuCBTPath := b.labCfg.Repos.XatuCBT
-	stateDir := b.orch.StateDir()
-
-	overridesPath := filepath.Join(
-		filepath.Dir(stateDir), constants.CBTOverridesFile,
-	)
+	overridesPath := b.overridesPath()
 
 	externalNames, transformNames, err := configtui.DiscoverModels(xatuCBTPath)
 	if err != nil {
@@ -350,10 +344,7 @@ func (b *labBackend) PutOverrides(data json.RawMessage) error {
 		return fmt.Errorf("invalid request body: %w", err)
 	}
 
-	stateDir := b.orch.StateDir()
-	overridesPath := filepath.Join(
-		filepath.Dir(stateDir), constants.CBTOverridesFile,
-	)
+	overridesPath := b.overridesPath()
 
 	existingOverrides, _, err := configtui.LoadOverrides(overridesPath)
 	if err != nil {
@@ -417,14 +408,14 @@ func (b *labBackend) PutOverrides(data json.RawMessage) error {
 
 // GetConfigFiles lists generated config files with override status.
 func (b *labBackend) GetConfigFiles() ([]configFileInfo, error) {
-	configsDir := filepath.Join(b.orch.StateDir(), "configs")
+	configsDir := filepath.Join(b.orch.StateDir(), constants.DirConfigs)
 
 	entries, err := os.ReadDir(configsDir)
 	if err != nil {
 		return nil, fmt.Errorf("failed to read configs directory: %w", err)
 	}
 
-	customDir := filepath.Join(b.orch.StateDir(), "custom-configs")
+	customDir := b.customConfigsDir()
 	files := make([]configFileInfo, 0, len(entries))
 
 	for _, entry := range entries {
@@ -458,7 +449,7 @@ func (b *labBackend) GetConfigFile(name string) (*configFileContent, error) {
 		return nil, fmt.Errorf("invalid file name")
 	}
 
-	configsDir := filepath.Join(b.orch.StateDir(), "configs")
+	configsDir := filepath.Join(b.orch.StateDir(), constants.DirConfigs)
 	safePath := filepath.Join(configsDir, cleanName)
 
 	content, err := os.ReadFile(safePath)
@@ -471,9 +462,7 @@ func (b *labBackend) GetConfigFile(name string) (*configFileContent, error) {
 		Content: string(content),
 	}
 
-	customPath := filepath.Join(
-		b.orch.StateDir(), "custom-configs", cleanName,
-	)
+	customPath := filepath.Join(b.customConfigsDir(), cleanName)
 
 	overrideContent, overrideErr := os.ReadFile(customPath)
 	if overrideErr == nil {
@@ -496,7 +485,7 @@ func (b *labBackend) PutConfigFileOverride(name, content string) error {
 		return fmt.Errorf("invalid YAML: %w", err)
 	}
 
-	customDir := filepath.Join(b.orch.StateDir(), "custom-configs")
+	customDir := b.customConfigsDir()
 	if err := os.MkdirAll(customDir, 0755); err != nil {
 		return fmt.Errorf("failed to create custom-configs directory: %w", err)
 	}
@@ -522,9 +511,7 @@ func (b *labBackend) DeleteConfigFileOverride(name string) error {
 		return fmt.Errorf("invalid file name")
 	}
 
-	safePath := filepath.Join(
-		b.orch.StateDir(), "custom-configs", cleanName,
-	)
+	safePath := filepath.Join(b.customConfigsDir(), cleanName)
 
 	if err := os.Remove(safePath); err != nil && !os.IsNotExist(err) {
 		return fmt.Errorf("failed to remove override: %w", err)
@@ -544,7 +531,11 @@ func (b *labBackend) Regenerate(ctx context.Context) error {
 
 // RecreateOrchestrator rebuilds the orchestrator with the current config.
 func (b *labBackend) RecreateOrchestrator() error {
-	newOrch, err := orchestrator.NewOrchestrator(b.log, b.labCfg, b.cfgPath)
+	if b.runtime == nil {
+		return fmt.Errorf("lab runtime is required to recreate orchestrator")
+	}
+
+	newOrch, err := orchestrator.NewOrchestratorWithRuntime(b.log, b.runtime)
 	if err != nil {
 		return fmt.Errorf("failed to recreate orchestrator: %w", err)
 	}
@@ -564,7 +555,69 @@ func (b *labBackend) StateDir() string {
 	return b.orch.StateDir()
 }
 
+func (b *labBackend) customConfigsDir() string {
+	return filepath.Join(b.workspaceStateDir(), constants.DirCustomConfigs)
+}
+
+func (b *labBackend) overridesPath() string {
+	if b.runtime != nil {
+		if b.runtime.Workspace != nil && b.runtime.Workspace.OverridesPath != "" {
+			return b.runtime.Workspace.OverridesPath
+		}
+
+		if b.runtime.Manifest != nil && b.runtime.Manifest.OverridesPath != "" {
+			return b.runtime.Manifest.OverridesPath
+		}
+	}
+
+	return filepath.Join(filepath.Dir(b.workspaceStateDir()), constants.CBTOverridesFile)
+}
+
+func (b *labBackend) workspaceStateDir() string {
+	if b.runtime != nil {
+		if b.runtime.Workspace != nil && b.runtime.Workspace.StateDir != "" {
+			return b.runtime.Workspace.StateDir
+		}
+
+		if b.runtime.Manifest != nil && b.runtime.Manifest.RootDir != "" {
+			return filepath.Join(b.runtime.Manifest.RootDir, ".xcli")
+		}
+	}
+
+	stateDir := b.orch.StateDir()
+
+	instancesDir := filepath.Dir(stateDir)
+	if filepath.Base(instancesDir) == "instances" {
+		return filepath.Dir(instancesDir)
+	}
+
+	return filepath.Dir(stateDir)
+}
+
 // RedisAddr returns the Redis address for the Lab stack.
 func (b *labBackend) RedisAddr() string {
-	return fmt.Sprintf("localhost:%d", b.labCfg.Infrastructure.RedisPort)
+	if port := b.portPlan().Redis; port > 0 {
+		return fmt.Sprintf("localhost:%d", port)
+	}
+
+	return "localhost:0"
+}
+
+func (b *labBackend) portPlan() instance.PortPlan {
+	if b.runtime != nil {
+		if len(b.runtime.Ports.AllPorts()) > 0 {
+			return b.runtime.Ports
+		}
+
+		if b.runtime.Manifest != nil && len(b.runtime.Manifest.Ports.AllPorts()) > 0 {
+			return b.runtime.Manifest.Ports
+		}
+	}
+
+	plan, err := instance.BuildPortPlan(b.labCfg, 0)
+	if err != nil {
+		return instance.PortPlan{}
+	}
+
+	return plan
 }
diff --git a/pkg/cc/backend_lab_test.go b/pkg/cc/backend_lab_test.go
new file mode 100644
index 0000000..3e86d2f
--- /dev/null
+++ b/pkg/cc/backend_lab_test.go
@@ -0,0 +1,149 @@
+package cc
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
+	"github.com/ethpandaops/xcli/pkg/instance"
+	"github.com/ethpandaops/xcli/pkg/orchestrator"
+	"github.com/ethpandaops/xcli/pkg/workspace"
+	"github.com/sirupsen/logrus"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLabBackendRedisAddrUsesRuntimePort(t *testing.T) {
+	labCfg := config.DefaultLab()
+	labCfg.Infrastructure.RedisPort = 6380
+	runtime := &instance.Runtime{
+		Ports: instance.PortPlan{Redis: 7380},
+		Manifest: &instance.Manifest{
+			Ports: instance.PortPlan{Redis: 7380},
+		},
+	}
+
+	backend := &labBackend{
+		labCfg:  labCfg,
+		runtime: runtime,
+	}
+
+	require.Equal(t, "localhost:7380", backend.RedisAddr())
+
+	summary, ok := backend.GetConfigSummary().(configResponse)
+	require.True(t, ok)
+	require.Equal(t, 7380, summary.Ports.Redis)
+}
+
+func TestLabBackendConfigOverrideUsesWorkspaceCustomConfigDir(t *testing.T) {
+	runtime := newTestLabRuntime(t, "cc-override")
+	orch, err := orchestrator.NewOrchestratorWithRuntime(logrus.New(), runtime)
+	require.NoError(t, err)
+
+	backend := newLabBackend(
+		logrus.New(),
+		orch,
+		runtime.LabConfig,
+		runtime.Workspace.ConfigPath,
+		runtime,
+		nil,
+	)
+	name := fmt.Sprintf(constants.ConfigFileCBTAPI, "mainnet")
+	content := "custom: true\n"
+
+	require.NoError(t, backend.PutConfigFileOverride(name, content))
+
+	workspaceOverride := filepath.Join(runtime.Workspace.StateDir, constants.DirCustomConfigs, name)
+	instanceOverride := filepath.Join(runtime.Manifest.StateDir, constants.DirCustomConfigs, name)
+	generated := filepath.Join(runtime.Manifest.StateDir, constants.DirConfigs, name)
+
+	require.FileExists(t, workspaceOverride)
+	require.NoFileExists(t, instanceOverride)
+	require.FileExists(t, generated)
+
+	generatedContent, err := os.ReadFile(generated)
+	require.NoError(t, err)
+	require.Equal(t, content, string(generatedContent))
+
+	file, err := backend.GetConfigFile(name)
+	require.NoError(t, err)
+	require.True(t, file.HasOverride)
+	require.Equal(t, content, file.OverrideContent)
+}
+
+func newTestLabRuntime(t *testing.T, instanceID string) *instance.Runtime {
+	t.Helper()
+
+	rootDir := t.TempDir()
+	reposDir := filepath.Join(rootDir, "repos")
+	repoPaths := map[string]string{
+		constants.RepoCBT:        filepath.Join(reposDir, constants.RepoCBT),
+		constants.RepoXatuCBT:    filepath.Join(reposDir, constants.RepoXatuCBT),
+		constants.RepoCBTAPI:     filepath.Join(reposDir, constants.RepoCBTAPI),
+		constants.RepoLabBackend: filepath.Join(reposDir, constants.RepoLabBackend),
+		constants.RepoLab:        filepath.Join(reposDir, constants.RepoLab),
+	}
+
+	for _, path := range repoPaths {
+		require.NoError(t, os.MkdirAll(path, 0755))
+	}
+
+	require.NoError(t, os.MkdirAll(filepath.Join(repoPaths[constants.RepoXatuCBT], "models", "external"), 0755))
+	require.NoError(t, os.MkdirAll(filepath.Join(repoPaths[constants.RepoXatuCBT], "models", "transformations"), 0755))
+	require.NoError(t, os.MkdirAll(filepath.Join(repoPaths[constants.RepoXatuCBT], "models", "scripts"), 0755))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(repoPaths[constants.RepoXatuCBT], "models", "external", "fct_block.sql"),
+		[]byte("SELECT 1"),
+		0600,
+	))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(repoPaths[constants.RepoXatuCBT], "models", "transformations", "fct_summary.sql"),
+		[]byte("SELECT 1"),
+		0600,
+	))
+
+	labCfg := config.DefaultLab()
+	labCfg.Repos = config.LabReposConfig{
+		CBT:        repoPaths[constants.RepoCBT],
+		XatuCBT:    repoPaths[constants.RepoXatuCBT],
+		CBTAPI:     repoPaths[constants.RepoCBTAPI],
+		LabBackend: repoPaths[constants.RepoLabBackend],
+		Lab:        repoPaths[constants.RepoLab],
+	}
+	labCfg.Networks = []config.NetworkConfig{{Name: "mainnet", Enabled: true, PortOffset: 0}}
+	labCfg.Infrastructure.Observability.Enabled = false
+
+	configPath := filepath.Join(rootDir, config.DefaultConfigFileName)
+	require.NoError(t, (&config.Config{Lab: labCfg}).Save(configPath))
+
+	ws := &workspace.Workspace{
+		RootDir:       rootDir,
+		ConfigPath:    configPath,
+		OverridesPath: filepath.Join(rootDir, constants.CBTOverridesFile),
+		StateDir:      filepath.Join(rootDir, ".xcli"),
+		ConfigExists:  true,
+	}
+
+	manifest, err := instance.NewManifest(context.Background(), ws, labCfg, instanceID)
+	require.NoError(t, err)
+	ports, err := instance.BuildPortPlan(labCfg, 0)
+	require.NoError(t, err)
+
+	dockerPlan := instance.NewDockerPlan(manifest.InstanceID, manifest.ConfigPath)
+	manifest.Ports = ports
+	manifest.Docker = dockerPlan
+
+	return &instance.Runtime{
+		Workspace:  ws,
+		LabConfig:  labCfg,
+		Registry:   instance.NewRegistry(filepath.Join(t.TempDir(), "instances")),
+		InstanceID: manifest.InstanceID,
+		Manifest:   manifest,
+		Ports:      ports,
+		Docker:     dockerPlan,
+		Repos:      manifest.Repos,
+	}
+}
diff --git a/pkg/cc/frontend/src/components/LabConfigEditor/LabConfigEditor.tsx b/pkg/cc/frontend/src/components/LabConfigEditor/LabConfigEditor.tsx
index 368aed0..d20664a 100644
--- a/pkg/cc/frontend/src/components/LabConfigEditor/LabConfigEditor.tsx
+++ b/pkg/cc/frontend/src/components/LabConfigEditor/LabConfigEditor.tsx
@@ -329,7 +329,8 @@ export default function LabConfigEditor({ onToast, onNavigateDashboard, stack }:
                 <h3 className="text-sm/5 font-semibold text-text-primary">Restart Required</h3>
               </div>
               <p className="mb-5 text-sm/5 text-text-tertiary">
-                Lab config changes require a full stack restart. The stack will be torn down and rebooted.
+                Lab config changes require a full stack restart. The selected instance will be stopped and started
+                again.
               </p>
               <div className="flex justify-end gap-2">
                 <button
diff --git a/pkg/cc/server.go b/pkg/cc/server.go
index d106dc4..f6cb058 100644
--- a/pkg/cc/server.go
+++ b/pkg/cc/server.go
@@ -11,6 +11,7 @@ import (
 
 	"github.com/ethpandaops/xcli/pkg/config"
 	"github.com/ethpandaops/xcli/pkg/git"
+	"github.com/ethpandaops/xcli/pkg/instance"
 	"github.com/ethpandaops/xcli/pkg/orchestrator"
 	"github.com/ethpandaops/xcli/pkg/tui"
 	"github.com/ethpandaops/xcli/pkg/ui"
@@ -41,6 +42,17 @@ func NewServer(
 	cfg *config.Config,
 	cfgPath string,
 	port int,
+) (*Server, error) {
+	return NewServerWithRuntime(log, cfg, cfgPath, port, nil)
+}
+
+// NewServerWithRuntime creates a Command Center server bound to a lab instance runtime.
+func NewServerWithRuntime(
+	log logrus.FieldLogger,
+	cfg *config.Config,
+	cfgPath string,
+	port int,
+	runtime *instance.Runtime,
 ) (*Server, error) {
 	l := log.WithField("component", "cc")
 	gitChk := git.NewChecker(l)
@@ -52,9 +64,11 @@ func NewServer(
 	}
 
 	if cfg.Lab != nil {
-		orch, err := orchestrator.NewOrchestrator(
-			l, cfg.Lab, cfgPath,
-		)
+		if runtime == nil {
+			return nil, fmt.Errorf("lab runtime is required for Command Center")
+		}
+
+		orch, err := orchestrator.NewOrchestratorWithRuntime(l, runtime)
 		if err != nil {
 			return nil, fmt.Errorf(
 				"failed to create lab orchestrator: %w", err,
@@ -66,7 +80,7 @@ func NewServer(
 		// which would seize raw mode/stdin in this long-lived server process.
 		orch.SetRenderer(ui.NewPlainRenderer())
 
-		backend := newLabBackend(l, orch, cfg.Lab, cfgPath, gitChk)
+		backend := newLabBackend(l, orch, cfg.Lab, cfgPath, runtime, gitChk)
 		wrapper := tui.NewOrchestratorWrapper(orch)
 		healthMon := tui.NewHealthMonitor(wrapper)
 		redisAdmin := newRedisAdmin(l, backend.RedisAddr)
diff --git a/pkg/cc/stack_context.go b/pkg/cc/stack_context.go
index fe1c6d2..b92348e 100644
--- a/pkg/cc/stack_context.go
+++ b/pkg/cc/stack_context.go
@@ -7,19 +7,12 @@ import (
 	"time"
 
 	"github.com/ethpandaops/xcli/pkg/ai"
-	"github.com/ethpandaops/xcli/pkg/constants"
 	"github.com/ethpandaops/xcli/pkg/tui"
 	"github.com/sirupsen/logrus"
 )
 
 const logHistorySize = 10000
 
-// dockerContainerNames maps observability service names to Docker container names.
-var dockerContainerNames = map[string]string{
-	constants.ServicePrometheus: constants.ContainerPrometheus,
-	constants.ServiceGrafana:    constants.ContainerGrafana,
-}
-
 // stackContext bundles all per-stack components so each stack operates
 // independently with its own SSE hub, health monitor, log streamer, etc.
 type stackContext struct {
diff --git a/pkg/commands/cc.go b/pkg/commands/cc.go
index 43becb1..d24adb7 100644
--- a/pkg/commands/cc.go
+++ b/pkg/commands/cc.go
@@ -4,7 +4,8 @@ import (
 	"fmt"
 
 	"github.com/ethpandaops/xcli/pkg/cc"
-	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/instance"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 )
@@ -12,8 +13,9 @@ import (
 // NewCCCommand creates the Command Center web dashboard command.
 func NewCCCommand(log logrus.FieldLogger, configPath string) *cobra.Command {
 	var (
-		port   int
-		noOpen bool
+		port             int
+		instanceOverride string
+		noOpen           bool
 	)
 
 	cmd := &cobra.Command{
@@ -31,12 +33,43 @@ The Command Center provides:
 The dashboard opens automatically in your default browser.
 Use --no-open to prevent this behavior.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			result, err := config.Load(configPath)
+			cfg, ws, err := workspace.LoadConfig(configPath, true, true)
 			if err != nil {
 				return fmt.Errorf("failed to load config: %w", err)
 			}
 
-			srv, err := cc.NewServer(log, result.Config, result.ConfigPath, port)
+			workspace.ResolveLabRepoPaths(cfg.Lab, ws.RootDir)
+
+			var runtime *instance.Runtime
+			if cfg.Lab != nil {
+				runtime, err = instance.ResolveRuntimeFromWorkspace(cmd.Context(), ws, cfg.Lab, instanceOverride, instance.RuntimeOptions{
+					ClaimPorts: false,
+					ProbePorts: true,
+				})
+				if err != nil {
+					return fmt.Errorf("failed to resolve lab instance runtime: %w", err)
+				}
+
+				if runtime.Workspace != nil && runtime.Workspace.ConfigPath != "" {
+					cfg, ws, err = workspace.LoadConfig(runtime.Workspace.ConfigPath, true, false)
+					if err != nil {
+						return fmt.Errorf("failed to load selected instance config: %w", err)
+					}
+
+					workspace.ResolveLabRepoPaths(cfg.Lab, ws.RootDir)
+					cfg.Lab = runtime.LabConfig
+				}
+
+				if !cmd.Flags().Changed("port") {
+					port = runtime.Ports.CommandCenter
+				}
+			}
+
+			if port == 0 {
+				port = instance.DefaultCommandCenterPort
+			}
+
+			srv, err := cc.NewServerWithRuntime(log, cfg, ws.ConfigPath, port, runtime)
 			if err != nil {
 				return fmt.Errorf("failed to create server: %w", err)
 			}
@@ -45,7 +78,8 @@ Use --no-open to prevent this behavior.`,
 		},
 	}
 
-	cmd.Flags().IntVarP(&port, "port", "p", 19280, "Port for the web dashboard")
+	cmd.Flags().IntVarP(&port, "port", "p", 0, "Port for the web dashboard (default: selected instance port)")
+	cmd.Flags().StringVar(&instanceOverride, "instance", "", "Lab instance id override")
 	cmd.Flags().BoolVar(&noOpen, "no-open", false, "Don't open browser automatically")
 
 	return cmd
diff --git a/pkg/commands/init.go b/pkg/commands/init.go
index 443e438..98632af 100644
--- a/pkg/commands/init.go
+++ b/pkg/commands/init.go
@@ -2,11 +2,11 @@ package commands
 
 import (
 	"fmt"
-	"os"
 
 	"github.com/ethpandaops/xcli/pkg/config"
 	"github.com/ethpandaops/xcli/pkg/ui"
 	"github.com/ethpandaops/xcli/pkg/version"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 )
@@ -37,9 +37,14 @@ func runRootInit(log logrus.FieldLogger, configPath string) error {
 
 	log.Info("initializing xcli configuration")
 
+	ws, err := workspace.Resolve(configPath, false, false)
+	if err != nil {
+		return err
+	}
+
 	// Check if config already exists
-	if _, err := os.Stat(configPath); err == nil {
-		ui.Success(fmt.Sprintf("Configuration file already exists: %s", configPath))
+	if ws.ConfigExists {
+		ui.Success(fmt.Sprintf("Configuration file already exists: %s", ws.ConfigPath))
 		ui.Blank()
 		ui.Info("To initialize specific stacks, run:")
 		fmt.Println("  xcli lab init        - Initialize lab stack")
@@ -53,22 +58,22 @@ func runRootInit(log logrus.FieldLogger, configPath string) error {
 	cfg := &config.Config{}
 
 	// Save empty configuration
-	if err := cfg.Save(configPath); err != nil {
+	if err := cfg.Save(ws.ConfigPath); err != nil {
 		return fmt.Errorf("failed to save configuration: %w", err)
 	}
 
-	log.WithField("file", configPath).Info("configuration file created")
+	log.WithField("file", ws.ConfigPath).Info("configuration file created")
 
 	// Print summary
 	ui.Blank()
 	ui.Success("xcli configuration initialized!")
-	ui.Info(fmt.Sprintf("Configuration file created: %s", configPath))
+	ui.Info(fmt.Sprintf("Configuration file created: %s", ws.ConfigPath))
 	ui.Blank()
 	ui.Header("Next steps:")
 	fmt.Println("  1. Run 'xcli lab init' to discover and configure lab repositories")
 	fmt.Println("  2. Run 'xcli xatu init' to configure the xatu stack")
 	fmt.Println("  3. Run 'xcli <stack> init' for other stacks as needed")
-	fmt.Printf("  3. Edit %s to customize settings\n", configPath)
+	fmt.Printf("  3. Edit %s to customize settings\n", ws.ConfigPath)
 
 	return nil
 }
diff --git a/pkg/commands/lab.go b/pkg/commands/lab.go
index 704a6f7..b748f02 100644
--- a/pkg/commands/lab.go
+++ b/pkg/commands/lab.go
@@ -8,6 +8,8 @@ import (
 
 // NewLabCommand creates the lab command namespace.
 func NewLabCommand(log logrus.FieldLogger, configPath string) *cobra.Command {
+	var instanceOverride string
+
 	cmd := &cobra.Command{
 		Use:   "lab",
 		Short: "Manage the xcli lab environment",
@@ -33,13 +35,16 @@ Common workflows:
      xcli lab mode hybrid    # Switch to hybrid mode
      xcli lab up             # Restart in new mode
 
-  4. Clean workspace:
-     xcli lab clean          # Remove all containers and artifacts
+  4. Stop safely:
+     xcli lab down           # Stop services and containers, preserve data
+     xcli lab destroy --instance <id>  # Explicit destructive removal
 
 Use 'xcli lab [command] --help' for more information about a command.`,
 	}
 
-	s := stack.NewLabStack(log, configPath)
+	cmd.PersistentFlags().StringVar(&instanceOverride, "instance", "", "Lab instance id override")
+
+	s := stack.NewLabStack(log, configPath, &instanceOverride)
 
 	// Shared stack commands via factories
 	cmd.AddCommand(stack.NewInitCommand(s))
@@ -54,13 +59,41 @@ Use 'xcli lab [command] --help' for more information about a command.`,
 	cmd.AddCommand(stack.NewStartCommand(s))
 	cmd.AddCommand(stack.NewStopCommand(s))
 	cmd.AddCommand(stack.NewRestartCommand(s))
+	cmd.AddCommand(NewLabListCommand())
+	cmd.AddCommand(NewLabShowCommand())
+
+	var destroyYes bool
+
+	destroyCmd := &cobra.Command{
+		Use:   "destroy",
+		Short: "Destroy one lab instance and delete its data",
+		Long: `Destroy one xcli lab instance and delete its generated state and data volumes.
+
+This is destructive and requires --instance <id>. Without --yes, you must type
+the instance id to confirm.`,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return s.Destroy(cmd.Context(), destroyYes)
+		},
+	}
+	destroyCmd.Flags().BoolVar(&destroyYes, "yes", false, "Skip confirmation prompt")
+	cmd.AddCommand(destroyCmd)
+
+	resetCmd := &cobra.Command{
+		Use:   "reset <redis>",
+		Short: "Reset one data store for one lab instance",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return s.Reset(cmd.Context(), args[0])
+		},
+	}
+	cmd.AddCommand(resetCmd)
 
 	// Lab-only commands
-	cmd.AddCommand(NewLabModeCommand(log, configPath))
-	cmd.AddCommand(NewLabConfigCommand(log, configPath))
+	cmd.AddCommand(NewLabModeCommand(log, configPath, &instanceOverride))
+	cmd.AddCommand(NewLabConfigCommand(log, configPath, &instanceOverride))
 	cmd.AddCommand(NewLabOverridesCommand(configPath))
-	cmd.AddCommand(NewLabTUICommand(log, configPath))
-	cmd.AddCommand(NewLabDiagnoseCommand(log, configPath))
+	cmd.AddCommand(NewLabTUICommand(log, configPath, &instanceOverride))
+	cmd.AddCommand(NewLabDiagnoseCommand(log, configPath, &instanceOverride))
 	cmd.AddCommand(NewLabReleaseCommand(log, configPath))
 	cmd.AddCommand(NewLabXatuCBTCommand(log, configPath))
 
diff --git a/pkg/commands/lab_config.go b/pkg/commands/lab_config.go
index 98956b3..f6d3631 100644
--- a/pkg/commands/lab_config.go
+++ b/pkg/commands/lab_config.go
@@ -4,18 +4,16 @@ import (
 	"fmt"
 
 	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/instance"
 	"github.com/ethpandaops/xcli/pkg/orchestrator"
 	"github.com/ethpandaops/xcli/pkg/ui"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 )
 
 // NewLabConfigCommand creates the lab config command.
-// NOTE: This is maintained for backward compatibility. Consider using:
-//
-//	xcli config show --stack=lab
-//	xcli config validate --stack=lab
-func NewLabConfigCommand(log logrus.FieldLogger, configPath string) *cobra.Command {
+func NewLabConfigCommand(log logrus.FieldLogger, configPath string, instanceOverride *string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "config",
 		Short: "Manage lab configuration",
@@ -71,13 +69,24 @@ Regenerates configurations for:
 Note: This does NOT restart services. Use 'xcli lab restart <service>' to apply
 the new configs.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			labCfg, cfgPath, err := config.LoadLabConfig(configPath)
+			labCfg, ws, err := workspace.LoadLabConfig(configPath, true)
 			if err != nil {
 				return fmt.Errorf("failed to load config: %w", err)
 			}
 
-			// Create orchestrator
-			orch, err := orchestrator.NewOrchestrator(log, labCfg, cfgPath)
+			printCommandWorkspaceSelection(ws)
+
+			runtime, err := instance.ResolveRuntimeFromWorkspace(cmd.Context(), ws, labCfg, instanceOverrideValue(instanceOverride), instance.RuntimeOptions{
+				ClaimPorts: false,
+				ProbePorts: true,
+			})
+			if err != nil {
+				return fmt.Errorf("failed to resolve lab instance runtime: %w", err)
+			}
+
+			ui.Info(fmt.Sprintf("Instance: %s", runtime.InstanceID))
+
+			orch, err := orchestrator.NewOrchestratorWithRuntime(log, runtime)
 			if err != nil {
 				return fmt.Errorf("failed to create orchestrator: %w", err)
 			}
diff --git a/pkg/commands/lab_diagnose.go b/pkg/commands/lab_diagnose.go
index 7131507..6f0f6cf 100644
--- a/pkg/commands/lab_diagnose.go
+++ b/pkg/commands/lab_diagnose.go
@@ -1,19 +1,31 @@
 package commands
 
 import (
+	"context"
 	"fmt"
+	"os"
 	"path/filepath"
+	"strconv"
+	"strings"
 
 	"github.com/ethpandaops/xcli/pkg/ai"
 	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
 	"github.com/ethpandaops/xcli/pkg/diagnostic"
+	"github.com/ethpandaops/xcli/pkg/instance"
+	"github.com/ethpandaops/xcli/pkg/portutil"
 	"github.com/ethpandaops/xcli/pkg/ui"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 )
 
 // NewLabDiagnoseCommand creates the lab diagnose command.
-func NewLabDiagnoseCommand(log logrus.FieldLogger, configPath string) *cobra.Command {
+func NewLabDiagnoseCommand(
+	log logrus.FieldLogger,
+	configPath string,
+	instanceOverride *string,
+) *cobra.Command {
 	var (
 		useAI    bool
 		provider string
@@ -22,34 +34,33 @@ func NewLabDiagnoseCommand(log logrus.FieldLogger, configPath string) *cobra.Com
 
 	cmd := &cobra.Command{
 		Use:   "diagnose",
-		Short: "Diagnose the most recent build failure",
-		Long: `Analyze the most recent build failure and provide diagnosis.
+		Short: "Diagnose the selected lab instance and latest build failure",
+		Long: `Analyze the selected lab instance and the most recent build failure.
+
+The instance section shows the authoritative config, overrides, state path,
+instance id, ports, reconciled status, and common multi-instance traps.
 
 By default, uses pattern matching for instant results.
 Use --ai flag to get AI-powered analysis from Claude Code.
 
 Examples:
-  xcli lab diagnose           # Diagnose latest failure with patterns
-  xcli lab diagnose --ai      # Use Claude Code for AI analysis
-  xcli lab diagnose --id xxx  # Diagnose specific report by ID`,
+  xcli lab diagnose                    # Show instance state and latest failure
+  xcli lab --instance alpha diagnose   # Diagnose another instance
+  xcli lab diagnose --ai               # Use Claude Code for AI analysis
+  xcli lab diagnose --id xxx           # Diagnose specific report by ID`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			// Load config to get the correct state directory
-			_, cfgPath, err := config.LoadLabConfig(configPath)
-			if err != nil {
-				return fmt.Errorf("failed to load config: %w", err)
-			}
-
-			// Compute stateDir from config path (same logic as orchestrator)
-			absConfigPath, err := filepath.Abs(cfgPath)
+			diag, err := buildLabDiagnosticContext(
+				cmd.Context(),
+				configPath,
+				instanceOverrideValue(instanceOverride),
+			)
 			if err != nil {
-				return fmt.Errorf("failed to get absolute config path: %w", err)
+				return err
 			}
 
-			configDir := filepath.Dir(absConfigPath)
-			stateDir := filepath.Join(configDir, ".xcli")
+			printLabDiagnostics(diag)
 
-			// Create store for diagnostic reports
-			store := diagnostic.NewStore(log, filepath.Join(stateDir, "errors"))
+			store := diagnostic.NewStore(log, filepath.Join(diag.Runtime.Manifest.StateDir, "errors"))
 
 			// Load report (latest or by ID)
 			var report *diagnostic.RebuildReport
@@ -61,7 +72,9 @@ Examples:
 			}
 
 			if err != nil {
-				return fmt.Errorf("no diagnostic reports found: %w", err)
+				ui.Info(fmt.Sprintf("No diagnostic reports found: %v", err))
+
+				return nil
 			}
 
 			// Check for failures
@@ -133,3 +146,320 @@ Examples:
 
 	return cmd
 }
+
+type labDiagnosticContext struct {
+	Runtime        *instance.Runtime
+	Reconciled     *instance.ReconciledInstance
+	Traps          []string
+	PortChecks     map[int]*portutil.PortConflict
+	ManifestLoaded bool
+}
+
+type diagnosticPortConflict struct {
+	Name    string
+	Port    int
+	PID     int
+	Process string
+}
+
+func instanceOverrideValue(value *string) string {
+	if value == nil {
+		return ""
+	}
+
+	return strings.TrimSpace(*value)
+}
+
+func buildLabDiagnosticContext(
+	ctx context.Context,
+	configPath string,
+	cliInstanceID string,
+) (*labDiagnosticContext, error) {
+	labCfg, ws, err := workspace.LoadLabConfig(configPath, false)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config: %w", err)
+	}
+
+	instanceID, err := instance.ResolveID(ws, labCfg, cliInstanceID)
+	if err != nil {
+		return nil, err
+	}
+
+	registry, err := instance.DefaultRegistry()
+	if err != nil {
+		return nil, err
+	}
+
+	var (
+		runtime        *instance.Runtime
+		manifestLoaded bool
+		traps          []string
+	)
+
+	manifest, loadErr := registry.Load(instanceID)
+	if loadErr == nil {
+		runtime, err = instance.NewRuntimeFromManifestConfig(ctx, manifest, registry)
+		if err != nil {
+			return nil, err
+		}
+
+		manifestLoaded = true
+	} else {
+		if !os.IsNotExist(loadErr) {
+			traps = append(traps, fmt.Sprintf("Could not load registry manifest for %s: %v", instanceID, loadErr))
+		}
+
+		runtime, err = instance.NewRuntimeFromWorkspace(ctx, ws, labCfg, cliInstanceID, instance.RuntimeOptions{
+			Registry:   registry,
+			ClaimPorts: false,
+			ProbePorts: false,
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to resolve candidate runtime: %w", err)
+		}
+
+		traps = append(traps, "No persisted manifest for this instance yet; run 'xcli lab up' to create one.")
+	}
+
+	if runtime.Workspace != nil {
+		ws = runtime.Workspace
+	}
+
+	if runtime.LabConfig != nil {
+		labCfg = runtime.LabConfig
+	}
+
+	if stray, ok, strayErr := detectStrayCWDOverrides(ws); strayErr != nil {
+		traps = append(traps, fmt.Sprintf("Could not inspect current-directory overrides: %v", strayErr))
+	} else if ok {
+		traps = append(traps, fmt.Sprintf(
+			"Current directory has %s, but authoritative overrides are %s",
+			stray,
+			ws.OverridesPath,
+		))
+	}
+
+	traps = append(traps, missingRepoPaths(labCfg)...)
+
+	var reconciled *instance.ReconciledInstance
+
+	result, reconcileErr := instance.NewReconciler(registry).ReconcileAll(ctx)
+	if reconcileErr != nil {
+		traps = append(traps, fmt.Sprintf("Could not reconcile instances: %v", reconcileErr))
+	} else {
+		for _, item := range result.Instances {
+			if item.InstanceID == runtime.InstanceID {
+				reconciled = item
+
+				break
+			}
+		}
+
+		if result.DockerError != nil {
+			traps = append(traps, fmt.Sprintf("Docker reconciliation skipped: %v", result.DockerError))
+		}
+	}
+
+	portChecks := probeRuntimePorts(runtime)
+
+	portConflicts := nonOwnedPortConflicts(runtime, portChecks)
+	for _, conflict := range portConflicts {
+		owner := fmt.Sprintf("PID %d", conflict.PID)
+		if conflict.Process != "" {
+			owner += " " + conflict.Process
+		}
+
+		traps = append(traps, fmt.Sprintf(
+			"Port %d (%s) is bound by %s and is not recorded as this instance app PID.",
+			conflict.Port,
+			conflict.Name,
+			owner,
+		))
+	}
+
+	return &labDiagnosticContext{
+		Runtime:        runtime,
+		Reconciled:     reconciled,
+		Traps:          traps,
+		PortChecks:     portChecks,
+		ManifestLoaded: manifestLoaded,
+	}, nil
+}
+
+func printLabDiagnostics(diag *labDiagnosticContext) {
+	runtime := diag.Runtime
+	manifest := runtime.Manifest
+
+	status := "unregistered"
+	if diag.Reconciled != nil {
+		status = diag.Reconciled.Status
+	} else if manifest.Status != "" {
+		status = manifest.Status
+	}
+
+	ui.Header("Instance Diagnostics")
+	ui.Table([]string{"Field", tableColumnValue}, [][]string{
+		{"Instance", runtime.InstanceID},
+		{"Status", status},
+		{"Manifest", boolLabel(diag.ManifestLoaded)},
+		{"Config", manifest.ConfigPath},
+		{"Overrides", manifest.OverridesPath},
+		{"State dir", manifest.StateDir},
+		{"Root", manifest.RootDir},
+		{"Mode", manifest.Mode},
+	})
+
+	if ports := runtime.Ports.NamedPorts(); len(ports) > 0 {
+		names := sortedKeysInt(ports)
+
+		rows := make([][]string, 0, len(names))
+		for _, name := range names {
+			port := ports[name]
+			if port == 0 {
+				continue
+			}
+
+			bound := "no"
+			owner := "-"
+
+			if conflict := diag.PortChecks[port]; conflict != nil && conflict.PID > 0 {
+				bound = "yes"
+
+				owner = fmt.Sprintf("PID %d", conflict.PID)
+				if conflict.Process != "" {
+					owner += " " + conflict.Process
+				}
+			}
+
+			rows = append(rows, []string{name, strconv.Itoa(port), bound, owner})
+		}
+
+		if len(rows) > 0 {
+			ui.Blank()
+			ui.Table([]string{"Port", tableColumnValue, "Bound", "Owner"}, rows)
+		}
+	}
+
+	if len(diag.Traps) == 0 {
+		ui.Blank()
+		ui.Success("No multi-instance traps detected")
+
+		return
+	}
+
+	ui.Blank()
+	ui.Header("Traps")
+
+	for _, trap := range diag.Traps {
+		ui.Warning(trap)
+	}
+}
+
+func detectStrayCWDOverrides(ws *workspace.Workspace) (string, bool, error) {
+	cwd, err := os.Getwd()
+	if err != nil {
+		return "", false, err
+	}
+
+	cwdOverrides, err := filepath.Abs(filepath.Join(cwd, constants.CBTOverridesFile))
+	if err != nil {
+		return "", false, err
+	}
+
+	if filepath.Clean(cwdOverrides) == filepath.Clean(ws.OverridesPath) {
+		return "", false, nil
+	}
+
+	if _, err := os.Stat(cwdOverrides); err == nil {
+		return cwdOverrides, true, nil
+	} else if !os.IsNotExist(err) {
+		return "", false, err
+	}
+
+	return "", false, nil
+}
+
+func missingRepoPaths(labCfg *config.LabConfig) []string {
+	missing := make([]string, 0)
+
+	for _, repo := range labCfg.Repos.Ordered() {
+		name := repo.Name
+
+		path := strings.TrimSpace(repo.Path)
+		if path == "" {
+			missing = append(missing, fmt.Sprintf("Repo %s has no configured path", name))
+
+			continue
+		}
+
+		if _, err := os.Stat(path); err != nil {
+			if os.IsNotExist(err) {
+				missing = append(missing, fmt.Sprintf("Repo %s path does not exist: %s", name, path))
+			} else {
+				missing = append(missing, fmt.Sprintf("Repo %s path could not be inspected: %s (%v)", name, path, err))
+			}
+		}
+	}
+
+	return missing
+}
+
+func probeRuntimePorts(runtime *instance.Runtime) map[int]*portutil.PortConflict {
+	ports := runtime.Ports.NamedPorts()
+
+	checks := make(map[int]*portutil.PortConflict, len(ports))
+	for _, port := range ports {
+		if port <= 0 {
+			continue
+		}
+
+		checks[port] = portutil.CheckPort(port)
+	}
+
+	return checks
+}
+
+func nonOwnedPortConflicts(
+	runtime *instance.Runtime,
+	portChecks map[int]*portutil.PortConflict,
+) []diagnosticPortConflict {
+	ownedPIDs := make(map[int]bool)
+
+	if runtime.Manifest != nil {
+		for _, pid := range runtime.Manifest.PIDs {
+			if pid > 0 {
+				ownedPIDs[pid] = true
+			}
+		}
+	}
+
+	ports := runtime.Ports.NamedPorts()
+	names := sortedKeysInt(ports)
+	conflicts := make([]diagnosticPortConflict, 0)
+
+	for _, name := range names {
+		port := ports[name]
+		if port <= 0 {
+			continue
+		}
+
+		conflict := portChecks[port]
+		if conflict == nil || conflict.PID <= 0 || ownedPIDs[conflict.PID] {
+			continue
+		}
+
+		process := strings.TrimSpace(conflict.Process)
+		if process != "" {
+			process = "(" + process + ")"
+		}
+
+		conflicts = append(conflicts, diagnosticPortConflict{
+			Name:    name,
+			Port:    port,
+			PID:     conflict.PID,
+			Process: process,
+		})
+	}
+
+	return conflicts
+}
diff --git a/pkg/commands/lab_diagnose_test.go b/pkg/commands/lab_diagnose_test.go
new file mode 100644
index 0000000..49fa5c3
--- /dev/null
+++ b/pkg/commands/lab_diagnose_test.go
@@ -0,0 +1,61 @@
+package commands
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/instance"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBuildLabDiagnosticContextSurfacesInstancePathsPortsAndTraps(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+
+	rootDir := t.TempDir()
+	configPath := filepath.Join(rootDir, config.DefaultConfigFileName)
+	require.NoError(t, os.WriteFile(configPath, []byte(`
+lab:
+  mode: local
+  repos:
+    cbt: missing/cbt
+    xatuCbt: missing/xatu-cbt
+    cbtApi: missing/cbt-api
+    labBackend: missing/lab-backend
+    lab: missing/lab
+  networks:
+    - name: mainnet
+      enabled: true
+      portOffset: 0
+  infrastructure:
+    clickhouse:
+      xatu:
+        mode: local
+      cbt:
+        mode: local
+    redis:
+      port: 6380
+  ports:
+    labBackend: 8080
+    labFrontend: 5173
+    cbtBase: 8081
+    cbtApiBase: 8091
+    cbtFrontendBase: 8085
+`), 0644))
+
+	diag, err := buildLabDiagnosticContext(context.Background(), configPath, "diag-one")
+	require.NoError(t, err)
+
+	require.Equal(t, "diag-one", diag.Runtime.InstanceID)
+	require.Equal(t, configPath, diag.Runtime.Manifest.ConfigPath)
+	require.Equal(t, instance.InstanceStateDir(rootDir, "diag-one"), diag.Runtime.Manifest.StateDir)
+	require.Equal(t, 8080, diag.Runtime.Ports.LabBackend)
+	require.False(t, diag.ManifestLoaded)
+
+	traps := strings.Join(diag.Traps, "\n")
+	require.Contains(t, traps, "No persisted manifest")
+	require.Contains(t, traps, "Repo cbt path does not exist")
+}
diff --git a/pkg/commands/lab_list.go b/pkg/commands/lab_list.go
new file mode 100644
index 0000000..c7d0111
--- /dev/null
+++ b/pkg/commands/lab_list.go
@@ -0,0 +1,277 @@
+package commands
+
+import (
+	"fmt"
+	"sort"
+	"strconv"
+	"strings"
+
+	"github.com/ethpandaops/xcli/pkg/instance"
+	"github.com/ethpandaops/xcli/pkg/ui"
+	"github.com/spf13/cobra"
+)
+
+// tableColumnValue is the "Value" table column header.
+const tableColumnValue = "Value"
+
+// NewLabListCommand creates the lab list command.
+func NewLabListCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "list",
+		Short: "List known lab instances",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			registry, err := instance.DefaultRegistry()
+			if err != nil {
+				return err
+			}
+
+			result, err := instance.NewReconciler(registry).ReconcileAll(cmd.Context())
+			if err != nil {
+				return err
+			}
+
+			if len(result.Instances) == 0 {
+				ui.Info("No lab instances registered")
+
+				if result.DockerError != nil {
+					ui.Warning(fmt.Sprintf("Docker reconciliation skipped: %v", result.DockerError))
+				}
+
+				return nil
+			}
+
+			printInstanceList(result.Instances)
+
+			if result.DockerError != nil {
+				ui.Warning(fmt.Sprintf("Docker reconciliation skipped: %v", result.DockerError))
+			}
+
+			return nil
+		},
+	}
+}
+
+// NewLabShowCommand creates the lab show command.
+func NewLabShowCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "show <instance-id>",
+		Short: "Show one lab instance",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			instanceID, err := instance.SanitizeID(args[0])
+			if err != nil {
+				return err
+			}
+
+			registry, err := instance.DefaultRegistry()
+			if err != nil {
+				return err
+			}
+
+			result, err := instance.NewReconciler(registry).ReconcileAll(cmd.Context())
+			if err != nil {
+				return err
+			}
+
+			for _, item := range result.Instances {
+				if item.InstanceID == instanceID {
+					printInstanceDetails(item)
+
+					if result.DockerError != nil {
+						ui.Warning(fmt.Sprintf("Docker reconciliation skipped: %v", result.DockerError))
+					}
+
+					return nil
+				}
+			}
+
+			return fmt.Errorf("instance %q not found", instanceID)
+		},
+	}
+}
+
+func printInstanceList(instances []*instance.ReconciledInstance) {
+	for i, item := range instances {
+		if i > 0 {
+			ui.Blank()
+		}
+
+		manifest := item.Manifest
+		ui.Header(fmt.Sprintf("%s (%s)", item.InstanceID, item.Status))
+		ui.Info(fmt.Sprintf("Root: %s", manifest.RootDir))
+		ui.Info(fmt.Sprintf("Config: %s", manifest.ConfigPath))
+
+		repoNames := make([]string, 0, len(manifest.Repos))
+		for name := range manifest.Repos {
+			repoNames = append(repoNames, name)
+		}
+
+		sort.Strings(repoNames)
+
+		rows := make([][]string, 0, len(repoNames))
+		for _, name := range repoNames {
+			repo := manifest.Repos[name]
+			rows = append(rows, []string{
+				name,
+				repo.Branch,
+				shortCommit(repo.Commit),
+				dirtyLabel(repo.Dirty),
+				repo.Path,
+			})
+		}
+
+		if len(rows) > 0 {
+			ui.Table([]string{"Repo", "Branch", "Commit", "Dirty", "Path"}, rows)
+		}
+	}
+}
+
+func printInstanceDetails(item *instance.ReconciledInstance) {
+	manifest := item.Manifest
+
+	ui.Header(fmt.Sprintf("%s (%s)", item.InstanceID, item.Status))
+	ui.Info(fmt.Sprintf("Registry: %t", item.RegistryPresent))
+	ui.Info(fmt.Sprintf("Root: %s", manifest.RootDir))
+	ui.Info(fmt.Sprintf("Config: %s", manifest.ConfigPath))
+	ui.Info(fmt.Sprintf("Overrides: %s", manifest.OverridesPath))
+	ui.Info(fmt.Sprintf("State dir: %s", manifest.StateDir))
+	ui.Info(fmt.Sprintf("Mode: %s", manifest.Mode))
+
+	if manifest.LastError != "" {
+		ui.Warning(fmt.Sprintf("Last error: %s", manifest.LastError))
+	}
+
+	if len(manifest.URLs) > 0 {
+		rows := sortedMapRows(manifest.URLs)
+
+		ui.Blank()
+		ui.Table([]string{"Service", "URL"}, rows)
+	}
+
+	if ports := manifest.Ports.NamedPorts(); len(ports) > 0 {
+		names := sortedKeysInt(ports)
+
+		rows := make([][]string, 0, len(names))
+		for _, name := range names {
+			port := ports[name]
+			if port == 0 {
+				continue
+			}
+
+			rows = append(rows, []string{
+				name,
+				strconv.Itoa(port),
+				boolLabel(item.Live.Ports[name]),
+			})
+		}
+
+		if len(rows) > 0 {
+			ui.Blank()
+			ui.Table([]string{"Port", tableColumnValue, "Bound"}, rows)
+		}
+	}
+
+	if len(manifest.Docker.Containers) > 0 || len(manifest.Docker.Volumes) > 0 || len(item.Live.DockerResources) > 0 {
+		rows := make([][]string, 0, len(manifest.Docker.Containers)+len(manifest.Docker.Volumes)+len(item.Live.DockerResources))
+		for _, name := range sortedKeysString(manifest.Docker.Containers) {
+			rows = append(rows, []string{"container", name, manifest.Docker.Containers[name], "-"})
+		}
+
+		for _, name := range sortedKeysString(manifest.Docker.Volumes) {
+			rows = append(rows, []string{"volume", name, manifest.Docker.Volumes[name], "-"})
+		}
+
+		for _, resource := range item.Live.DockerResources {
+			rows = append(rows, []string{resource.Kind, "live", resource.Name, resource.State})
+		}
+
+		ui.Blank()
+		ui.Table([]string{"Type", "Service", "Name", "State"}, rows)
+	}
+
+	printRepoTable(manifest)
+}
+
+func printRepoTable(manifest *instance.Manifest) {
+	repoNames := make([]string, 0, len(manifest.Repos))
+	for name := range manifest.Repos {
+		repoNames = append(repoNames, name)
+	}
+
+	sort.Strings(repoNames)
+
+	rows := make([][]string, 0, len(repoNames))
+	for _, name := range repoNames {
+		repo := manifest.Repos[name]
+		rows = append(rows, []string{
+			name,
+			repo.Branch,
+			shortCommit(repo.Commit),
+			dirtyLabel(repo.Dirty),
+			repo.Path,
+		})
+	}
+
+	if len(rows) > 0 {
+		ui.Blank()
+		ui.Table([]string{"Repo", "Branch", "Commit", "Dirty", "Path"}, rows)
+	}
+}
+
+func shortCommit(commit string) string {
+	commit = strings.TrimSpace(commit)
+	if len(commit) <= 12 {
+		return commit
+	}
+
+	return commit[:12]
+}
+
+func dirtyLabel(dirty bool) string {
+	if dirty {
+		return "dirty"
+	}
+
+	return "clean"
+}
+
+func sortedMapRows(values map[string]string) [][]string {
+	keys := sortedKeysString(values)
+
+	rows := make([][]string, 0, len(keys))
+	for _, key := range keys {
+		rows = append(rows, []string{key, values[key]})
+	}
+
+	return rows
+}
+
+func sortedKeysString(values map[string]string) []string {
+	keys := make([]string, 0, len(values))
+	for key := range values {
+		keys = append(keys, key)
+	}
+
+	sort.Strings(keys)
+
+	return keys
+}
+
+func sortedKeysInt(values map[string]int) []string {
+	keys := make([]string, 0, len(values))
+	for key := range values {
+		keys = append(keys, key)
+	}
+
+	sort.Strings(keys)
+
+	return keys
+}
+
+func boolLabel(value bool) string {
+	if value {
+		return "yes"
+	}
+
+	return "no"
+}
diff --git a/pkg/commands/lab_mode.go b/pkg/commands/lab_mode.go
index 78881c9..8056628 100644
--- a/pkg/commands/lab_mode.go
+++ b/pkg/commands/lab_mode.go
@@ -3,16 +3,17 @@ package commands
 import (
 	"fmt"
 
-	"github.com/ethpandaops/xcli/pkg/config"
 	"github.com/ethpandaops/xcli/pkg/constants"
+	"github.com/ethpandaops/xcli/pkg/instance"
 	"github.com/ethpandaops/xcli/pkg/orchestrator"
 	"github.com/ethpandaops/xcli/pkg/ui"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 )
 
 // NewLabModeCommand creates the lab mode command.
-func NewLabModeCommand(log logrus.FieldLogger, configPath string) *cobra.Command {
+func NewLabModeCommand(log logrus.FieldLogger, configPath string, instanceOverride *string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "mode <local|hybrid>",
 		Short: "Switch deployment mode between fully local and hybrid external data source",
@@ -48,17 +49,17 @@ Examples:
 			}
 
 			// Load config (need full config to save it later)
-			result, err := config.Load(configPath)
+			rootCfg, ws, err := workspace.LoadConfig(configPath, true, true)
 			if err != nil {
 				return fmt.Errorf("failed to load config: %w", err)
 			}
 
-			if result.Config.Lab == nil {
+			if rootCfg.Lab == nil {
 				return fmt.Errorf("lab configuration not found - run 'xcli lab init' first")
 			}
 
-			labCfg := result.Config.Lab
-			cfgPath := result.ConfigPath
+			labCfg := rootCfg.Lab
+			cfgPath := ws.ConfigPath
 
 			// Check if already in requested mode
 			if labCfg.Mode == mode {
@@ -101,7 +102,7 @@ Examples:
 			}
 
 			// Save config
-			if err := result.Config.Save(cfgPath); err != nil {
+			if err := rootCfg.Save(cfgPath); err != nil {
 				return fmt.Errorf("failed to save config: %w", err)
 			}
 
@@ -126,14 +127,21 @@ Examples:
 
 			_, _ = fmt.Scanln(&response)
 			if response == "y" || response == "Y" {
-				orch, err := orchestrator.NewOrchestrator(log, labCfg, cfgPath)
+				runtime, err := instance.ResolveRuntime(cmd.Context(), cfgPath, instanceOverrideValue(instanceOverride), false, instance.RuntimeOptions{
+					ClaimPorts: false,
+					ProbePorts: true,
+				})
+				if err != nil {
+					return fmt.Errorf("failed to resolve lab instance runtime: %w", err)
+				}
+
+				orch, err := orchestrator.NewOrchestratorWithRuntime(log, runtime)
 				if err != nil {
 					return fmt.Errorf("failed to create orchestrator: %w", err)
 				}
-				// Tear down infrastructure completely
-				// This is necessary because local vs hybrid mode use different infrastructure
+				// Stop and restart because local vs hybrid mode use different infrastructure.
 				if err := orch.Down(cmd.Context(), nil); err != nil {
-					return fmt.Errorf("failed to tear down: %w", err)
+					return fmt.Errorf("failed to stop stack: %w", err)
 				}
 				// Restart with auto-build enabled, no force rebuild
 				if err := orch.Up(cmd.Context(), false, false, nil); err != nil {
diff --git a/pkg/commands/lab_overrides.go b/pkg/commands/lab_overrides.go
index bd11a16..758f1d5 100644
--- a/pkg/commands/lab_overrides.go
+++ b/pkg/commands/lab_overrides.go
@@ -2,11 +2,9 @@ package commands
 
 import (
 	"fmt"
-	"path/filepath"
 
-	"github.com/ethpandaops/xcli/pkg/config"
 	"github.com/ethpandaops/xcli/pkg/configtui"
-	"github.com/ethpandaops/xcli/pkg/constants"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/spf13/cobra"
 )
 
@@ -27,15 +25,14 @@ The TUI allows you to:
 Changes are saved to .cbt-overrides.yaml. Run 'xcli lab config regenerate'
 to apply changes to CBT configuration.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			labCfg, cfgPath, err := config.LoadLabConfig(configPath)
+			labCfg, ws, err := workspace.LoadLabConfig(configPath, true)
 			if err != nil {
 				return fmt.Errorf("failed to load config: %w", err)
 			}
 
-			// Derive overrides path (same directory as .xcli.yaml).
-			overridesPath := filepath.Join(filepath.Dir(cfgPath), constants.CBTOverridesFile)
+			printCommandWorkspaceSelection(ws)
 
-			return configtui.Run(labCfg.Repos.XatuCBT, overridesPath)
+			return configtui.Run(labCfg.Repos.XatuCBT, ws.OverridesPath)
 		},
 	}
 }
diff --git a/pkg/commands/lab_release.go b/pkg/commands/lab_release.go
index 739f555..de3f00f 100644
--- a/pkg/commands/lab_release.go
+++ b/pkg/commands/lab_release.go
@@ -12,6 +12,7 @@ import (
 	"github.com/ethpandaops/xcli/pkg/git"
 	"github.com/ethpandaops/xcli/pkg/release"
 	"github.com/ethpandaops/xcli/pkg/ui"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/pterm/pterm"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
@@ -1131,7 +1132,7 @@ func runPreflightChecks(
 		return nil
 	}
 
-	labCfg, _, err := config.LoadLabConfig(configPath)
+	labCfg, _, err := workspace.LoadLabConfig(configPath, false)
 	if err != nil {
 		log.WithError(err).Debug("could not load lab config for pre-flight checks (skipping local repo checks)")
 
diff --git a/pkg/commands/lab_tui.go b/pkg/commands/lab_tui.go
index 19f2929..da0bca1 100644
--- a/pkg/commands/lab_tui.go
+++ b/pkg/commands/lab_tui.go
@@ -3,15 +3,16 @@ package commands
 import (
 	"fmt"
 
-	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/instance"
 	"github.com/ethpandaops/xcli/pkg/orchestrator"
 	"github.com/ethpandaops/xcli/pkg/tui"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 )
 
 // NewLabTUICommand creates the lab TUI command.
-func NewLabTUICommand(log logrus.FieldLogger, configPath string) *cobra.Command {
+func NewLabTUICommand(log logrus.FieldLogger, configPath string, instanceOverride *string) *cobra.Command {
 	return &cobra.Command{
 		Use:   "tui",
 		Short: "Launch interactive TUI dashboard",
@@ -37,13 +38,21 @@ Note: TUI requires an interactive terminal (TTY).
 For non-interactive use, use 'xcli lab status' instead.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// Load config
-			labCfg, cfgPath, err := config.LoadLabConfig(configPath)
+			labCfg, ws, err := workspace.LoadLabConfig(configPath, false)
 			if err != nil {
 				return fmt.Errorf("failed to load config: %w", err)
 			}
 
+			runtime, err := instance.ResolveRuntimeFromWorkspace(cmd.Context(), ws, labCfg, instanceOverrideValue(instanceOverride), instance.RuntimeOptions{
+				ClaimPorts: false,
+				ProbePorts: true,
+			})
+			if err != nil {
+				return fmt.Errorf("failed to resolve lab instance runtime: %w", err)
+			}
+
 			// Initialize orchestrator
-			orch, err := orchestrator.NewOrchestrator(log, labCfg, cfgPath)
+			orch, err := orchestrator.NewOrchestratorWithRuntime(log, runtime)
 			if err != nil {
 				return fmt.Errorf("failed to create orchestrator: %w", err)
 			}
diff --git a/pkg/commands/lab_xatu_cbt_generate_seed_data.go b/pkg/commands/lab_xatu_cbt_generate_seed_data.go
index 6fca2c4..a7b8429 100644
--- a/pkg/commands/lab_xatu_cbt_generate_seed_data.go
+++ b/pkg/commands/lab_xatu_cbt_generate_seed_data.go
@@ -10,6 +10,7 @@ import (
 	"github.com/ethpandaops/xcli/pkg/constants"
 	"github.com/ethpandaops/xcli/pkg/seeddata"
 	"github.com/ethpandaops/xcli/pkg/ui"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 )
@@ -96,7 +97,7 @@ func runGenerateSeedData(
 	sanitizeIPs bool,
 ) error {
 	// Load configuration
-	labCfg, _, err := config.LoadLabConfig(configPath)
+	labCfg, _, err := workspace.LoadLabConfig(configPath, false)
 	if err != nil {
 		return fmt.Errorf("failed to load config: %w", err)
 	}
diff --git a/pkg/commands/lab_xatu_cbt_generate_transformation.go b/pkg/commands/lab_xatu_cbt_generate_transformation.go
index 564e36d..f16ce6c 100644
--- a/pkg/commands/lab_xatu_cbt_generate_transformation.go
+++ b/pkg/commands/lab_xatu_cbt_generate_transformation.go
@@ -13,6 +13,7 @@ import (
 	"github.com/ethpandaops/xcli/pkg/constants"
 	"github.com/ethpandaops/xcli/pkg/seeddata"
 	"github.com/ethpandaops/xcli/pkg/ui"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 )
@@ -164,7 +165,7 @@ func runGenerateTransformationTest(
 	parallel := opts.parallel
 
 	// Load configuration
-	labCfg, _, err := config.LoadLabConfig(configPath)
+	labCfg, _, err := workspace.LoadLabConfig(configPath, false)
 	if err != nil {
 		return fmt.Errorf("failed to load config: %w", err)
 	}
diff --git a/pkg/commands/workspace.go b/pkg/commands/workspace.go
new file mode 100644
index 0000000..f20a622
--- /dev/null
+++ b/pkg/commands/workspace.go
@@ -0,0 +1,14 @@
+package commands
+
+import (
+	"fmt"
+
+	"github.com/ethpandaops/xcli/pkg/ui"
+	"github.com/ethpandaops/xcli/pkg/workspace"
+)
+
+func printCommandWorkspaceSelection(ws *workspace.Workspace) {
+	ui.Info(fmt.Sprintf("Config: %s", ws.ConfigPath))
+	ui.Info(fmt.Sprintf("Overrides: %s", ws.OverridesPath))
+	ui.Info(fmt.Sprintf("State dir: %s", ws.StateDir))
+}
diff --git a/pkg/config/config.go b/pkg/config/config.go
index 1cee37e..f38f8cc 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -14,6 +14,35 @@ import (
 	"github.com/ethpandaops/xcli/pkg/constants"
 )
 
+// DefaultConfigFileName is the workspace-local xcli configuration file.
+const DefaultConfigFileName = ".xcli.yaml"
+
+var runtimeConfigPath string
+
+// SetRuntimeConfigPath records the config path selected by CLI flag parsing.
+//
+// Most command constructors receive their config path before Cobra parses
+// persistent flags, so runtime loaders use this value when their local fallback
+// is still the default path.
+func SetRuntimeConfigPath(path string) {
+	runtimeConfigPath = strings.TrimSpace(path)
+}
+
+// EffectiveConfigPath returns the config path that should be used by runtime
+// loaders after global flag parsing has completed.
+func EffectiveConfigPath(path string) string {
+	if path == "" {
+		path = DefaultConfigFileName
+	}
+
+	if (path == DefaultConfigFileName || path == "."+string(filepath.Separator)+DefaultConfigFileName) &&
+		runtimeConfigPath != "" {
+		return runtimeConfigPath
+	}
+
+	return path
+}
+
 // Config represents the xcli root configuration
 // It contains stack-specific configurations and optional workspace-level settings.
 type Config struct {
@@ -30,6 +59,7 @@ type Config struct {
 // LabConfig represents the lab stack configuration.
 type LabConfig struct {
 	Repos          LabReposConfig       `yaml:"repos"`
+	Instance       LabInstanceConfig    `yaml:"instance,omitempty"`
 	Mode           string               `yaml:"mode"`
 	Networks       []NetworkConfig      `yaml:"networks"`
 	Infrastructure InfrastructureConfig `yaml:"infrastructure"`
@@ -38,6 +68,11 @@ type LabConfig struct {
 	TUI            TUIConfig            `yaml:"tui"`
 }
 
+// LabInstanceConfig contains per-instance identity settings.
+type LabInstanceConfig struct {
+	ID string `yaml:"id,omitempty"`
+}
+
 // LabReposConfig contains paths to lab repositories.
 type LabReposConfig struct {
 	CBT        string `yaml:"cbt"`
@@ -47,6 +82,34 @@ type LabReposConfig struct {
 	Lab        string `yaml:"lab"`
 }
 
+// LabRepoPath is one named lab repository path.
+type LabRepoPath struct {
+	Name string
+	Path string
+}
+
+// Map returns the configured lab repositories keyed by canonical repository name.
+func (r LabReposConfig) Map() map[string]string {
+	return map[string]string{
+		constants.RepoCBT:        r.CBT,
+		constants.RepoXatuCBT:    r.XatuCBT,
+		constants.RepoCBTAPI:     r.CBTAPI,
+		constants.RepoLabBackend: r.LabBackend,
+		constants.RepoLab:        r.Lab,
+	}
+}
+
+// Ordered returns lab repositories in the standard display/init order.
+func (r LabReposConfig) Ordered() []LabRepoPath {
+	return []LabRepoPath{
+		{Name: constants.RepoCBT, Path: r.CBT},
+		{Name: constants.RepoXatuCBT, Path: r.XatuCBT},
+		{Name: constants.RepoCBTAPI, Path: r.CBTAPI},
+		{Name: constants.RepoLabBackend, Path: r.LabBackend},
+		{Name: constants.RepoLab, Path: r.Lab},
+	}
+}
+
 // NetworkConfig represents a network configuration.
 type NetworkConfig struct {
 	Name             string `yaml:"name"`
@@ -238,15 +301,7 @@ func (c *Config) Validate() error {
 
 // ValidateRepos checks if repository paths are valid.
 func (c *LabConfig) ValidateRepos() error {
-	repos := map[string]string{
-		"cbt":         c.Repos.CBT,
-		"xatu-cbt":    c.Repos.XatuCBT,
-		"cbt-api":     c.Repos.CBTAPI,
-		"lab-backend": c.Repos.LabBackend,
-		"lab":         c.Repos.Lab,
-	}
-
-	for name, path := range repos {
+	for name, path := range c.Repos.Map() {
 		absPath, err := filepath.Abs(path)
 		if err != nil {
 			return fmt.Errorf("invalid path for %s: %w", name, err)
@@ -433,23 +488,23 @@ func DefaultLab() *LabConfig {
 				},
 				CBT: ClickHouseClusterConfig{Mode: constants.InfraModeLocal},
 			},
-			Redis:   RedisConfig{Port: 6380},
+			Redis:   RedisConfig{Port: constants.DefaultRedisPort},
 			Volumes: VolumesConfig{Persist: true},
 			Observability: ObservabilityConfig{
 				Enabled:        false,
 				PrometheusPort: constants.DefaultPrometheusPort,
 				GrafanaPort:    constants.DefaultGrafanaPort,
 			},
-			ClickHouseXatuPort: 8125,
-			ClickHouseCBTPort:  8123,
-			RedisPort:          6380,
+			ClickHouseXatuPort: constants.DefaultClickHouseXatuHTTPPort,
+			ClickHouseCBTPort:  constants.DefaultClickHouseCBTHTTPPort,
+			RedisPort:          constants.DefaultRedisPort,
 		},
 		Ports: LabPortsConfig{
-			LabBackend:      8080,
-			LabFrontend:     5173,
-			CBTBase:         8081,
-			CBTAPIBase:      8091,
-			CBTFrontendBase: 8085,
+			LabBackend:      constants.DefaultLabBackendPort,
+			LabFrontend:     constants.DefaultLabFrontendPort,
+			CBTBase:         constants.DefaultCBTBasePort,
+			CBTAPIBase:      constants.DefaultCBTAPIBasePort,
+			CBTFrontendBase: constants.DefaultCBTFrontendBasePort,
 		},
 		Dev: LabDevConfig{
 			LabRebuildOnChange: false,
@@ -461,13 +516,14 @@ func DefaultLab() *LabConfig {
 	}
 }
 
-// Load reads and parses a config file
-// Supports both old (flat) and new (namespaced) config formats for backward compatibility.
+// Load reads and parses a config file.
 // If the path is ".xcli.yaml" (the default), it will search upward through parent directories.
 // Returns the config and the resolved absolute path to the config file.
 func Load(path string) (*LoadResult, error) {
+	path = EffectiveConfigPath(path)
+
 	// If using default path, search for it in parent directories
-	if path == ".xcli.yaml" {
+	if path == DefaultConfigFileName {
 		path = FindConfig(path)
 	}
 
@@ -498,24 +554,6 @@ func Load(path string) (*LoadResult, error) {
 		return nil, fmt.Errorf("failed to parse config file: %w", err)
 	}
 
-	// Check if this is an old format config (has top-level "repos" field instead of "lab")
-	// by attempting to parse as LabConfig
-	var legacyCheck struct {
-		Repos *LabReposConfig `yaml:"repos,omitempty"`
-		Lab   *LabConfig      `yaml:"lab,omitempty"`
-	}
-	if err := yaml.Unmarshal(data, &legacyCheck); err == nil {
-		if legacyCheck.Repos != nil && legacyCheck.Lab == nil {
-			// Old format detected - migrate it
-			var labCfg LabConfig
-			if err := yaml.Unmarshal(data, &labCfg); err != nil {
-				return nil, fmt.Errorf("failed to parse legacy config: %w", err)
-			}
-
-			cfg.Lab = &labCfg
-		}
-	}
-
 	// Apply defaults to loaded config
 	cfg.setDefaults()
 
@@ -525,49 +563,18 @@ func Load(path string) (*LoadResult, error) {
 	}, nil
 }
 
-// LoadLabConfig loads and validates lab configuration from the config file.
-// This is a convenience function that combines Load with lab-specific validation.
-// Returns the lab config and the config file path, or an error if loading fails
-// or if the lab configuration is not found.
-func LoadLabConfig(configPath string) (*LabConfig, string, error) {
-	result, err := Load(configPath)
-	if err != nil {
-		return nil, "", fmt.Errorf("failed to load config: %w", err)
-	}
-
-	if result.Config.Lab == nil {
-		return nil, "", fmt.Errorf("lab configuration not found - run 'xcli lab init' first")
-	}
-
-	return result.Config.Lab, result.ConfigPath, nil
-}
-
-// FindConfig searches for a config file using multiple strategies:
-// 1. Search upward from current directory to filesystem root
-// 2. Search immediate child directories
-// 3. Check global config for registered project paths
+// FindConfig searches upward from current directory to filesystem root.
 // Returns the absolute path to the config file, or the provided fallback path if not found.
 func FindConfig(fallback string) string {
-	const configFileName = ".xcli.yaml"
-
 	// Start from current working directory
 	cwd, err := os.Getwd()
 	if err != nil {
 		return fallback
 	}
 
-	// Strategy 1: Search upward
-	if path := searchUpward(cwd, configFileName); path != "" {
-		return path
-	}
-
-	// Strategy 2: Search immediate child directories
-	if path := searchChildren(cwd, configFileName); path != "" {
-		return path
-	}
-
-	// Strategy 3: Check global config
-	if path := searchGlobalConfig(); path != "" {
+	// Search upward only. Child-directory and global fallbacks can silently
+	// select another workspace when multiple xcli instances exist.
+	if path := searchUpward(cwd, DefaultConfigFileName); path != "" {
 		return path
 	}
 
@@ -584,15 +591,15 @@ func (c *Config) setDefaults() {
 
 	// Infrastructure defaults
 	if c.Lab.Infrastructure.ClickHouseXatuPort == 0 {
-		c.Lab.Infrastructure.ClickHouseXatuPort = 8123
+		c.Lab.Infrastructure.ClickHouseXatuPort = constants.DefaultClickHouseXatuHTTPPort
 	}
 
 	if c.Lab.Infrastructure.ClickHouseCBTPort == 0 {
-		c.Lab.Infrastructure.ClickHouseCBTPort = 8124
+		c.Lab.Infrastructure.ClickHouseCBTPort = constants.DefaultClickHouseCBTHTTPPort
 	}
 
 	if c.Lab.Infrastructure.RedisPort == 0 {
-		c.Lab.Infrastructure.RedisPort = 6380
+		c.Lab.Infrastructure.RedisPort = constants.DefaultRedisPort
 	}
 
 	// TUI defaults
@@ -639,45 +646,3 @@ func searchUpward(startDir, configFileName string) string {
 		currentDir = parentDir
 	}
 }
-
-// searchChildren looks for config file in immediate child directories.
-func searchChildren(parentDir, configFileName string) string {
-	entries, err := os.ReadDir(parentDir)
-	if err != nil {
-		return ""
-	}
-
-	for _, entry := range entries {
-		if !entry.IsDir() {
-			continue
-		}
-
-		configPath := filepath.Join(parentDir, entry.Name(), configFileName)
-		if _, err := os.Stat(configPath); err == nil {
-			// Found it - return absolute path
-			absPath, err := filepath.Abs(configPath)
-			if err != nil {
-				return configPath
-			}
-
-			return absPath
-		}
-	}
-
-	return ""
-}
-
-// searchGlobalConfig checks the global config file for the xcli installation path.
-func searchGlobalConfig() string {
-	globalCfg, err := LoadGlobalConfig()
-	if err != nil || globalCfg.XCLIPath == "" {
-		return ""
-	}
-
-	configPath := filepath.Join(globalCfg.XCLIPath, ".xcli.yaml")
-	if _, err := os.Stat(configPath); err == nil {
-		return configPath
-	}
-
-	return ""
-}
diff --git a/pkg/configgen/generator.go b/pkg/configgen/generator.go
index c62a14b..a44ea2c 100644
--- a/pkg/configgen/generator.go
+++ b/pkg/configgen/generator.go
@@ -16,6 +16,7 @@ import (
 	"dario.cat/mergo"
 	"github.com/ethpandaops/xcli/pkg/config"
 	"github.com/ethpandaops/xcli/pkg/constants"
+	"github.com/ethpandaops/xcli/pkg/instance"
 	"github.com/ethpandaops/xcli/pkg/seeddata"
 	"github.com/sirupsen/logrus"
 	"gopkg.in/yaml.v3"
@@ -24,13 +25,6 @@ import (
 //go:embed templates/*
 var templatesFS embed.FS
 
-const (
-	// cbtMetricsPortBase is the base port for CBT engine metrics endpoints.
-	cbtMetricsPortBase = 9100
-	// cbtAPIMetricsPortBase is the base port for CBT API metrics endpoints.
-	cbtAPIMetricsPortBase = 9200
-)
-
 const (
 	keyPort                      = "Port"
 	keyEnv                       = "env"
@@ -41,13 +35,13 @@ const (
 	envExternalModelMinTimestamp = "EXTERNAL_MODEL_MIN_TIMESTAMP"
 	envExternalModelMinBlock     = "EXTERNAL_MODEL_MIN_BLOCK"
 	envModelsScriptsPath         = "MODELS_SCRIPTS_PATH"
-	modelsScriptsPath            = "../xatu-cbt/models/scripts"
 )
 
 // Generator generates service configuration files.
 type Generator struct {
-	log logrus.FieldLogger
-	cfg *config.LabConfig
+	log     logrus.FieldLogger
+	cfg     *config.LabConfig
+	runtime *instance.Runtime
 }
 
 // NewGenerator creates a new Generator instance.
@@ -58,16 +52,89 @@ func NewGenerator(log logrus.FieldLogger, cfg *config.LabConfig) *Generator {
 	}
 }
 
+// NewRuntimeGenerator creates a Generator bound to a resolved instance runtime.
+func NewRuntimeGenerator(log logrus.FieldLogger, runtime *instance.Runtime) *Generator {
+	var cfg *config.LabConfig
+	if runtime != nil {
+		cfg = runtime.LabConfig
+	}
+
+	return &Generator{
+		log:     log.WithField("component", "config-generator"),
+		cfg:     cfg,
+		runtime: runtime,
+	}
+}
+
+func (g *Generator) networkPorts(network string) instance.NetworkPortPlan {
+	return g.portPlan().Networks[network]
+}
+
+func (g *Generator) clickHouseCBTHTTPPort() int {
+	return g.portPlan().ClickHouseCBT01HTTP
+}
+
+func (g *Generator) clickHouseCBTNativePort() int {
+	return g.portPlan().ClickHouseCBT01TCP
+}
+
+func (g *Generator) redisPort() int {
+	return g.portPlan().Redis
+}
+
+func (g *Generator) labBackendPort() int {
+	return g.portPlan().LabBackend
+}
+
+func (g *Generator) labFrontendPort() int {
+	return g.portPlan().LabFrontend
+}
+
+func (g *Generator) prometheusPort() int {
+	return g.portPlan().Prometheus
+}
+
+func (g *Generator) portPlan() instance.PortPlan {
+	fallback := instance.DefaultPortPlan()
+
+	if g.cfg != nil {
+		if plan, err := instance.BuildPortPlan(g.cfg, 0); err == nil {
+			fallback = plan
+		}
+	}
+
+	if g.runtime == nil {
+		return fallback
+	}
+
+	plan := g.runtime.Ports
+	if len(plan.AllPorts()) == 0 && g.runtime.Manifest != nil {
+		plan = g.runtime.Manifest.Ports
+	}
+
+	return plan.WithDefaults(fallback)
+}
+
+func (g *Generator) xatuCBTModelsPath(kind string) string {
+	if g.runtime != nil && g.runtime.LabConfig != nil && g.runtime.LabConfig.Repos.XatuCBT != "" {
+		return filepath.Join(g.runtime.LabConfig.Repos.XatuCBT, keyModels, kind)
+	}
+
+	if g.cfg != nil && g.cfg.Repos.XatuCBT != "" {
+		return filepath.Join(g.cfg.Repos.XatuCBT, keyModels, kind)
+	}
+
+	return filepath.Join(constants.RepoXatuCBT, keyModels, kind)
+}
+
 // GenerateCBTConfig generates CBT configuration for a network.
 // It generates a base config from template, then deep merges auto-generated
 // defaults and user overrides on top. User overrides take ultimate precedence.
 func (g *Generator) GenerateCBTConfig(network string, userOverridesPath string) (string, error) {
-	metricsPort := cbtMetricsPortBase
 	redisDB := 0
 
 	for i, net := range g.cfg.EnabledNetworks() {
 		if net.Name == network {
-			metricsPort = cbtMetricsPortBase + i
 			redisDB = i // mainnet=0, sepolia=1, holesky=2, etc.
 
 			break
@@ -85,7 +152,7 @@ func (g *Generator) GenerateCBTConfig(network string, userOverridesPath string)
 		externalDatabase = g.cfg.Infrastructure.ClickHouse.Xatu.ExternalDatabase
 	}
 
-	frontendPort := g.cfg.GetCBTFrontendPort(network)
+	networkPorts := g.networkPorts(network)
 
 	var genesisTimestamp uint64
 	if timestamp, ok := constants.NetworkGenesisTimestamps[network]; ok {
@@ -94,11 +161,15 @@ func (g *Generator) GenerateCBTConfig(network string, userOverridesPath string)
 
 	data := map[string]any{
 		"Network":                    network,
-		"MetricsPort":                metricsPort,
+		"ClickHouseHTTPPort":         g.clickHouseCBTHTTPPort(),
+		"MetricsPort":                networkPorts.CBTMetrics,
 		"RedisDB":                    redisDB,
-		"FrontendPort":               frontendPort,
+		"RedisPort":                  g.redisPort(),
+		"FrontendPort":               networkPorts.CBTFrontend,
 		"GenesisTimestamp":           genesisTimestamp,
 		"ExternalClickHouseDatabase": externalDatabase,
+		"ExternalModelsPath":         g.xatuCBTModelsPath("external"),
+		"TransformationModelsPath":   g.xatuCBTModelsPath("transformations"),
 	}
 
 	tmpl, err := template.New("cbt-config").ParseFS(templatesFS, "templates/cbt.yaml.tmpl")
@@ -167,21 +238,13 @@ func (g *Generator) GenerateCBTConfig(network string, userOverridesPath string)
 
 // GenerateCBTAPIConfig generates cbt-api configuration for a network.
 func (g *Generator) GenerateCBTAPIConfig(network string) (string, error) {
-	port := g.cfg.GetCBTAPIPort(network)
-	metricsPort := cbtAPIMetricsPortBase
-
-	for i, net := range g.cfg.EnabledNetworks() {
-		if net.Name == network {
-			metricsPort = cbtAPIMetricsPortBase + i
-
-			break
-		}
-	}
+	networkPorts := g.networkPorts(network)
 
 	data := map[string]any{
-		"Network":     network,
-		keyPort:       port,
-		"MetricsPort": metricsPort,
+		"Network":              network,
+		keyPort:                networkPorts.CBTAPI,
+		"MetricsPort":          networkPorts.CBTAPIMetrics,
+		"ClickHouseNativePort": g.clickHouseCBTNativePort(),
 	}
 
 	tmpl, err := template.New("cbt-api-config").ParseFS(templatesFS, "templates/cbt-api.yaml.tmpl")
@@ -225,7 +288,7 @@ func (g *Generator) GenerateLabBackendConfig(
 	for _, net := range g.cfg.Networks {
 		entry := map[string]any{
 			"Name":    net.Name,
-			keyPort:   g.cfg.GetCBTAPIPort(net.Name),
+			keyPort:   g.networkPorts(net.Name).CBTAPI,
 			"Enabled": net.Enabled,
 		}
 
@@ -244,8 +307,9 @@ func (g *Generator) GenerateLabBackendConfig(
 
 	data := map[string]any{
 		"Networks":     networks,
-		keyPort:        g.cfg.Ports.LabBackend,
-		"FrontendPort": g.cfg.Ports.LabFrontend,
+		keyPort:        g.labBackendPort(),
+		"FrontendPort": g.labFrontendPort(),
+		"RedisPort":    g.redisPort(),
 	}
 
 	tmpl, err := template.New("lab-backend-config").ParseFS(
@@ -279,7 +343,7 @@ func (g *Generator) generateAutoDefaults(network string) (map[string]any, error)
 			keyNetwork:                   network,
 			envExternalModelMinTimestamp: fmt.Sprintf("%d", externalModelMinTimestamp),
 			envExternalModelMinBlock:     fmt.Sprintf("%d", externalModelMinBlock),
-			envModelsScriptsPath:         modelsScriptsPath,
+			envModelsScriptsPath:         g.xatuCBTModelsPath("scripts"),
 		},
 	}
 
diff --git a/pkg/configgen/generator_test.go b/pkg/configgen/generator_test.go
index b91d532..5688050 100644
--- a/pkg/configgen/generator_test.go
+++ b/pkg/configgen/generator_test.go
@@ -1,15 +1,24 @@
 package configgen
 
 import (
+	"context"
+	"fmt"
 	"os"
 	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
 	"testing"
 
 	"dario.cat/mergo"
 	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
+	"github.com/ethpandaops/xcli/pkg/instance"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/sirupsen/logrus"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"gopkg.in/yaml.v3"
 )
 
 const (
@@ -375,13 +384,14 @@ func TestRemoveEmptyMaps(t *testing.T) {
 }
 
 func TestEmptyOverrideDoesNotWipeAutoDefaults(t *testing.T) {
+	scriptsPath := filepath.Join(constants.RepoXatuCBT, keyModels, "scripts")
 	baseConfig := map[string]any{
 		keyModels: map[string]any{
 			keyEnv: map[string]any{
 				keyNetwork:                   networkMainnet,
 				envExternalModelMinTimestamp: "1234567890",
 				envExternalModelMinBlock:     "23800000",
-				envModelsScriptsPath:         modelsScriptsPath,
+				envModelsScriptsPath:         scriptsPath,
 			},
 		},
 	}
@@ -406,7 +416,7 @@ func TestEmptyOverrideDoesNotWipeAutoDefaults(t *testing.T) {
 	assert.Equal(t, networkMainnet, env[keyNetwork])
 	assert.Equal(t, "1234567890", env[envExternalModelMinTimestamp])
 	assert.Equal(t, "23800000", env[envExternalModelMinBlock])
-	assert.Equal(t, modelsScriptsPath, env[envModelsScriptsPath])
+	assert.Equal(t, scriptsPath, env[envModelsScriptsPath])
 }
 
 func TestUserOverridesTakePrecedence(t *testing.T) {
@@ -446,13 +456,14 @@ func TestUserOverridesTakePrecedence(t *testing.T) {
 }
 
 func TestCommentOnlyEnvOverrideDoesNotWipeAutoDefaults(t *testing.T) {
+	scriptsPath := filepath.Join(constants.RepoXatuCBT, keyModels, "scripts")
 	baseConfig := map[string]any{
 		keyModels: map[string]any{
 			keyEnv: map[string]any{
 				keyNetwork:                   networkMainnet,
 				envExternalModelMinTimestamp: "1234567890",
 				envExternalModelMinBlock:     "23800000",
-				envModelsScriptsPath:         modelsScriptsPath,
+				envModelsScriptsPath:         scriptsPath,
 			},
 		},
 	}
@@ -483,7 +494,7 @@ models:
 	assert.Equal(t, networkMainnet, env[keyNetwork])
 	assert.Equal(t, "1234567890", env[envExternalModelMinTimestamp])
 	assert.Equal(t, "23800000", env[envExternalModelMinBlock])
-	assert.Equal(t, modelsScriptsPath, env[envModelsScriptsPath])
+	assert.Equal(t, scriptsPath, env[envModelsScriptsPath])
 }
 
 func TestExpandDefaultEnabled(t *testing.T) {
@@ -592,3 +603,347 @@ func TestExpandDefaultEnabled(t *testing.T) {
 		assert.Len(t, ov, 1)
 	})
 }
+
+func TestRuntimeGeneratorUsesAllocatedPathsAndPorts(t *testing.T) {
+	registry := instance.NewRegistry(filepath.Join(t.TempDir(), "lab", "instances"))
+	allocator := instance.NewAllocator(registry, false)
+
+	firstRuntime := newConfiggenRuntime(t, registry, allocator, "first")
+	secondRuntime := newConfiggenRuntime(t, registry, allocator, "second")
+
+	require.Equal(t, 0, firstRuntime.Ports.Slot)
+	require.Equal(t, 1, secondRuntime.Ports.Slot)
+	require.Empty(t, firstRuntime.Ports.Overlaps(secondRuntime.Ports))
+
+	firstDir, err := NewRuntimeGenerator(logrus.New(), firstRuntime).GenerateRuntimeConfigs()
+	require.NoError(t, err)
+	require.Equal(t, filepath.Join(firstRuntime.Manifest.StateDir, constants.DirConfigs), firstDir)
+
+	secondDir, err := NewRuntimeGenerator(logrus.New(), secondRuntime).GenerateRuntimeConfigs()
+	require.NoError(t, err)
+	require.Equal(t, filepath.Join(secondRuntime.Manifest.StateDir, constants.DirConfigs), secondDir)
+
+	assertGeneratedConfigMatchesRuntime(t, firstRuntime, firstDir)
+	assertGeneratedConfigMatchesRuntime(t, secondRuntime, secondDir)
+	assertNoForbiddenRuntimeLiterals(t, firstRuntime, firstDir)
+	assertNoForbiddenRuntimeLiterals(t, secondRuntime, secondDir)
+}
+
+func TestRuntimeGeneratorCopiesCustomConfigsFromRootState(t *testing.T) {
+	registry := instance.NewRegistry(filepath.Join(t.TempDir(), "lab", "instances"))
+	allocator := instance.NewAllocator(registry, false)
+	runtime := newConfiggenRuntime(t, registry, allocator, "custom")
+
+	customConfigsDir := filepath.Join(runtime.Workspace.StateDir, constants.DirCustomConfigs)
+	require.NoError(t, os.MkdirAll(customConfigsDir, 0755))
+
+	customAPIConfig := "custom: true\n"
+	customAPIPath := filepath.Join(
+		customConfigsDir,
+		fmt.Sprintf(constants.ConfigFileCBTAPI, networkMainnet),
+	)
+	require.NoError(t, os.WriteFile(customAPIPath, []byte(customAPIConfig), 0600))
+
+	configsDir, err := NewRuntimeGenerator(logrus.New(), runtime).GenerateRuntimeConfigs()
+	require.NoError(t, err)
+
+	renderedAPIConfig := readGeneratedConfig(
+		t,
+		configsDir,
+		fmt.Sprintf(constants.ConfigFileCBTAPI, networkMainnet),
+	)
+	require.Equal(t, customAPIConfig, renderedAPIConfig)
+}
+
+func newConfiggenRuntime(
+	t *testing.T,
+	registry *instance.Registry,
+	allocator *instance.Allocator,
+	name string,
+) *instance.Runtime {
+	t.Helper()
+
+	configPath := writeConfiggenRuntimeConfig(t, name)
+	labCfg, ws, err := workspace.LoadLabConfig(configPath, false)
+	require.NoError(t, err)
+
+	runtime, err := instance.NewRuntimeFromWorkspace(
+		context.Background(),
+		ws,
+		labCfg,
+		"",
+		instance.RuntimeOptions{
+			Registry:   registry,
+			Allocator:  allocator,
+			ClaimPorts: true,
+		},
+	)
+	require.NoError(t, err)
+
+	return runtime
+}
+
+func writeConfiggenRuntimeConfig(t *testing.T, name string) string {
+	t.Helper()
+
+	rootDir := filepath.Join(t.TempDir(), name)
+	reposDir := filepath.Join(rootDir, "repos")
+
+	repos := []string{
+		constants.RepoCBT,
+		constants.RepoXatuCBT,
+		constants.RepoCBTAPI,
+		constants.RepoLabBackend,
+		constants.RepoLab,
+	}
+	for _, repo := range repos {
+		require.NoError(t, os.MkdirAll(filepath.Join(reposDir, repo), 0755))
+	}
+
+	xatuCBTRepo := filepath.Join(reposDir, constants.RepoXatuCBT)
+	require.NoError(t, os.MkdirAll(filepath.Join(xatuCBTRepo, keyModels, "external"), 0755))
+	require.NoError(t, os.MkdirAll(filepath.Join(xatuCBTRepo, keyModels, "transformations"), 0755))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(xatuCBTRepo, keyModels, "external", fctBlock+".sql"),
+		[]byte("SELECT 1"),
+		0600,
+	))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(xatuCBTRepo, keyModels, "transformations", fctSummary+".sql"),
+		[]byte("SELECT 1"),
+		0600,
+	))
+
+	overridesPath := filepath.Join(rootDir, constants.CBTOverridesFile)
+	overrides := `
+models:
+  env:
+    EXTERNAL_MODEL_MIN_BLOCK: "123"
+`
+	require.NoError(t, os.WriteFile(overridesPath, []byte(overrides), 0600))
+
+	configPath := filepath.Join(rootDir, config.DefaultConfigFileName)
+	content := `
+lab:
+  mode: hybrid
+  repos:
+    cbt: repos/cbt
+    xatuCbt: repos/xatu-cbt
+    cbtApi: repos/cbt-api
+    labBackend: repos/lab-backend
+    lab: repos/lab
+  networks:
+    - name: mainnet
+      enabled: true
+      portOffset: 0
+    - name: sepolia
+      enabled: true
+      portOffset: 1
+  infrastructure:
+    clickhouse:
+      xatu:
+        mode: external
+        externalUrl: "http://example.invalid:9000"
+      cbt:
+        mode: local
+    redis:
+      port: 6380
+    observability:
+      enabled: true
+      prometheusPort: 9090
+      grafanaPort: 3000
+    clickhouseXatuPort: 8125
+    clickhouseCbtPort: 8123
+    redisPort: 6380
+  ports:
+    labBackend: 8080
+    labFrontend: 5173
+    cbtBase: 8081
+    cbtApiBase: 8091
+    cbtFrontendBase: 8085
+`
+	require.NoError(t, os.WriteFile(configPath, []byte(content), 0644))
+
+	return configPath
+}
+
+func assertGeneratedConfigMatchesRuntime(
+	t *testing.T,
+	runtime *instance.Runtime,
+	configsDir string,
+) {
+	t.Helper()
+
+	xatuCBTRepo := runtime.LabConfig.Repos.XatuCBT
+	require.True(t, filepath.IsAbs(xatuCBTRepo))
+
+	for _, network := range runtime.LabConfig.EnabledNetworks() {
+		ports := runtime.Ports.Networks[network.Name]
+
+		cbtConfig := readGeneratedConfig(
+			t,
+			configsDir,
+			fmt.Sprintf(constants.ConfigFileCBT, network.Name),
+		)
+		assert.Contains(t, cbtConfig, filepath.Join(xatuCBTRepo, keyModels, "external"))
+		assert.Contains(t, cbtConfig, filepath.Join(xatuCBTRepo, keyModels, "transformations"))
+		assert.Contains(t, cbtConfig, filepath.Join(xatuCBTRepo, keyModels, "scripts"))
+		assert.Contains(
+			t,
+			cbtConfig,
+			"localhost:"+strconv.Itoa(runtime.Ports.ClickHouseCBT01HTTP),
+		)
+		assert.Contains(t, cbtConfig, "localhost:"+strconv.Itoa(runtime.Ports.Redis))
+		assert.Contains(t, cbtConfig, strconv.Itoa(ports.CBTMetrics))
+		assert.Contains(t, cbtConfig, strconv.Itoa(ports.CBTFrontend))
+		assertRuntimeOverrideMerged(t, cbtConfig)
+
+		apiConfig := readGeneratedConfig(
+			t,
+			configsDir,
+			fmt.Sprintf(constants.ConfigFileCBTAPI, network.Name),
+		)
+		assert.Contains(t, apiConfig, "port: "+strconv.Itoa(ports.CBTAPI))
+		assert.Contains(t, apiConfig, "metrics_port: "+strconv.Itoa(ports.CBTAPIMetrics))
+		assert.Contains(
+			t,
+			apiConfig,
+			"localhost:"+strconv.Itoa(runtime.Ports.ClickHouseCBT01TCP),
+		)
+	}
+
+	backendConfig := readGeneratedConfig(t, configsDir, constants.ConfigFileLabBackend)
+	assert.Contains(t, backendConfig, "port: "+strconv.Itoa(runtime.Ports.LabBackend))
+	assert.Contains(t, backendConfig, "localhost:"+strconv.Itoa(runtime.Ports.Redis))
+
+	for _, network := range runtime.LabConfig.EnabledNetworks() {
+		assert.Contains(
+			t,
+			backendConfig,
+			"localhost:"+strconv.Itoa(runtime.Ports.Networks[network.Name].CBTAPI),
+		)
+	}
+
+	prometheusConfig := readGeneratedConfig(t, configsDir, "prometheus.yml")
+	assert.Contains(
+		t,
+		prometheusConfig,
+		"host.docker.internal:"+strconv.Itoa(runtime.Ports.LabBackend),
+	)
+
+	for _, network := range runtime.LabConfig.EnabledNetworks() {
+		ports := runtime.Ports.Networks[network.Name]
+		assert.Contains(
+			t,
+			prometheusConfig,
+			"host.docker.internal:"+strconv.Itoa(ports.CBTMetrics),
+		)
+		assert.Contains(
+			t,
+			prometheusConfig,
+			"host.docker.internal:"+strconv.Itoa(ports.CBTAPIMetrics),
+		)
+	}
+
+	datasourceConfig := readGeneratedConfig(
+		t,
+		configsDir,
+		filepath.Join("grafana", "provisioning", "datasources", "datasource.yml"),
+	)
+	assert.Contains(
+		t,
+		datasourceConfig,
+		"host.docker.internal:"+strconv.Itoa(runtime.Ports.Prometheus),
+	)
+}
+
+func assertRuntimeOverrideMerged(t *testing.T, cbtConfig string) {
+	t.Helper()
+
+	var parsed map[string]any
+	require.NoError(t, yaml.Unmarshal([]byte(cbtConfig), &parsed))
+
+	models, ok := parsed[keyModels].(map[string]any)
+	require.True(t, ok)
+
+	env, ok := models[keyEnv].(map[string]any)
+	require.True(t, ok)
+	require.Equal(t, "123", env[envExternalModelMinBlock])
+}
+
+func assertNoForbiddenRuntimeLiterals(
+	t *testing.T,
+	runtime *instance.Runtime,
+	configsDir string,
+) {
+	t.Helper()
+
+	generated := readGeneratedTree(t, configsDir)
+	require.NotContains(t, generated, "../xatu-cbt")
+
+	conditionalLiterals := map[string]int{
+		"localhost:8123": 8123,
+		"localhost:9000": 9000,
+		"localhost:6380": 6380,
+	}
+
+	for literal, port := range conditionalLiterals {
+		if !planContainsPort(runtime.Ports, port) {
+			require.NotContains(t, generated, literal)
+		}
+	}
+
+	for _, port := range []int{9100, 9200} {
+		if !planContainsPort(runtime.Ports, port) {
+			require.NotRegexp(t, regexp.MustCompile(`\b`+strconv.Itoa(port)+`\b`), generated)
+		}
+	}
+}
+
+func readGeneratedConfig(t *testing.T, configsDir, name string) string {
+	t.Helper()
+
+	data, err := os.ReadFile(filepath.Join(configsDir, name))
+	require.NoError(t, err)
+
+	return string(data)
+}
+
+func readGeneratedTree(t *testing.T, root string) string {
+	t.Helper()
+
+	var builder strings.Builder
+
+	err := filepath.WalkDir(root, func(path string, entry os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+
+		if entry.IsDir() {
+			return nil
+		}
+
+		data, readErr := os.ReadFile(path)
+		if readErr != nil {
+			return readErr
+		}
+
+		builder.Write(data)
+		builder.WriteByte('\n')
+
+		return nil
+	})
+	require.NoError(t, err)
+
+	return builder.String()
+}
+
+func planContainsPort(plan instance.PortPlan, port int) bool {
+	for _, planned := range plan.AllPorts() {
+		if planned == port {
+			return true
+		}
+	}
+
+	return false
+}
diff --git a/pkg/configgen/observability.go b/pkg/configgen/observability.go
index d4113f3..3e5ebc4 100644
--- a/pkg/configgen/observability.go
+++ b/pkg/configgen/observability.go
@@ -35,14 +35,14 @@ const (
 	valAuto       = "auto"
 )
 
-// grafanaDatasourceConfig is the static Grafana datasource provisioning YAML.
-const grafanaDatasourceConfig = `apiVersion: 1
+// grafanaDatasourceConfigTemplate is the Grafana datasource provisioning YAML.
+const grafanaDatasourceConfigTemplate = `apiVersion: 1
 datasources:
   - name: Prometheus
     type: prometheus
     uid: prometheus
     access: proxy
-    url: http://host.docker.internal:9090
+    url: http://host.docker.internal:%d
     isDefault: true
     editable: false
 `
@@ -94,8 +94,8 @@ func (g *Generator) GeneratePrometheusConfig(outputDir string) (string, error) {
 	targets := make([]PrometheusTarget, 0, 10)
 
 	// Add CBT engine targets for each enabled network
-	for i, net := range g.cfg.EnabledNetworks() {
-		metricsPort := cbtMetricsPortBase + i
+	for _, net := range g.cfg.EnabledNetworks() {
+		metricsPort := g.networkPorts(net.Name).CBTMetrics
 		targets = append(targets, PrometheusTarget{
 			JobName: fmt.Sprintf("cbt-%s", net.Name),
 			Address: fmt.Sprintf("host.docker.internal:%d", metricsPort),
@@ -103,8 +103,8 @@ func (g *Generator) GeneratePrometheusConfig(outputDir string) (string, error) {
 	}
 
 	// Add cbt-api targets for each enabled network
-	for i, net := range g.cfg.EnabledNetworks() {
-		metricsPort := cbtAPIMetricsPortBase + i
+	for _, net := range g.cfg.EnabledNetworks() {
+		metricsPort := g.networkPorts(net.Name).CBTAPIMetrics
 		targets = append(targets, PrometheusTarget{
 			JobName: fmt.Sprintf("cbt-api-%s", net.Name),
 			Address: fmt.Sprintf("host.docker.internal:%d", metricsPort),
@@ -114,7 +114,7 @@ func (g *Generator) GeneratePrometheusConfig(outputDir string) (string, error) {
 	// Add lab-backend target (assuming it exposes metrics on /metrics)
 	targets = append(targets, PrometheusTarget{
 		JobName: "lab-backend",
-		Address: fmt.Sprintf("host.docker.internal:%d", g.cfg.Ports.LabBackend),
+		Address: fmt.Sprintf("host.docker.internal:%d", g.labBackendPort()),
 		Path:    "/metrics",
 	})
 
@@ -166,8 +166,9 @@ func (g *Generator) GenerateGrafanaProvisioning(outputDir, xcliDir string) error
 	// Generate datasource provisioning file
 	datasourcePath := filepath.Join(outputDir, "grafana", "provisioning", "datasources", "datasource.yml")
 
-	//nolint:gosec // Config file permissions are intentionally 0644 for readability
-	if err := os.WriteFile(datasourcePath, []byte(grafanaDatasourceConfig), 0644); err != nil {
+	datasourceConfig := fmt.Sprintf(grafanaDatasourceConfigTemplate, g.prometheusPort())
+	//nolint:gosec // G306: config file intentionally world-readable
+	if err := os.WriteFile(datasourcePath, []byte(datasourceConfig), 0644); err != nil {
 		return fmt.Errorf("failed to write datasource.yml: %w", err)
 	}
 
diff --git a/pkg/configgen/runtime.go b/pkg/configgen/runtime.go
new file mode 100644
index 0000000..969b88c
--- /dev/null
+++ b/pkg/configgen/runtime.go
@@ -0,0 +1,131 @@
+package configgen
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/ethpandaops/xcli/pkg/constants"
+)
+
+// GenerateRuntimeConfigs writes all generated service configs for the bound
+// runtime under <root>/.xcli/instances/<id>/configs.
+func (g *Generator) GenerateRuntimeConfigs() (string, error) {
+	if g.runtime == nil {
+		return "", fmt.Errorf("runtime is required")
+	}
+
+	if g.runtime.Workspace == nil {
+		return "", fmt.Errorf("runtime workspace is required")
+	}
+
+	if g.runtime.Manifest == nil {
+		return "", fmt.Errorf("runtime manifest is required")
+	}
+
+	configsDir := filepath.Join(g.runtime.Manifest.StateDir, constants.DirConfigs)
+	if err := os.MkdirAll(configsDir, 0755); err != nil {
+		return "", fmt.Errorf("failed to create configs directory: %w", err)
+	}
+
+	customConfigsDir := filepath.Join(g.runtime.Workspace.StateDir, constants.DirCustomConfigs)
+	userOverridesPath := g.runtime.Workspace.OverridesPath
+
+	for _, network := range g.cfg.EnabledNetworks() {
+		cbtFilename := fmt.Sprintf(constants.ConfigFileCBT, network.Name)
+		cbtPath := filepath.Join(configsDir, cbtFilename)
+
+		if hasCustomConfig, customPath := findCustomConfig(customConfigsDir, cbtFilename); hasCustomConfig {
+			if err := copyFile(customPath, cbtPath); err != nil {
+				return "", fmt.Errorf("failed to copy custom CBT config for %s: %w", network.Name, err)
+			}
+		} else {
+			cbtConfig, err := g.GenerateCBTConfig(network.Name, userOverridesPath)
+			if err != nil {
+				return "", fmt.Errorf("failed to generate CBT config for %s: %w", network.Name, err)
+			}
+
+			//nolint:gosec // Config files are intentionally readable.
+			if err := os.WriteFile(cbtPath, []byte(cbtConfig), 0644); err != nil {
+				return "", fmt.Errorf("failed to write CBT config: %w", err)
+			}
+		}
+
+		apiFilename := fmt.Sprintf(constants.ConfigFileCBTAPI, network.Name)
+		apiPath := filepath.Join(configsDir, apiFilename)
+
+		if hasCustomConfig, customPath := findCustomConfig(customConfigsDir, apiFilename); hasCustomConfig {
+			if err := copyFile(customPath, apiPath); err != nil {
+				return "", fmt.Errorf("failed to copy custom cbt-api config for %s: %w", network.Name, err)
+			}
+		} else {
+			apiConfig, err := g.GenerateCBTAPIConfig(network.Name)
+			if err != nil {
+				return "", fmt.Errorf("failed to generate cbt-api config for %s: %w", network.Name, err)
+			}
+
+			//nolint:gosec // Config files are intentionally readable.
+			if err := os.WriteFile(apiPath, []byte(apiConfig), 0644); err != nil {
+				return "", fmt.Errorf("failed to write cbt-api config: %w", err)
+			}
+		}
+	}
+
+	backendFilename := constants.ConfigFileLabBackend
+	backendPath := filepath.Join(configsDir, backendFilename)
+
+	if hasCustomConfig, customPath := findCustomConfig(customConfigsDir, backendFilename); hasCustomConfig {
+		if err := copyFile(customPath, backendPath); err != nil {
+			return "", fmt.Errorf("failed to copy custom lab-backend config: %w", err)
+		}
+	} else {
+		backendConfig, err := g.GenerateLabBackendConfig(userOverridesPath)
+		if err != nil {
+			return "", fmt.Errorf("failed to generate lab-backend config: %w", err)
+		}
+
+		//nolint:gosec // Config files are intentionally readable.
+		if err := os.WriteFile(backendPath, []byte(backendConfig), 0644); err != nil {
+			return "", fmt.Errorf("failed to write lab-backend config: %w", err)
+		}
+	}
+
+	if g.cfg.Infrastructure.Observability.Enabled {
+		if _, err := g.GeneratePrometheusConfig(configsDir); err != nil {
+			return "", fmt.Errorf("failed to generate Prometheus config: %w", err)
+		}
+
+		if err := g.GenerateGrafanaProvisioning(configsDir, g.runtime.Workspace.StateDir); err != nil {
+			return "", fmt.Errorf("failed to generate Grafana provisioning: %w", err)
+		}
+	}
+
+	return configsDir, nil
+}
+
+func findCustomConfig(customConfigsDir, filename string) (bool, string) {
+	path := filepath.Join(customConfigsDir, filename)
+	if _, err := os.Stat(path); err == nil {
+		return true, path
+	}
+
+	return false, ""
+}
+
+func copyFile(src, dst string) error {
+	data, err := os.ReadFile(src)
+	if err != nil {
+		return fmt.Errorf("failed to read %s: %w", src, err)
+	}
+
+	if err := os.MkdirAll(filepath.Dir(dst), 0755); err != nil {
+		return fmt.Errorf("failed to create destination directory: %w", err)
+	}
+
+	//nolint:gosec // Config files are intentionally readable.
+	if err := os.WriteFile(dst, data, 0644); err != nil {
+		return fmt.Errorf("failed to write %s: %w", dst, err)
+	}
+
+	return nil
+}
diff --git a/pkg/configgen/templates/cbt-api.yaml.tmpl b/pkg/configgen/templates/cbt-api.yaml.tmpl
index 10fa592..0a60239 100644
--- a/pkg/configgen/templates/cbt-api.yaml.tmpl
+++ b/pkg/configgen/templates/cbt-api.yaml.tmpl
@@ -9,7 +9,7 @@ server:
   idle_timeout: 120s
 
 clickhouse:
-  dsn: "clickhouse://default:supersecret@localhost:9000?compress=true"
+  dsn: "clickhouse://default:supersecret@localhost:{{ .ClickHouseNativePort }}?compress=true"
   database: "{{ .Network }}"
   use_final: true
   max_open_conns: 10
diff --git a/pkg/configgen/templates/cbt.yaml.tmpl b/pkg/configgen/templates/cbt.yaml.tmpl
index b061a5a..f4f22a2 100644
--- a/pkg/configgen/templates/cbt.yaml.tmpl
+++ b/pkg/configgen/templates/cbt.yaml.tmpl
@@ -4,7 +4,7 @@ logging: debug
 metricsAddr: ":{{ .MetricsPort }}"
 
 clickhouse:
-  url: "http://default:supersecret@localhost:8123"
+  url: "http://default:supersecret@localhost:{{ .ClickHouseHTTPPort }}"
   cluster: "{cluster}"
   localSuffix: "_local"
   queryTimeout: 10m
@@ -26,18 +26,18 @@ interval_types:
     - name: Timestamp
 
 redis:
-  url: "redis://localhost:6380/{{ .RedisDB }}"
+  url: "redis://localhost:{{ .RedisPort }}/{{ .RedisDB }}"
 
 models:
   external:
     defaultCluster: "xatu_cluster"
     defaultDatabase: "{{ .ExternalClickHouseDatabase }}"
     paths:
-      - "../xatu-cbt/models/external"
+      - "{{ .ExternalModelsPath }}"
   transformations:
     defaultDatabase: "{{ .Network }}"
     paths:
-      - "../xatu-cbt/models/transformations"
+      - "{{ .TransformationModelsPath }}"
 
 frontend:
   enabled: true
diff --git a/pkg/configgen/templates/lab-backend.yaml.tmpl b/pkg/configgen/templates/lab-backend.yaml.tmpl
index afd9d90..cd4f6b9 100644
--- a/pkg/configgen/templates/lab-backend.yaml.tmpl
+++ b/pkg/configgen/templates/lab-backend.yaml.tmpl
@@ -8,7 +8,7 @@ server:
   log_level: "info"
 
 redis:
-  address: "localhost:6380"
+  address: "localhost:{{ .RedisPort }}"
   password: ""
   db: 0
   dial_timeout: 5s
diff --git a/pkg/constants/constants.go b/pkg/constants/constants.go
index 2c14949..9e1901c 100644
--- a/pkg/constants/constants.go
+++ b/pkg/constants/constants.go
@@ -94,14 +94,23 @@ const (
 	// Default ports.
 	DefaultPrometheusPort = 9090
 	DefaultGrafanaPort    = 3000
+)
 
-	// Container names.
-	ContainerPrometheus = "xcli-prometheus"
-	ContainerGrafana    = "xcli-grafana"
-
-	// Volume names.
-	VolumePrometheus = "xcli-prometheus-data"
-	VolumeGrafana    = "xcli-grafana-data"
+// Lab slot-0 port defaults.
+const (
+	DefaultLabBackendPort           = 8080
+	DefaultLabFrontendPort          = 5173
+	DefaultCBTBasePort              = 8081
+	DefaultCBTAPIBasePort           = 8091
+	DefaultCBTFrontendBasePort      = 8085
+	DefaultCBTMetricsBasePort       = 9100
+	DefaultCBTAPIMetricsBasePort    = 9200
+	DefaultClickHouseCBTHTTPPort    = 8123
+	DefaultClickHouseCBTNativePort  = 9000
+	DefaultClickHouseXatuHTTPPort   = 8125
+	DefaultClickHouseXatuNativePort = 9002
+	DefaultRedisPort                = 6380
+	DefaultCommandCenterPort        = 19280
 )
 
 // PID file template.
diff --git a/pkg/git/snapshot.go b/pkg/git/snapshot.go
new file mode 100644
index 0000000..17d3531
--- /dev/null
+++ b/pkg/git/snapshot.go
@@ -0,0 +1,76 @@
+package git
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+)
+
+// RepoVersion is a fast local version snapshot for a git repository.
+type RepoVersion struct {
+	Path   string `json:"path"`
+	Branch string `json:"branch"`
+	Commit string `json:"commit"`
+	Dirty  bool   `json:"dirty"`
+}
+
+// Snapshot reads branch, commit SHA, and dirty state without fetching.
+func Snapshot(ctx context.Context, repoPath string) (RepoVersion, error) {
+	absPath, err := filepath.Abs(repoPath)
+	if err != nil {
+		return RepoVersion{Path: repoPath}, fmt.Errorf("failed to resolve repo path: %w", err)
+	}
+
+	version := RepoVersion{Path: absPath}
+
+	if _, statErr := os.Stat(absPath); statErr != nil {
+		return version, fmt.Errorf("failed to inspect repo path %s: %w", absPath, statErr)
+	}
+
+	if _, workTreeErr := gitOutput(ctx, absPath, "rev-parse", "--is-inside-work-tree"); workTreeErr != nil {
+		return version, fmt.Errorf("not a git worktree at %s: %w", absPath, workTreeErr)
+	}
+
+	branch, err := gitOutput(ctx, absPath, "branch", "--show-current")
+	if err != nil {
+		return version, fmt.Errorf("failed to read branch: %w", err)
+	}
+
+	if branch == "" {
+		branch, err = gitOutput(ctx, absPath, "rev-parse", "--abbrev-ref", "HEAD")
+		if err != nil {
+			return version, fmt.Errorf("failed to read detached branch state: %w", err)
+		}
+	}
+
+	commit, err := gitOutput(ctx, absPath, "rev-parse", "HEAD")
+	if err != nil {
+		return version, fmt.Errorf("failed to read commit: %w", err)
+	}
+
+	status, err := gitOutput(ctx, absPath, "status", "--porcelain")
+	if err != nil {
+		return version, fmt.Errorf("failed to read dirty state: %w", err)
+	}
+
+	version.Branch = branch
+	version.Commit = commit
+	version.Dirty = status != ""
+
+	return version, nil
+}
+
+func gitOutput(ctx context.Context, repoPath string, args ...string) (string, error) {
+	cmd := exec.CommandContext(ctx, "git", args...)
+	cmd.Dir = repoPath
+
+	out, err := cmd.Output()
+	if err != nil {
+		return "", err
+	}
+
+	return strings.TrimSpace(string(out)), nil
+}
diff --git a/pkg/git/snapshot_test.go b/pkg/git/snapshot_test.go
new file mode 100644
index 0000000..045da72
--- /dev/null
+++ b/pkg/git/snapshot_test.go
@@ -0,0 +1,53 @@
+package git
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestSnapshotReadsBranchCommitAndDirtyState(t *testing.T) {
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not available")
+	}
+
+	ctx := context.Background()
+	repoDir := t.TempDir()
+
+	runGit(t, repoDir, "init")
+	runGit(t, repoDir, "config", "user.email", "test@example.com")
+	runGit(t, repoDir, "config", "user.name", "Test User")
+	runGit(t, repoDir, "config", "commit.gpgsign", "false")
+
+	require.NoError(t, os.WriteFile(filepath.Join(repoDir, "README.md"), []byte("hello\n"), 0644))
+	runGit(t, repoDir, "add", "README.md")
+	runGit(t, repoDir, "commit", "-m", "initial")
+
+	version, err := Snapshot(ctx, repoDir)
+	require.NoError(t, err)
+	require.Equal(t, repoDir, version.Path)
+	require.NotEmpty(t, version.Branch)
+	require.Len(t, version.Commit, 40)
+	require.False(t, version.Dirty)
+
+	require.NoError(t, os.WriteFile(filepath.Join(repoDir, "dirty.txt"), []byte("dirty\n"), 0644))
+
+	version, err = Snapshot(ctx, repoDir)
+	require.NoError(t, err)
+	require.True(t, version.Dirty)
+}
+
+func runGit(t *testing.T, repoDir string, args ...string) {
+	t.Helper()
+
+	cmd := exec.Command("git", args...)
+	cmd.Dir = repoDir
+
+	out, err := cmd.CombinedOutput()
+	require.NoError(t, err, strings.TrimSpace(string(out)))
+}
diff --git a/pkg/infrastructure/bounds_seeder.go b/pkg/infrastructure/bounds_seeder.go
index 5f649bd..bfe625b 100644
--- a/pkg/infrastructure/bounds_seeder.go
+++ b/pkg/infrastructure/bounds_seeder.go
@@ -6,8 +6,10 @@ import (
 	"encoding/base64"
 	"fmt"
 	"os/exec"
+	"strconv"
 	"strings"
 
+	"github.com/ethpandaops/xcli/pkg/instance"
 	"github.com/sirupsen/logrus"
 )
 
@@ -18,9 +20,6 @@ const (
 	prodK8sContext = "platform-analytics-hel1-production"
 	prodNamespace  = "clickhouse"
 
-	// localRedisContainer is the local Docker container name for xatu-cbt Redis.
-	localRedisContainer = "xatu-cbt-redis"
-
 	// redisBoundsKeyPrefix is the Redis key prefix for external model bounds.
 	redisBoundsKeyPrefix = "cbt:external:"
 
@@ -34,11 +33,18 @@ const (
 	cmdRedisCLI = "redis-cli"
 	// flagN is the "-n" flag (redis-cli database number / kubectl namespace).
 	flagN = "-n"
+	// flagH is the redis-cli "-h" host flag.
+	flagH = "-h"
+	// flagP is the redis-cli "-p" port flag.
+	flagP = "-p"
+	// localhostIP is the loopback address used to reach local Redis.
+	localhostIP = "127.0.0.1"
 )
 
 // BoundsSeeder handles seeding CBT external bounds from production Redis.
 type BoundsSeeder struct {
-	log logrus.FieldLogger
+	log     logrus.FieldLogger
+	runtime *instance.Runtime
 }
 
 // redisBound represents a key-value pair from Redis.
@@ -49,8 +55,14 @@ type redisBound struct {
 
 // NewBoundsSeeder creates a new bounds seeder.
 func NewBoundsSeeder(log logrus.FieldLogger) *BoundsSeeder {
+	return NewBoundsSeederWithRuntime(log, nil)
+}
+
+// NewBoundsSeederWithRuntime creates a bounds seeder for one lab instance.
+func NewBoundsSeederWithRuntime(log logrus.FieldLogger, runtime *instance.Runtime) *BoundsSeeder {
 	return &BoundsSeeder{
-		log: log.WithField("component", "bounds_seeder"),
+		log:     log.WithField("component", "bounds_seeder"),
+		runtime: runtime,
 	}
 }
 
@@ -103,14 +115,8 @@ func (s *BoundsSeeder) SeedFromProduction(ctx context.Context, network string, r
 
 // CheckNeedsSeeding checks if local Redis has any external bounds for the given network.
 func (s *BoundsSeeder) CheckNeedsSeeding(ctx context.Context, redisDB int) (bool, error) {
-	args := []string{
-		cmdExec, localRedisContainer,
-		cmdRedisCLI,
-		flagN, fmt.Sprintf("%d", redisDB),
-		"KEYS", redisBoundsKeyPrefix + "*",
-	}
-
-	cmd := exec.CommandContext(ctx, "docker", args...)
+	//nolint:gosec // G204: args are internally constructed, not user input
+	cmd := exec.CommandContext(ctx, cmdRedisCLI, s.localRedisArgs(redisDB, "KEYS", redisBoundsKeyPrefix+"*")...)
 
 	output, err := cmd.CombinedOutput()
 	if err != nil {
@@ -238,14 +244,8 @@ func (s *BoundsSeeder) bulkInsertLocal(ctx context.Context, redisDB int, bounds
 			len(b.Key), b.Key, len(b.Value), b.Value)
 	}
 
-	args := []string{
-		cmdExec, "-i", localRedisContainer,
-		cmdRedisCLI,
-		flagN, fmt.Sprintf("%d", redisDB),
-		"--pipe",
-	}
-
-	cmd := exec.CommandContext(ctx, "docker", args...)
+	//nolint:gosec // G204: args are internally constructed, not user input
+	cmd := exec.CommandContext(ctx, cmdRedisCLI, s.localRedisArgs(redisDB, "--pipe")...)
 	cmd.Stdin = &protocol
 
 	output, err := cmd.CombinedOutput()
@@ -258,6 +258,27 @@ func (s *BoundsSeeder) bulkInsertLocal(ctx context.Context, redisDB int, bounds
 	return nil
 }
 
+func (s *BoundsSeeder) localRedisArgs(redisDB int, args ...string) []string {
+	redisPort := instance.DefaultPortPlan().Redis
+	if s.runtime != nil {
+		if s.runtime.Ports.Redis > 0 {
+			redisPort = s.runtime.Ports.Redis
+		} else if s.runtime.Manifest != nil && s.runtime.Manifest.Ports.Redis > 0 {
+			redisPort = s.runtime.Manifest.Ports.Redis
+		}
+	}
+
+	result := make([]string, 0, 6+len(args))
+	result = append(result,
+		flagH, localhostIP,
+		flagP, strconv.Itoa(redisPort),
+		flagN, strconv.Itoa(redisDB),
+	)
+	result = append(result, args...)
+
+	return result
+}
+
 // prodRedisDetails returns the production Redis pod name and password k8s secret name for a network.
 func prodRedisDetails(network string) (podName, secretName string) {
 	return fmt.Sprintf("%s-cbt-redis-node-0", network),
diff --git a/pkg/infrastructure/manager.go b/pkg/infrastructure/manager.go
index feefb88..4b1f914 100644
--- a/pkg/infrastructure/manager.go
+++ b/pkg/infrastructure/manager.go
@@ -11,6 +11,8 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"sort"
+	"strconv"
 	"strings"
 	"time"
 
@@ -18,6 +20,7 @@ import (
 	"github.com/ethpandaops/xcli/pkg/configgen"
 	"github.com/ethpandaops/xcli/pkg/constants"
 	executil "github.com/ethpandaops/xcli/pkg/exec"
+	"github.com/ethpandaops/xcli/pkg/instance"
 	"github.com/ethpandaops/xcli/pkg/mode"
 	"github.com/ethpandaops/xcli/pkg/ui"
 	"github.com/sirupsen/logrus"
@@ -33,6 +36,13 @@ const (
 
 	// logFieldHost is the structured log field key for a host.
 	logFieldHost = "host"
+
+	defaultXatuCBTProjectName = "xatu-cbt-platform"
+
+	// cmdInfra is the xatu-cbt "infra" subcommand.
+	cmdInfra = "infra"
+	// flagProjectName is the xatu-cbt "--project-name" flag.
+	flagProjectName = "--project-name"
 )
 
 // clickHouseClusterShards are the shard suffixes for ClickHouse clusters.
@@ -47,13 +57,30 @@ type Manager struct {
 	verbose       bool
 	observability *ObservabilityManager
 	xcliDir       string
+	runtime       *instance.Runtime
+	runCmd        func(*exec.Cmd, bool) error
 }
 
 // NewManager creates a new infrastructure manager.
 // Mode parameter provides mode-specific behavior (services, ports, etc.)
 func NewManager(log logrus.FieldLogger, cfg *config.LabConfig, m mode.Mode, xcliDir string) *Manager {
+	return NewManagerWithRuntime(log, cfg, m, xcliDir, nil)
+}
+
+// NewManagerWithRuntime creates an infrastructure manager bound to an instance runtime.
+func NewManagerWithRuntime(
+	log logrus.FieldLogger,
+	cfg *config.LabConfig,
+	m mode.Mode,
+	xcliDir string,
+	runtime *instance.Runtime,
+) *Manager {
 	xatuCBTPath := cfg.Repos.XatuCBT + "/bin/xatu-cbt"
 
+	if runtime != nil && runtime.Manifest != nil && runtime.Manifest.StateDir != "" {
+		xcliDir = runtime.Manifest.StateDir
+	}
+
 	return &Manager{
 		log:         log.WithField("component", "infrastructure"),
 		cfg:         cfg,
@@ -61,6 +88,8 @@ func NewManager(log logrus.FieldLogger, cfg *config.LabConfig, m mode.Mode, xcli
 		xatuCBTPath: xatuCBTPath,
 		verbose:     false,
 		xcliDir:     xcliDir,
+		runtime:     runtime,
+		runCmd:      executil.RunCmd,
 	}
 }
 
@@ -69,6 +98,161 @@ func (m *Manager) SetVerbose(verbose bool) {
 	m.verbose = verbose
 }
 
+// DockerContainerName returns the Docker container name for xcli-managed services.
+func (m *Manager) DockerContainerName(service string) (string, bool) {
+	if service != constants.ServicePrometheus && service != constants.ServiceGrafana {
+		return "", false
+	}
+
+	resources := newObservabilityResources(m.cfg, m.runtime)
+
+	name := resources.containers[service]
+	if name == "" {
+		return "", false
+	}
+
+	return name, true
+}
+
+func (m *Manager) userStateDir() string {
+	if m.runtime != nil && m.runtime.Workspace != nil && m.runtime.Workspace.StateDir != "" {
+		return m.runtime.Workspace.StateDir
+	}
+
+	return m.xcliDir
+}
+
+func (m *Manager) xatuCBTProjectName() string {
+	if m.runtime == nil {
+		return defaultXatuCBTProjectName
+	}
+
+	if plan := m.runtime.EffectiveDockerPlan(); plan.ProjectName != "" {
+		return plan.ProjectName
+	}
+
+	return defaultXatuCBTProjectName
+}
+
+func (m *Manager) infraStartArgs(xatuSource string) []string {
+	return []string{
+		cmdInfra,
+		"start",
+		flagProjectName,
+		m.xatuCBTProjectName(),
+		"--xatu-source",
+		xatuSource,
+	}
+}
+
+func (m *Manager) infraActionArgs(action string) []string {
+	return []string{
+		cmdInfra,
+		action,
+		flagProjectName,
+		m.xatuCBTProjectName(),
+	}
+}
+
+func (m *Manager) xatuCBTCommand(ctx context.Context, args ...string) (*exec.Cmd, error) {
+	//nolint:gosec // G204: args are internally constructed, not user input
+	cmd := exec.CommandContext(ctx, m.xatuCBTPath, args...)
+	cmd.Dir = m.cfg.Repos.XatuCBT
+
+	env, err := m.xatuCBTEnv(os.Environ())
+	if err != nil {
+		return nil, err
+	}
+
+	cmd.Env = env
+
+	return cmd, nil
+}
+
+func (m *Manager) runXatuCBT(ctx context.Context, args ...string) error {
+	cmd, err := m.xatuCBTCommand(ctx, args...)
+	if err != nil {
+		return err
+	}
+
+	runCmd := m.runCmd
+	if runCmd == nil {
+		runCmd = executil.RunCmd
+	}
+
+	return runCmd(cmd, m.verbose)
+}
+
+func (m *Manager) xatuCBTEnv(base []string) ([]string, error) {
+	plan, err := m.xatuCBTPortPlan()
+	if err != nil {
+		return nil, err
+	}
+
+	return mergeEnv(base, plan.XatuCBTEnv(m.xatuCBTProjectName())), nil
+}
+
+func (m *Manager) xatuCBTPortPlan() (instance.PortPlan, error) {
+	fallback, err := instance.BuildPortPlan(m.cfg, 0)
+	if err != nil {
+		return instance.PortPlan{}, err
+	}
+
+	if m.runtime == nil {
+		return fallback, nil
+	}
+
+	plan := m.runtime.Ports
+	if len(plan.AllPorts()) == 0 && m.runtime.Manifest != nil {
+		plan = m.runtime.Manifest.Ports
+	}
+
+	return plan.WithDefaults(fallback), nil
+}
+
+func (m *Manager) healthCheckPorts() ([]int, error) {
+	if m.runtime == nil {
+		return m.mode.GetHealthCheckPorts(), nil
+	}
+
+	plan, err := m.xatuCBTPortPlan()
+	if err != nil {
+		return nil, err
+	}
+
+	ports := []int{plan.ClickHouseCBT01HTTP, plan.Redis}
+	if !m.mode.NeedsExternalClickHouse() {
+		ports = append(ports, plan.ClickHouseXatu01HTTP)
+	}
+
+	return ports, nil
+}
+
+func mergeEnv(base []string, overrides map[string]string) []string {
+	env := make([]string, 0, len(base)+len(overrides))
+	for _, entry := range base {
+		name, _, found := strings.Cut(entry, "=")
+		if found && overrides[name] != "" {
+			continue
+		}
+
+		env = append(env, entry)
+	}
+
+	names := make([]string, 0, len(overrides))
+	for name := range overrides {
+		names = append(names, name)
+	}
+
+	sort.Strings(names)
+
+	for _, name := range names {
+		env = append(env, fmt.Sprintf("%s=%s", name, overrides[name]))
+	}
+
+	return env
+}
+
 // Start starts infrastructure via xatu-cbt.
 func (m *Manager) Start(ctx context.Context) error {
 	// Check if infrastructure is already running
@@ -98,7 +282,7 @@ func (m *Manager) Start(ctx context.Context) error {
 	spinner := ui.NewSpinner("Starting infrastructure services")
 
 	// Build command arguments
-	args := []string{"infra", "start", "--xatu-source", xatuSource}
+	args := m.infraStartArgs(xatuSource)
 
 	// Add external Xatu URL if in external mode. Credentials configured via the
 	// separate externalUsername/externalPassword fields must be embedded into the
@@ -128,11 +312,7 @@ func (m *Manager) Start(ctx context.Context) error {
 		args = append(args, "--xatu-ref", m.cfg.Dev.XatuRef)
 	}
 
-	//nolint:gosec // xatuCBTPath is from config and validated during discovery
-	cmd := exec.CommandContext(ctx, m.xatuCBTPath, args...)
-	cmd.Dir = m.cfg.Repos.XatuCBT
-
-	if err := executil.RunCmd(cmd, m.verbose); err != nil {
+	if err := m.runXatuCBT(ctx, args...); err != nil {
 		spinner.Fail("Failed to start infrastructure services")
 
 		return fmt.Errorf("failed to start infrastructure: %w", err)
@@ -182,11 +362,7 @@ func (m *Manager) Stop(ctx context.Context) error {
 		}
 	}
 
-	//nolint:gosec // xatuCBTPath is from config and validated during discovery
-	cmd := exec.CommandContext(ctx, m.xatuCBTPath, "infra", "stop")
-	cmd.Dir = m.cfg.Repos.XatuCBT
-
-	if err := executil.RunCmd(cmd, m.verbose); err != nil {
+	if err := m.runXatuCBT(ctx, m.infraActionArgs("stop")...); err != nil {
 		return fmt.Errorf("failed to stop infrastructure: %w", err)
 	}
 
@@ -195,21 +371,31 @@ func (m *Manager) Stop(ctx context.Context) error {
 	return nil
 }
 
-// Reset resets infrastructure (clean slate).
+// Reset resets infrastructure and removes data. Use Stop for ordinary shutdown.
 func (m *Manager) Reset(ctx context.Context) error {
+	return m.Destroy(ctx)
+}
+
+// Destroy removes infrastructure containers and volumes for this instance.
+func (m *Manager) Destroy(ctx context.Context) error {
 	m.log.WithField("mode", m.mode.Name()).Info("resetting infrastructure")
 
-	// Stop first
-	if err := m.Stop(ctx); err != nil {
-		m.log.WithError(err).Warn("Failed to stop infrastructure")
-	}
+	if m.cfg.Infrastructure.Observability.Enabled {
+		if m.observability == nil {
+			obsMgr, err := NewObservabilityManagerWithRuntime(m.log, m.cfg, m.xcliDir, m.runtime)
+			if err != nil {
+				return fmt.Errorf("failed to create observability manager: %w", err)
+			}
 
-	// Remove volumes
-	//nolint:gosec // xatuCBTPath is from config and validated during discovery
-	cmd := exec.CommandContext(ctx, m.xatuCBTPath, "infra", "reset")
-	cmd.Dir = m.cfg.Repos.XatuCBT
+			m.observability = obsMgr
+		}
+
+		if err := m.observability.Destroy(ctx); err != nil {
+			m.log.WithError(err).Warn("failed to destroy observability stack")
+		}
+	}
 
-	if err := executil.RunCmd(cmd, m.verbose); err != nil {
+	if err := m.runXatuCBT(ctx, m.infraActionArgs("reset")...); err != nil {
 		return fmt.Errorf("failed to reset infrastructure: %w", err)
 	}
 
@@ -218,18 +404,54 @@ func (m *Manager) Reset(ctx context.Context) error {
 	return nil
 }
 
+// ResetRedis intentionally clears Redis data for this instance only.
+func (m *Manager) ResetRedis(ctx context.Context) error {
+	plan, err := m.xatuCBTPortPlan()
+	if err != nil {
+		return err
+	}
+
+	//nolint:gosec // G204: args are internally constructed, not user input
+	cmd := exec.CommandContext(
+		ctx,
+		"redis-cli",
+		"-h",
+		"127.0.0.1",
+		"-p",
+		strconv.Itoa(plan.Redis),
+		"FLUSHALL",
+	)
+
+	runCmd := m.runCmd
+	if runCmd == nil {
+		runCmd = executil.RunCmd
+	}
+
+	if err := runCmd(cmd, m.verbose); err != nil {
+		return fmt.Errorf("failed to reset Redis for instance %s: %w", m.xatuCBTProjectName(), err)
+	}
+
+	return nil
+}
+
 // SetupNetwork runs migrations for a network.
 func (m *Manager) SetupNetwork(ctx context.Context, network string) error {
 	m.log.WithField("network", network).Info("running network setup")
 
 	// xatu-cbt network setup uses NETWORK env var, not --network flag
-	//nolint:gosec // xatuCBTPath is from config and validated during discovery
-	cmd := exec.CommandContext(ctx, m.xatuCBTPath, "network", "setup", "--force")
-	cmd.Dir = m.cfg.Repos.XatuCBT
+	cmd, err := m.xatuCBTCommand(ctx, "network", "setup", "--force")
+	if err != nil {
+		return err
+	}
 
-	cmd.Env = append(os.Environ(), fmt.Sprintf("NETWORK=%s", network))
+	cmd.Env = mergeEnv(cmd.Env, map[string]string{"NETWORK": network})
 
-	if err := executil.RunCmd(cmd, m.verbose); err != nil {
+	runCmd := m.runCmd
+	if runCmd == nil {
+		runCmd = executil.RunCmd
+	}
+
+	if err := runCmd(cmd, m.verbose); err != nil {
 		return fmt.Errorf("failed to setup network %s: %w", network, err)
 	}
 
@@ -238,8 +460,12 @@ func (m *Manager) SetupNetwork(ctx context.Context, network string) error {
 
 // IsRunning checks if infrastructure is running.
 func (m *Manager) IsRunning(ctx context.Context) bool {
-	// Get ports from mode (instead of hard-coded ports)
-	ports := m.mode.GetHealthCheckPorts()
+	ports, err := m.healthCheckPorts()
+	if err != nil {
+		m.log.WithError(err).Warn("failed to resolve infrastructure health check ports")
+
+		return false
+	}
 
 	for _, port := range ports {
 		addr := fmt.Sprintf("localhost:%d", port)
@@ -253,8 +479,10 @@ func (m *Manager) IsRunning(ctx context.Context) bool {
 
 // WaitForReady waits for infrastructure to be ready.
 func (m *Manager) WaitForReady(ctx context.Context, timeout time.Duration, spinner *ui.Spinner) error {
-	// Get ports from mode (instead of hard-coded checks)
-	ports := m.mode.GetHealthCheckPorts()
+	ports, err := m.healthCheckPorts()
+	if err != nil {
+		return fmt.Errorf("failed to resolve infrastructure health check ports: %w", err)
+	}
 
 	m.log.WithFields(logrus.Fields{
 		"mode":  m.mode.Name(),
@@ -304,14 +532,21 @@ func (m *Manager) WaitForReady(ctx context.Context, timeout time.Duration, spinn
 // Hybrid mode shows ClickHouse CBT + Redis; local mode adds ClickHouse Xatu.
 func (m *Manager) Status(ctx context.Context) map[string]bool {
 	// Map ports to display names for mode-relevant infrastructure only.
+	plan, err := m.xatuCBTPortPlan()
+	if err != nil {
+		m.log.WithError(err).Warn("failed to resolve infrastructure status ports")
+
+		return map[string]bool{}
+	}
+
 	portNames := map[int]string{
-		m.cfg.Infrastructure.ClickHouseCBTPort: "ClickHouse CBT",
-		m.cfg.Infrastructure.RedisPort:         "Redis",
+		plan.ClickHouseCBT01HTTP: "ClickHouse CBT",
+		plan.Redis:               "Redis",
 	}
 
 	// Local mode also runs a local ClickHouse Xatu instance.
 	if !m.mode.NeedsExternalClickHouse() {
-		portNames[m.cfg.Infrastructure.ClickHouseXatuPort] = "ClickHouse Xatu"
+		portNames[plan.ClickHouseXatu01HTTP] = "ClickHouse Xatu"
 	}
 
 	status := make(map[string]bool, len(portNames))
@@ -345,7 +580,7 @@ func (m *Manager) TestExternalConnection(ctx context.Context) error {
 	port := parsedURL.Port()
 	if port == "" {
 		// Default ClickHouse native port
-		port = "9000"
+		port = strconv.Itoa(constants.DefaultClickHouseCBTNativePort)
 	}
 
 	// Extract username and password
@@ -439,7 +674,7 @@ func (m *Manager) GetObservabilityStatus(ctx context.Context) (map[string]Contai
 	}
 
 	if m.observability == nil {
-		obsMgr, err := NewObservabilityManager(m.log, m.cfg, m.xcliDir)
+		obsMgr, err := NewObservabilityManagerWithRuntime(m.log, m.cfg, m.xcliDir, m.runtime)
 		if err != nil {
 			return nil, fmt.Errorf("failed to create observability manager: %w", err)
 		}
@@ -457,7 +692,7 @@ func (m *Manager) RestartObservabilityService(ctx context.Context, service strin
 	}
 
 	if m.observability == nil {
-		obsMgr, err := NewObservabilityManager(m.log, m.cfg, m.xcliDir)
+		obsMgr, err := NewObservabilityManagerWithRuntime(m.log, m.cfg, m.xcliDir, m.runtime)
 		if err != nil {
 			return fmt.Errorf("failed to create observability manager: %w", err)
 		}
@@ -475,7 +710,7 @@ func (m *Manager) StartObservabilityService(ctx context.Context, service string)
 	}
 
 	if m.observability == nil {
-		obsMgr, err := NewObservabilityManager(m.log, m.cfg, m.xcliDir)
+		obsMgr, err := NewObservabilityManagerWithRuntime(m.log, m.cfg, m.xcliDir, m.runtime)
 		if err != nil {
 			return fmt.Errorf("failed to create observability manager: %w", err)
 		}
@@ -493,7 +728,7 @@ func (m *Manager) StopObservabilityService(ctx context.Context, service string)
 	}
 
 	if m.observability == nil {
-		obsMgr, err := NewObservabilityManager(m.log, m.cfg, m.xcliDir)
+		obsMgr, err := NewObservabilityManagerWithRuntime(m.log, m.cfg, m.xcliDir, m.runtime)
 		if err != nil {
 			return fmt.Errorf("failed to create observability manager: %w", err)
 		}
@@ -515,7 +750,7 @@ func (m *Manager) AutoSeedBoundsIfNeeded(ctx context.Context, spinner ui.Task) e
 
 	m.log.Debug("Checking if external bounds seeding is needed...")
 
-	seeder := NewBoundsSeeder(m.log)
+	seeder := NewBoundsSeederWithRuntime(m.log, m.runtime)
 
 	enabledNetworks := m.cfg.EnabledNetworks()
 	if len(enabledNetworks) == 0 {
@@ -650,16 +885,12 @@ func (m *Manager) checkClusterShardDNS(ctx context.Context, host string) error {
 // transformations depend on. Only invoked in local mode; an external/remote xatu
 // already has its schema.
 func (m *Manager) migrateXatu(ctx context.Context) error {
-	args := []string{"infra", "migrate-xatu"}
+	args := m.infraActionArgs("migrate-xatu")
 	if m.cfg.Dev.XatuRef != "" {
 		args = append(args, "--xatu-ref", m.cfg.Dev.XatuRef)
 	}
 
-	//nolint:gosec // xatuCBTPath is from config and validated during discovery
-	cmd := exec.CommandContext(ctx, m.xatuCBTPath, args...)
-	cmd.Dir = m.cfg.Repos.XatuCBT
-
-	if err := executil.RunCmd(cmd, m.verbose); err != nil {
+	if err := m.runXatuCBT(ctx, args...); err != nil {
 		return fmt.Errorf("failed to run xatu migrations: %w", err)
 	}
 
@@ -677,6 +908,9 @@ func (m *Manager) startObservability(ctx context.Context) error {
 	}
 
 	generator := configgen.NewGenerator(m.log, m.cfg)
+	if m.runtime != nil {
+		generator = configgen.NewRuntimeGenerator(m.log, m.runtime)
+	}
 
 	m.log.Debug("generating observability configs")
 
@@ -684,13 +918,13 @@ func (m *Manager) startObservability(ctx context.Context) error {
 		return fmt.Errorf("failed to generate Prometheus config: %w", err)
 	}
 
-	if err := generator.GenerateGrafanaProvisioning(configsDir, m.xcliDir); err != nil {
+	if err := generator.GenerateGrafanaProvisioning(configsDir, m.userStateDir()); err != nil {
 		return fmt.Errorf("failed to generate Grafana provisioning: %w", err)
 	}
 
 	// Create and start the observability manager
 	if m.observability == nil {
-		obsMgr, err := NewObservabilityManager(m.log, m.cfg, m.xcliDir)
+		obsMgr, err := NewObservabilityManagerWithRuntime(m.log, m.cfg, m.xcliDir, m.runtime)
 		if err != nil {
 			return fmt.Errorf("failed to create observability manager: %w", err)
 		}
@@ -705,7 +939,7 @@ func (m *Manager) startObservability(ctx context.Context) error {
 func (m *Manager) stopObservability(ctx context.Context) error {
 	if m.observability == nil {
 		// Create manager just for stopping (in case containers exist from previous run)
-		obsMgr, err := NewObservabilityManager(m.log, m.cfg, m.xcliDir)
+		obsMgr, err := NewObservabilityManagerWithRuntime(m.log, m.cfg, m.xcliDir, m.runtime)
 		if err != nil {
 			return fmt.Errorf("failed to create observability manager: %w", err)
 		}
diff --git a/pkg/infrastructure/observability.go b/pkg/infrastructure/observability.go
index 3c9055a..bc56f17 100644
--- a/pkg/infrastructure/observability.go
+++ b/pkg/infrastructure/observability.go
@@ -11,17 +11,20 @@ import (
 	"strings"
 	"time"
 
+	cerrdefs "github.com/containerd/errdefs"
 	"github.com/docker/docker/api/types/container"
 	"github.com/docker/docker/api/types/filters"
 	"github.com/docker/docker/api/types/image"
 	"github.com/docker/docker/api/types/mount"
 	"github.com/docker/docker/api/types/network"
+	"github.com/docker/docker/api/types/volume"
 	"github.com/docker/docker/client"
 	"github.com/docker/go-connections/nat"
 	"github.com/sirupsen/logrus"
 
 	"github.com/ethpandaops/xcli/pkg/config"
 	"github.com/ethpandaops/xcli/pkg/constants"
+	"github.com/ethpandaops/xcli/pkg/instance"
 	"github.com/ethpandaops/xcli/pkg/ui"
 )
 
@@ -40,10 +43,18 @@ type ContainerStatus struct {
 
 // ObservabilityManager handles Prometheus and Grafana containers.
 type ObservabilityManager struct {
-	log     logrus.FieldLogger
-	docker  *client.Client
-	cfg     *config.LabConfig
-	xcliDir string
+	log       logrus.FieldLogger
+	docker    *client.Client
+	cfg       *config.LabConfig
+	xcliDir   string
+	resources observabilityResources
+}
+
+type observabilityResources struct {
+	containers map[string]string
+	volumes    map[string]string
+	labels     map[string]string
+	ports      map[string]int
 }
 
 // NewObservabilityManager creates a new observability manager.
@@ -51,20 +62,106 @@ func NewObservabilityManager(
 	log logrus.FieldLogger,
 	cfg *config.LabConfig,
 	xcliDir string,
+) (*ObservabilityManager, error) {
+	return NewObservabilityManagerWithRuntime(log, cfg, xcliDir, nil)
+}
+
+// NewObservabilityManagerWithRuntime creates a manager using instance-scoped
+// Docker resources when a runtime is supplied.
+func NewObservabilityManagerWithRuntime(
+	log logrus.FieldLogger,
+	cfg *config.LabConfig,
+	xcliDir string,
+	runtime *instance.Runtime,
 ) (*ObservabilityManager, error) {
 	dockerClient, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
 	if err != nil {
 		return nil, fmt.Errorf("failed to create Docker client: %w", err)
 	}
 
+	if runtime != nil && runtime.Manifest != nil && runtime.Manifest.StateDir != "" {
+		xcliDir = runtime.Manifest.StateDir
+	}
+
 	return &ObservabilityManager{
-		log:     log.WithField("component", "observability"),
-		docker:  dockerClient,
-		cfg:     cfg,
-		xcliDir: xcliDir,
+		log:       log.WithField("component", "observability"),
+		docker:    dockerClient,
+		cfg:       cfg,
+		xcliDir:   xcliDir,
+		resources: newObservabilityResources(cfg, runtime),
 	}, nil
 }
 
+func newObservabilityResources(
+	cfg *config.LabConfig,
+	runtime *instance.Runtime,
+) observabilityResources {
+	resources := observabilityResources{
+		containers: map[string]string{},
+		volumes:    map[string]string{},
+		labels:     map[string]string{},
+		ports: map[string]int{
+			constants.ServicePrometheus: cfg.Infrastructure.Observability.PrometheusPort,
+			constants.ServiceGrafana:    cfg.Infrastructure.Observability.GrafanaPort,
+		},
+	}
+
+	if runtime == nil {
+		return resources
+	}
+
+	dockerPlan := runtime.EffectiveDockerPlan()
+
+	for service, name := range dockerPlan.Containers {
+		if name != "" {
+			resources.containers[service] = name
+		}
+	}
+
+	for service, name := range dockerPlan.Volumes {
+		if name != "" {
+			resources.volumes[service] = name
+		}
+	}
+
+	resources.labels = copyStringMap(dockerPlan.Labels)
+
+	if runtime.Ports.Prometheus != 0 {
+		resources.ports[constants.ServicePrometheus] = runtime.Ports.Prometheus
+	}
+
+	if runtime.Ports.Grafana != 0 {
+		resources.ports[constants.ServiceGrafana] = runtime.Ports.Grafana
+	}
+
+	return resources
+}
+
+func copyStringMap(values map[string]string) map[string]string {
+	copied := make(map[string]string, len(values))
+	for key, value := range values {
+		copied[key] = value
+	}
+
+	return copied
+}
+
+func (m *ObservabilityManager) containerName(service string) string {
+	return m.resources.containers[service]
+}
+
+func (m *ObservabilityManager) volumeName(service string) string {
+	return m.resources.volumes[service]
+}
+
+func (m *ObservabilityManager) servicePort(service string) int {
+	return m.resources.ports[service]
+}
+
+func (m *ObservabilityManager) labels() map[string]string {
+	return copyStringMap(m.resources.labels)
+}
+
 // Start starts Prometheus and Grafana containers.
 func (m *ObservabilityManager) Start(ctx context.Context) error {
 	if !m.cfg.Infrastructure.Observability.Enabled {
@@ -104,8 +201,8 @@ func (m *ObservabilityManager) Start(ctx context.Context) error {
 
 	spinner.Success("Observability services are healthy")
 
-	promPort := m.cfg.Infrastructure.Observability.PrometheusPort
-	grafanaPort := m.cfg.Infrastructure.Observability.GrafanaPort
+	promPort := m.servicePort(constants.ServicePrometheus)
+	grafanaPort := m.servicePort(constants.ServiceGrafana)
 
 	m.log.WithFields(logrus.Fields{
 		"prometheus_url": fmt.Sprintf("http://localhost:%d", promPort),
@@ -115,7 +212,7 @@ func (m *ObservabilityManager) Start(ctx context.Context) error {
 	return nil
 }
 
-// Stop stops and removes observability containers.
+// Stop stops and removes observability containers while preserving volumes.
 func (m *ObservabilityManager) Stop(ctx context.Context) error {
 	if !m.cfg.Infrastructure.Observability.Enabled {
 		return nil
@@ -124,29 +221,39 @@ func (m *ObservabilityManager) Stop(ctx context.Context) error {
 	m.log.Info("stopping observability stack")
 
 	// Stop Grafana first
-	if err := m.stopContainer(ctx, constants.ContainerGrafana); err != nil {
+	if err := m.stopContainer(ctx, m.containerName(constants.ServiceGrafana)); err != nil {
 		m.log.WithError(err).Warn("failed to stop Grafana container")
 	}
 
 	// Stop Prometheus
-	if err := m.stopContainer(ctx, constants.ContainerPrometheus); err != nil {
+	if err := m.stopContainer(ctx, m.containerName(constants.ServicePrometheus)); err != nil {
 		m.log.WithError(err).Warn("failed to stop Prometheus container")
 	}
 
-	// Remove volumes if not persisting
-	if !m.cfg.Infrastructure.Volumes.Persist {
-		m.log.Debug("removing observability volumes")
+	m.log.Info("observability stack stopped")
 
-		if err := m.removeVolume(ctx, constants.VolumePrometheus); err != nil {
-			m.log.WithError(err).Warn("failed to remove Prometheus volume")
-		}
+	return nil
+}
 
-		if err := m.removeVolume(ctx, constants.VolumeGrafana); err != nil {
-			m.log.WithError(err).Warn("failed to remove Grafana volume")
-		}
+// Destroy stops observability containers and removes their volumes.
+func (m *ObservabilityManager) Destroy(ctx context.Context) error {
+	if err := m.Stop(ctx); err != nil {
+		return err
 	}
 
-	m.log.Info("observability stack stopped")
+	if !m.cfg.Infrastructure.Observability.Enabled {
+		return nil
+	}
+
+	m.log.Debug("removing observability volumes")
+
+	if err := m.removeVolume(ctx, m.volumeName(constants.ServicePrometheus)); err != nil {
+		m.log.WithError(err).Warn("failed to remove Prometheus volume")
+	}
+
+	if err := m.removeVolume(ctx, m.volumeName(constants.ServiceGrafana)); err != nil {
+		m.log.WithError(err).Warn("failed to remove Grafana volume")
+	}
 
 	return nil
 }
@@ -175,12 +282,12 @@ func (m *ObservabilityManager) StopService(ctx context.Context, service string)
 	case constants.ServicePrometheus:
 		m.log.Info("stopping Prometheus")
 
-		return m.stopContainer(ctx, constants.ContainerPrometheus)
+		return m.stopContainer(ctx, m.containerName(service))
 
 	case constants.ServiceGrafana:
 		m.log.Info("stopping Grafana")
 
-		return m.stopContainer(ctx, constants.ContainerGrafana)
+		return m.stopContainer(ctx, m.containerName(service))
 
 	default:
 		return fmt.Errorf("unknown observability service: %s", service)
@@ -193,7 +300,7 @@ func (m *ObservabilityManager) RestartService(ctx context.Context, service strin
 	case constants.ServicePrometheus:
 		m.log.Info("restarting Prometheus")
 
-		if err := m.stopContainer(ctx, constants.ContainerPrometheus); err != nil {
+		if err := m.stopContainer(ctx, m.containerName(service)); err != nil {
 			m.log.WithError(err).Debug("failed to stop Prometheus container")
 		}
 
@@ -202,7 +309,7 @@ func (m *ObservabilityManager) RestartService(ctx context.Context, service strin
 	case constants.ServiceGrafana:
 		m.log.Info("restarting Grafana")
 
-		if err := m.stopContainer(ctx, constants.ContainerGrafana); err != nil {
+		if err := m.stopContainer(ctx, m.containerName(service)); err != nil {
 			m.log.WithError(err).Debug("failed to stop Grafana container")
 		}
 
@@ -218,26 +325,26 @@ func (m *ObservabilityManager) Status(ctx context.Context) (map[string]Container
 	status := make(map[string]ContainerStatus, 2)
 
 	// Check Prometheus
-	promStatus, err := m.getContainerStatus(ctx, constants.ContainerPrometheus)
+	promStatus, err := m.getContainerStatus(ctx, constants.ServicePrometheus)
 	if err != nil {
 		promStatus = ContainerStatus{
 			Name:    constants.ServicePrometheus,
 			State:   "not found",
 			Running: false,
-			Port:    m.cfg.Infrastructure.Observability.PrometheusPort,
+			Port:    m.servicePort(constants.ServicePrometheus),
 		}
 	}
 
 	status[constants.ServicePrometheus] = promStatus
 
 	// Check Grafana
-	grafanaStatus, err := m.getContainerStatus(ctx, constants.ContainerGrafana)
+	grafanaStatus, err := m.getContainerStatus(ctx, constants.ServiceGrafana)
 	if err != nil {
 		grafanaStatus = ContainerStatus{
 			Name:    constants.ServiceGrafana,
 			State:   "not found",
 			Running: false,
-			Port:    m.cfg.Infrastructure.Observability.GrafanaPort,
+			Port:    m.servicePort(constants.ServiceGrafana),
 		}
 	}
 
@@ -257,7 +364,8 @@ func (m *ObservabilityManager) Close() error {
 
 // startPrometheus starts the Prometheus container.
 func (m *ObservabilityManager) startPrometheus(ctx context.Context) error {
-	containerName := constants.ContainerPrometheus
+	containerName := m.containerName(constants.ServicePrometheus)
+	volumeName := m.volumeName(constants.ServicePrometheus)
 
 	// Check if container already exists and is running
 	if running, err := m.isContainerRunning(ctx, containerName); err == nil && running {
@@ -278,7 +386,11 @@ func (m *ObservabilityManager) startPrometheus(ctx context.Context) error {
 
 	// Prepare config path
 	configPath := filepath.Join(m.xcliDir, "configs", "prometheus.yml")
-	promPort := m.cfg.Infrastructure.Observability.PrometheusPort
+
+	promPort := m.servicePort(constants.ServicePrometheus)
+	if err := m.ensureVolume(ctx, volumeName); err != nil {
+		return fmt.Errorf("failed to create Prometheus volume: %w", err)
+	}
 
 	// Create container
 	containerConfig := &container.Config{
@@ -291,6 +403,7 @@ func (m *ObservabilityManager) startPrometheus(ctx context.Context) error {
 		ExposedPorts: nat.PortSet{
 			"9090/tcp": struct{}{},
 		},
+		Labels: m.labels(),
 	}
 
 	hostConfig := &container.HostConfig{
@@ -300,7 +413,7 @@ func (m *ObservabilityManager) startPrometheus(ctx context.Context) error {
 		Mounts: []mount.Mount{
 			{
 				Type:   mount.TypeVolume,
-				Source: constants.VolumePrometheus,
+				Source: volumeName,
 				Target: "/prometheus",
 			},
 		},
@@ -339,7 +452,8 @@ func (m *ObservabilityManager) startPrometheus(ctx context.Context) error {
 
 // startGrafana starts the Grafana container.
 func (m *ObservabilityManager) startGrafana(ctx context.Context) error {
-	containerName := constants.ContainerGrafana
+	containerName := m.containerName(constants.ServiceGrafana)
+	volumeName := m.volumeName(constants.ServiceGrafana)
 
 	// Check if container already exists and is running
 	if running, err := m.isContainerRunning(ctx, containerName); err == nil && running {
@@ -361,7 +475,11 @@ func (m *ObservabilityManager) startGrafana(ctx context.Context) error {
 	// Prepare paths
 	provisioningPath := filepath.Join(m.xcliDir, "configs", "grafana", "provisioning")
 	dashboardsPath := filepath.Join(m.xcliDir, "configs", "grafana", "dashboards")
-	grafanaPort := m.cfg.Infrastructure.Observability.GrafanaPort
+
+	grafanaPort := m.servicePort(constants.ServiceGrafana)
+	if err := m.ensureVolume(ctx, volumeName); err != nil {
+		return fmt.Errorf("failed to create Grafana volume: %w", err)
+	}
 
 	// Create container
 	containerConfig := &container.Config{
@@ -375,6 +493,7 @@ func (m *ObservabilityManager) startGrafana(ctx context.Context) error {
 		ExposedPorts: nat.PortSet{
 			"3000/tcp": struct{}{},
 		},
+		Labels: m.labels(),
 	}
 
 	hostConfig := &container.HostConfig{
@@ -385,7 +504,7 @@ func (m *ObservabilityManager) startGrafana(ctx context.Context) error {
 		Mounts: []mount.Mount{
 			{
 				Type:   mount.TypeVolume,
-				Source: constants.VolumeGrafana,
+				Source: volumeName,
 				Target: "/var/lib/grafana",
 			},
 		},
@@ -431,8 +550,8 @@ func (m *ObservabilityManager) waitForHealth(ctx context.Context, timeout time.D
 	defer ticker.Stop()
 
 	ports := []int{
-		m.cfg.Infrastructure.Observability.PrometheusPort,
-		m.cfg.Infrastructure.Observability.GrafanaPort,
+		m.servicePort(constants.ServicePrometheus),
+		m.servicePort(constants.ServiceGrafana),
 	}
 
 	for {
@@ -502,6 +621,10 @@ func (m *ObservabilityManager) isContainerRunning(ctx context.Context, name stri
 	for _, c := range containerList {
 		for _, n := range c.Names {
 			if strings.TrimPrefix(n, "/") == name {
+				if err := validateDockerLabels("container", name, c.Labels, m.labels()); err != nil {
+					return false, err
+				}
+
 				return true, nil
 			}
 		}
@@ -549,7 +672,9 @@ func (m *ObservabilityManager) stopContainer(ctx context.Context, name string) e
 }
 
 // getContainerStatus gets the status of a container.
-func (m *ObservabilityManager) getContainerStatus(ctx context.Context, name string) (ContainerStatus, error) {
+func (m *ObservabilityManager) getContainerStatus(ctx context.Context, service string) (ContainerStatus, error) {
+	name := m.containerName(service)
+
 	containerList, err := m.docker.ContainerList(ctx, container.ListOptions{
 		All: true,
 		Filters: filters.NewArgs(
@@ -563,20 +688,11 @@ func (m *ObservabilityManager) getContainerStatus(ctx context.Context, name stri
 	for _, c := range containerList {
 		for _, n := range c.Names {
 			if strings.TrimPrefix(n, "/") == name {
-				var port int
-
-				switch name {
-				case constants.ContainerPrometheus:
-					port = m.cfg.Infrastructure.Observability.PrometheusPort
-				case constants.ContainerGrafana:
-					port = m.cfg.Infrastructure.Observability.GrafanaPort
-				}
-
 				return ContainerStatus{
-					Name:    name,
+					Name:    service,
 					State:   c.State,
 					Running: c.State == "running",
-					Port:    port,
+					Port:    m.servicePort(service),
 				}, nil
 			}
 		}
@@ -585,6 +701,49 @@ func (m *ObservabilityManager) getContainerStatus(ctx context.Context, name stri
 	return ContainerStatus{}, fmt.Errorf("container %s not found", name)
 }
 
+func (m *ObservabilityManager) ensureVolume(ctx context.Context, name string) error {
+	if name == "" {
+		return fmt.Errorf("volume name is required")
+	}
+
+	labels := m.labels()
+
+	vol, err := m.docker.VolumeInspect(ctx, name)
+	if err == nil {
+		return validateDockerLabels("volume", name, vol.Labels, labels)
+	}
+
+	if !cerrdefs.IsNotFound(err) {
+		return fmt.Errorf("failed to inspect volume %s: %w", name, err)
+	}
+
+	_, err = m.docker.VolumeCreate(ctx, volume.CreateOptions{
+		Name:   name,
+		Labels: labels,
+	})
+	if err != nil {
+		return fmt.Errorf("failed to create volume %s: %w", name, err)
+	}
+
+	return nil
+}
+
+func validateDockerLabels(resourceType, name string, actual, expected map[string]string) error {
+	for key, expectedValue := range expected {
+		if actual[key] != expectedValue {
+			return fmt.Errorf(
+				"%s %s exists without expected label %s=%s",
+				resourceType,
+				name,
+				key,
+				expectedValue,
+			)
+		}
+	}
+
+	return nil
+}
+
 // removeVolume removes a Docker volume.
 func (m *ObservabilityManager) removeVolume(ctx context.Context, name string) error {
 	if err := m.docker.VolumeRemove(ctx, name, true); err != nil {
diff --git a/pkg/infrastructure/observability_test.go b/pkg/infrastructure/observability_test.go
new file mode 100644
index 0000000..ca5b1c0
--- /dev/null
+++ b/pkg/infrastructure/observability_test.go
@@ -0,0 +1,74 @@
+package infrastructure
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
+	"github.com/ethpandaops/xcli/pkg/instance"
+	"github.com/stretchr/testify/require"
+)
+
+func TestObservabilityResourcesUseRuntimeDockerPlanAndPorts(t *testing.T) {
+	cfg := testObservabilityConfig()
+	configPath := filepath.Join(t.TempDir(), config.DefaultConfigFileName)
+	dockerPlan := instance.NewDockerPlan("alpha", configPath)
+	runtime := &instance.Runtime{
+		Docker: dockerPlan,
+		Manifest: &instance.Manifest{
+			Docker:   dockerPlan,
+			StateDir: filepath.Join(t.TempDir(), ".xcli", "instances", "alpha"),
+		},
+		Ports: instance.PortPlan{
+			Prometheus: 19090,
+			Grafana:    13000,
+		},
+	}
+
+	resources := newObservabilityResources(cfg, runtime)
+	require.Equal(t, "xcli-alpha-prometheus", resources.containers[constants.ServicePrometheus])
+	require.Equal(t, "xcli-alpha-grafana", resources.containers[constants.ServiceGrafana])
+	require.Equal(t, "xcli-alpha-prometheus-data", resources.volumes[constants.ServicePrometheus])
+	require.Equal(t, "xcli-alpha-grafana-data", resources.volumes[constants.ServiceGrafana])
+	require.Equal(t, 19090, resources.ports[constants.ServicePrometheus])
+	require.Equal(t, 13000, resources.ports[constants.ServiceGrafana])
+	require.Equal(t, "alpha", resources.labels["com.ethpandaops.xcli.instance"])
+	require.Equal(t, configPath, resources.labels["com.ethpandaops.xcli.config"])
+
+	manager := &ObservabilityManager{cfg: cfg, resources: resources}
+	require.Equal(t, "xcli-alpha-prometheus", manager.containerName(constants.ServicePrometheus))
+	require.Equal(t, "xcli-alpha-prometheus-data", manager.volumeName(constants.ServicePrometheus))
+	require.Equal(t, 19090, manager.servicePort(constants.ServicePrometheus))
+
+	labels := manager.labels()
+	labels["com.ethpandaops.xcli.instance"] = "mutated"
+	require.Equal(t, "alpha", manager.labels()["com.ethpandaops.xcli.instance"])
+}
+
+func TestInfrastructureManagerExposesRuntimeDockerContainerName(t *testing.T) {
+	cfg := testObservabilityConfig()
+	configPath := filepath.Join(t.TempDir(), config.DefaultConfigFileName)
+	dockerPlan := instance.NewDockerPlan("beta", configPath)
+	runtime := &instance.Runtime{Docker: dockerPlan}
+	manager := &Manager{cfg: cfg, runtime: runtime}
+
+	name, ok := manager.DockerContainerName(constants.ServiceGrafana)
+	require.True(t, ok)
+	require.Equal(t, "xcli-beta-grafana", name)
+
+	_, ok = manager.DockerContainerName(constants.ServiceLabBackend)
+	require.False(t, ok)
+}
+
+func testObservabilityConfig() *config.LabConfig {
+	return &config.LabConfig{
+		Infrastructure: config.InfrastructureConfig{
+			Observability: config.ObservabilityConfig{
+				Enabled:        true,
+				PrometheusPort: 9090,
+				GrafanaPort:    3000,
+			},
+		},
+	}
+}
diff --git a/pkg/infrastructure/xatu_cbt_contract_test.go b/pkg/infrastructure/xatu_cbt_contract_test.go
new file mode 100644
index 0000000..6ccdbc3
--- /dev/null
+++ b/pkg/infrastructure/xatu_cbt_contract_test.go
@@ -0,0 +1,263 @@
+package infrastructure
+
+import (
+	"context"
+	"os/exec"
+	"path/filepath"
+	"slices"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
+	"github.com/ethpandaops/xcli/pkg/instance"
+	"github.com/ethpandaops/xcli/pkg/mode"
+	"github.com/sirupsen/logrus"
+	"github.com/stretchr/testify/require"
+)
+
+func TestXatuCBTInfraCommandsUseInstanceProjectAndPortEnv(t *testing.T) {
+	labCfg := xatuCBTContractConfig(t)
+	slot0, err := instance.BuildPortPlan(labCfg, 0)
+	require.NoError(t, err)
+	slot1, err := instance.BuildPortPlan(labCfg, 1)
+	require.NoError(t, err)
+
+	require.Equal(t, 8123, slot0.ClickHouseCBT01HTTP)
+	require.Equal(t, 9000, slot0.ClickHouseCBT01TCP)
+	require.Equal(t, 8124, slot0.ClickHouseCBT02HTTP)
+	require.Equal(t, 9001, slot0.ClickHouseCBT02TCP)
+	require.Equal(t, 8125, slot0.ClickHouseXatu01HTTP)
+	require.Equal(t, 9002, slot0.ClickHouseXatu01TCP)
+	require.Equal(t, 8126, slot0.ClickHouseXatu02HTTP)
+	require.Equal(t, 9003, slot0.ClickHouseXatu02TCP)
+	require.Equal(t, 6380, slot0.Redis)
+
+	for _, tt := range []struct {
+		name       string
+		instanceID string
+		ports      instance.PortPlan
+	}{
+		{name: "slot 0 defaults", instanceID: "alpha", ports: slot0},
+		{name: "slot 1 stride", instanceID: "beta", ports: slot1},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			runtime := xatuCBTContractRuntime(t, labCfg, tt.instanceID, tt.ports)
+			manager := NewManagerWithRuntime(logrus.New(), labCfg, nil, runtime.Manifest.StateDir, runtime)
+
+			var captured *exec.Cmd
+
+			manager.runCmd = func(cmd *exec.Cmd, _ bool) error {
+				captured = cmd
+
+				return nil
+			}
+
+			commands := map[string][]string{
+				"start":   manager.infraStartArgs(constants.InfraModeLocal),
+				"stop":    manager.infraActionArgs("stop"),
+				"reset":   manager.infraActionArgs("reset"),
+				"migrate": manager.infraActionArgs("migrate-xatu"),
+			}
+
+			for commandName, args := range commands {
+				captured = nil
+
+				require.NoError(t, manager.runXatuCBT(context.Background(), args...))
+				require.NotNil(t, captured, commandName)
+
+				require.Contains(t, captured.Args, "--project-name", commandName)
+				requireArgValue(t, captured.Args, "--project-name", "xcli-"+tt.instanceID)
+				require.Equal(t, labCfg.Repos.XatuCBT, captured.Dir)
+				requirePortEnv(t, captured.Env, tt.ports)
+			}
+		})
+	}
+}
+
+func TestXatuCBTRunHelperHandsScopedCommandToRunner(t *testing.T) {
+	labCfg := xatuCBTContractConfig(t)
+	ports, err := instance.BuildPortPlan(labCfg, 1)
+	require.NoError(t, err)
+
+	runtime := xatuCBTContractRuntime(t, labCfg, "runner", ports)
+	manager := NewManagerWithRuntime(logrus.New(), labCfg, nil, runtime.Manifest.StateDir, runtime)
+
+	var captured *exec.Cmd
+
+	manager.runCmd = func(cmd *exec.Cmd, _ bool) error {
+		captured = cmd
+
+		return nil
+	}
+
+	require.NoError(t, manager.runXatuCBT(context.Background(), manager.infraActionArgs("migrate-xatu")...))
+	require.NotNil(t, captured)
+	requireArgValue(t, captured.Args, "--project-name", "xcli-runner")
+	requirePortEnv(t, captured.Env, ports)
+}
+
+func TestSafeStopDestroyAndRedisResetUseSeparateCommands(t *testing.T) {
+	labCfg := xatuCBTContractConfig(t)
+	labCfg.Infrastructure.Observability.Enabled = false
+	ports, err := instance.BuildPortPlan(labCfg, 1)
+	require.NoError(t, err)
+
+	runtime := xatuCBTContractRuntime(t, labCfg, "safety", ports)
+	stackMode, err := mode.NewMode(&config.Config{Lab: labCfg})
+	require.NoError(t, err)
+
+	manager := NewManagerWithRuntime(logrus.New(), labCfg, stackMode, runtime.Manifest.StateDir, runtime)
+
+	var captured []*exec.Cmd
+
+	manager.runCmd = func(cmd *exec.Cmd, _ bool) error {
+		captured = append(captured, cmd)
+
+		return nil
+	}
+
+	require.NoError(t, manager.Stop(context.Background()))
+	require.Len(t, captured, 1)
+	require.Equal(t, []string{
+		manager.xatuCBTPath,
+		"infra",
+		"stop",
+		"--project-name",
+		"xcli-safety",
+	}, captured[0].Args)
+	require.NotContains(t, strings.Join(captured[0].Args, " "), "reset")
+	require.NotContains(t, strings.Join(captured[0].Args, " "), "FLUSHALL")
+
+	captured = nil
+
+	require.NoError(t, manager.Destroy(context.Background()))
+	require.Len(t, captured, 1)
+	require.Equal(t, []string{
+		manager.xatuCBTPath,
+		"infra",
+		"reset",
+		"--project-name",
+		"xcli-safety",
+	}, captured[0].Args)
+
+	captured = nil
+
+	require.NoError(t, manager.ResetRedis(context.Background()))
+	require.Len(t, captured, 1)
+	require.Equal(t, []string{
+		"redis-cli",
+		"-h",
+		"127.0.0.1",
+		"-p",
+		strconv.Itoa(ports.Redis),
+		"FLUSHALL",
+	}, captured[0].Args)
+}
+
+func TestBoundsSeederUsesRuntimeRedisPort(t *testing.T) {
+	labCfg := xatuCBTContractConfig(t)
+	ports, err := instance.BuildPortPlan(labCfg, 2)
+	require.NoError(t, err)
+
+	runtime := xatuCBTContractRuntime(t, labCfg, "bounds", ports)
+	seeder := NewBoundsSeederWithRuntime(logrus.New(), runtime)
+
+	require.Equal(t, []string{
+		"-h",
+		"127.0.0.1",
+		"-p",
+		strconv.Itoa(ports.Redis),
+		"-n",
+		"3",
+		"KEYS",
+		"cbt:external:*",
+	}, seeder.localRedisArgs(3, "KEYS", "cbt:external:*"))
+}
+
+func xatuCBTContractConfig(t *testing.T) *config.LabConfig {
+	t.Helper()
+
+	root := t.TempDir()
+	cfg := config.DefaultLab()
+	cfg.Mode = constants.ModeLocal
+	cfg.Repos = config.LabReposConfig{
+		CBT:        filepath.Join(root, constants.RepoCBT),
+		XatuCBT:    filepath.Join(root, constants.RepoXatuCBT),
+		CBTAPI:     filepath.Join(root, constants.RepoCBTAPI),
+		LabBackend: filepath.Join(root, constants.RepoLabBackend),
+		Lab:        filepath.Join(root, constants.RepoLab),
+	}
+	cfg.Infrastructure.ClickHouse.Xatu.Mode = constants.InfraModeLocal
+	cfg.Infrastructure.ClickHouse.Xatu.ExternalURL = ""
+
+	return cfg
+}
+
+func xatuCBTContractRuntime(
+	t *testing.T,
+	labCfg *config.LabConfig,
+	instanceID string,
+	ports instance.PortPlan,
+) *instance.Runtime {
+	t.Helper()
+
+	root := t.TempDir()
+	configPath := filepath.Join(root, config.DefaultConfigFileName)
+	docker := instance.NewDockerPlan(instanceID, configPath)
+
+	return &instance.Runtime{
+		LabConfig:  labCfg,
+		InstanceID: instanceID,
+		Ports:      ports,
+		Docker:     docker,
+		Manifest: &instance.Manifest{
+			InstanceID: instanceID,
+			ConfigPath: configPath,
+			StateDir:   instance.InstanceStateDir(root, instanceID),
+			Ports:      ports,
+			Docker:     docker,
+		},
+	}
+}
+
+func requireArgValue(t *testing.T, args []string, flag string, want string) {
+	t.Helper()
+
+	index := slices.Index(args, flag)
+	require.NotEqual(t, -1, index, "missing %s in %v", flag, args)
+	require.Greater(t, len(args), index+1)
+	require.Equal(t, want, args[index+1])
+}
+
+func requirePortEnv(t *testing.T, env []string, ports instance.PortPlan) {
+	t.Helper()
+
+	values := envMap(env)
+	require.Equal(t, strconv.Itoa(ports.ClickHouseCBT01HTTP), values["CLICKHOUSE_CBT_01_HTTP_PORT"])
+	require.Equal(t, strconv.Itoa(ports.ClickHouseCBT01TCP), values["CLICKHOUSE_CBT_01_NATIVE_PORT"])
+	require.Equal(t, strconv.Itoa(ports.ClickHouseCBT02HTTP), values["CLICKHOUSE_CBT_02_HTTP_PORT"])
+	require.Equal(t, strconv.Itoa(ports.ClickHouseCBT02TCP), values["CLICKHOUSE_CBT_02_NATIVE_PORT"])
+	require.Equal(t, strconv.Itoa(ports.ClickHouseXatu01HTTP), values["CLICKHOUSE_XATU_01_HTTP_PORT"])
+	require.Equal(t, strconv.Itoa(ports.ClickHouseXatu01TCP), values["CLICKHOUSE_XATU_01_NATIVE_PORT"])
+	require.Equal(t, strconv.Itoa(ports.ClickHouseXatu02HTTP), values["CLICKHOUSE_XATU_02_HTTP_PORT"])
+	require.Equal(t, strconv.Itoa(ports.ClickHouseXatu02TCP), values["CLICKHOUSE_XATU_02_NATIVE_PORT"])
+	require.Equal(t, strconv.Itoa(ports.Redis), values["REDIS_PORT"])
+
+	for _, name := range instance.XatuCBTBindAddressVars() {
+		require.Equal(t, "127.0.0.1", values[name])
+	}
+}
+
+func envMap(env []string) map[string]string {
+	values := make(map[string]string, len(env))
+	for _, entry := range env {
+		name, value, found := strings.Cut(entry, "=")
+		if found {
+			values[name] = value
+		}
+	}
+
+	return values
+}
diff --git a/pkg/instance/allocator.go b/pkg/instance/allocator.go
new file mode 100644
index 0000000..f629ec0
--- /dev/null
+++ b/pkg/instance/allocator.go
@@ -0,0 +1,267 @@
+package instance
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"sort"
+	"syscall"
+	"time"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+)
+
+const defaultMaxAllocationSlots = 100
+
+const reservationGracePeriod = 10 * time.Minute
+
+// Allocator assigns preferred port slots under the global registry lock.
+type Allocator struct {
+	registry   *Registry
+	lockPath   string
+	probePorts bool
+	maxSlots   int
+}
+
+// NewAllocator returns an allocator using the given registry.
+func NewAllocator(registry *Registry, probePorts bool) *Allocator {
+	lockPath := ""
+	if registry != nil && registry.dir != "" {
+		lockPath = filepath.Join(filepath.Dir(registry.dir), "registry.lock")
+	}
+
+	return &Allocator{
+		registry:   registry,
+		lockPath:   lockPath,
+		probePorts: probePorts,
+		maxSlots:   defaultMaxAllocationSlots,
+	}
+}
+
+// AllocationRequest describes one port allocation.
+type AllocationRequest struct {
+	InstanceID string
+	LabConfig  *config.LabConfig
+	Manifest   *Manifest
+	Claim      bool
+}
+
+// Allocate fills a PortPlan. If Claim is true, it writes a reserved manifest
+// while still holding the registry lock so concurrent allocators see the slot.
+func (a *Allocator) Allocate(ctx context.Context, req AllocationRequest) (PortPlan, error) {
+	if req.InstanceID == "" {
+		return PortPlan{}, fmt.Errorf("instance id is required")
+	}
+
+	if req.LabConfig == nil {
+		return PortPlan{}, fmt.Errorf("lab config is required")
+	}
+
+	if a.registry == nil {
+		var err error
+
+		a.registry, err = DefaultRegistry()
+		if err != nil {
+			return PortPlan{}, err
+		}
+	}
+
+	if a.lockPath == "" {
+		lockPath, err := DefaultRegistryLockPath()
+		if err != nil {
+			return PortPlan{}, err
+		}
+
+		a.lockPath = lockPath
+	}
+
+	unlock, err := lockFile(a.lockPath)
+	if err != nil {
+		return PortPlan{}, err
+	}
+	defer unlock()
+
+	activePorts, err := a.activeRegistryPorts(req.InstanceID)
+	if err != nil {
+		return PortPlan{}, err
+	}
+
+	var rejected []string
+
+	for slot := 0; slot < a.maxSlots; slot++ {
+		if err := ctx.Err(); err != nil {
+			return PortPlan{}, err
+		}
+
+		plan, planErr := BuildPortPlan(req.LabConfig, slot)
+		if planErr != nil {
+			return PortPlan{}, planErr
+		}
+
+		if overlap := overlapWithSet(plan.AllPorts(), activePorts); len(overlap) > 0 {
+			rejected = append(rejected, fmt.Sprintf("slot %d registry ports in use: %v", slot, overlap))
+
+			continue
+		}
+
+		if a.probePorts {
+			boundPorts := boundPorts(plan.AllPorts())
+			if len(boundPorts) > 0 {
+				rejected = append(rejected, fmt.Sprintf("slot %d bound ports in use: %v", slot, boundPorts))
+
+				continue
+			}
+		}
+
+		if req.Claim {
+			if req.Manifest == nil {
+				return PortPlan{}, fmt.Errorf("manifest is required to claim allocated ports")
+			}
+
+			req.Manifest.Ports = plan
+			req.Manifest.Status = StatusReserved
+
+			req.Manifest.Docker = NewDockerPlan(req.InstanceID, req.Manifest.ConfigPath)
+			if err := a.registry.Save(req.Manifest); err != nil {
+				return PortPlan{}, err
+			}
+		}
+
+		return plan, nil
+	}
+
+	return PortPlan{}, fmt.Errorf("no available port slot found after %d slots (%v)", a.maxSlots, rejected)
+}
+
+// DefaultRegistryLockPath returns ~/.xcli/lab/registry.lock.
+func DefaultRegistryLockPath() (string, error) {
+	homeDir, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("failed to get home directory: %w", err)
+	}
+
+	return filepath.Join(homeDir, ".xcli", "lab", "registry.lock"), nil
+}
+
+func (a *Allocator) activeRegistryPorts(instanceID string) (map[int]bool, error) {
+	manifests, err := a.registry.LoadAll()
+	if err != nil {
+		return nil, err
+	}
+
+	ports := make(map[int]bool)
+
+	for _, manifest := range manifests {
+		if manifest.InstanceID == instanceID || !isActiveManifest(manifest) {
+			continue
+		}
+
+		for _, port := range manifest.Ports.AllPorts() {
+			ports[port] = true
+		}
+	}
+
+	return ports, nil
+}
+
+func isActiveManifest(manifest *Manifest) bool {
+	if manifest == nil {
+		return false
+	}
+
+	switch manifest.Status {
+	case StatusRunning:
+		return true
+	case StatusReserved:
+		if reservationHasBacking(manifest) {
+			return true
+		}
+
+		if manifest.UpdatedAt.IsZero() {
+			return false
+		}
+
+		return time.Since(manifest.UpdatedAt) <= reservationGracePeriod
+	default:
+		return false
+	}
+}
+
+func reservationHasBacking(manifest *Manifest) bool {
+	for _, pid := range manifest.PIDs {
+		if pid > 0 && defaultPIDAlive(pid) {
+			return true
+		}
+	}
+
+	for _, port := range manifest.Ports.AllPorts() {
+		if port > 0 && !isPortFree(port) {
+			return true
+		}
+	}
+
+	return false
+}
+
+func lockFile(path string) (func(), error) {
+	if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+		return nil, fmt.Errorf("failed to create lock directory: %w", err)
+	}
+
+	file, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0600)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open lock file: %w", err)
+	}
+
+	if err := syscall.Flock(int(file.Fd()), syscall.LOCK_EX); err != nil {
+		_ = file.Close()
+
+		return nil, fmt.Errorf("failed to lock registry: %w", err)
+	}
+
+	return func() {
+		_ = syscall.Flock(int(file.Fd()), syscall.LOCK_UN)
+		_ = file.Close()
+	}, nil
+}
+
+func boundPorts(ports []int) []int {
+	bound := make([]int, 0)
+
+	for _, port := range ports {
+		if !isPortFree(port) {
+			bound = append(bound, port)
+		}
+	}
+
+	sort.Ints(bound)
+
+	return bound
+}
+
+func isPortFree(port int) bool {
+	listener, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", port))
+	if err != nil {
+		return false
+	}
+
+	_ = listener.Close()
+
+	return true
+}
+
+func overlapWithSet(ports []int, used map[int]bool) []int {
+	overlap := make([]int, 0)
+
+	for _, port := range ports {
+		if used[port] {
+			overlap = append(overlap, port)
+		}
+	}
+
+	sort.Ints(overlap)
+
+	return overlap
+}
diff --git a/pkg/instance/allocator_test.go b/pkg/instance/allocator_test.go
new file mode 100644
index 0000000..9779a4c
--- /dev/null
+++ b/pkg/instance/allocator_test.go
@@ -0,0 +1,153 @@
+package instance
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	xcligit "github.com/ethpandaops/xcli/pkg/git"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAllocatorClaimsDistinctNonOverlappingSlots(t *testing.T) {
+	registry := NewRegistry(filepath.Join(t.TempDir(), "lab", "instances"))
+	allocator := NewAllocator(registry, false)
+	labCfg := config.DefaultLab()
+
+	first := testManifest(t, "first")
+	firstPlan, err := allocator.Allocate(context.Background(), AllocationRequest{
+		InstanceID: first.InstanceID,
+		LabConfig:  labCfg,
+		Manifest:   first,
+		Claim:      true,
+	})
+	require.NoError(t, err)
+	require.Equal(t, 0, firstPlan.Slot)
+
+	second := testManifest(t, "second")
+	secondPlan, err := allocator.Allocate(context.Background(), AllocationRequest{
+		InstanceID: second.InstanceID,
+		LabConfig:  labCfg,
+		Manifest:   second,
+		Claim:      true,
+	})
+	require.NoError(t, err)
+	require.Equal(t, 1, secondPlan.Slot)
+	require.Empty(t, firstPlan.Overlaps(secondPlan))
+
+	loaded, err := registry.Load("first")
+	require.NoError(t, err)
+	require.Equal(t, StatusReserved, loaded.Status)
+	require.Equal(t, firstPlan, loaded.Ports)
+}
+
+func TestAllocatorStoppedManifestDoesNotHogSlot(t *testing.T) {
+	registry := NewRegistry(filepath.Join(t.TempDir(), "lab", "instances"))
+	allocator := NewAllocator(registry, false)
+	labCfg := config.DefaultLab()
+
+	stopped := testManifest(t, "stopped")
+	stoppedPlan, err := BuildPortPlan(labCfg, 0)
+	require.NoError(t, err)
+
+	stopped.Ports = stoppedPlan
+	stopped.Status = StatusStopped
+	require.NoError(t, registry.Save(stopped))
+
+	next := testManifest(t, "next")
+	nextPlan, err := allocator.Allocate(context.Background(), AllocationRequest{
+		InstanceID: next.InstanceID,
+		LabConfig:  labCfg,
+		Manifest:   next,
+		Claim:      true,
+	})
+	require.NoError(t, err)
+	require.Equal(t, 0, nextPlan.Slot)
+}
+
+func TestAllocatorOldReservedManifestDoesNotHogSlot(t *testing.T) {
+	registry := NewRegistry(filepath.Join(t.TempDir(), "lab", "instances"))
+	allocator := NewAllocator(registry, false)
+	labCfg := config.DefaultLab()
+
+	reserved := testManifest(t, "reserved")
+	reserved.Ports = PortPlan{LabBackend: 35080}
+	reserved.Status = StatusReserved
+	reserved.UpdatedAt = time.Now().Add(-reservationGracePeriod - time.Minute)
+	require.NoError(t, writeJSONAtomic(registry.ManifestPath(reserved.InstanceID), reserved))
+
+	next := testManifest(t, "next")
+	nextPlan, err := allocator.Allocate(context.Background(), AllocationRequest{
+		InstanceID: next.InstanceID,
+		LabConfig:  labCfg,
+		Manifest:   next,
+		Claim:      true,
+	})
+	require.NoError(t, err)
+	require.Equal(t, 0, nextPlan.Slot)
+}
+
+func TestAllocatorSkipsBoundPorts(t *testing.T) {
+	port, closeListener := listenOnFreePort(t, 18080, 19080)
+	if port == 0 {
+		t.Skip("localhost bind is not permitted in this environment")
+	}
+	defer closeListener()
+
+	registry := NewRegistry(filepath.Join(t.TempDir(), "lab", "instances"))
+	allocator := NewAllocator(registry, true)
+	labCfg := config.DefaultLab()
+	labCfg.Ports.LabBackend = port
+
+	manifest := testManifest(t, "bound")
+	plan, err := allocator.Allocate(context.Background(), AllocationRequest{
+		InstanceID: manifest.InstanceID,
+		LabConfig:  labCfg,
+		Manifest:   manifest,
+		Claim:      true,
+	})
+	require.NoError(t, err)
+	require.NotZero(t, plan.Slot)
+}
+
+func testManifest(t *testing.T, id string) *Manifest {
+	t.Helper()
+
+	rootDir := t.TempDir()
+	configPath := filepath.Join(rootDir, config.DefaultConfigFileName)
+
+	return &Manifest{
+		SchemaVersion: SchemaVersion,
+		InstanceID:    id,
+		Status:        StatusCreated,
+		RootDir:       rootDir,
+		ConfigPath:    configPath,
+		OverridesPath: filepath.Join(rootDir, ".cbt-overrides.yaml"),
+		StateDir:      InstanceStateDir(rootDir, id),
+		Repos:         map[string]xcligit.RepoVersion{},
+		Docker:        NewDockerPlan(id, configPath),
+		PIDs:          map[string]int{},
+		URLs:          map[string]string{},
+	}
+}
+
+func listenOnFreePort(t *testing.T, start int, end int) (int, func()) {
+	t.Helper()
+
+	for port := start; port < end; port++ {
+		listener, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", port))
+		if err != nil {
+			continue
+		}
+
+		return port, func() {
+			_ = listener.Close()
+		}
+	}
+
+	return 0, func() {}
+}
diff --git a/pkg/instance/identity.go b/pkg/instance/identity.go
new file mode 100644
index 0000000..15cddce
--- /dev/null
+++ b/pkg/instance/identity.go
@@ -0,0 +1,52 @@
+package instance
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/workspace"
+)
+
+const idHashLength = 16
+
+var invalidDockerNameChars = regexp.MustCompile(`[^a-z0-9_-]+`)
+
+// ResolveID returns the selected instance id. CLI override wins over config,
+// then the deterministic config-root/hash id is used.
+func ResolveID(ws *workspace.Workspace, labCfg *config.LabConfig, cliOverride string) (string, error) {
+	override := strings.TrimSpace(cliOverride)
+	if override == "" && labCfg != nil {
+		override = strings.TrimSpace(labCfg.Instance.ID)
+	}
+
+	if override != "" {
+		return SanitizeID(override)
+	}
+
+	if ws == nil {
+		return "", fmt.Errorf("workspace is required to derive instance id")
+	}
+
+	sum := sha256.Sum256([]byte(ws.ConfigPath))
+	hash := hex.EncodeToString(sum[:])[:idHashLength]
+
+	return SanitizeID(fmt.Sprintf("%s-%s", filepath.Base(ws.RootDir), hash))
+}
+
+// SanitizeID converts arbitrary input into a docker-name-safe id.
+func SanitizeID(id string) (string, error) {
+	id = strings.ToLower(strings.TrimSpace(id))
+	id = invalidDockerNameChars.ReplaceAllString(id, "-")
+	id = strings.Trim(id, "-_")
+
+	if id == "" {
+		return "", fmt.Errorf("instance id is empty after sanitization")
+	}
+
+	return id, nil
+}
diff --git a/pkg/instance/identity_test.go b/pkg/instance/identity_test.go
new file mode 100644
index 0000000..c3ef6fd
--- /dev/null
+++ b/pkg/instance/identity_test.go
@@ -0,0 +1,64 @@
+package instance
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/workspace"
+	"github.com/stretchr/testify/require"
+)
+
+const testConfigPath = "/tmp/.xcli.yaml"
+
+func TestResolveIDDerivesDeterministicConfigPathID(t *testing.T) {
+	rootDir := t.TempDir()
+	configPath := filepath.Join(rootDir, config.DefaultConfigFileName)
+	ws := &workspace.Workspace{RootDir: rootDir, ConfigPath: configPath}
+
+	got, err := ResolveID(ws, &config.LabConfig{}, "")
+	require.NoError(t, err)
+
+	sum := sha256.Sum256([]byte(configPath))
+	want := fmt.Sprintf("%s-%s", filepath.Base(rootDir), hex.EncodeToString(sum[:])[:idHashLength])
+	require.Equal(t, want, got)
+	require.Len(t, strings.TrimPrefix(got, filepath.Base(rootDir)+"-"), 16)
+
+	gotAgain, err := ResolveID(ws, &config.LabConfig{}, "")
+	require.NoError(t, err)
+	require.Equal(t, got, gotAgain)
+}
+
+func TestResolveIDConfigOverride(t *testing.T) {
+	ws := &workspace.Workspace{RootDir: t.TempDir(), ConfigPath: testConfigPath}
+	labCfg := &config.LabConfig{
+		Instance: config.LabInstanceConfig{ID: "My Lab.Instance!"},
+	}
+
+	got, err := ResolveID(ws, labCfg, "")
+	require.NoError(t, err)
+	require.Equal(t, "my-lab-instance", got)
+}
+
+func TestResolveIDCLIOverrideWins(t *testing.T) {
+	ws := &workspace.Workspace{RootDir: t.TempDir(), ConfigPath: testConfigPath}
+	labCfg := &config.LabConfig{
+		Instance: config.LabInstanceConfig{ID: "from-config"},
+	}
+
+	got, err := ResolveID(ws, labCfg, "from-cli")
+	require.NoError(t, err)
+	require.Equal(t, "from-cli", got)
+}
+
+func TestResolveIDRejectsEmptySanitizedOverride(t *testing.T) {
+	ws := &workspace.Workspace{RootDir: t.TempDir(), ConfigPath: testConfigPath}
+
+	_, err := ResolveID(ws, &config.LabConfig{}, "!!!")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "instance id is empty")
+}
diff --git a/pkg/instance/manifest.go b/pkg/instance/manifest.go
new file mode 100644
index 0000000..91f88ab
--- /dev/null
+++ b/pkg/instance/manifest.go
@@ -0,0 +1,227 @@
+package instance
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
+	xcligit "github.com/ethpandaops/xcli/pkg/git"
+	"github.com/ethpandaops/xcli/pkg/workspace"
+)
+
+const (
+	// SchemaVersion is the manifest schema version written by this xcli build.
+	SchemaVersion = 1
+
+	StatusCreated  = "created"
+	StatusReserved = "reserved"
+	StatusRunning  = "running"
+	StatusStopped  = "stopped"
+	StatusStale    = "stale"
+)
+
+// Manifest records discoverable state for one xcli lab instance.
+type Manifest struct {
+	SchemaVersion int                            `json:"schemaVersion"`
+	InstanceID    string                         `json:"instanceId"`
+	Status        string                         `json:"status"`
+	RootDir       string                         `json:"rootDir"`
+	ConfigPath    string                         `json:"configPath"`
+	OverridesPath string                         `json:"overridesPath"`
+	StateDir      string                         `json:"stateDir"`
+	Mode          string                         `json:"mode"`
+	Repos         map[string]xcligit.RepoVersion `json:"repos"`
+	Ports         PortPlan                       `json:"ports"`
+	Docker        DockerPlan                     `json:"docker"`
+	PIDs          map[string]int                 `json:"pids"`
+	URLs          map[string]string              `json:"urls"`
+	CreatedAt     time.Time                      `json:"createdAt"`
+	UpdatedAt     time.Time                      `json:"updatedAt"`
+	LastError     string                         `json:"lastError,omitempty"`
+}
+
+// PortPlan is the complete set of host ports managed for an instance.
+type PortPlan struct {
+	Slot                 int                        `json:"slot"`
+	LabBackend           int                        `json:"labBackend,omitempty"`
+	LabFrontend          int                        `json:"labFrontend,omitempty"`
+	CBTBase              int                        `json:"cbtBase,omitempty"`
+	CBTAPIBase           int                        `json:"cbtApiBase,omitempty"`
+	CBTFrontendBase      int                        `json:"cbtFrontendBase,omitempty"`
+	CBTMetricsBase       int                        `json:"cbtMetricsBase,omitempty"`
+	CBTAPIMetricsBase    int                        `json:"cbtApiMetricsBase,omitempty"`
+	ClickHouseXatu01HTTP int                        `json:"clickhouseXatu01Http,omitempty"`
+	ClickHouseXatu01TCP  int                        `json:"clickhouseXatu01Tcp,omitempty"`
+	ClickHouseXatu02HTTP int                        `json:"clickhouseXatu02Http,omitempty"`
+	ClickHouseXatu02TCP  int                        `json:"clickhouseXatu02Tcp,omitempty"`
+	ClickHouseCBT01HTTP  int                        `json:"clickhouseCbt01Http,omitempty"`
+	ClickHouseCBT01TCP   int                        `json:"clickhouseCbt01Tcp,omitempty"`
+	ClickHouseCBT02HTTP  int                        `json:"clickhouseCbt02Http,omitempty"`
+	ClickHouseCBT02TCP   int                        `json:"clickhouseCbt02Tcp,omitempty"`
+	Redis                int                        `json:"redis,omitempty"`
+	Prometheus           int                        `json:"prometheus,omitempty"`
+	Grafana              int                        `json:"grafana,omitempty"`
+	CommandCenter        int                        `json:"commandCenter,omitempty"`
+	Networks             map[string]NetworkPortPlan `json:"networks,omitempty"`
+}
+
+// NetworkPortPlan records derived per-network application and metrics ports.
+type NetworkPortPlan struct {
+	CBT           int `json:"cbt,omitempty"`
+	CBTAPI        int `json:"cbtApi,omitempty"`
+	CBTFrontend   int `json:"cbtFrontend,omitempty"`
+	CBTMetrics    int `json:"cbtMetrics,omitempty"`
+	CBTAPIMetrics int `json:"cbtApiMetrics,omitempty"`
+}
+
+// DockerPlan records deterministic Docker names for one instance.
+type DockerPlan struct {
+	ProjectName string            `json:"projectName"`
+	Containers  map[string]string `json:"containers"`
+	Volumes     map[string]string `json:"volumes"`
+	Labels      map[string]string `json:"labels"`
+}
+
+// NewManifest builds a manifest shell for the resolved lab workspace.
+func NewManifest(
+	ctx context.Context,
+	ws *workspace.Workspace,
+	labCfg *config.LabConfig,
+	cliInstanceID string,
+) (*Manifest, error) {
+	if ws == nil {
+		return nil, fmt.Errorf("workspace is required")
+	}
+
+	if labCfg == nil {
+		return nil, fmt.Errorf("lab config is required")
+	}
+
+	instanceID, err := ResolveID(ws, labCfg, cliInstanceID)
+	if err != nil {
+		return nil, err
+	}
+
+	now := time.Now().UTC()
+	repos, snapshotErr := SnapshotLabRepos(ctx, labCfg)
+
+	lastError := ""
+	if snapshotErr != nil {
+		lastError = snapshotErr.Error()
+	}
+
+	return &Manifest{
+		SchemaVersion: SchemaVersion,
+		InstanceID:    instanceID,
+		Status:        StatusCreated,
+		RootDir:       ws.RootDir,
+		ConfigPath:    ws.ConfigPath,
+		OverridesPath: ws.OverridesPath,
+		StateDir:      InstanceStateDir(ws.RootDir, instanceID),
+		Mode:          labCfg.Mode,
+		Repos:         repos,
+		Ports:         PortPlan{},
+		Docker:        NewDockerPlan(instanceID, ws.ConfigPath),
+		PIDs:          map[string]int{},
+		URLs:          map[string]string{},
+		CreatedAt:     now,
+		UpdatedAt:     now,
+		LastError:     lastError,
+	}, nil
+}
+
+// SnapshotLabRepos snapshots each configured lab repository without fetching.
+func SnapshotLabRepos(ctx context.Context, labCfg *config.LabConfig) (map[string]xcligit.RepoVersion, error) {
+	repoPaths := labCfg.Repos.Map()
+
+	repos := make(map[string]xcligit.RepoVersion, len(repoPaths))
+	errs := make([]string, 0)
+
+	for name, path := range repoPaths {
+		version, err := xcligit.Snapshot(ctx, path)
+		if err != nil {
+			version.Path = path
+
+			errs = append(errs, fmt.Sprintf("%s: %v", name, err))
+		}
+
+		repos[name] = version
+	}
+
+	if len(errs) > 0 {
+		return repos, errors.New(strings.Join(errs, "; "))
+	}
+
+	return repos, nil
+}
+
+// InstanceStateDir returns the per-instance state directory under a root.
+func InstanceStateDir(rootDir, instanceID string) string {
+	return filepath.Join(rootDir, ".xcli", "instances", instanceID)
+}
+
+// LocalManifestPath returns the root-local manifest copy path.
+func LocalManifestPath(rootDir, instanceID string) string {
+	return filepath.Join(InstanceStateDir(rootDir, instanceID), "manifest.json")
+}
+
+// NewDockerPlan returns deterministic Docker names for this instance.
+func NewDockerPlan(instanceID, configPath string) DockerPlan {
+	labels := map[string]string{
+		DockerLabelInstance: instanceID,
+		DockerLabelConfig:   configPath,
+	}
+
+	containers := map[string]string{
+		constants.ServicePrometheus: fmt.Sprintf("xcli-%s-%s", instanceID, constants.ServicePrometheus),
+		constants.ServiceGrafana:    fmt.Sprintf("xcli-%s-%s", instanceID, constants.ServiceGrafana),
+	}
+
+	volumes := map[string]string{
+		constants.ServicePrometheus: fmt.Sprintf("xcli-%s-%s-data", instanceID, constants.ServicePrometheus),
+		constants.ServiceGrafana:    fmt.Sprintf("xcli-%s-%s-data", instanceID, constants.ServiceGrafana),
+	}
+
+	return DockerPlan{
+		ProjectName: fmt.Sprintf("xcli-%s", instanceID),
+		Containers:  containers,
+		Volumes:     volumes,
+		Labels:      labels,
+	}
+}
+
+// EffectiveDockerPlan returns the manifest Docker plan with deterministic
+// fallbacks filled from the instance id and config path.
+func (m *Manifest) EffectiveDockerPlan() DockerPlan {
+	if m == nil {
+		return DockerPlan{}
+	}
+
+	return m.Docker.WithDefaults(NewDockerPlan(m.InstanceID, m.ConfigPath))
+}
+
+// WithDefaults fills missing Docker plan fields from fallback.
+func (p DockerPlan) WithDefaults(fallback DockerPlan) DockerPlan {
+	if p.ProjectName == "" {
+		p.ProjectName = fallback.ProjectName
+	}
+
+	if len(p.Containers) == 0 {
+		p.Containers = fallback.Containers
+	}
+
+	if len(p.Volumes) == 0 {
+		p.Volumes = fallback.Volumes
+	}
+
+	if len(p.Labels) == 0 {
+		p.Labels = fallback.Labels
+	}
+
+	return p
+}
diff --git a/pkg/instance/manifest_test.go b/pkg/instance/manifest_test.go
new file mode 100644
index 0000000..7240625
--- /dev/null
+++ b/pkg/instance/manifest_test.go
@@ -0,0 +1,87 @@
+package instance
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
+	"github.com/ethpandaops/xcli/pkg/workspace"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewManifestCapturesWorkspaceReposAndDockerPlan(t *testing.T) {
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not available")
+	}
+
+	rootDir := t.TempDir()
+	configPath := filepath.Join(rootDir, config.DefaultConfigFileName)
+	repoDir := initTestRepo(t)
+
+	ws := &workspace.Workspace{
+		RootDir:       rootDir,
+		ConfigPath:    configPath,
+		OverridesPath: filepath.Join(rootDir, constants.CBTOverridesFile),
+		StateDir:      filepath.Join(rootDir, ".xcli"),
+		ConfigExists:  true,
+	}
+	labCfg := &config.LabConfig{
+		Instance: config.LabInstanceConfig{ID: "Example One"},
+		Mode:     constants.ModeHybrid,
+		Repos: config.LabReposConfig{
+			CBT:        repoDir,
+			XatuCBT:    repoDir,
+			CBTAPI:     repoDir,
+			LabBackend: repoDir,
+			Lab:        repoDir,
+		},
+	}
+
+	manifest, err := NewManifest(context.Background(), ws, labCfg, "")
+	require.NoError(t, err)
+
+	require.Equal(t, SchemaVersion, manifest.SchemaVersion)
+	require.Equal(t, "example-one", manifest.InstanceID)
+	require.Equal(t, StatusCreated, manifest.Status)
+	require.Equal(t, rootDir, manifest.RootDir)
+	require.Equal(t, configPath, manifest.ConfigPath)
+	require.Equal(t, InstanceStateDir(rootDir, "example-one"), manifest.StateDir)
+	require.Equal(t, constants.ModeHybrid, manifest.Mode)
+	require.Equal(t, "xcli-example-one", manifest.Docker.ProjectName)
+	require.Equal(t, "example-one", manifest.Docker.Labels["com.ethpandaops.xcli.instance"])
+	require.NotEmpty(t, manifest.Repos[constants.RepoCBT].Commit)
+	require.False(t, manifest.CreatedAt.IsZero())
+	require.False(t, manifest.UpdatedAt.IsZero())
+	require.Empty(t, manifest.LastError)
+}
+
+func initTestRepo(t *testing.T) string {
+	t.Helper()
+
+	repoDir := t.TempDir()
+	runInstanceGit(t, repoDir, "init")
+	runInstanceGit(t, repoDir, "config", "user.email", "test@example.com")
+	runInstanceGit(t, repoDir, "config", "user.name", "Test User")
+	runInstanceGit(t, repoDir, "config", "commit.gpgsign", "false")
+
+	require.NoError(t, os.WriteFile(filepath.Join(repoDir, "README.md"), []byte("hello\n"), 0644))
+	runInstanceGit(t, repoDir, "add", "README.md")
+	runInstanceGit(t, repoDir, "commit", "-m", "initial")
+
+	return repoDir
+}
+
+func runInstanceGit(t *testing.T, repoDir string, args ...string) {
+	t.Helper()
+
+	cmd := exec.Command("git", args...)
+	cmd.Dir = repoDir
+
+	out, err := cmd.CombinedOutput()
+	require.NoError(t, err, strings.TrimSpace(string(out)))
+}
diff --git a/pkg/instance/ports.go b/pkg/instance/ports.go
new file mode 100644
index 0000000..1a50414
--- /dev/null
+++ b/pkg/instance/ports.go
@@ -0,0 +1,389 @@
+package instance
+
+import (
+	"fmt"
+	"sort"
+	"strconv"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
+)
+
+const (
+	portStride = 1000
+
+	DefaultCommandCenterPort = constants.DefaultCommandCenterPort
+)
+
+var xatuCBTBindAddressVars = []string{
+	"CLICKHOUSE_CBT_01_HTTP_ADDRESS",
+	"CLICKHOUSE_CBT_01_NATIVE_ADDRESS",
+	"CLICKHOUSE_CBT_02_HTTP_ADDRESS",
+	"CLICKHOUSE_CBT_02_NATIVE_ADDRESS",
+	"CLICKHOUSE_XATU_01_HTTP_ADDRESS",
+	"CLICKHOUSE_XATU_01_NATIVE_ADDRESS",
+	"CLICKHOUSE_XATU_02_HTTP_ADDRESS",
+	"CLICKHOUSE_XATU_02_NATIVE_ADDRESS",
+	"REDIS_ADDRESS",
+}
+
+var namedPortFields = []struct {
+	name string
+	get  func(PortPlan) int
+}{
+	{"lab-backend", func(p PortPlan) int { return p.LabBackend }},
+	{"lab-frontend", func(p PortPlan) int { return p.LabFrontend }},
+	{"command-center", func(p PortPlan) int { return p.CommandCenter }},
+	{"clickhouse-cbt-01-http", func(p PortPlan) int { return p.ClickHouseCBT01HTTP }},
+	{"clickhouse-cbt-01-native", func(p PortPlan) int { return p.ClickHouseCBT01TCP }},
+	{"clickhouse-cbt-02-http", func(p PortPlan) int { return p.ClickHouseCBT02HTTP }},
+	{"clickhouse-cbt-02-native", func(p PortPlan) int { return p.ClickHouseCBT02TCP }},
+	{"clickhouse-xatu-01-http", func(p PortPlan) int { return p.ClickHouseXatu01HTTP }},
+	{"clickhouse-xatu-01-native", func(p PortPlan) int { return p.ClickHouseXatu01TCP }},
+	{"clickhouse-xatu-02-http", func(p PortPlan) int { return p.ClickHouseXatu02HTTP }},
+	{"clickhouse-xatu-02-native", func(p PortPlan) int { return p.ClickHouseXatu02TCP }},
+	{"redis", func(p PortPlan) int { return p.Redis }},
+	{"prometheus", func(p PortPlan) int { return p.Prometheus }},
+	{"grafana", func(p PortPlan) int { return p.Grafana }},
+}
+
+var xatuCBTPortEnvFields = []struct {
+	name string
+	get  func(PortPlan) int
+}{
+	{"CLICKHOUSE_CBT_01_HTTP_PORT", func(p PortPlan) int { return p.ClickHouseCBT01HTTP }},
+	{"CLICKHOUSE_CBT_01_NATIVE_PORT", func(p PortPlan) int { return p.ClickHouseCBT01TCP }},
+	{"CLICKHOUSE_CBT_02_HTTP_PORT", func(p PortPlan) int { return p.ClickHouseCBT02HTTP }},
+	{"CLICKHOUSE_CBT_02_NATIVE_PORT", func(p PortPlan) int { return p.ClickHouseCBT02TCP }},
+	{"CLICKHOUSE_XATU_01_HTTP_PORT", func(p PortPlan) int { return p.ClickHouseXatu01HTTP }},
+	{"CLICKHOUSE_XATU_01_NATIVE_PORT", func(p PortPlan) int { return p.ClickHouseXatu01TCP }},
+	{"CLICKHOUSE_XATU_02_HTTP_PORT", func(p PortPlan) int { return p.ClickHouseXatu02HTTP }},
+	{"CLICKHOUSE_XATU_02_NATIVE_PORT", func(p PortPlan) int { return p.ClickHouseXatu02TCP }},
+	{"REDIS_PORT", func(p PortPlan) int { return p.Redis }},
+}
+
+// XatuCBTBindAddressVars returns the bind-address env vars xcli pins to localhost.
+func XatuCBTBindAddressVars() []string {
+	return append([]string(nil), xatuCBTBindAddressVars...)
+}
+
+// DefaultPortPlan returns the slot-0 defaults before config overrides.
+func DefaultPortPlan() PortPlan {
+	return PortPlan{
+		LabBackend:           constants.DefaultLabBackendPort,
+		LabFrontend:          constants.DefaultLabFrontendPort,
+		CBTBase:              constants.DefaultCBTBasePort,
+		CBTAPIBase:           constants.DefaultCBTAPIBasePort,
+		CBTFrontendBase:      constants.DefaultCBTFrontendBasePort,
+		CBTMetricsBase:       constants.DefaultCBTMetricsBasePort,
+		CBTAPIMetricsBase:    constants.DefaultCBTAPIMetricsBasePort,
+		ClickHouseXatu01HTTP: constants.DefaultClickHouseXatuHTTPPort,
+		ClickHouseXatu01TCP:  constants.DefaultClickHouseXatuNativePort,
+		ClickHouseXatu02HTTP: constants.DefaultClickHouseXatuHTTPPort + 1,
+		ClickHouseXatu02TCP:  constants.DefaultClickHouseXatuNativePort + 1,
+		ClickHouseCBT01HTTP:  constants.DefaultClickHouseCBTHTTPPort,
+		ClickHouseCBT01TCP:   constants.DefaultClickHouseCBTNativePort,
+		ClickHouseCBT02HTTP:  constants.DefaultClickHouseCBTHTTPPort + 1,
+		ClickHouseCBT02TCP:   constants.DefaultClickHouseCBTNativePort + 1,
+		Redis:                constants.DefaultRedisPort,
+		Prometheus:           constants.DefaultPrometheusPort,
+		Grafana:              constants.DefaultGrafanaPort,
+		CommandCenter:        constants.DefaultCommandCenterPort,
+	}
+}
+
+// BuildPortPlan returns the preferred ports for a slot.
+func BuildPortPlan(labCfg *config.LabConfig, slot int) (PortPlan, error) {
+	if labCfg == nil {
+		return PortPlan{}, fmt.Errorf("lab config is required")
+	}
+
+	if slot < 0 {
+		return PortPlan{}, fmt.Errorf("slot must be non-negative")
+	}
+
+	offset := slot * portStride
+	defaults := DefaultPortPlan()
+	cbtHTTP := withDefault(labCfg.Infrastructure.ClickHouseCBTPort, defaults.ClickHouseCBT01HTTP)
+	xatuHTTP := withDefault(labCfg.Infrastructure.ClickHouseXatuPort, defaults.ClickHouseXatu01HTTP)
+	redis := withDefault(labCfg.Infrastructure.RedisPort, labCfg.Infrastructure.Redis.Port, defaults.Redis)
+	prometheus := withDefault(labCfg.Infrastructure.Observability.PrometheusPort, defaults.Prometheus)
+	grafana := withDefault(labCfg.Infrastructure.Observability.GrafanaPort, defaults.Grafana)
+
+	cbtBase := withDefault(labCfg.Ports.CBTBase, defaults.CBTBase)
+	cbtAPIBase := withDefault(labCfg.Ports.CBTAPIBase, defaults.CBTAPIBase)
+	cbtFrontendBase := withDefault(labCfg.Ports.CBTFrontendBase, defaults.CBTFrontendBase)
+	cbtMetricsBase := defaults.CBTMetricsBase + offset
+	cbtAPIMetricsBase := defaults.CBTAPIMetricsBase + offset
+
+	plan := PortPlan{
+		Slot:                 slot,
+		LabBackend:           withDefault(labCfg.Ports.LabBackend, defaults.LabBackend) + offset,
+		LabFrontend:          withDefault(labCfg.Ports.LabFrontend, defaults.LabFrontend) + offset,
+		CBTBase:              cbtBase + offset,
+		CBTAPIBase:           cbtAPIBase + offset,
+		CBTFrontendBase:      cbtFrontendBase + offset,
+		CBTMetricsBase:       cbtMetricsBase,
+		CBTAPIMetricsBase:    cbtAPIMetricsBase,
+		ClickHouseXatu01HTTP: xatuHTTP + offset,
+		ClickHouseXatu01TCP:  defaults.ClickHouseXatu01TCP + offset,
+		ClickHouseXatu02HTTP: xatuHTTP + 1 + offset,
+		ClickHouseXatu02TCP:  defaults.ClickHouseXatu02TCP + offset,
+		ClickHouseCBT01HTTP:  cbtHTTP + offset,
+		ClickHouseCBT01TCP:   defaults.ClickHouseCBT01TCP + offset,
+		ClickHouseCBT02HTTP:  cbtHTTP + 1 + offset,
+		ClickHouseCBT02TCP:   defaults.ClickHouseCBT02TCP + offset,
+		Redis:                redis + offset,
+		Prometheus:           prometheus + offset,
+		Grafana:              grafana + offset,
+		CommandCenter:        defaults.CommandCenter + offset,
+		Networks:             make(map[string]NetworkPortPlan, len(labCfg.EnabledNetworks())),
+	}
+
+	for i, network := range labCfg.EnabledNetworks() {
+		plan.Networks[network.Name] = NetworkPortPlan{
+			CBT:           cbtBase + network.PortOffset + offset,
+			CBTAPI:        cbtAPIBase + network.PortOffset + offset,
+			CBTFrontend:   cbtFrontendBase + network.PortOffset + offset,
+			CBTMetrics:    cbtMetricsBase + i,
+			CBTAPIMetrics: cbtAPIMetricsBase + i,
+		}
+	}
+
+	if duplicates := plan.DuplicatePorts(); len(duplicates) > 0 {
+		return PortPlan{}, fmt.Errorf("port plan has duplicate ports: %v", duplicates)
+	}
+
+	return plan, nil
+}
+
+// WithDefaults fills zero fields in p from fallback.
+func (p PortPlan) WithDefaults(fallback PortPlan) PortPlan {
+	if p.LabBackend == 0 {
+		p.LabBackend = fallback.LabBackend
+	}
+
+	if p.LabFrontend == 0 {
+		p.LabFrontend = fallback.LabFrontend
+	}
+
+	if p.CBTBase == 0 {
+		p.CBTBase = fallback.CBTBase
+	}
+
+	if p.CBTAPIBase == 0 {
+		p.CBTAPIBase = fallback.CBTAPIBase
+	}
+
+	if p.CBTFrontendBase == 0 {
+		p.CBTFrontendBase = fallback.CBTFrontendBase
+	}
+
+	if p.CBTMetricsBase == 0 {
+		p.CBTMetricsBase = fallback.CBTMetricsBase
+	}
+
+	if p.CBTAPIMetricsBase == 0 {
+		p.CBTAPIMetricsBase = fallback.CBTAPIMetricsBase
+	}
+
+	if p.ClickHouseXatu01HTTP == 0 {
+		p.ClickHouseXatu01HTTP = fallback.ClickHouseXatu01HTTP
+	}
+
+	if p.ClickHouseXatu01TCP == 0 {
+		p.ClickHouseXatu01TCP = fallback.ClickHouseXatu01TCP
+	}
+
+	if p.ClickHouseXatu02HTTP == 0 {
+		p.ClickHouseXatu02HTTP = fallback.ClickHouseXatu02HTTP
+	}
+
+	if p.ClickHouseXatu02TCP == 0 {
+		p.ClickHouseXatu02TCP = fallback.ClickHouseXatu02TCP
+	}
+
+	if p.ClickHouseCBT01HTTP == 0 {
+		p.ClickHouseCBT01HTTP = fallback.ClickHouseCBT01HTTP
+	}
+
+	if p.ClickHouseCBT01TCP == 0 {
+		p.ClickHouseCBT01TCP = fallback.ClickHouseCBT01TCP
+	}
+
+	if p.ClickHouseCBT02HTTP == 0 {
+		p.ClickHouseCBT02HTTP = fallback.ClickHouseCBT02HTTP
+	}
+
+	if p.ClickHouseCBT02TCP == 0 {
+		p.ClickHouseCBT02TCP = fallback.ClickHouseCBT02TCP
+	}
+
+	if p.Redis == 0 {
+		p.Redis = fallback.Redis
+	}
+
+	if p.Prometheus == 0 {
+		p.Prometheus = fallback.Prometheus
+	}
+
+	if p.Grafana == 0 {
+		p.Grafana = fallback.Grafana
+	}
+
+	if p.CommandCenter == 0 {
+		p.CommandCenter = fallback.CommandCenter
+	}
+
+	p.Networks = networkPortsWithDefaults(p.Networks, fallback.Networks)
+
+	return p
+}
+
+// XatuCBTEnv returns the project and host-port env vars for xatu-cbt infra.
+func (p PortPlan) XatuCBTEnv(projectName string) map[string]string {
+	p = p.WithDefaults(DefaultPortPlan())
+
+	env := map[string]string{
+		"XATU_CBT_PROJECT_NAME": projectName,
+	}
+	for _, field := range xatuCBTPortEnvFields {
+		env[field.name] = strconv.Itoa(field.get(p))
+	}
+
+	for _, name := range xatuCBTBindAddressVars {
+		env[name] = "127.0.0.1"
+	}
+
+	return env
+}
+
+// AllPorts returns every concrete port in this plan, sorted ascending.
+func (p PortPlan) AllPorts() []int {
+	namedPorts := p.NamedPorts()
+
+	ports := make([]int, 0, len(namedPorts))
+	for _, port := range namedPorts {
+		ports = append(ports, port)
+	}
+
+	filtered := ports[:0]
+	for _, port := range ports {
+		if port > 0 {
+			filtered = append(filtered, port)
+		}
+	}
+
+	sort.Ints(filtered)
+
+	return filtered
+}
+
+// NamedPorts returns the named concrete ports in this plan.
+func (p PortPlan) NamedPorts() map[string]int {
+	ports := make(map[string]int, len(namedPortFields)+len(p.Networks)*5)
+	for _, field := range namedPortFields {
+		ports[field.name] = field.get(p)
+	}
+
+	for network, networkPorts := range p.Networks {
+		ports["cbt-"+network] = networkPorts.CBT
+		ports["cbt-api-"+network] = networkPorts.CBTAPI
+		ports["cbt-frontend-"+network] = networkPorts.CBTFrontend
+		ports["cbt-metrics-"+network] = networkPorts.CBTMetrics
+		ports["cbt-api-metrics-"+network] = networkPorts.CBTAPIMetrics
+	}
+
+	return ports
+}
+
+func networkPortsWithDefaults(
+	ports map[string]NetworkPortPlan,
+	fallback map[string]NetworkPortPlan,
+) map[string]NetworkPortPlan {
+	if len(ports) == 0 && len(fallback) == 0 {
+		return ports
+	}
+
+	merged := make(map[string]NetworkPortPlan, len(ports)+len(fallback))
+	for name, network := range fallback {
+		merged[name] = network
+	}
+
+	for name, network := range ports {
+		fallbackNetwork := merged[name]
+		if network.CBT == 0 {
+			network.CBT = fallbackNetwork.CBT
+		}
+
+		if network.CBTAPI == 0 {
+			network.CBTAPI = fallbackNetwork.CBTAPI
+		}
+
+		if network.CBTFrontend == 0 {
+			network.CBTFrontend = fallbackNetwork.CBTFrontend
+		}
+
+		if network.CBTMetrics == 0 {
+			network.CBTMetrics = fallbackNetwork.CBTMetrics
+		}
+
+		if network.CBTAPIMetrics == 0 {
+			network.CBTAPIMetrics = fallbackNetwork.CBTAPIMetrics
+		}
+
+		merged[name] = network
+	}
+
+	return merged
+}
+
+// DuplicatePorts returns ports that appear more than once in the full plan.
+func (p PortPlan) DuplicatePorts() []int {
+	counts := make(map[int]int)
+	for _, port := range p.AllPorts() {
+		counts[port]++
+	}
+
+	duplicates := make([]int, 0)
+
+	for port, count := range counts {
+		if count > 1 {
+			duplicates = append(duplicates, port)
+		}
+	}
+
+	sort.Ints(duplicates)
+
+	return duplicates
+}
+
+// Overlaps returns ports present in both plans.
+func (p PortPlan) Overlaps(other PortPlan) []int {
+	seen := make(map[int]bool)
+	for _, port := range p.AllPorts() {
+		seen[port] = true
+	}
+
+	overlap := make([]int, 0)
+
+	for _, port := range other.AllPorts() {
+		if seen[port] {
+			overlap = append(overlap, port)
+		}
+	}
+
+	sort.Ints(overlap)
+
+	return overlap
+}
+
+func withDefault(values ...int) int {
+	for _, value := range values {
+		if value != 0 {
+			return value
+		}
+	}
+
+	return 0
+}
diff --git a/pkg/instance/ports_test.go b/pkg/instance/ports_test.go
new file mode 100644
index 0000000..a29c3cb
--- /dev/null
+++ b/pkg/instance/ports_test.go
@@ -0,0 +1,65 @@
+package instance
+
+import (
+	"testing"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBuildPortPlanSlotZeroUsesCurrentDefaults(t *testing.T) {
+	labCfg := config.DefaultLab()
+
+	plan, err := BuildPortPlan(labCfg, 0)
+	require.NoError(t, err)
+
+	require.Equal(t, 0, plan.Slot)
+	require.Equal(t, 8080, plan.LabBackend)
+	require.Equal(t, 5173, plan.LabFrontend)
+	require.Equal(t, 19280, plan.CommandCenter)
+	require.Equal(t, 8123, plan.ClickHouseCBT01HTTP)
+	require.Equal(t, 9000, plan.ClickHouseCBT01TCP)
+	require.Equal(t, 8124, plan.ClickHouseCBT02HTTP)
+	require.Equal(t, 9001, plan.ClickHouseCBT02TCP)
+	require.Equal(t, 8125, plan.ClickHouseXatu01HTTP)
+	require.Equal(t, 9002, plan.ClickHouseXatu01TCP)
+	require.Equal(t, 8126, plan.ClickHouseXatu02HTTP)
+	require.Equal(t, 9003, plan.ClickHouseXatu02TCP)
+	require.Equal(t, 6380, plan.Redis)
+	require.Equal(t, 9090, plan.Prometheus)
+	require.Equal(t, 3000, plan.Grafana)
+
+	mainnet := plan.Networks["mainnet"]
+	require.Equal(t, 8081, mainnet.CBT)
+	require.Equal(t, 8091, mainnet.CBTAPI)
+	require.Equal(t, 8085, mainnet.CBTFrontend)
+	require.Equal(t, 9100, mainnet.CBTMetrics)
+	require.Equal(t, 9200, mainnet.CBTAPIMetrics)
+
+	require.Empty(t, plan.DuplicatePorts())
+}
+
+func TestBuildPortPlanAppliesStrideAcrossFullPlan(t *testing.T) {
+	labCfg := config.DefaultLab()
+
+	slot0, err := BuildPortPlan(labCfg, 0)
+	require.NoError(t, err)
+	slot2, err := BuildPortPlan(labCfg, 2)
+	require.NoError(t, err)
+
+	require.Equal(t, slot0.LabBackend+2*portStride, slot2.LabBackend)
+	require.Equal(t, slot0.CommandCenter+2*portStride, slot2.CommandCenter)
+	require.Equal(t, slot0.ClickHouseCBT01HTTP+2*portStride, slot2.ClickHouseCBT01HTTP)
+	require.Equal(t, slot0.ClickHouseCBT02TCP+2*portStride, slot2.ClickHouseCBT02TCP)
+	require.Equal(t, slot0.ClickHouseXatu01HTTP+2*portStride, slot2.ClickHouseXatu01HTTP)
+	require.Equal(t, slot0.ClickHouseXatu02TCP+2*portStride, slot2.ClickHouseXatu02TCP)
+	require.Equal(t, slot0.Redis+2*portStride, slot2.Redis)
+	require.Equal(t, slot0.Prometheus+2*portStride, slot2.Prometheus)
+	require.Equal(t, slot0.Grafana+2*portStride, slot2.Grafana)
+
+	require.Equal(t, slot0.Networks["mainnet"].CBT+2*portStride, slot2.Networks["mainnet"].CBT)
+	require.Equal(t, slot0.Networks["mainnet"].CBTAPI+2*portStride, slot2.Networks["mainnet"].CBTAPI)
+	require.Equal(t, slot0.Networks["mainnet"].CBTFrontend+2*portStride, slot2.Networks["mainnet"].CBTFrontend)
+	require.Equal(t, slot0.Networks["mainnet"].CBTMetrics+2*portStride, slot2.Networks["mainnet"].CBTMetrics)
+	require.Equal(t, slot0.Networks["mainnet"].CBTAPIMetrics+2*portStride, slot2.Networks["mainnet"].CBTAPIMetrics)
+}
diff --git a/pkg/instance/reconcile.go b/pkg/instance/reconcile.go
new file mode 100644
index 0000000..94a0d1a
--- /dev/null
+++ b/pkg/instance/reconcile.go
@@ -0,0 +1,391 @@
+package instance
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/api/types/volume"
+	"github.com/docker/docker/client"
+)
+
+const (
+	StatusOrphan = "orphan"
+
+	// DockerResourceKindContainer is the DockerResource.Kind value for containers.
+	DockerResourceKindContainer = "container"
+
+	DockerLabelInstance = "com.ethpandaops.xcli.instance"
+	DockerLabelConfig   = "com.ethpandaops.xcli.config"
+
+	DockerComposeProjectLabel = "com.docker.compose.project"
+)
+
+// DockerResource is a labeled Docker resource discovered during reconciliation.
+type DockerResource struct {
+	Kind   string
+	ID     string
+	Name   string
+	State  string
+	Labels map[string]string
+}
+
+// DockerResourceProvider lists Docker resources labeled with an xcli instance id.
+type DockerResourceProvider interface {
+	ListXCLIResources(ctx context.Context) ([]DockerResource, error)
+}
+
+// Reconciler compares persisted manifests with live host state.
+type Reconciler struct {
+	Registry    *Registry
+	Docker      DockerResourceProvider
+	PIDAlive    func(pid int) bool
+	PortBound   func(port int) bool
+	DockerError error
+}
+
+// ReconcileResult is a snapshot of all known and discovered instances.
+type ReconcileResult struct {
+	Instances   []*ReconciledInstance
+	DockerError error
+}
+
+// ReconciledInstance is one manifest plus live-state observations.
+type ReconciledInstance struct {
+	Manifest        *Manifest
+	InstanceID      string
+	Status          string
+	RegistryPresent bool
+	Orphan          bool
+	Live            LiveState
+}
+
+// LiveState records observed backing resources for an instance.
+type LiveState struct {
+	PIDs            map[string]bool
+	Ports           map[string]bool
+	DockerResources []DockerResource
+	BackingExists   bool
+}
+
+// NewReconciler creates a reconciler backed by the default host checks.
+func NewReconciler(registry *Registry) *Reconciler {
+	return &Reconciler{Registry: registry}
+}
+
+// ReconcileAll reads the registry and reconciles it against live resources.
+func (r *Reconciler) ReconcileAll(ctx context.Context) (*ReconcileResult, error) {
+	registry := r.Registry
+
+	var err error
+	if registry == nil {
+		registry, err = DefaultRegistry()
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	manifests, err := registry.LoadAll()
+	if err != nil {
+		return nil, err
+	}
+
+	resources, dockerErr := r.listDockerResources(ctx)
+	resourcesByInstance := make(map[string][]DockerResource)
+
+	for _, resource := range resources {
+		instanceID := dockerResourceInstanceID(resource)
+		if instanceID == "" {
+			continue
+		}
+
+		resourcesByInstance[instanceID] = append(resourcesByInstance[instanceID], resource)
+	}
+
+	seen := make(map[string]bool, len(manifests))
+	instances := make([]*ReconciledInstance, 0, len(manifests)+len(resourcesByInstance))
+
+	for _, manifest := range manifests {
+		if manifest == nil || manifest.InstanceID == "" {
+			continue
+		}
+
+		seen[manifest.InstanceID] = true
+		instances = append(instances, r.reconcileManifest(manifest, true, resourcesByInstance[manifest.InstanceID]))
+	}
+
+	orphanIDs := make([]string, 0)
+
+	for instanceID := range resourcesByInstance {
+		if !seen[instanceID] {
+			orphanIDs = append(orphanIDs, instanceID)
+		}
+	}
+
+	sort.Strings(orphanIDs)
+
+	for _, instanceID := range orphanIDs {
+		instances = append(instances, r.reconcileOrphan(instanceID, resourcesByInstance[instanceID]))
+	}
+
+	sort.Slice(instances, func(i, j int) bool {
+		return instances[i].InstanceID < instances[j].InstanceID
+	})
+
+	return &ReconcileResult{Instances: instances, DockerError: dockerErr}, nil
+}
+
+func (r *Reconciler) reconcileManifest(
+	manifest *Manifest,
+	registryPresent bool,
+	resources []DockerResource,
+) *ReconciledInstance {
+	live := LiveState{
+		PIDs:            r.checkPIDs(manifest.PIDs),
+		Ports:           r.checkPorts(manifest.Ports),
+		DockerResources: resources,
+	}
+	live.BackingExists = anyTrue(live.PIDs) || anyTrue(live.Ports) || hasDockerContainer(resources)
+
+	status := manifest.Status
+	if status == "" {
+		status = StatusCreated
+	}
+
+	if registryPresent &&
+		(manifest.Status == StatusRunning || manifest.Status == StatusReserved) &&
+		!live.BackingExists {
+		status = StatusStale
+	}
+
+	return &ReconciledInstance{
+		Manifest:        manifest,
+		InstanceID:      manifest.InstanceID,
+		Status:          status,
+		RegistryPresent: registryPresent,
+		Live:            live,
+	}
+}
+
+func (r *Reconciler) reconcileOrphan(instanceID string, resources []DockerResource) *ReconciledInstance {
+	configPath := ""
+	for _, resource := range resources {
+		if configPath = strings.TrimSpace(resource.Labels[DockerLabelConfig]); configPath != "" {
+			break
+		}
+	}
+
+	manifest := &Manifest{
+		SchemaVersion: SchemaVersion,
+		InstanceID:    instanceID,
+		Status:        StatusOrphan,
+		ConfigPath:    configPath,
+		PIDs:          map[string]int{},
+		URLs:          map[string]string{},
+	}
+	manifest.Docker = manifest.EffectiveDockerPlan()
+
+	return &ReconciledInstance{
+		Manifest:        manifest,
+		InstanceID:      instanceID,
+		Status:          StatusOrphan,
+		RegistryPresent: false,
+		Orphan:          true,
+		Live: LiveState{
+			PIDs:            map[string]bool{},
+			Ports:           map[string]bool{},
+			DockerResources: resources,
+			BackingExists:   len(resources) > 0,
+		},
+	}
+}
+
+func (r *Reconciler) listDockerResources(ctx context.Context) ([]DockerResource, error) {
+	provider := r.Docker
+	if provider == nil {
+		var err error
+
+		provider, err = NewDockerResourceProvider()
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	return provider.ListXCLIResources(ctx)
+}
+
+func (r *Reconciler) checkPIDs(pids map[string]int) map[string]bool {
+	result := make(map[string]bool, len(pids))
+
+	check := r.PIDAlive
+	if check == nil {
+		check = defaultPIDAlive
+	}
+
+	for name, pid := range pids {
+		result[name] = pid > 0 && check(pid)
+	}
+
+	return result
+}
+
+func (r *Reconciler) checkPorts(plan PortPlan) map[string]bool {
+	ports := plan.NamedPorts()
+	result := make(map[string]bool, len(ports))
+
+	check := r.PortBound
+	if check == nil {
+		check = defaultPortBound
+	}
+
+	names := make([]string, 0, len(ports))
+	for name := range ports {
+		names = append(names, name)
+	}
+
+	sort.Strings(names)
+
+	for _, name := range names {
+		port := ports[name]
+		if port > 0 {
+			result[name] = check(port)
+		}
+	}
+
+	return result
+}
+
+func anyTrue(values map[string]bool) bool {
+	for _, value := range values {
+		if value {
+			return true
+		}
+	}
+
+	return false
+}
+
+func dockerResourceInstanceID(resource DockerResource) string {
+	instanceID := strings.TrimSpace(resource.Labels[DockerLabelInstance])
+	if instanceID != "" {
+		return instanceID
+	}
+
+	projectName := strings.TrimSpace(resource.Labels[DockerComposeProjectLabel])
+	if strings.HasPrefix(projectName, "xcli-") && len(projectName) > len("xcli-") {
+		return strings.TrimPrefix(projectName, "xcli-")
+	}
+
+	return ""
+}
+
+func hasDockerContainer(resources []DockerResource) bool {
+	for _, resource := range resources {
+		if resource.Kind == DockerResourceKindContainer {
+			return true
+		}
+	}
+
+	return false
+}
+
+func defaultPIDAlive(pid int) bool {
+	proc, err := os.FindProcess(pid)
+	if err != nil {
+		return false
+	}
+
+	return proc.Signal(syscall.Signal(0)) == nil
+}
+
+func defaultPortBound(port int) bool {
+	conn, err := net.DialTimeout("tcp", "127.0.0.1:"+strconv.Itoa(port), 250*time.Millisecond)
+	if err != nil {
+		return false
+	}
+
+	_ = conn.Close()
+
+	return true
+}
+
+type dockerResourceProvider struct {
+	client *client.Client
+}
+
+// NewDockerResourceProvider returns a Docker-backed resource provider.
+func NewDockerResourceProvider() (DockerResourceProvider, error) {
+	dockerClient, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
+	if err != nil {
+		return nil, fmt.Errorf("failed to create Docker client: %w", err)
+	}
+
+	return &dockerResourceProvider{client: dockerClient}, nil
+}
+
+func (p *dockerResourceProvider) ListXCLIResources(ctx context.Context) ([]DockerResource, error) {
+	resources := make([]DockerResource, 0)
+	seen := make(map[string]bool)
+
+	for _, label := range []string{DockerLabelInstance, DockerComposeProjectLabel} {
+		filterArgs := filters.NewArgs(filters.Arg("label", label))
+
+		containers, err := p.client.ContainerList(ctx, container.ListOptions{All: true, Filters: filterArgs})
+		if err != nil {
+			return nil, fmt.Errorf("failed to list Docker containers: %w", err)
+		}
+
+		for _, item := range containers {
+			name := item.ID
+			if len(item.Names) > 0 {
+				name = strings.TrimPrefix(item.Names[0], "/")
+			}
+
+			key := "container:" + item.ID
+			if seen[key] {
+				continue
+			}
+
+			seen[key] = true
+
+			resources = append(resources, DockerResource{
+				Kind:   DockerResourceKindContainer,
+				ID:     item.ID,
+				Name:   name,
+				State:  item.State,
+				Labels: item.Labels,
+			})
+		}
+
+		volumes, err := p.client.VolumeList(ctx, volume.ListOptions{Filters: filterArgs})
+		if err != nil {
+			return nil, fmt.Errorf("failed to list Docker volumes: %w", err)
+		}
+
+		for _, item := range volumes.Volumes {
+			key := "volume:" + item.Name
+			if seen[key] {
+				continue
+			}
+
+			seen[key] = true
+
+			resources = append(resources, DockerResource{
+				Kind:   "volume",
+				Name:   item.Name,
+				State:  "present",
+				Labels: item.Labels,
+			})
+		}
+	}
+
+	return resources, nil
+}
diff --git a/pkg/instance/reconcile_test.go b/pkg/instance/reconcile_test.go
new file mode 100644
index 0000000..5f21119
--- /dev/null
+++ b/pkg/instance/reconcile_test.go
@@ -0,0 +1,131 @@
+package instance
+
+import (
+	"context"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestReconcilerMarksStaleAndDiscoversDockerOrphans(t *testing.T) {
+	rootDir := t.TempDir()
+	registry := NewRegistry(filepath.Join(t.TempDir(), "instances"))
+
+	running := &Manifest{
+		SchemaVersion: SchemaVersion,
+		InstanceID:    "dead",
+		Status:        StatusRunning,
+		RootDir:       rootDir,
+		ConfigPath:    filepath.Join(rootDir, ".xcli.yaml"),
+		StateDir:      InstanceStateDir(rootDir, "dead"),
+		Docker:        NewDockerPlan("dead", filepath.Join(rootDir, ".xcli.yaml")),
+		PIDs:          map[string]int{"lab-backend": 999999},
+		Ports: PortPlan{
+			LabBackend:  18080,
+			LabFrontend: 15173,
+		},
+		URLs: map[string]string{},
+	}
+	require.NoError(t, registry.Save(running))
+
+	reconciler := &Reconciler{
+		Registry: registry,
+		Docker: fakeDockerResources{resources: []DockerResource{
+			orphanDockerResource("orphan"),
+			composeProjectDockerResource("composeonly"),
+		}},
+		PIDAlive:  func(int) bool { return false },
+		PortBound: func(int) bool { return false },
+	}
+
+	result, err := reconciler.ReconcileAll(context.Background())
+	require.NoError(t, err)
+	require.NoError(t, result.DockerError)
+	require.Len(t, result.Instances, 3)
+
+	byID := map[string]*ReconciledInstance{}
+	for _, item := range result.Instances {
+		byID[item.InstanceID] = item
+	}
+
+	require.Equal(t, StatusStale, byID["dead"].Status)
+	require.True(t, byID["dead"].RegistryPresent)
+	require.False(t, byID["dead"].Live.BackingExists)
+
+	require.Equal(t, StatusOrphan, byID["orphan"].Status)
+	require.False(t, byID["orphan"].RegistryPresent)
+	require.True(t, byID["orphan"].Orphan)
+	require.True(t, byID["orphan"].Live.BackingExists)
+	require.Len(t, byID["orphan"].Live.DockerResources, 1)
+
+	require.Equal(t, StatusOrphan, byID["composeonly"].Status)
+	require.False(t, byID["composeonly"].RegistryPresent)
+	require.True(t, byID["composeonly"].Orphan)
+	require.True(t, byID["composeonly"].Live.BackingExists)
+	require.Len(t, byID["composeonly"].Live.DockerResources, 1)
+}
+
+func TestReconcilerMarksReservedWithoutBackingStale(t *testing.T) {
+	rootDir := t.TempDir()
+	registry := NewRegistry(filepath.Join(t.TempDir(), "instances"))
+
+	reserved := &Manifest{
+		SchemaVersion: SchemaVersion,
+		InstanceID:    "reserved",
+		Status:        StatusReserved,
+		RootDir:       rootDir,
+		ConfigPath:    filepath.Join(rootDir, ".xcli.yaml"),
+		StateDir:      InstanceStateDir(rootDir, "reserved"),
+		Docker:        NewDockerPlan("reserved", filepath.Join(rootDir, ".xcli.yaml")),
+		PIDs:          map[string]int{},
+		Ports:         PortPlan{LabBackend: 18080},
+		URLs:          map[string]string{},
+	}
+	require.NoError(t, registry.Save(reserved))
+
+	reconciler := &Reconciler{
+		Registry:  registry,
+		Docker:    fakeDockerResources{},
+		PIDAlive:  func(int) bool { return false },
+		PortBound: func(int) bool { return false },
+	}
+
+	result, err := reconciler.ReconcileAll(context.Background())
+	require.NoError(t, err)
+	require.Len(t, result.Instances, 1)
+	require.Equal(t, StatusStale, result.Instances[0].Status)
+}
+
+type fakeDockerResources struct {
+	resources []DockerResource
+}
+
+func (f fakeDockerResources) ListXCLIResources(context.Context) ([]DockerResource, error) {
+	return f.resources, nil
+}
+
+func orphanDockerResource(instanceID string) DockerResource {
+	return DockerResource{
+		Kind:  DockerResourceKindContainer,
+		ID:    "container-id",
+		Name:  "xcli-" + instanceID + "-prometheus",
+		State: "running",
+		Labels: map[string]string{
+			DockerLabelInstance: instanceID,
+			DockerLabelConfig:   filepath.Join("/tmp", instanceID, ".xcli.yaml"),
+		},
+	}
+}
+
+func composeProjectDockerResource(instanceID string) DockerResource {
+	return DockerResource{
+		Kind:  DockerResourceKindContainer,
+		ID:    "compose-container-id",
+		Name:  "xcli-" + instanceID + "-redis-1",
+		State: "running",
+		Labels: map[string]string{
+			DockerComposeProjectLabel: "xcli-" + instanceID,
+		},
+	}
+}
diff --git a/pkg/instance/registry.go b/pkg/instance/registry.go
new file mode 100644
index 0000000..2c42cb6
--- /dev/null
+++ b/pkg/instance/registry.go
@@ -0,0 +1,241 @@
+package instance
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+)
+
+const manifestFileMode = 0644
+
+// Registry persists lab instance manifests in the user-global registry.
+type Registry struct {
+	dir string
+}
+
+// NewRegistry creates a registry rooted at dir.
+func NewRegistry(dir string) *Registry {
+	return &Registry{dir: dir}
+}
+
+// DefaultRegistry returns the user-global lab instance registry.
+func DefaultRegistry() (*Registry, error) {
+	dir, err := DefaultRegistryDir()
+	if err != nil {
+		return nil, err
+	}
+
+	return NewRegistry(dir), nil
+}
+
+// DefaultRegistryDir returns ~/.xcli/lab/instances.
+func DefaultRegistryDir() (string, error) {
+	homeDir, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("failed to get home directory: %w", err)
+	}
+
+	return filepath.Join(homeDir, ".xcli", "lab", "instances"), nil
+}
+
+// ManifestPath returns the global registry file for an instance.
+func (r *Registry) ManifestPath(instanceID string) string {
+	return filepath.Join(r.dir, instanceID+".json")
+}
+
+// Save writes the global manifest and the root-local manifest copy.
+func (r *Registry) Save(manifest *Manifest) error {
+	if manifest == nil {
+		return fmt.Errorf("manifest is required")
+	}
+
+	if manifest.InstanceID == "" {
+		return fmt.Errorf("manifest instance id is required")
+	}
+
+	if err := r.checkManifestConflict(manifest); err != nil {
+		return err
+	}
+
+	now := time.Now().UTC()
+	if manifest.CreatedAt.IsZero() {
+		manifest.CreatedAt = now
+	}
+
+	manifest.UpdatedAt = now
+
+	if err := writeJSONAtomic(r.ManifestPath(manifest.InstanceID), manifest); err != nil {
+		return fmt.Errorf("failed to write global manifest: %w", err)
+	}
+
+	localPath := LocalManifestPath(manifest.RootDir, manifest.InstanceID)
+	if err := writeJSONAtomic(localPath, manifest); err != nil {
+		return fmt.Errorf("failed to write local manifest copy: %w", err)
+	}
+
+	return nil
+}
+
+func (r *Registry) checkManifestConflict(manifest *Manifest) error {
+	existing, err := r.Load(manifest.InstanceID)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) || os.IsNotExist(err) {
+			return nil
+		}
+
+		return fmt.Errorf("failed to inspect existing manifest %q: %w", manifest.InstanceID, err)
+	}
+
+	if existing == nil || existing.ConfigPath == "" || manifest.ConfigPath == "" {
+		return nil
+	}
+
+	if sameConfigPath(existing.ConfigPath, manifest.ConfigPath) {
+		return nil
+	}
+
+	return fmt.Errorf(
+		"instance id %q is already registered for config %s; refusing to overwrite with config %s",
+		manifest.InstanceID,
+		existing.ConfigPath,
+		manifest.ConfigPath,
+	)
+}
+
+// Load reads one manifest by id from the global registry.
+func (r *Registry) Load(instanceID string) (*Manifest, error) {
+	data, err := os.ReadFile(r.ManifestPath(instanceID))
+	if err != nil {
+		return nil, fmt.Errorf("failed to read manifest %q: %w", instanceID, err)
+	}
+
+	var manifest Manifest
+	if err := json.Unmarshal(data, &manifest); err != nil {
+		return nil, fmt.Errorf("failed to parse manifest %q: %w", instanceID, err)
+	}
+
+	return &manifest, nil
+}
+
+// LoadAll reads all manifests from the global registry.
+func (r *Registry) LoadAll() ([]*Manifest, error) {
+	entries, err := os.ReadDir(r.dir)
+	if os.IsNotExist(err) {
+		return []*Manifest{}, nil
+	}
+
+	if err != nil {
+		return nil, fmt.Errorf("failed to read registry dir: %w", err)
+	}
+
+	manifests := make([]*Manifest, 0, len(entries))
+
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") {
+			continue
+		}
+
+		instanceID := strings.TrimSuffix(entry.Name(), ".json")
+
+		manifest, loadErr := r.Load(instanceID)
+		if loadErr != nil {
+			return nil, loadErr
+		}
+
+		manifests = append(manifests, manifest)
+	}
+
+	sort.Slice(manifests, func(i, j int) bool {
+		return manifests[i].InstanceID < manifests[j].InstanceID
+	})
+
+	return manifests, nil
+}
+
+// Delete removes the global manifest and root-local manifest copy.
+func (r *Registry) Delete(manifest *Manifest) error {
+	if manifest == nil {
+		return fmt.Errorf("manifest is required")
+	}
+
+	if manifest.InstanceID == "" {
+		return fmt.Errorf("manifest instance id is required")
+	}
+
+	paths := []string{r.ManifestPath(manifest.InstanceID)}
+	if manifest.RootDir != "" {
+		paths = append(paths, LocalManifestPath(manifest.RootDir, manifest.InstanceID))
+	}
+
+	for _, path := range paths {
+		if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+			return fmt.Errorf("failed to remove manifest %s: %w", path, err)
+		}
+	}
+
+	return nil
+}
+
+func writeJSONAtomic(path string, value any) error {
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return fmt.Errorf("failed to create directory %s: %w", dir, err)
+	}
+
+	data, err := json.MarshalIndent(value, "", "  ")
+	if err != nil {
+		return fmt.Errorf("failed to marshal json: %w", err)
+	}
+
+	data = append(data, '\n')
+
+	tmp, err := os.CreateTemp(dir, ".manifest-*.tmp")
+	if err != nil {
+		return fmt.Errorf("failed to create temp file: %w", err)
+	}
+
+	tmpName := tmp.Name()
+	defer os.Remove(tmpName)
+
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+
+		return fmt.Errorf("failed to write temp file: %w", err)
+	}
+
+	if err := tmp.Chmod(manifestFileMode); err != nil {
+		_ = tmp.Close()
+
+		return fmt.Errorf("failed to chmod temp file: %w", err)
+	}
+
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("failed to close temp file: %w", err)
+	}
+
+	if err := os.Rename(tmpName, path); err != nil {
+		return fmt.Errorf("failed to replace %s: %w", path, err)
+	}
+
+	return nil
+}
+
+func sameConfigPath(a, b string) bool {
+	aAbs, aErr := filepath.Abs(a)
+	bAbs, bErr := filepath.Abs(b)
+
+	if aErr == nil {
+		a = aAbs
+	}
+
+	if bErr == nil {
+		b = bAbs
+	}
+
+	return filepath.Clean(a) == filepath.Clean(b)
+}
diff --git a/pkg/instance/registry_test.go b/pkg/instance/registry_test.go
new file mode 100644
index 0000000..28cea76
--- /dev/null
+++ b/pkg/instance/registry_test.go
@@ -0,0 +1,146 @@
+package instance
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	xcligit "github.com/ethpandaops/xcli/pkg/git"
+	"github.com/stretchr/testify/require"
+)
+
+func TestRegistrySaveWritesGlobalAndLocalManifest(t *testing.T) {
+	rootDir := t.TempDir()
+	registry := NewRegistry(filepath.Join(t.TempDir(), "instances"))
+
+	manifest := &Manifest{
+		SchemaVersion: SchemaVersion,
+		InstanceID:    "alpha",
+		Status:        StatusCreated,
+		RootDir:       rootDir,
+		ConfigPath:    filepath.Join(rootDir, ".xcli.yaml"),
+		OverridesPath: filepath.Join(rootDir, ".cbt-overrides.yaml"),
+		StateDir:      InstanceStateDir(rootDir, "alpha"),
+		Mode:          "hybrid",
+		Repos: map[string]xcligit.RepoVersion{
+			"cbt": {Path: "/repos/cbt", Branch: "main", Commit: "abcdef", Dirty: true},
+		},
+		Ports:     PortPlan{},
+		Docker:    NewDockerPlan("alpha", filepath.Join(rootDir, ".xcli.yaml")),
+		PIDs:      map[string]int{},
+		URLs:      map[string]string{},
+		CreatedAt: time.Now().UTC().Add(-time.Minute),
+	}
+
+	require.NoError(t, registry.Save(manifest))
+
+	globalPath := registry.ManifestPath("alpha")
+	localPath := LocalManifestPath(rootDir, "alpha")
+
+	require.FileExists(t, globalPath)
+	require.FileExists(t, localPath)
+
+	globalData, err := os.ReadFile(globalPath)
+	require.NoError(t, err)
+
+	localData, err := os.ReadFile(localPath)
+	require.NoError(t, err)
+	require.Equal(t, string(globalData), string(localData))
+
+	loaded, err := registry.Load("alpha")
+	require.NoError(t, err)
+	require.Equal(t, "alpha", loaded.InstanceID)
+	require.Equal(t, "main", loaded.Repos["cbt"].Branch)
+	require.False(t, loaded.UpdatedAt.IsZero())
+}
+
+func TestRegistryLoadAllSorted(t *testing.T) {
+	rootDir := t.TempDir()
+	registry := NewRegistry(filepath.Join(t.TempDir(), "instances"))
+
+	for _, id := range []string{"bravo", "alpha"} {
+		require.NoError(t, registry.Save(&Manifest{
+			SchemaVersion: SchemaVersion,
+			InstanceID:    id,
+			Status:        StatusCreated,
+			RootDir:       rootDir,
+			ConfigPath:    filepath.Join(rootDir, ".xcli.yaml"),
+			OverridesPath: filepath.Join(rootDir, ".cbt-overrides.yaml"),
+			StateDir:      InstanceStateDir(rootDir, id),
+			Repos:         map[string]xcligit.RepoVersion{},
+			Docker:        NewDockerPlan(id, filepath.Join(rootDir, ".xcli.yaml")),
+			PIDs:          map[string]int{},
+			URLs:          map[string]string{},
+		}))
+	}
+
+	manifests, err := registry.LoadAll()
+	require.NoError(t, err)
+	require.Len(t, manifests, 2)
+	require.Equal(t, "alpha", manifests[0].InstanceID)
+	require.Equal(t, "bravo", manifests[1].InstanceID)
+}
+
+func TestRegistryDeleteRemovesGlobalAndLocalManifest(t *testing.T) {
+	rootDir := t.TempDir()
+	registry := NewRegistry(filepath.Join(t.TempDir(), "instances"))
+	manifest := &Manifest{
+		SchemaVersion: SchemaVersion,
+		InstanceID:    "delete-me",
+		Status:        StatusStopped,
+		RootDir:       rootDir,
+		ConfigPath:    filepath.Join(rootDir, ".xcli.yaml"),
+		OverridesPath: filepath.Join(rootDir, ".cbt-overrides.yaml"),
+		StateDir:      InstanceStateDir(rootDir, "delete-me"),
+		Repos:         map[string]xcligit.RepoVersion{},
+		Docker:        NewDockerPlan("delete-me", filepath.Join(rootDir, ".xcli.yaml")),
+		PIDs:          map[string]int{},
+		URLs:          map[string]string{},
+	}
+
+	require.NoError(t, registry.Save(manifest))
+	require.FileExists(t, registry.ManifestPath("delete-me"))
+	require.FileExists(t, LocalManifestPath(rootDir, "delete-me"))
+
+	require.NoError(t, registry.Delete(manifest))
+	require.NoFileExists(t, registry.ManifestPath("delete-me"))
+	require.NoFileExists(t, LocalManifestPath(rootDir, "delete-me"))
+}
+
+func TestRegistryRejectsSameIDWithDifferentConfigPath(t *testing.T) {
+	rootDir := t.TempDir()
+	registry := NewRegistry(filepath.Join(t.TempDir(), "instances"))
+
+	configOne := filepath.Join(rootDir, "one", ".xcli.yaml")
+	configTwo := filepath.Join(rootDir, "two", ".xcli.yaml")
+	first := &Manifest{
+		SchemaVersion: SchemaVersion,
+		InstanceID:    "same-id",
+		Status:        StatusStopped,
+		RootDir:       rootDir,
+		ConfigPath:    configOne,
+		StateDir:      InstanceStateDir(rootDir, "same-id"),
+		Repos:         map[string]xcligit.RepoVersion{},
+		Docker:        NewDockerPlan("same-id", configOne),
+		PIDs:          map[string]int{},
+		URLs:          map[string]string{},
+	}
+	second := *first
+	second.ConfigPath = configTwo
+	second.Docker = NewDockerPlan("same-id", configTwo)
+
+	require.NoError(t, registry.Save(first))
+	err := registry.Save(&second)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "already registered")
+}
+
+func TestDefaultRegistryDir(t *testing.T) {
+	homeDir := t.TempDir()
+	t.Setenv("HOME", homeDir)
+
+	got, err := DefaultRegistryDir()
+	require.NoError(t, err)
+	require.Equal(t, filepath.Join(homeDir, ".xcli", "lab", "instances"), got)
+}
diff --git a/pkg/instance/runtime.go b/pkg/instance/runtime.go
new file mode 100644
index 0000000..268e444
--- /dev/null
+++ b/pkg/instance/runtime.go
@@ -0,0 +1,236 @@
+package instance
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	xcligit "github.com/ethpandaops/xcli/pkg/git"
+	"github.com/ethpandaops/xcli/pkg/workspace"
+)
+
+// Runtime is the fully resolved per-instance bundle used by later stack phases.
+type Runtime struct {
+	Workspace  *workspace.Workspace
+	LabConfig  *config.LabConfig
+	Registry   *Registry
+	InstanceID string
+	Manifest   *Manifest
+	Ports      PortPlan
+	Docker     DockerPlan
+	Repos      map[string]xcligit.RepoVersion
+}
+
+// EffectiveDockerPlan returns the runtime Docker plan with manifest/id fallbacks.
+func (r *Runtime) EffectiveDockerPlan() DockerPlan {
+	if r == nil {
+		return DockerPlan{}
+	}
+
+	fallback := DockerPlan{}
+	if r.Manifest != nil {
+		fallback = r.Manifest.EffectiveDockerPlan()
+	}
+
+	if fallback.ProjectName == "" && r.InstanceID != "" {
+		configPath := ""
+		if r.Manifest != nil {
+			configPath = r.Manifest.ConfigPath
+		}
+
+		fallback = NewDockerPlan(r.InstanceID, configPath)
+	}
+
+	return r.Docker.WithDefaults(fallback)
+}
+
+// RuntimeOptions configures runtime assembly.
+type RuntimeOptions struct {
+	Registry   *Registry
+	Allocator  *Allocator
+	ClaimPorts bool
+	ProbePorts bool
+}
+
+// ResolveRuntime loads a persisted runtime for the selected instance when one
+// exists, otherwise assembles an unfinalized runtime with the supplied options.
+func ResolveRuntime(
+	ctx context.Context,
+	configPath string,
+	cliInstanceID string,
+	checkCWDOverrides bool,
+	opts RuntimeOptions,
+) (*Runtime, error) {
+	labCfg, ws, err := workspace.LoadLabConfig(configPath, checkCWDOverrides)
+	if err != nil {
+		return nil, err
+	}
+
+	return ResolveRuntimeFromWorkspace(ctx, ws, labCfg, cliInstanceID, opts)
+}
+
+// ResolveRuntimeFromWorkspace is ResolveRuntime for callers that already
+// loaded the authoritative workspace.
+func ResolveRuntimeFromWorkspace(
+	ctx context.Context,
+	ws *workspace.Workspace,
+	labCfg *config.LabConfig,
+	cliInstanceID string,
+	opts RuntimeOptions,
+) (*Runtime, error) {
+	instanceID, err := ResolveID(ws, labCfg, cliInstanceID)
+	if err != nil {
+		return nil, err
+	}
+
+	registry := opts.Registry
+	if registry == nil {
+		registry, err = DefaultRegistry()
+		if err != nil {
+			return nil, err
+		}
+
+		opts.Registry = registry
+	}
+
+	if _, statErr := os.Stat(registry.ManifestPath(instanceID)); statErr == nil {
+		manifest, loadErr := registry.Load(instanceID)
+		if loadErr != nil {
+			return nil, loadErr
+		}
+
+		if cliInstanceID != "" {
+			return NewRuntimeFromManifestConfig(ctx, manifest, registry)
+		}
+
+		if manifest.ConfigPath != "" && ws.ConfigPath != "" && !sameConfigPath(manifest.ConfigPath, ws.ConfigPath) {
+			return nil, fmt.Errorf(
+				"instance id %q is registered for config %s, not current config %s",
+				instanceID,
+				manifest.ConfigPath,
+				ws.ConfigPath,
+			)
+		}
+
+		return NewRuntimeFromManifest(manifest, labCfg, ws, registry)
+	} else if !os.IsNotExist(statErr) {
+		return nil, fmt.Errorf("failed to inspect instance manifest %q: %w", instanceID, statErr)
+	}
+
+	return NewRuntimeFromWorkspace(ctx, ws, labCfg, cliInstanceID, opts)
+}
+
+// NewRuntimeFromWorkspace assembles a runtime from an already resolved workspace.
+func NewRuntimeFromWorkspace(
+	ctx context.Context,
+	ws *workspace.Workspace,
+	labCfg *config.LabConfig,
+	cliInstanceID string,
+	opts RuntimeOptions,
+) (*Runtime, error) {
+	manifest, err := NewManifest(ctx, ws, labCfg, cliInstanceID)
+	if err != nil {
+		return nil, err
+	}
+
+	registry := opts.Registry
+	if registry == nil {
+		registry, err = DefaultRegistry()
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	allocator := opts.Allocator
+	if allocator == nil {
+		allocator = NewAllocator(registry, opts.ProbePorts)
+	}
+
+	ports, err := allocator.Allocate(ctx, AllocationRequest{
+		InstanceID: manifest.InstanceID,
+		LabConfig:  labCfg,
+		Manifest:   manifest,
+		Claim:      opts.ClaimPorts,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to allocate ports: %w", err)
+	}
+
+	manifest.Ports = ports
+	manifest.Docker = NewDockerPlan(manifest.InstanceID, manifest.ConfigPath)
+
+	return &Runtime{
+		Workspace:  ws,
+		LabConfig:  labCfg,
+		Registry:   registry,
+		InstanceID: manifest.InstanceID,
+		Manifest:   manifest,
+		Ports:      ports,
+		Docker:     manifest.Docker,
+		Repos:      manifest.Repos,
+	}, nil
+}
+
+// NewRuntimeFromManifestConfig reloads the workspace and lab config recorded
+// in a persisted manifest before assembling the runtime.
+func NewRuntimeFromManifestConfig(
+	_ context.Context,
+	manifest *Manifest,
+	registry *Registry,
+) (*Runtime, error) {
+	if manifest == nil {
+		return nil, fmt.Errorf("manifest is required")
+	}
+
+	if manifest.ConfigPath == "" {
+		return nil, fmt.Errorf("manifest %q has no config path", manifest.InstanceID)
+	}
+
+	labCfg, ws, err := workspace.LoadLabConfig(manifest.ConfigPath, false)
+	if err != nil {
+		return nil, fmt.Errorf(
+			"failed to load config for instance %q from %s: %w",
+			manifest.InstanceID,
+			manifest.ConfigPath,
+			err,
+		)
+	}
+
+	return NewRuntimeFromManifest(manifest, labCfg, ws, registry)
+}
+
+// NewRuntimeFromManifest assembles a runtime from persisted instance state.
+func NewRuntimeFromManifest(
+	manifest *Manifest,
+	labCfg *config.LabConfig,
+	ws *workspace.Workspace,
+	registry *Registry,
+) (*Runtime, error) {
+	if manifest == nil {
+		return nil, fmt.Errorf("manifest is required")
+	}
+
+	if labCfg == nil {
+		return nil, fmt.Errorf("lab config is required")
+	}
+
+	if ws == nil {
+		return nil, fmt.Errorf("workspace is required")
+	}
+
+	if manifest.Docker.ProjectName == "" {
+		manifest.Docker = NewDockerPlan(manifest.InstanceID, manifest.ConfigPath)
+	}
+
+	return &Runtime{
+		Workspace:  ws,
+		LabConfig:  labCfg,
+		Registry:   registry,
+		InstanceID: manifest.InstanceID,
+		Manifest:   manifest,
+		Ports:      manifest.Ports,
+		Docker:     manifest.Docker,
+		Repos:      manifest.Repos,
+	}, nil
+}
diff --git a/pkg/instance/runtime_test.go b/pkg/instance/runtime_test.go
new file mode 100644
index 0000000..602c2d3
--- /dev/null
+++ b/pkg/instance/runtime_test.go
@@ -0,0 +1,128 @@
+package instance
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/workspace"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewRuntimeFromWorkspaceAssemblesAndClaimsDistinctPlans(t *testing.T) {
+	registry := NewRegistry(filepath.Join(t.TempDir(), "lab", "instances"))
+	allocator := NewAllocator(registry, false)
+
+	firstConfig := writeRuntimeConfig(t, "first")
+	secondConfig := writeRuntimeConfig(t, "second")
+	firstLabCfg, firstWorkspace, err := workspace.LoadLabConfig(firstConfig, false)
+	require.NoError(t, err)
+	secondLabCfg, secondWorkspace, err := workspace.LoadLabConfig(secondConfig, false)
+	require.NoError(t, err)
+
+	first, err := NewRuntimeFromWorkspace(context.Background(), firstWorkspace, firstLabCfg, "", RuntimeOptions{
+		Registry:   registry,
+		Allocator:  allocator,
+		ClaimPorts: true,
+	})
+	require.NoError(t, err)
+
+	second, err := NewRuntimeFromWorkspace(context.Background(), secondWorkspace, secondLabCfg, "", RuntimeOptions{
+		Registry:   registry,
+		Allocator:  allocator,
+		ClaimPorts: true,
+	})
+	require.NoError(t, err)
+
+	require.NotEqual(t, first.InstanceID, second.InstanceID)
+	require.Equal(t, 0, first.Ports.Slot)
+	require.Equal(t, 1, second.Ports.Slot)
+	require.Empty(t, first.Ports.Overlaps(second.Ports))
+	require.Equal(t, first.Ports, first.Manifest.Ports)
+	require.Equal(t, InstanceStateDir(first.Workspace.RootDir, first.InstanceID), first.Manifest.StateDir)
+	require.Equal(t, filepath.Join(filepath.Dir(firstConfig), "repos", "cbt"), first.LabConfig.Repos.CBT)
+}
+
+func TestResolveRuntimeExplicitInstanceLoadsManifestWorkspace(t *testing.T) {
+	registry := NewRegistry(filepath.Join(t.TempDir(), "lab", "instances"))
+	allocator := NewAllocator(registry, false)
+
+	foreignConfig := writeRuntimeConfig(t, "foreign")
+	currentConfig := writeRuntimeConfig(t, "current")
+	foreignLabCfg, foreignWorkspace, err := workspace.LoadLabConfig(foreignConfig, false)
+	require.NoError(t, err)
+
+	foreign, err := NewRuntimeFromWorkspace(context.Background(), foreignWorkspace, foreignLabCfg, "", RuntimeOptions{
+		Registry:   registry,
+		Allocator:  allocator,
+		ClaimPorts: true,
+	})
+	require.NoError(t, err)
+
+	currentLabCfg, currentWorkspace, err := workspace.LoadLabConfig(currentConfig, false)
+	require.NoError(t, err)
+
+	resolved, err := ResolveRuntimeFromWorkspace(
+		context.Background(),
+		currentWorkspace,
+		currentLabCfg,
+		foreign.InstanceID,
+		RuntimeOptions{Registry: registry, ProbePorts: false},
+	)
+	require.NoError(t, err)
+	require.Equal(t, foreign.Workspace.ConfigPath, resolved.Workspace.ConfigPath)
+	require.Equal(t, foreign.Workspace.RootDir, resolved.Workspace.RootDir)
+	require.Equal(t, foreign.Manifest.ConfigPath, resolved.Manifest.ConfigPath)
+	require.Equal(t, filepath.Join(foreign.Workspace.RootDir, "repos", "cbt"), resolved.LabConfig.Repos.CBT)
+	require.NotEqual(t, currentWorkspace.ConfigPath, resolved.Workspace.ConfigPath)
+}
+
+func writeRuntimeConfig(t *testing.T, name string) string {
+	t.Helper()
+
+	rootDir := filepath.Join(t.TempDir(), name)
+	require.NoError(t, os.MkdirAll(filepath.Join(rootDir, "repos"), 0755))
+
+	configPath := filepath.Join(rootDir, config.DefaultConfigFileName)
+	content := `
+lab:
+  mode: hybrid
+  repos:
+    cbt: repos/cbt
+    xatuCbt: repos/xatu-cbt
+    cbtApi: repos/cbt-api
+    labBackend: repos/lab-backend
+    lab: repos/lab
+  networks:
+    - name: mainnet
+      enabled: true
+      portOffset: 0
+  infrastructure:
+    clickhouse:
+      xatu:
+        mode: external
+        externalUrl: "http://example.invalid:9000"
+      cbt:
+        mode: local
+    redis:
+      port: 6380
+    observability:
+      enabled: true
+      prometheusPort: 9090
+      grafanaPort: 3000
+    clickhouseXatuPort: 8125
+    clickhouseCbtPort: 8123
+    redisPort: 6380
+  ports:
+    labBackend: 8080
+    labFrontend: 5173
+    cbtBase: 8081
+    cbtApiBase: 8091
+    cbtFrontendBase: 8085
+`
+	require.NoError(t, os.WriteFile(configPath, []byte(content), 0644))
+
+	return configPath
+}
diff --git a/pkg/mode/mode.go b/pkg/mode/mode.go
index e4ffc80..c9458d3 100644
--- a/pkg/mode/mode.go
+++ b/pkg/mode/mode.go
@@ -19,8 +19,8 @@ type Mode interface {
 	GetInfrastructureServices() []string
 
 	// GetHealthCheckPorts returns ports to health check for infrastructure readiness
-	// Local: [8123 (xatu-local), 8124 (cbt), 6380 (redis)]
-	// Hybrid: [8124 (cbt), 6380 (redis), <external-clickhouse-port>]
+	// Local: [8125 (xatu-local), 8123 (cbt), 6380 (redis)]
+	// Hybrid: [8123 (cbt), 6380 (redis), <external-clickhouse-port>]
 	GetHealthCheckPorts() []int
 
 	// GetObservabilityPorts returns ports for observability services (Prometheus, Grafana)
diff --git a/pkg/orchestrator/orchestrator.go b/pkg/orchestrator/orchestrator.go
index 07e677d..b2dd56d 100644
--- a/pkg/orchestrator/orchestrator.go
+++ b/pkg/orchestrator/orchestrator.go
@@ -10,6 +10,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"sort"
 	"strconv"
 	"strings"
 	"time"
@@ -20,6 +21,7 @@ import (
 	"github.com/ethpandaops/xcli/pkg/constants"
 	"github.com/ethpandaops/xcli/pkg/git"
 	"github.com/ethpandaops/xcli/pkg/infrastructure"
+	"github.com/ethpandaops/xcli/pkg/instance"
 	"github.com/ethpandaops/xcli/pkg/mode"
 	"github.com/ethpandaops/xcli/pkg/portutil"
 	"github.com/ethpandaops/xcli/pkg/process"
@@ -47,6 +49,7 @@ type Orchestrator struct {
 	proc     process.Manager
 	builder  *builder.Manager
 	stateDir string
+	runtime  *instance.Runtime
 	verbose  bool
 	render   ui.Renderer
 }
@@ -56,6 +59,44 @@ func NewOrchestrator(
 	log logrus.FieldLogger,
 	cfg *config.LabConfig,
 	configPath string,
+) (*Orchestrator, error) {
+	return newOrchestrator(log, cfg, configPath, nil)
+}
+
+// NewOrchestratorWithRuntime creates an orchestrator bound to an instance runtime.
+func NewOrchestratorWithRuntime(
+	log logrus.FieldLogger,
+	runtime *instance.Runtime,
+) (*Orchestrator, error) {
+	if runtime == nil {
+		return nil, fmt.Errorf("runtime is required")
+	}
+
+	if runtime.LabConfig == nil {
+		return nil, fmt.Errorf("runtime lab config is required")
+	}
+
+	configPath := ""
+	if runtime.Manifest != nil {
+		configPath = runtime.Manifest.ConfigPath
+	}
+
+	if configPath == "" && runtime.Workspace != nil {
+		configPath = runtime.Workspace.ConfigPath
+	}
+
+	if configPath == "" {
+		return nil, fmt.Errorf("runtime config path is required")
+	}
+
+	return newOrchestrator(log, runtime.LabConfig, configPath, runtime)
+}
+
+func newOrchestrator(
+	log logrus.FieldLogger,
+	cfg *config.LabConfig,
+	configPath string,
+	runtime *instance.Runtime,
 ) (*Orchestrator, error) {
 	// Get absolute path of config file
 	absConfigPath, err := filepath.Abs(configPath)
@@ -65,7 +106,11 @@ func NewOrchestrator(
 
 	// State directory is in the same directory as the config file
 	configDir := filepath.Dir(absConfigPath)
+
 	stateDir := filepath.Join(configDir, ".xcli")
+	if runtime != nil && runtime.Manifest != nil && runtime.Manifest.StateDir != "" {
+		stateDir = runtime.Manifest.StateDir
+	}
 
 	// Create mode from config (wrapping LabConfig to get Config)
 	fullConfig := &config.Config{Lab: cfg}
@@ -86,10 +131,11 @@ func NewOrchestrator(
 		log:      log.WithField("component", "orchestrator"),
 		cfg:      cfg,
 		mode:     m,
-		infra:    infrastructure.NewManager(log, cfg, m, stateDir),
+		infra:    infrastructure.NewManagerWithRuntime(log, cfg, m, stateDir, runtime),
 		proc:     process.NewManager(log, stateDir),
 		builder:  builder.NewManager(log, cfg, stateDir),
 		stateDir: stateDir,
+		runtime:  runtime,
 		verbose:  false,
 		render:   ui.NewPlainRenderer(),
 	}, nil
@@ -162,7 +208,26 @@ func (o *Orchestrator) Up(
 	skipBuild bool,
 	forceBuild bool,
 	progress ProgressFunc,
-) error {
+) (err error) {
+	releaseReservationOnFailure := o.runtime != nil &&
+		o.runtime.Manifest != nil &&
+		o.runtime.Manifest.Status == instance.StatusReserved
+	upComplete := false
+
+	defer func() {
+		if upComplete || !releaseReservationOnFailure {
+			return
+		}
+
+		if err == nil {
+			err = fmt.Errorf("lab up did not complete")
+		}
+
+		if releaseErr := o.releaseRuntimeReservation(err); releaseErr != nil {
+			o.log.WithError(releaseErr).Warn("failed to release instance reservation after failed up")
+		}
+	}()
+
 	// Display startup banner
 	o.render.Banner("Starting Lab Stack")
 
@@ -436,21 +501,34 @@ func (o *Orchestrator) Up(
 
 	serviceSpinner.Success("All services started")
 
+	if err := o.finalizeRuntimeManifest(ctx); err != nil {
+		return fmt.Errorf("failed to write instance manifest: %w", err)
+	}
+
+	upComplete = true
+
 	reportProgress(progress, "complete", "Stack is running!")
 
 	o.render.Blank()
 	o.render.Success("Stack is running!")
 
-	// Build services list
+	o.displayRuntimeSummary()
+	o.render.ServiceTable("Services", o.serviceSummary())
+	o.render.Blank()
+
+	return nil
+}
+
+func (o *Orchestrator) serviceSummary() []ui.Service {
 	services := []ui.Service{
 		{
 			Name:   "Lab Frontend",
-			URL:    fmt.Sprintf("http://localhost:%d", o.cfg.Ports.LabFrontend),
+			URL:    o.getServiceURL(constants.ServiceLabFrontend),
 			Status: statusRunning,
 		},
 		{
 			Name:   "Lab Backend",
-			URL:    fmt.Sprintf("http://localhost:%d", o.cfg.Ports.LabBackend),
+			URL:    o.getServiceURL(constants.ServiceLabBackend),
 			Status: statusRunning,
 		},
 	}
@@ -458,41 +536,221 @@ func (o *Orchestrator) Up(
 	for _, net := range o.cfg.EnabledNetworks() {
 		services = append(services, ui.Service{
 			Name:   fmt.Sprintf("CBT API (%s)", net.Name),
-			URL:    fmt.Sprintf("http://localhost:%d", o.cfg.GetCBTAPIPort(net.Name)),
+			URL:    o.getServiceURL(constants.ServiceNameCBTAPI(net.Name)),
 			Status: statusRunning,
 		})
 		services = append(services, ui.Service{
 			Name:   fmt.Sprintf("CBT Frontend (%s)", net.Name),
-			URL:    fmt.Sprintf("http://localhost:%d", o.cfg.GetCBTFrontendPort(net.Name)),
+			URL:    o.getServiceURL(constants.ServiceNameCBT(net.Name)),
 			Status: statusRunning,
 		})
 	}
 
-	// Add observability services if enabled
 	if o.cfg.Infrastructure.Observability.Enabled {
 		services = append(services, ui.Service{
 			Name:   "Prometheus",
-			URL:    fmt.Sprintf("http://localhost:%d", o.cfg.Infrastructure.Observability.PrometheusPort),
+			URL:    o.getServiceURL(constants.ServicePrometheus),
 			Status: statusRunning,
 		})
 		services = append(services, ui.Service{
 			Name:   "Grafana",
-			URL:    fmt.Sprintf("http://localhost:%d", o.cfg.Infrastructure.Observability.GrafanaPort),
+			URL:    o.getServiceURL(constants.ServiceGrafana),
 			Status: statusRunning,
 		})
 	}
 
-	o.render.ServiceTable("Services", services)
+	return services
+}
+
+func (o *Orchestrator) displayRuntimeSummary() {
+	if o.runtime == nil || o.runtime.Manifest == nil {
+		return
+	}
+
+	manifest := o.runtime.Manifest
+	o.render.Header("Instance")
+	o.render.Info(fmt.Sprintf("ID: %s", manifest.InstanceID))
+	o.render.Info(fmt.Sprintf("Config: %s", manifest.ConfigPath))
+	o.render.Info(fmt.Sprintf("Overrides: %s", manifest.OverridesPath))
+	o.render.Info(fmt.Sprintf("State dir: %s", manifest.StateDir))
+
 	o.render.Blank()
+	o.render.Header("Repositories")
+
+	names := make([]string, 0, len(manifest.Repos))
+	for name := range manifest.Repos {
+		names = append(names, name)
+	}
+
+	sort.Strings(names)
+
+	for _, name := range names {
+		version := manifest.Repos[name]
+
+		branch := version.Branch
+		if branch == "" {
+			branch = "unknown"
+		}
+
+		commit := shortCommit(version.Commit)
+		if commit == "" {
+			commit = "unknown"
+		}
+
+		state := "clean"
+		if version.Dirty {
+			state = "dirty"
+		}
+
+		o.render.Info(fmt.Sprintf("%s: %s %s %s (%s)", name, branch, commit, state, version.Path))
+	}
+
+	if manifest.LastError != "" {
+		o.render.Warning(fmt.Sprintf("Repo snapshot warning: %s", manifest.LastError))
+	}
+
+	o.render.Blank()
+}
+
+func (o *Orchestrator) finalizeRuntimeManifest(ctx context.Context) error {
+	if o.runtime == nil || o.runtime.Manifest == nil {
+		return nil
+	}
+
+	manifest := o.runtime.Manifest
+	updatedManifest := *manifest
+
+	repos, snapshotErr := instance.SnapshotLabRepos(ctx, o.cfg)
+	if len(repos) > 0 {
+		updatedManifest.Repos = repos
+		o.runtime.Repos = repos
+	}
+
+	if snapshotErr != nil {
+		updatedManifest.LastError = snapshotErr.Error()
+	} else {
+		updatedManifest.LastError = ""
+	}
+
+	updatedManifest.Status = instance.StatusRunning
+	updatedManifest.Ports = o.runtime.Ports
+	updatedManifest.Docker = o.runtime.Docker
+	updatedManifest.PIDs = o.managedPIDs()
+	updatedManifest.URLs = o.runtimeURLs()
+
+	registry, err := o.runtimeRegistry()
+	if err != nil {
+		return err
+	}
+
+	if err := registry.Save(&updatedManifest); err != nil {
+		return err
+	}
+
+	*manifest = updatedManifest
 
 	return nil
 }
 
-// Down stops all services and tears down infrastructure (removes volumes).
+func (o *Orchestrator) markRuntimeStopped() error {
+	if o.runtime == nil || o.runtime.Manifest == nil {
+		return nil
+	}
+
+	o.runtime.Manifest.Status = instance.StatusStopped
+	o.runtime.Manifest.PIDs = map[string]int{}
+
+	registry, err := o.runtimeRegistry()
+	if err != nil {
+		return err
+	}
+
+	return registry.Save(o.runtime.Manifest)
+}
+
+func (o *Orchestrator) releaseRuntimeReservation(upErr error) error {
+	if o.runtime == nil || o.runtime.Manifest == nil {
+		return nil
+	}
+
+	o.runtime.Manifest.Status = instance.StatusStopped
+	if upErr != nil {
+		o.runtime.Manifest.LastError = upErr.Error()
+	}
+
+	o.runtime.Manifest.PIDs = map[string]int{}
+
+	registry, err := o.runtimeRegistry()
+	if err != nil {
+		return err
+	}
+
+	return registry.Save(o.runtime.Manifest)
+}
+
+func (o *Orchestrator) runtimeRegistry() (*instance.Registry, error) {
+	if o.runtime == nil {
+		return instance.DefaultRegistry()
+	}
+
+	if o.runtime.Registry != nil {
+		return o.runtime.Registry, nil
+	}
+
+	registry, err := instance.DefaultRegistry()
+	if err != nil {
+		return nil, err
+	}
+
+	o.runtime.Registry = registry
+
+	return registry, nil
+}
+
+func (o *Orchestrator) managedPIDs() map[string]int {
+	processes := o.proc.List()
+
+	pids := make(map[string]int, len(processes))
+	for _, p := range processes {
+		pids[p.Name] = p.PID
+	}
+
+	return pids
+}
+
+func (o *Orchestrator) runtimeURLs() map[string]string {
+	urls := map[string]string{
+		constants.ServiceLabFrontend: o.getServiceURL(constants.ServiceLabFrontend),
+		constants.ServiceLabBackend:  o.getServiceURL(constants.ServiceLabBackend),
+		"command-center":             fmt.Sprintf("http://localhost:%d", o.portPlan().CommandCenter),
+	}
+
+	for _, net := range o.cfg.EnabledNetworks() {
+		urls[constants.ServiceNameCBT(net.Name)] = o.getServiceURL(constants.ServiceNameCBT(net.Name))
+		urls[constants.ServiceNameCBTAPI(net.Name)] = o.getServiceURL(constants.ServiceNameCBTAPI(net.Name))
+	}
+
+	if o.cfg.Infrastructure.Observability.Enabled {
+		urls[constants.ServicePrometheus] = o.getServiceURL(constants.ServicePrometheus)
+		urls[constants.ServiceGrafana] = o.getServiceURL(constants.ServiceGrafana)
+	}
+
+	return urls
+}
+
+func shortCommit(commit string) string {
+	if len(commit) <= 12 {
+		return commit
+	}
+
+	return commit[:12]
+}
+
+// Down stops all services and infrastructure while preserving data.
 // progress is an optional callback for reporting teardown phase updates.
 // Pass nil to disable progress reporting (e.g. from CLI callers).
 func (o *Orchestrator) Down(ctx context.Context, progress ProgressFunc) error {
-	o.log.Info("tearing down stack")
+	o.log.Info("stopping stack")
 
 	// Stop services first
 	reportProgress(progress, "stop_services", "Stopping services...")
@@ -537,45 +795,101 @@ func (o *Orchestrator) Down(ctx context.Context, progress ProgressFunc) error {
 		spinner.Success("Log files cleaned")
 	}
 
-	// Final cleanup: Kill any remaining pnpm/vite/esbuild processes
-	// This handles orphaned child processes that reparented after their parent died
-	o.log.Debug("cleaning up orphaned node processes (pnpm/vite/esbuild)")
+	// Stop infrastructure without removing volumes.
+	reportProgress(progress, "stop_infrastructure", "Stopping infrastructure...")
+
+	spinner = o.render.Task("Stopping infrastructure")
+
+	o.log.Info("stopping infrastructure")
 
-	patterns := []string{
-		"lab.*vite",
-		"lab.*esbuild",
-		"pnpm.*dev",
+	if err := o.infra.Stop(ctx); err != nil {
+		spinner.Fail("Failed to stop infrastructure")
+
+		return fmt.Errorf("failed to stop infrastructure: %w", err)
 	}
 
-	for _, pattern := range patterns {
-		pkillCmd := exec.Command("pkill", "-KILL", "-f", pattern)
-		if err := pkillCmd.Run(); err != nil {
-			o.log.WithError(err).WithField("pattern", pattern).Debug("pkill found no matching processes")
-		}
+	spinner.Success("Infrastructure stopped; data preserved")
+
+	if err := o.markRuntimeStopped(); err != nil {
+		return fmt.Errorf("failed to update instance manifest: %w", err)
 	}
 
-	// Reset infrastructure (stops containers and removes volumes)
-	reportProgress(progress, "stop_infrastructure", "Stopping infrastructure...")
+	reportProgress(progress, "complete", "Stack stopped")
+
+	o.log.Info("stack stopped")
+
+	return nil
+}
+
+// Destroy removes all resources and generated state for the selected instance.
+func (o *Orchestrator) Destroy(ctx context.Context, progress ProgressFunc) error {
+	o.log.Info("destroying stack")
 
-	spinner = o.render.Task("Stopping infrastructure and removing volumes")
+	reportProgress(progress, "stop_services", "Stopping services...")
 
-	o.log.Info("resetting infrastructure")
+	spinner := o.render.Task("Stopping services")
+	if err := o.proc.StopAll(ctx); err != nil {
+		o.log.WithError(err).Warn("failed to stop services")
+		spinner.Warning("Services stopped (with warnings)")
+	} else {
+		spinner.Success("Services stopped")
+	}
 
-	if err := o.infra.Reset(ctx); err != nil {
-		spinner.Fail("Failed to reset infrastructure")
+	reportProgress(progress, "cleanup_orphans", "Cleaning up orphaned processes...")
+
+	spinner = o.render.Task("Cleaning up orphaned processes")
 
-		return fmt.Errorf("failed to reset infrastructure: %w", err)
+	orphanedCount := o.cleanupOrphanedProcesses()
+	if orphanedCount > 0 {
+		spinner.Success(fmt.Sprintf("Cleaned up %d orphaned processes", orphanedCount))
+	} else {
+		spinner.Success("No orphaned processes found")
 	}
 
-	spinner.Success("Infrastructure stopped and volumes removed")
+	reportProgress(progress, "destroy_infrastructure", "Destroying infrastructure...")
 
-	reportProgress(progress, "complete", "Stack stopped")
+	spinner = o.render.Task("Destroying infrastructure and volumes")
+	if err := o.infra.Destroy(ctx); err != nil {
+		spinner.Fail("Failed to destroy infrastructure")
+
+		return fmt.Errorf("failed to destroy infrastructure: %w", err)
+	}
+
+	spinner.Success("Infrastructure and volumes destroyed")
+
+	if o.runtime != nil && o.runtime.Manifest != nil {
+		reportProgress(progress, "remove_state", "Removing generated state...")
+
+		spinner = o.render.Task("Removing generated state")
+		if err := os.RemoveAll(o.runtime.Manifest.StateDir); err != nil {
+			spinner.Fail("Failed to remove generated state")
 
-	o.log.Info("teardown complete")
+			return fmt.Errorf("failed to remove generated state: %w", err)
+		}
+
+		spinner.Success("Generated state removed")
+
+		registry, err := o.runtimeRegistry()
+		if err != nil {
+			return err
+		}
+
+		if err := registry.Delete(o.runtime.Manifest); err != nil {
+			return err
+		}
+	}
+
+	reportProgress(progress, "complete", "Stack destroyed")
+	o.log.Info("stack destroyed")
 
 	return nil
 }
 
+// ResetRedis intentionally clears Redis data for the selected instance.
+func (o *Orchestrator) ResetRedis(ctx context.Context) error {
+	return o.infra.ResetRedis(ctx)
+}
+
 // StopServices stops all running services without tearing down infrastructure.
 // progress is an optional callback for reporting stop phase updates.
 // Pass nil to disable progress reporting (e.g. from CLI callers).
@@ -632,10 +946,19 @@ func (o *Orchestrator) RebuildObservability(ctx context.Context, service string)
 		return fmt.Errorf("observability is not enabled")
 	}
 
-	// Regenerate configs
-	configsDir := filepath.Join(o.stateDir, "configs")
+	if err := o.regenerateObservabilityConfig(service); err != nil {
+		return err
+	}
 
-	generator := configgen.NewGenerator(o.log, o.cfg)
+	// Restart the service
+	return o.infra.RestartObservabilityService(ctx, service)
+}
+
+func (o *Orchestrator) regenerateObservabilityConfig(service string) error {
+	generator, configsDir, userStateDir := o.observabilityConfigGenerator()
+	if err := os.MkdirAll(configsDir, 0755); err != nil {
+		return fmt.Errorf("failed to create configs directory: %w", err)
+	}
 
 	switch service {
 	case constants.ServicePrometheus:
@@ -648,7 +971,7 @@ func (o *Orchestrator) RebuildObservability(ctx context.Context, service string)
 	case constants.ServiceGrafana:
 		o.log.Info("regenerating Grafana provisioning")
 
-		if err := generator.GenerateGrafanaProvisioning(configsDir, o.stateDir); err != nil {
+		if err := generator.GenerateGrafanaProvisioning(configsDir, userStateDir); err != nil {
 			return fmt.Errorf("failed to generate Grafana provisioning: %w", err)
 		}
 
@@ -656,8 +979,22 @@ func (o *Orchestrator) RebuildObservability(ctx context.Context, service string)
 		return fmt.Errorf("unknown observability service: %s", service)
 	}
 
-	// Restart the service
-	return o.infra.RestartObservabilityService(ctx, service)
+	return nil
+}
+
+func (o *Orchestrator) observabilityConfigGenerator() (*configgen.Generator, string, string) {
+	if o.runtime != nil && o.runtime.Manifest != nil {
+		configsDir := filepath.Join(o.runtime.Manifest.StateDir, constants.DirConfigs)
+
+		userStateDir := o.stateDir
+		if o.runtime.Workspace != nil && o.runtime.Workspace.StateDir != "" {
+			userStateDir = o.runtime.Workspace.StateDir
+		}
+
+		return configgen.NewRuntimeGenerator(o.log, o.runtime), configsDir, userStateDir
+	}
+
+	return configgen.NewGenerator(o.log, o.cfg), filepath.Join(o.stateDir, constants.DirConfigs), o.stateDir
 }
 
 // StartService starts a specific service by name.
@@ -901,7 +1238,7 @@ func (o *Orchestrator) Status(ctx context.Context) error {
 			}
 		}
 
-		fmt.Println("\nRun 'xcli lab down' to clean up orphaned processes")
+		fmt.Println("\nRun 'xcli lab stop' to stop the selected instance")
 	}
 
 	return nil
@@ -910,6 +1247,12 @@ func (o *Orchestrator) Status(ctx context.Context) error {
 // GenerateConfigs generates configuration files for all services.
 // Public method so it can be called by rebuild commands.
 func (o *Orchestrator) GenerateConfigs(ctx context.Context) error {
+	if o.runtime != nil {
+		_, err := configgen.NewRuntimeGenerator(o.log, o.runtime).GenerateRuntimeConfigs()
+
+		return err
+	}
+
 	configsDir := filepath.Join(o.stateDir, "configs")
 	if err := os.MkdirAll(configsDir, 0755); err != nil {
 		return fmt.Errorf("failed to create configs directory: %w", err)
@@ -1037,8 +1380,8 @@ func (o *Orchestrator) WaitForCBTAPIReady(ctx context.Context) error {
 		return fmt.Errorf("no networks enabled")
 	}
 
-	// Use the first enabled network's cbt-api
-	port := o.cfg.GetCBTAPIPort(networks[0].Name)
+	// Use the first enabled network's cbt-api.
+	port := o.networkPortPlan(networks[0].Name).CBTAPI
 	healthURL := fmt.Sprintf("http://localhost:%d/health", port)
 
 	// Retry for up to 30 seconds
@@ -1167,18 +1510,9 @@ func (o *Orchestrator) checkGitStatus(ctx context.Context) {
 
 	checker := git.NewChecker(o.log)
 
-	// Build map of repositories to check
-	repos := map[string]string{
-		"cbt":                    o.cfg.Repos.CBT,
-		"xatu-cbt":               o.cfg.Repos.XatuCBT,
-		"cbt-api":                o.cfg.Repos.CBTAPI,
-		constants.RepoLabBackend: o.cfg.Repos.LabBackend,
-		"lab":                    o.cfg.Repos.Lab,
-	}
-
 	o.log.Info("checking git status for all repositories")
 
-	statuses := checker.CheckRepositories(ctx, repos)
+	statuses := checker.CheckRepositories(ctx, o.cfg.Repos.Map())
 
 	// Check if any repos are out of date
 	hasOutOfDateRepos := false
@@ -1263,15 +1597,7 @@ func (o *Orchestrator) validatePrerequisites(ctx context.Context) error {
 	o.log.Info("validating prerequisites")
 
 	// Check that all required repositories exist
-	requiredRepos := map[string]string{
-		"cbt":                    o.cfg.Repos.CBT,
-		"xatu-cbt":               o.cfg.Repos.XatuCBT,
-		"cbt-api":                o.cfg.Repos.CBTAPI,
-		constants.RepoLabBackend: o.cfg.Repos.LabBackend,
-		"lab":                    o.cfg.Repos.Lab,
-	}
-
-	for repoName, repoPath := range requiredRepos {
+	for repoName, repoPath := range o.cfg.Repos.Map() {
 		if repoPath == "" {
 			return fmt.Errorf("repository %s not configured", repoName)
 		}
@@ -1302,28 +1628,49 @@ func (o *Orchestrator) validatePrerequisites(ctx context.Context) error {
 	return nil
 }
 
+func (o *Orchestrator) portPlan() instance.PortPlan {
+	if o.runtime != nil {
+		return o.runtime.Ports
+	}
+
+	plan, err := instance.BuildPortPlan(o.cfg, 0)
+	if err != nil {
+		o.log.WithError(err).Warn("failed to build fallback port plan")
+
+		return instance.PortPlan{}
+	}
+
+	return plan
+}
+
+func (o *Orchestrator) networkPortPlan(network string) instance.NetworkPortPlan {
+	plan := o.portPlan()
+	if ports, ok := plan.Networks[network]; ok {
+		return ports
+	}
+
+	return instance.NetworkPortPlan{}
+}
+
 // checkPortConflicts checks if any ports needed by services are already in use.
 func (o *Orchestrator) checkPortConflicts() []portutil.PortConflict {
 	enabledNetworks := o.cfg.EnabledNetworks()
 	portsToCheck := make([]int, 0, 2+4*len(enabledNetworks))
+	plan := o.portPlan()
 
 	// Lab backend and frontend ports
-	portsToCheck = append(portsToCheck, o.cfg.Ports.LabBackend)
-	portsToCheck = append(portsToCheck, o.cfg.Ports.LabFrontend)
+	portsToCheck = append(portsToCheck, plan.LabBackend)
+	portsToCheck = append(portsToCheck, plan.LabFrontend)
 
 	// CBT, CBT API, and CBT frontend ports for each enabled network
-	for i, network := range enabledNetworks {
-		// CBT API service port
-		portsToCheck = append(portsToCheck, o.cfg.GetCBTAPIPort(network.Name))
-
-		// CBT frontend port
-		portsToCheck = append(portsToCheck, o.cfg.GetCBTFrontendPort(network.Name))
-
-		// CBT metrics port (9100 + network index)
-		portsToCheck = append(portsToCheck, 9100+i)
-
-		// CBT API metrics port (9200 + network index)
-		portsToCheck = append(portsToCheck, 9200+i)
+	for _, network := range enabledNetworks {
+		networkPorts := o.networkPortPlan(network.Name)
+		portsToCheck = append(portsToCheck,
+			networkPorts.CBTAPI,
+			networkPorts.CBTFrontend,
+			networkPorts.CBTMetrics,
+			networkPorts.CBTAPIMetrics,
+		)
 	}
 
 	return portutil.CheckPorts(portsToCheck)
@@ -1398,11 +1745,13 @@ func (o *Orchestrator) cleanupOrphanedProcessesForService(service string) {
 
 // getServicePorts returns the port(s) used by a service.
 func (o *Orchestrator) getServicePorts(service string) []int {
+	plan := o.portPlan()
+
 	switch service {
 	case "lab-frontend":
-		return []int{o.cfg.Ports.LabFrontend}
+		return []int{plan.LabFrontend}
 	case constants.ServiceLabBackend:
-		port := o.cfg.Ports.LabBackend
+		port := plan.LabBackend
 		if p := o.readConfigPort(constants.ConfigFileLabBackend); p != 0 {
 			port = p
 		}
@@ -1410,23 +1759,24 @@ func (o *Orchestrator) getServicePorts(service string) []int {
 		return []int{port}
 	default:
 		// Check if it's a CBT or CBT-API service
-		for i, network := range o.cfg.EnabledNetworks() {
+		for _, network := range o.cfg.EnabledNetworks() {
+			networkPorts := o.networkPortPlan(network.Name)
 			if service == "cbt-"+network.Name {
-				fePort := o.cfg.GetCBTFrontendPort(network.Name)
+				fePort := networkPorts.CBTFrontend
 				if p := o.readConfigPort(fmt.Sprintf(constants.ConfigFileCBT, network.Name)); p != 0 {
 					fePort = p
 				}
 
-				return []int{9100 + i, fePort}
+				return []int{networkPorts.CBTMetrics, fePort}
 			}
 
 			if service == "cbt-api-"+network.Name {
-				port := o.cfg.GetCBTAPIPort(network.Name)
+				port := networkPorts.CBTAPI
 				if p := o.readConfigPort(fmt.Sprintf(constants.ConfigFileCBTAPI, network.Name)); p != 0 {
 					port = p
 				}
 
-				return []int{port, 9200 + i}
+				return []int{port, networkPorts.CBTAPIMetrics}
 			}
 		}
 	}
@@ -1436,25 +1786,28 @@ func (o *Orchestrator) getServicePorts(service string) []int {
 
 // getServiceURL returns the URL for a service based on its name.
 func (o *Orchestrator) getServiceURL(service string) string {
+	plan := o.portPlan()
+
 	switch service {
 	case constants.ServiceLabFrontend:
-		return fmt.Sprintf("http://localhost:%d", o.cfg.Ports.LabFrontend)
+		return fmt.Sprintf("http://localhost:%d", plan.LabFrontend)
 	case constants.ServiceLabBackend:
-		port := o.cfg.Ports.LabBackend
+		port := plan.LabBackend
 		if p := o.readConfigPort(constants.ConfigFileLabBackend); p != 0 {
 			port = p
 		}
 
 		return fmt.Sprintf("http://localhost:%d", port)
 	case constants.ServicePrometheus:
-		return fmt.Sprintf("http://localhost:%d", o.cfg.Infrastructure.Observability.PrometheusPort)
+		return fmt.Sprintf("http://localhost:%d", plan.Prometheus)
 	case constants.ServiceGrafana:
-		return fmt.Sprintf("http://localhost:%d", o.cfg.Infrastructure.Observability.GrafanaPort)
+		return fmt.Sprintf("http://localhost:%d", plan.Grafana)
 	default:
 		// Check if it's a CBT or CBT-API service
 		for _, network := range o.cfg.EnabledNetworks() {
+			networkPorts := o.networkPortPlan(network.Name)
 			if service == constants.ServiceNameCBT(network.Name) {
-				fePort := o.cfg.GetCBTFrontendPort(network.Name)
+				fePort := networkPorts.CBTFrontend
 				if p := o.readConfigPort(fmt.Sprintf(constants.ConfigFileCBT, network.Name)); p != 0 {
 					fePort = p
 				}
@@ -1463,7 +1816,7 @@ func (o *Orchestrator) getServiceURL(service string) string {
 			}
 
 			if service == constants.ServiceNameCBTAPI(network.Name) {
-				port := o.cfg.GetCBTAPIPort(network.Name)
+				port := networkPorts.CBTAPI
 				if p := o.readConfigPort(fmt.Sprintf(constants.ConfigFileCBTAPI, network.Name)); p != 0 {
 					port = p
 				}
@@ -1702,9 +2055,24 @@ func (o *Orchestrator) startLabFrontend(ctx context.Context) error {
 		}
 	}
 
-	cmd := exec.CommandContext(ctx, "pnpm", "dev")
+	plan := o.portPlan()
+	//nolint:gosec // G204: args are internally constructed, not user input
+	cmd := exec.CommandContext(
+		ctx,
+		"pnpm",
+		"dev",
+		"--",
+		"--host",
+		"0.0.0.0",
+		"--port",
+		strconv.Itoa(plan.LabFrontend),
+	)
 	cmd.Dir = o.cfg.Repos.Lab
-	cmd.Env = os.Environ()
+
+	cmd.Env = append(
+		os.Environ(),
+		fmt.Sprintf("BACKEND=http://localhost:%d", plan.LabBackend),
+	)
 
 	return o.proc.Start(ctx, constants.ServiceLabFrontend, cmd, nil)
 }
diff --git a/pkg/orchestrator/orchestrator_test.go b/pkg/orchestrator/orchestrator_test.go
new file mode 100644
index 0000000..c947b0b
--- /dev/null
+++ b/pkg/orchestrator/orchestrator_test.go
@@ -0,0 +1,378 @@
+package orchestrator
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
+	"github.com/ethpandaops/xcli/pkg/instance"
+	"github.com/ethpandaops/xcli/pkg/process"
+	"github.com/ethpandaops/xcli/pkg/workspace"
+	"github.com/sirupsen/logrus"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewOrchestratorWithRuntimeUsesInstanceStateAndDockerPlan(t *testing.T) {
+	rootDir := t.TempDir()
+	configPath := filepath.Join(rootDir, config.DefaultConfigFileName)
+	stateDir := instance.InstanceStateDir(rootDir, "gamma")
+	dockerPlan := instance.NewDockerPlan("gamma", configPath)
+	runtime := &instance.Runtime{
+		LabConfig: testRuntimeLabConfig(),
+		Docker:    dockerPlan,
+		Manifest: &instance.Manifest{
+			ConfigPath: configPath,
+			StateDir:   stateDir,
+			Docker:     dockerPlan,
+		},
+		Ports: instance.PortPlan{
+			Prometheus: 19090,
+			Grafana:    13000,
+		},
+	}
+
+	orch, err := NewOrchestratorWithRuntime(logrus.New(), runtime)
+	require.NoError(t, err)
+	require.Equal(t, stateDir, orch.StateDir())
+
+	containerName, ok := orch.InfrastructureManager().DockerContainerName(constants.ServicePrometheus)
+	require.True(t, ok)
+	require.Equal(t, "xcli-gamma-prometheus", containerName)
+}
+
+func TestFinalizeRuntimeManifestWritesRunningInstance(t *testing.T) {
+	ctx := context.Background()
+	runtime := newOrchestratorTestRuntime(t, "theta", 1)
+
+	orch, err := NewOrchestratorWithRuntime(logrus.New(), runtime)
+	require.NoError(t, err)
+
+	orch.proc = &fakeProcessManager{
+		processes: []*process.Process{
+			{Name: constants.ServiceLabBackend, PID: 1234},
+			{Name: constants.ServiceLabFrontend, PID: 5678},
+		},
+	}
+
+	require.NoError(t, orch.finalizeRuntimeManifest(ctx))
+
+	loaded, err := runtime.Registry.Load(runtime.InstanceID)
+	require.NoError(t, err)
+	require.Equal(t, instance.StatusRunning, loaded.Status)
+	require.Equal(t, runtime.Ports.LabBackend, loaded.Ports.LabBackend)
+	require.Equal(t, runtime.Docker.ProjectName, loaded.Docker.ProjectName)
+	require.Equal(t, 1234, loaded.PIDs[constants.ServiceLabBackend])
+	require.Equal(
+		t,
+		"http://localhost:6173",
+		loaded.URLs[constants.ServiceLabFrontend],
+	)
+	require.Equal(
+		t,
+		"http://localhost:9080",
+		loaded.URLs[constants.ServiceLabBackend],
+	)
+	require.Equal(
+		t,
+		"http://localhost:10090",
+		loaded.URLs[constants.ServicePrometheus],
+	)
+	require.Equal(
+		t,
+		"http://localhost:20280",
+		loaded.URLs["command-center"],
+	)
+
+	for _, repo := range []string{
+		constants.RepoCBT,
+		constants.RepoXatuCBT,
+		constants.RepoCBTAPI,
+		constants.RepoLabBackend,
+		constants.RepoLab,
+	} {
+		version := loaded.Repos[repo]
+		require.NotEmpty(t, version.Path)
+		require.NotEmpty(t, version.Branch)
+		require.NotEmpty(t, version.Commit)
+		assert.False(t, version.Dirty)
+	}
+
+	_, err = os.Stat(instance.LocalManifestPath(runtime.Workspace.RootDir, runtime.InstanceID))
+	require.NoError(t, err)
+}
+
+func TestMarkRuntimeStoppedPersistsStoppedManifest(t *testing.T) {
+	runtime := newOrchestratorTestRuntime(t, "stopped", 0)
+	runtime.Manifest.Status = instance.StatusRunning
+	runtime.Manifest.PIDs = map[string]int{constants.ServiceLabBackend: 1234}
+	require.NoError(t, runtime.Registry.Save(runtime.Manifest))
+
+	orch, err := NewOrchestratorWithRuntime(logrus.New(), runtime)
+	require.NoError(t, err)
+
+	require.NoError(t, orch.markRuntimeStopped())
+
+	loaded, err := runtime.Registry.Load(runtime.InstanceID)
+	require.NoError(t, err)
+	require.Equal(t, instance.StatusStopped, loaded.Status)
+	require.Empty(t, loaded.PIDs)
+}
+
+func TestReleaseRuntimeReservationMarksStoppedWithLastError(t *testing.T) {
+	runtime := newOrchestratorTestRuntime(t, "reserved-fail", 0)
+	runtime.Manifest.Status = instance.StatusReserved
+	require.NoError(t, runtime.Registry.Save(runtime.Manifest))
+
+	orch, err := NewOrchestratorWithRuntime(logrus.New(), runtime)
+	require.NoError(t, err)
+
+	require.NoError(t, orch.releaseRuntimeReservation(assert.AnError))
+
+	loaded, err := runtime.Registry.Load(runtime.InstanceID)
+	require.NoError(t, err)
+	require.Equal(t, instance.StatusStopped, loaded.Status)
+	require.Contains(t, loaded.LastError, assert.AnError.Error())
+	require.Empty(t, loaded.PIDs)
+}
+
+func TestReleaseRuntimeReservationIgnoresTransientInMemoryRunningStatus(t *testing.T) {
+	runtime := newOrchestratorTestRuntime(t, "reserved-status-flipped", 0)
+	runtime.Manifest.Status = instance.StatusReserved
+	require.NoError(t, runtime.Registry.Save(runtime.Manifest))
+	runtime.Manifest.Status = instance.StatusRunning
+
+	orch, err := NewOrchestratorWithRuntime(logrus.New(), runtime)
+	require.NoError(t, err)
+
+	require.NoError(t, orch.releaseRuntimeReservation(assert.AnError))
+
+	loaded, err := runtime.Registry.Load(runtime.InstanceID)
+	require.NoError(t, err)
+	require.Equal(t, instance.StatusStopped, loaded.Status)
+	require.Contains(t, loaded.LastError, assert.AnError.Error())
+}
+
+func TestRuntimePortsDriveFrontendCommand(t *testing.T) {
+	ctx := context.Background()
+	runtime := newOrchestratorTestRuntime(t, "lambda", 1)
+	require.NoError(t, os.MkdirAll(filepath.Join(runtime.LabConfig.Repos.Lab, "node_modules"), 0755))
+
+	binDir := t.TempDir()
+	pnpmPath := filepath.Join(binDir, "pnpm")
+	require.NoError(t, os.WriteFile(pnpmPath, []byte("#!/bin/sh\nexit 0\n"), 0755))
+	t.Setenv("PATH", binDir+string(os.PathListSeparator)+os.Getenv("PATH"))
+
+	orch, err := NewOrchestratorWithRuntime(logrus.New(), runtime)
+	require.NoError(t, err)
+
+	fakeProc := &fakeProcessManager{}
+	orch.proc = fakeProc
+
+	require.NoError(t, orch.startLabFrontend(ctx))
+	require.NotNil(t, fakeProc.lastCmd)
+	require.Equal(t, runtime.LabConfig.Repos.Lab, fakeProc.lastCmd.Dir)
+	require.Equal(t, constants.ServiceLabFrontend, fakeProc.lastName)
+	require.Contains(t, strings.Join(fakeProc.lastCmd.Args, " "), "--port 6173")
+	require.Contains(t, fakeProc.lastCmd.Env, "BACKEND=http://localhost:9080")
+}
+
+func TestRebuildObservabilityRegeneratesRuntimePorts(t *testing.T) {
+	runtime := newOrchestratorTestRuntime(t, "observability-runtime", 1)
+	orch, err := NewOrchestratorWithRuntime(logrus.New(), runtime)
+	require.NoError(t, err)
+
+	require.NoError(t, orch.regenerateObservabilityConfig(constants.ServicePrometheus))
+	require.NoError(t, orch.regenerateObservabilityConfig(constants.ServiceGrafana))
+
+	prometheusConfig, err := os.ReadFile(filepath.Join(runtime.Manifest.StateDir, constants.DirConfigs, "prometheus.yml"))
+	require.NoError(t, err)
+	require.Contains(t, string(prometheusConfig), fmt.Sprintf("host.docker.internal:%d", runtime.Ports.LabBackend))
+	require.Contains(t, string(prometheusConfig), fmt.Sprintf("host.docker.internal:%d", runtime.Ports.Networks["mainnet"].CBTMetrics))
+	require.NotContains(t, string(prometheusConfig), "host.docker.internal:8080")
+	require.NotContains(t, string(prometheusConfig), "host.docker.internal:9100")
+
+	datasourceConfig, err := os.ReadFile(filepath.Join(
+		runtime.Manifest.StateDir,
+		constants.DirConfigs,
+		"grafana",
+		"provisioning",
+		"datasources",
+		"datasource.yml",
+	))
+	require.NoError(t, err)
+	require.Contains(t, string(datasourceConfig), fmt.Sprintf("host.docker.internal:%d", runtime.Ports.Prometheus))
+	require.NotContains(t, string(datasourceConfig), "host.docker.internal:9090")
+}
+
+func testRuntimeLabConfig() *config.LabConfig {
+	return &config.LabConfig{
+		Mode: constants.ModeHybrid,
+		Repos: config.LabReposConfig{
+			CBT:        "/tmp/cbt",
+			XatuCBT:    "/tmp/xatu-cbt",
+			CBTAPI:     "/tmp/cbt-api",
+			LabBackend: "/tmp/lab-backend",
+			Lab:        "/tmp/lab",
+		},
+		Networks: []config.NetworkConfig{
+			{Name: "mainnet", Enabled: true},
+		},
+		Infrastructure: config.InfrastructureConfig{
+			ClickHouse: config.ClickHouseConfig{
+				Xatu: config.ClickHouseClusterConfig{
+					Mode:        constants.InfraModeExternal,
+					ExternalURL: "http://example.invalid:9000",
+				},
+				CBT: config.ClickHouseClusterConfig{Mode: constants.InfraModeLocal},
+			},
+			Observability: config.ObservabilityConfig{
+				Enabled:        true,
+				PrometheusPort: 9090,
+				GrafanaPort:    3000,
+			},
+			ClickHouseCBTPort: 8123,
+			RedisPort:         6380,
+		},
+		Ports: config.LabPortsConfig{
+			LabBackend:      8080,
+			LabFrontend:     5173,
+			CBTBase:         8081,
+			CBTAPIBase:      8091,
+			CBTFrontendBase: 8085,
+		},
+	}
+}
+
+func newOrchestratorTestRuntime(t *testing.T, instanceID string, slot int) *instance.Runtime {
+	t.Helper()
+
+	rootDir := t.TempDir()
+	reposDir := filepath.Join(rootDir, "repos")
+	cfg := testRuntimeLabConfig()
+	cfg.Repos = config.LabReposConfig{
+		CBT:        filepath.Join(reposDir, constants.RepoCBT),
+		XatuCBT:    filepath.Join(reposDir, constants.RepoXatuCBT),
+		CBTAPI:     filepath.Join(reposDir, constants.RepoCBTAPI),
+		LabBackend: filepath.Join(reposDir, constants.RepoLabBackend),
+		Lab:        filepath.Join(reposDir, constants.RepoLab),
+	}
+
+	for _, path := range []string{
+		cfg.Repos.CBT,
+		cfg.Repos.XatuCBT,
+		cfg.Repos.CBTAPI,
+		cfg.Repos.LabBackend,
+		cfg.Repos.Lab,
+	} {
+		initTestGitRepo(t, path)
+	}
+
+	configPath := filepath.Join(rootDir, config.DefaultConfigFileName)
+	require.NoError(t, os.WriteFile(configPath, []byte("lab: {}\n"), 0644))
+
+	ws := &workspace.Workspace{
+		RootDir:       rootDir,
+		ConfigPath:    configPath,
+		OverridesPath: filepath.Join(rootDir, constants.CBTOverridesFile),
+		StateDir:      filepath.Join(rootDir, ".xcli"),
+	}
+
+	manifest, err := instance.NewManifest(context.Background(), ws, cfg, instanceID)
+	require.NoError(t, err)
+
+	ports, err := instance.BuildPortPlan(cfg, slot)
+	require.NoError(t, err)
+
+	dockerPlan := instance.NewDockerPlan(manifest.InstanceID, manifest.ConfigPath)
+	manifest.Ports = ports
+	manifest.Docker = dockerPlan
+
+	return &instance.Runtime{
+		Workspace:  ws,
+		LabConfig:  cfg,
+		Registry:   instance.NewRegistry(filepath.Join(t.TempDir(), "instances")),
+		InstanceID: manifest.InstanceID,
+		Manifest:   manifest,
+		Ports:      ports,
+		Docker:     dockerPlan,
+		Repos:      manifest.Repos,
+	}
+}
+
+func initTestGitRepo(t *testing.T, path string) {
+	t.Helper()
+
+	require.NoError(t, os.MkdirAll(path, 0755))
+	runGit(t, path, "init")
+	runGit(t, path, "config", "commit.gpgsign", "false")
+	runGit(t, path, "config", "user.email", "xcli-test@example.invalid")
+	runGit(t, path, "config", "user.name", "xcli test")
+	require.NoError(t, os.WriteFile(filepath.Join(path, "README.md"), []byte("# test\n"), 0644))
+	runGit(t, path, "add", "README.md")
+	runGit(t, path, "commit", "-m", "initial")
+}
+
+func runGit(t *testing.T, dir string, args ...string) {
+	t.Helper()
+
+	cmd := exec.Command("git", args...)
+	cmd.Dir = dir
+	out, err := cmd.CombinedOutput()
+	require.NoError(t, err, string(out))
+}
+
+type fakeProcessManager struct {
+	processes []*process.Process
+	lastName  string
+	lastCmd   *exec.Cmd
+}
+
+func (f *fakeProcessManager) Start(
+	_ context.Context,
+	name string,
+	cmd *exec.Cmd,
+	_ process.HealthChecker,
+) error {
+	f.lastName = name
+	f.lastCmd = cmd
+	f.processes = append(f.processes, &process.Process{
+		Name:    name,
+		Cmd:     cmd,
+		PID:     9999,
+		Started: time.Now(),
+	})
+
+	return nil
+}
+
+func (f *fakeProcessManager) Stop(context.Context, string) error { return nil }
+func (f *fakeProcessManager) StopAll(context.Context) error      { return nil }
+func (f *fakeProcessManager) Restart(context.Context, string) error {
+	return nil
+}
+func (f *fakeProcessManager) List() []*process.Process { return f.processes }
+func (f *fakeProcessManager) Get(name string) (*process.Process, bool) {
+	for _, proc := range f.processes {
+		if proc.Name == name {
+			return proc, true
+		}
+	}
+
+	return nil, false
+}
+func (f *fakeProcessManager) IsRunning(name string) bool {
+	_, ok := f.Get(name)
+
+	return ok
+}
+func (f *fakeProcessManager) ReloadPIDs()                                  {}
+func (f *fakeProcessManager) TailLogs(context.Context, string, bool) error { return nil }
+func (f *fakeProcessManager) CleanLogs() error                             { return nil }
diff --git a/pkg/portutil/portutil.go b/pkg/portutil/portutil.go
index fdca779..a328e79 100644
--- a/pkg/portutil/portutil.go
+++ b/pkg/portutil/portutil.go
@@ -69,7 +69,7 @@ func FormatConflicts(conflicts []PortConflict) string {
 	}
 
 	sb.WriteString("\nTo fix this:\n")
-	sb.WriteString("  1. Run 'xcli lab down' to clean up\n")
+	sb.WriteString("  1. Run 'xcli lab stop' to stop the selected instance\n")
 
 	if len(conflicts) > 0 && conflicts[0].PID > 0 {
 		sb.WriteString("  2. Or manually kill processes: ")
diff --git a/pkg/stack/commands.go b/pkg/stack/commands.go
index bec7f26..2fefeaa 100644
--- a/pkg/stack/commands.go
+++ b/pkg/stack/commands.go
@@ -88,7 +88,7 @@ func NewDownCommand(s Stack) *cobra.Command {
 func NewCleanCommand(s Stack) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   cmdClean,
-		Short: fmt.Sprintf("Remove all %s containers and artifacts", s.Name()),
+		Short: fmt.Sprintf("Stop the %s stack without deleting data", s.Name()),
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return s.Clean(cmd.Context())
 		},
@@ -190,12 +190,17 @@ func NewStartCommand(s Stack) *cobra.Command {
 // NewStopCommand creates the stop subcommand for a stack.
 func NewStopCommand(s Stack) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:               "stop <service>",
-		Short:             fmt.Sprintf("Stop a specific %s service", s.Name()),
-		Args:              cobra.ExactArgs(1),
+		Use:               "stop [service]",
+		Short:             fmt.Sprintf("Stop the %s stack or a specific service", s.Name()),
+		Args:              cobra.MaximumNArgs(1),
 		ValidArgsFunction: s.CompleteServices(),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return s.Stop(cmd.Context(), args[0])
+			service := ""
+			if len(args) > 0 {
+				service = args[0]
+			}
+
+			return s.Stop(cmd.Context(), service)
 		},
 	}
 
diff --git a/pkg/stack/lab.go b/pkg/stack/lab.go
index 50591a3..4a8c0dc 100644
--- a/pkg/stack/lab.go
+++ b/pkg/stack/lab.go
@@ -16,10 +16,12 @@ import (
 	"github.com/ethpandaops/xcli/pkg/constants"
 	"github.com/ethpandaops/xcli/pkg/diagnostic"
 	"github.com/ethpandaops/xcli/pkg/discovery"
+	"github.com/ethpandaops/xcli/pkg/instance"
 	"github.com/ethpandaops/xcli/pkg/orchestrator"
 	"github.com/ethpandaops/xcli/pkg/prerequisites"
 	"github.com/ethpandaops/xcli/pkg/ui"
 	"github.com/ethpandaops/xcli/pkg/version"
+	"github.com/ethpandaops/xcli/pkg/workspace"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 )
@@ -30,22 +32,141 @@ const repoLabFrontend = "lab-frontend"
 
 // labStack implements Stack for the lab development environment.
 type labStack struct {
-	log        logrus.FieldLogger
-	configPath string
+	log              logrus.FieldLogger
+	configPath       string
+	instanceOverride *string
 
 	// Flag values bound during ConfigureCommand.
 	upMode         string
 	upVerbose      bool
 	rebuildVerbose bool
+	statusAll      bool
 }
 
 // NewLabStack creates a new lab stack instance.
-func NewLabStack(log logrus.FieldLogger, configPath string) Stack {
-	return &labStack{log: log, configPath: configPath}
+func NewLabStack(log logrus.FieldLogger, configPath string, instanceOverride *string) *labStack {
+	return &labStack{log: log, configPath: configPath, instanceOverride: instanceOverride}
 }
 
 func (s *labStack) Name() string { return constants.RepoLab }
 
+func (s *labStack) loadLabConfig(checkCWDOverrides bool) (*config.LabConfig, *workspace.Workspace, error) {
+	return workspace.LoadLabConfig(s.configPath, checkCWDOverrides)
+}
+
+func printRuntimeSelection(runtime *instance.Runtime) {
+	if runtime == nil || runtime.Manifest == nil {
+		return
+	}
+
+	ui.Info(fmt.Sprintf("Instance: %s", runtime.InstanceID))
+	ui.Info(fmt.Sprintf("Config: %s", runtime.Manifest.ConfigPath))
+	ui.Info(fmt.Sprintf("Overrides: %s", runtime.Manifest.OverridesPath))
+	ui.Info(fmt.Sprintf("State dir: %s", runtime.Manifest.StateDir))
+}
+
+func (s *labStack) instanceOverrideValue() string {
+	if s.instanceOverride == nil {
+		return ""
+	}
+
+	return strings.TrimSpace(*s.instanceOverride)
+}
+
+func (s *labStack) loadLifecycleRuntime() (*instance.Runtime, error) {
+	if override := s.instanceOverrideValue(); override != "" {
+		return s.loadLifecycleRuntimeByID(override)
+	}
+
+	labCfg, ws, err := s.loadLabConfig(true)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config: %w", err)
+	}
+
+	instanceID, err := instance.ResolveID(ws, labCfg, "")
+	if err != nil {
+		return nil, err
+	}
+
+	registry, err := instance.DefaultRegistry()
+	if err != nil {
+		return nil, err
+	}
+
+	manifest, err := registry.Load(instanceID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load instance %q manifest: %w", instanceID, err)
+	}
+
+	return instance.NewRuntimeFromManifest(manifest, labCfg, ws, registry)
+}
+
+func (s *labStack) loadLifecycleRuntimeByID(instanceID string) (*instance.Runtime, error) {
+	instanceID, err := instance.SanitizeID(instanceID)
+	if err != nil {
+		return nil, err
+	}
+
+	registry, err := instance.DefaultRegistry()
+	if err != nil {
+		return nil, err
+	}
+
+	manifest, err := registry.Load(instanceID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load instance %q manifest: %w", instanceID, err)
+	}
+
+	runtime, err := instance.NewRuntimeFromManifestConfig(context.Background(), manifest, registry)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config for instance %q: %w", instanceID, err)
+	}
+
+	return runtime, nil
+}
+
+type lifecycleRuntimeMode int
+
+const (
+	lifecycleRuntimeSelected lifecycleRuntimeMode = iota
+	lifecycleRuntimeRequiredID
+)
+
+func (s *labStack) withRuntimeOrchestrator(
+	_ context.Context,
+	mode lifecycleRuntimeMode,
+	fn func(*instance.Runtime, *orchestrator.Orchestrator) error,
+) error {
+	var (
+		runtime *instance.Runtime
+		err     error
+	)
+
+	switch mode {
+	case lifecycleRuntimeSelected:
+		runtime, err = s.loadLifecycleRuntime()
+	case lifecycleRuntimeRequiredID:
+		if s.instanceOverrideValue() == "" {
+			return fmt.Errorf("requires --instance <id>")
+		}
+
+		runtime, err = s.loadLifecycleRuntimeByID(s.instanceOverrideValue())
+	default:
+		return fmt.Errorf("unknown lifecycle runtime mode: %d", mode)
+	}
+
+	if err != nil {
+		return err
+	}
+
+	orch, err := orchestrator.NewOrchestratorWithRuntime(s.log, runtime)
+	if err != nil {
+		return fmt.Errorf("failed to create orchestrator: %w", err)
+	}
+
+	return fn(runtime, orch)
+}
+
 // ConfigureCommand adds lab-specific flags and descriptions to commands.
 func (s *labStack) ConfigureCommand(name string, cmd *cobra.Command) {
 	switch name {
@@ -115,7 +236,7 @@ Examples:
 This will:
   - Stop all application services (CBT, cbt-api, lab-backend, frontend)
   - Stop infrastructure (ClickHouse, Redis)
-  - Remove Docker containers and volumes
+  - Preserve ClickHouse, Redis, Prometheus, and Grafana data volumes
 
 The stack can be restarted with 'xcli lab up'.
 
@@ -123,33 +244,13 @@ Example:
   xcli lab down`
 
 	case cmdClean:
-		cmd.Long = `Completely clean the lab workspace by removing all generated artifacts.
+		cmd.Long = `Stop the selected lab instance without deleting data.
 
-This will:
-  - Stop and remove all Docker containers
-  - Remove Docker volumes (data will be lost!)
-  - Delete generated configuration files (.xcli/ directory)
-  - Remove build artifacts (binaries in each repo)
-  - Clean proto-generated files
-
-Warning: This is a destructive operation!
-  - All data in ClickHouse and Redis will be lost
-  - You will need to rebuild with 'xcli lab build' or 'xcli lab up'
-  - Generated configs will need to be recreated
-
-This does NOT remove:
-  - Source code or repositories
-  - Your .xcli.yaml configuration file
-  - node_modules or other dependencies
-
-Use cases:
-  - Starting completely fresh after config changes
-  - Clearing disk space
-  - Troubleshooting persistent issues
-  - Switching between major configuration changes
+This is a non-destructive alias for 'xcli lab down'. Use
+'xcli lab destroy --instance <id>' when you intentionally want to remove data.
 
-Examples:
-  xcli lab clean                   # Remove all containers, volumes, and build artifacts`
+Example:
+  xcli lab clean`
 
 	case cmdBuild:
 		cmd.Long = `Build all lab projects from source without starting services.
@@ -236,6 +337,7 @@ Examples:
 Note: All rebuild commands automatically restart their respective services if running.`
 
 	case cmdStatus:
+		cmd.Flags().BoolVar(&s.statusAll, "all", false, "Show all lab instances")
 		cmd.Long = `Display status of all lab services and infrastructure.
 
 Shows:
@@ -264,7 +366,9 @@ Example:
   xcli lab start cbt-mainnet`
 
 	case cmdStop:
-		cmd.Long = `Stop a specific lab service.
+		cmd.Long = `Stop the selected lab instance or a specific lab service.
+
+Without a service name this is equivalent to 'xcli lab down' and preserves data.
 
 Available services:
   - lab-backend
@@ -273,6 +377,7 @@ Available services:
   - cbt-api-<network>    (e.g., cbt-api-mainnet, cbt-api-sepolia)
 
 Example:
+  xcli lab stop
   xcli lab stop lab-backend
   xcli lab stop cbt-mainnet`
 
@@ -291,12 +396,12 @@ func (s *labStack) CompleteServices() ValidArgsFunc {
 		log := logrus.New()
 		log.SetOutput(io.Discard)
 
-		labCfg, cfgPath, err := config.LoadLabConfig(s.configPath)
+		labCfg, ws, err := s.loadLabConfig(false)
 		if err != nil {
 			return nil, cobra.ShellCompDirectiveNoFileComp
 		}
 
-		orch, err := orchestrator.NewOrchestrator(log, labCfg, cfgPath)
+		orch, err := orchestrator.NewOrchestrator(log, labCfg, ws.ConfigPath)
 		if err != nil {
 			return nil, cobra.ShellCompDirectiveNoFileComp
 		}
@@ -336,25 +441,24 @@ func (s *labStack) Init(ctx context.Context) error {
 		resolvedConfigPath string
 	)
 
-	if _, err := os.Stat(s.configPath); err == nil {
+	ws, err := workspace.Resolve(s.configPath, false, false)
+	if err != nil {
+		return err
+	}
+
+	if ws.ConfigExists {
 		s.log.Info("loading existing configuration")
 
-		result, err := config.Load(s.configPath)
-		if err != nil {
-			return fmt.Errorf("failed to load existing config: %w", err)
+		result, loadErr := config.Load(ws.ConfigPath)
+		if loadErr != nil {
+			return fmt.Errorf("failed to load existing config: %w", loadErr)
 		}
 
 		rootCfg = result.Config
 		resolvedConfigPath = result.ConfigPath
 	} else {
 		rootCfg = &config.Config{}
-
-		absPath, err := filepath.Abs(s.configPath)
-		if err != nil {
-			return fmt.Errorf("failed to get absolute config path: %w", err)
-		}
-
-		resolvedConfigPath = absPath
+		resolvedConfigPath = ws.ConfigPath
 	}
 
 	var existingXatu *config.ClickHouseClusterConfig
@@ -402,26 +506,18 @@ func (s *labStack) Init(ctx context.Context) error {
 
 	prereqChecker := prerequisites.NewChecker(s.log)
 
-	repoMap := map[string]string{
-		constants.RepoCBT:        repos.CBT,
-		constants.RepoXatuCBT:    repos.XatuCBT,
-		constants.RepoCBTAPI:     repos.CBTAPI,
-		constants.RepoLabBackend: repos.LabBackend,
-		constants.RepoLab:        repos.Lab,
-	}
-
 	ui.Header("Checking prerequisites")
 
-	for repoName, repoPath := range repoMap {
-		spinner = ui.NewSpinner(fmt.Sprintf("Running prerequisites for %s", repoName))
+	for _, repo := range repos.Ordered() {
+		spinner = ui.NewSpinner(fmt.Sprintf("Running prerequisites for %s", repo.Name))
 
-		if err := prereqChecker.Run(ctx, repoPath, repoName); err != nil {
-			spinner.Fail(fmt.Sprintf("Prerequisites failed for %s", repoName))
+		if err := prereqChecker.Run(ctx, repo.Path, repo.Name); err != nil {
+			spinner.Fail(fmt.Sprintf("Prerequisites failed for %s", repo.Name))
 
-			return fmt.Errorf("failed to run prerequisites for %s: %w", repoName, err)
+			return fmt.Errorf("failed to run prerequisites for %s: %w", repo.Name, err)
 		}
 
-		spinner.Success(fmt.Sprintf("%s prerequisites complete", repoName))
+		spinner.Success(fmt.Sprintf("%s prerequisites complete", repo.Name))
 	}
 
 	labCfg := config.DefaultLab()
@@ -450,17 +546,15 @@ func (s *labStack) Init(ctx context.Context) error {
 
 	ui.Header("Discovered repositories:")
 
-	rows := [][]string{
-		{constants.RepoCBT, repos.CBT},
-		{constants.RepoXatuCBT, repos.XatuCBT},
-		{constants.RepoCBTAPI, repos.CBTAPI},
-		{constants.RepoLabBackend, repos.LabBackend},
-		{constants.RepoLab, repos.Lab},
+	rows := make([][]string, 0, len(repos.Ordered()))
+	for _, repo := range repos.Ordered() {
+		rows = append(rows, []string{repo.Name, repo.Path})
 	}
+
 	ui.Table([]string{"Repository", "Path"}, rows)
 
 	ui.Blank()
-	ui.Info(fmt.Sprintf("Lab configuration saved to: %s", s.configPath))
+	ui.Info(fmt.Sprintf("Lab configuration saved to: %s", resolvedConfigPath))
 
 	ui.Header("Next steps:")
 	fmt.Println("  1. Review and edit the 'lab:' section in .xcli.yaml if needed")
@@ -546,7 +640,7 @@ func (s *labStack) Check(ctx context.Context) error {
 
 	spinner := renderer.Task("Checking configuration file")
 
-	labCfg, _, err := config.LoadLabConfig(s.configPath)
+	labCfg, _, err := s.loadLabConfig(true)
 	if err != nil {
 		spinner.Fail(fmt.Sprintf("Configuration file error: %v", err))
 
@@ -569,17 +663,11 @@ func (s *labStack) Check(ctx context.Context) error {
 		spinner = renderer.Task("Checking repository paths")
 
 		repoCheckPassed := true
-		repos := map[string]string{
-			constants.RepoCBT:        labCfg.Repos.CBT,
-			constants.RepoXatuCBT:    labCfg.Repos.XatuCBT,
-			constants.RepoCBTAPI:     labCfg.Repos.CBTAPI,
-			constants.RepoLabBackend: labCfg.Repos.LabBackend,
-			constants.RepoLab:        labCfg.Repos.Lab,
-		}
-
 		missingRepos := []string{}
 
-		for name, path := range repos {
+		for _, repo := range labCfg.Repos.Ordered() {
+			name, path := repo.Name, repo.Path
+
 			absPath, err := filepath.Abs(path)
 			if err != nil {
 				missingRepos = append(missingRepos,
@@ -686,7 +774,7 @@ func (s *labStack) Check(ctx context.Context) error {
 
 // Up starts the lab stack.
 func (s *labStack) Up(ctx context.Context) error {
-	labCfg, cfgPath, err := config.LoadLabConfig(s.configPath)
+	labCfg, ws, err := s.loadLabConfig(true)
 	if err != nil {
 		return err
 	}
@@ -699,7 +787,17 @@ func (s *labStack) Up(ctx context.Context) error {
 		return fmt.Errorf("invalid lab configuration: %w", validationErr)
 	}
 
-	orch, err := orchestrator.NewOrchestrator(s.log, labCfg, cfgPath)
+	runtime, err := instance.NewRuntimeFromWorkspace(ctx, ws, labCfg, s.instanceOverrideValue(), instance.RuntimeOptions{
+		ClaimPorts: true,
+		ProbePorts: true,
+	})
+	if err != nil {
+		return fmt.Errorf("failed to resolve lab instance runtime: %w", err)
+	}
+
+	printRuntimeSelection(runtime)
+
+	orch, err := orchestrator.NewOrchestratorWithRuntime(s.log, runtime)
 	if err != nil {
 		return fmt.Errorf("failed to create orchestrator: %w", err)
 	}
@@ -748,146 +846,106 @@ func (s *labStack) Up(ctx context.Context) error {
 
 // Down stops the lab stack.
 func (s *labStack) Down(ctx context.Context) error {
-	labCfg, cfgPath, err := config.LoadLabConfig(s.configPath)
-	if err != nil {
-		return fmt.Errorf("failed to load config: %w", err)
-	}
+	return s.withRuntimeOrchestrator(ctx, lifecycleRuntimeSelected, func(runtime *instance.Runtime, orch *orchestrator.Orchestrator) error {
+		printRuntimeSelection(runtime)
 
-	orch, err := orchestrator.NewOrchestrator(s.log, labCfg, cfgPath)
-	if err != nil {
-		return fmt.Errorf("failed to create orchestrator: %w", err)
-	}
+		renderer := ui.NewRenderer(nil)
+		defer renderer.Close()
 
-	renderer := ui.NewRenderer(nil)
-	defer renderer.Close()
+		orch.SetRenderer(renderer)
+		renderer.Banner("Stopping Lab Stack")
 
-	orch.SetRenderer(renderer)
-	renderer.Banner("Tearing Down Lab Stack")
+		if err := orch.Down(ctx, nil); err != nil {
+			return err
+		}
 
-	if err := orch.Down(ctx, nil); err != nil {
-		return err
-	}
+		renderer.Blank()
+		renderer.Success("Stack stopped successfully")
+		renderer.Info("All services and containers stopped. Data volumes were preserved.")
+		renderer.Info("Run 'xcli lab up' to restart this instance.")
 
-	renderer.Blank()
-	renderer.Success("Stack torn down successfully")
-	renderer.Info("All services stopped, logs cleaned, and volumes removed.")
-	renderer.Info("Run 'xcli lab up' to start fresh.")
-
-	return nil
+		return nil
+	})
 }
 
-// Clean removes all lab containers, volumes, and build artifacts.
+// Clean is a non-destructive alias for stopping the lab stack.
 func (s *labStack) Clean(ctx context.Context) error {
-	labCfg, cfgPath, err := config.LoadLabConfig(s.configPath)
-	if err != nil {
-		return fmt.Errorf("failed to load config: %w", err)
-	}
-
-	ui.Warning("WARNING: This will remove all lab containers, volumes, and generated files!")
-	fmt.Println("\nThis includes:")
-	fmt.Println("  - All Docker containers and volumes (data will be lost)")
-	fmt.Println("  - Generated configs in .xcli/ directory")
-	fmt.Println("  - Build artifacts (binaries)")
-	fmt.Println("  - Proto-generated files")
-	fmt.Print("\nContinue? (y/N): ")
-
-	var response string
-
-	_, _ = fmt.Scanln(&response)
+	ui.Info("xcli lab clean is non-destructive and now stops the selected instance.")
+	ui.Info("Use 'xcli lab destroy --instance <id>' to remove data.")
 
-	if response != "y" && response != "Y" {
-		ui.Info("Cancelled.")
+	return s.Down(ctx)
+}
 
-		return nil
+// Destroy removes all resources and generated state for a named lab instance.
+func (s *labStack) Destroy(ctx context.Context, yes bool) error {
+	if s.instanceOverrideValue() == "" {
+		return fmt.Errorf("destroy requires --instance <id>")
 	}
 
-	orch, err := orchestrator.NewOrchestrator(s.log, labCfg, cfgPath)
-	if err != nil {
-		return fmt.Errorf("failed to create orchestrator: %w", err)
-	}
+	return s.withRuntimeOrchestrator(ctx, lifecycleRuntimeRequiredID, func(runtime *instance.Runtime, orch *orchestrator.Orchestrator) error {
+		printRuntimeSelection(runtime)
 
-	renderer := ui.NewRenderer(nil)
-	defer renderer.Close()
+		if !yes {
+			fmt.Printf("Type %q to destroy this instance and delete its data: ", runtime.InstanceID)
 
-	orch.SetRenderer(renderer)
-	renderer.Banner("Cleaning Lab Workspace")
+			var confirmation string
 
-	renderer.Phase("[1/3] Stopping and removing Docker containers and volumes")
+			_, _ = fmt.Scanln(&confirmation)
 
-	if err := orch.Down(ctx, nil); err != nil {
-		renderer.Warning(fmt.Sprintf("Failed to stop services: %v", err))
-		renderer.Info("Continuing with cleanup...")
-	}
+			if confirmation != runtime.InstanceID {
+				ui.Info("Cancelled.")
 
-	renderer.Phase("[2/3] Removing generated configuration files")
+				return nil
+			}
+		}
 
-	configDir := filepath.Dir(cfgPath)
-	stateDir := filepath.Join(configDir, ".xcli")
+		renderer := ui.NewRenderer(nil)
+		defer renderer.Close()
 
-	spinner := renderer.Task("Removing generated configuration files")
+		orch.SetRenderer(renderer)
+		renderer.Banner("Destroying Lab Instance")
 
-	if _, err := os.Stat(stateDir); err == nil {
-		if err := os.RemoveAll(stateDir); err != nil {
-			spinner.Warning(fmt.Sprintf("Failed to remove %s: %v", stateDir, err))
-		} else {
-			spinner.Success("Generated files removed")
+		if err := orch.Destroy(ctx, nil); err != nil {
+			return err
 		}
-	} else {
-		spinner.Success("No generated files found")
-	}
 
-	renderer.Phase("[3/3] Removing build artifacts")
+		renderer.Blank()
+		renderer.Success("Instance destroyed")
 
-	spinner = renderer.Task("Removing build artifacts")
+		return nil
+	})
+}
 
-	repos := map[string]string{
-		constants.RepoCBT:        labCfg.Repos.CBT,
-		constants.RepoXatuCBT:    labCfg.Repos.XatuCBT,
-		constants.RepoCBTAPI:     labCfg.Repos.CBTAPI,
-		constants.RepoLabBackend: labCfg.Repos.LabBackend,
+// Reset intentionally clears one data store for a named lab instance.
+func (s *labStack) Reset(ctx context.Context, target string) error {
+	if s.instanceOverrideValue() == "" {
+		return fmt.Errorf("reset requires --instance <id>")
 	}
 
-	totalRemoved := 0
+	target = strings.ToLower(strings.TrimSpace(target))
+	if target != "redis" {
+		return fmt.Errorf("unsupported reset target %q; supported target: redis", target)
+	}
 
-	for name, path := range repos {
-		absPath, err := filepath.Abs(path)
-		if err != nil {
-			continue
-		}
+	return s.withRuntimeOrchestrator(ctx, lifecycleRuntimeRequiredID, func(runtime *instance.Runtime, orch *orchestrator.Orchestrator) error {
+		printRuntimeSelection(runtime)
 
-		artifacts := []string{
-			filepath.Join(absPath, name),
-			filepath.Join(absPath, "bin"),
-			filepath.Join(absPath, "dist"),
-		}
+		spinner := ui.NewSpinner("Resetting Redis")
+		if err := orch.ResetRedis(ctx); err != nil {
+			spinner.Fail("Failed to reset Redis")
 
-		for _, artifact := range artifacts {
-			if _, err := os.Stat(artifact); err == nil {
-				if err := os.RemoveAll(artifact); err != nil {
-					spinner.Warning(fmt.Sprintf("Failed to remove %s: %v", artifact, err))
-				} else {
-					totalRemoved++
-				}
-			}
+			return err
 		}
-	}
 
-	if totalRemoved > 0 {
-		spinner.Success(fmt.Sprintf("Removed %d build artifacts", totalRemoved))
-	} else {
-		spinner.Success("No build artifacts found")
-	}
+		spinner.Success("Redis reset for selected instance")
 
-	renderer.Blank()
-	renderer.Success("Lab workspace cleaned successfully!")
-	renderer.Info("Next step: xcli lab up")
-
-	return nil
+		return nil
+	})
 }
 
 // Build builds all lab projects from source without starting services.
 func (s *labStack) Build(ctx context.Context, _ []string) error {
-	labCfg, cfgPath, err := config.LoadLabConfig(s.configPath)
+	labCfg, ws, err := s.loadLabConfig(false)
 	if err != nil {
 		return err
 	}
@@ -896,15 +954,7 @@ func (s *labStack) Build(ctx context.Context, _ []string) error {
 		return fmt.Errorf("invalid lab configuration: %w", validateErr)
 	}
 
-	absConfigPath, err := filepath.Abs(cfgPath)
-	if err != nil {
-		return fmt.Errorf("failed to get absolute config path: %w", err)
-	}
-
-	configDir := filepath.Dir(absConfigPath)
-	stateDir := filepath.Join(configDir, ".xcli")
-
-	buildMgr := builder.NewManager(s.log, labCfg, stateDir)
+	buildMgr := builder.NewManager(s.log, labCfg, ws.StateDir)
 
 	renderer := ui.NewRenderer(nil)
 	buildMgr.SetRenderer(renderer)
@@ -928,301 +978,323 @@ func (s *labStack) Build(ctx context.Context, _ []string) error {
 
 // Rebuild rebuilds a specific lab component and restarts affected services.
 func (s *labStack) Rebuild(ctx context.Context, project string) error {
-	labCfg, cfgPath, err := config.LoadLabConfig(s.configPath)
-	if err != nil {
-		return fmt.Errorf("failed to load config: %w", err)
-	}
+	return s.withRuntimeOrchestrator(ctx, lifecycleRuntimeSelected, func(runtime *instance.Runtime, orch *orchestrator.Orchestrator) error {
+		printRuntimeSelection(runtime)
 
-	absConfigPath, err := filepath.Abs(cfgPath)
-	if err != nil {
-		return fmt.Errorf("failed to get absolute config path: %w", err)
-	}
+		labCfg := runtime.LabConfig
 
-	configDir := filepath.Dir(absConfigPath)
-	stateDir := filepath.Join(configDir, ".xcli")
+		orch.SetVerbose(s.rebuildVerbose)
 
-	orch, err := orchestrator.NewOrchestrator(s.log, labCfg, cfgPath)
-	if err != nil {
-		return fmt.Errorf("failed to create orchestrator: %w", err)
-	}
+		switch project {
+		case constants.RepoXatuCBT, "all":
+			return s.runFullRebuild(ctx, orch, runtime.Manifest.StateDir)
 
-	orch.SetVerbose(s.rebuildVerbose)
+		case constants.RepoCBT:
+			spinner := ui.NewSpinner("Rebuilding CBT")
 
-	switch project {
-	case constants.RepoXatuCBT, "all":
-		return s.runFullRebuild(ctx, orch, stateDir)
+			if err := orch.Builder().BuildCBT(ctx, true); err != nil {
+				spinner.Fail("Failed to rebuild CBT")
 
-	case constants.RepoCBT:
-		spinner := ui.NewSpinner("Rebuilding CBT")
-
-		if err := orch.Builder().BuildCBT(ctx, true); err != nil {
-			spinner.Fail("Failed to rebuild CBT")
-
-			return fmt.Errorf("failed to rebuild CBT: %w", err)
-		}
+				return fmt.Errorf("failed to rebuild CBT: %w", err)
+			}
 
-		spinner.Success("CBT rebuilt successfully")
+			spinner.Success("CBT rebuilt successfully")
 
-		enabledNetworks := orch.Config().EnabledNetworks()
-		for _, network := range enabledNetworks {
-			serviceName := fmt.Sprintf("cbt-%s", network.Name)
-			spinner = ui.NewSpinner(fmt.Sprintf("Restarting %s", serviceName))
+			enabledNetworks := orch.Config().EnabledNetworks()
+			for _, network := range enabledNetworks {
+				serviceName := fmt.Sprintf("cbt-%s", network.Name)
+				spinner = ui.NewSpinner(fmt.Sprintf("Restarting %s", serviceName))
 
-			if err := orch.Restart(ctx, serviceName); err != nil {
-				spinner.Warning(fmt.Sprintf("Could not restart %s", serviceName))
-			} else {
-				spinner.Success(fmt.Sprintf("%s restarted", serviceName))
+				if err := orch.Restart(ctx, serviceName); err != nil {
+					spinner.Warning(fmt.Sprintf("Could not restart %s", serviceName))
+				} else {
+					spinner.Success(fmt.Sprintf("%s restarted", serviceName))
+				}
 			}
-		}
 
-	case constants.RepoCBTAPI:
-		spinner := ui.NewSpinner("Regenerating protos and rebuilding cbt-api")
+		case constants.RepoCBTAPI:
+			spinner := ui.NewSpinner("Regenerating protos and rebuilding cbt-api")
 
-		if err := orch.Builder().BuildCBTAPI(ctx, true); err != nil {
-			spinner.Fail("Failed to rebuild cbt-api")
+			if err := orch.Builder().BuildCBTAPI(ctx, true); err != nil {
+				spinner.Fail("Failed to rebuild cbt-api")
 
-			return fmt.Errorf("failed to rebuild cbt-api: %w", err)
-		}
+				return fmt.Errorf("failed to rebuild cbt-api: %w", err)
+			}
 
-		spinner.Success("cbt-api rebuilt successfully")
+			spinner.Success("cbt-api rebuilt successfully")
 
-		enabledNetworks := orch.Config().EnabledNetworks()
-		for _, network := range enabledNetworks {
-			serviceName := fmt.Sprintf("cbt-api-%s", network.Name)
-			spinner = ui.NewSpinner(fmt.Sprintf("Restarting %s", serviceName))
+			enabledNetworks := orch.Config().EnabledNetworks()
+			for _, network := range enabledNetworks {
+				serviceName := fmt.Sprintf("cbt-api-%s", network.Name)
+				spinner = ui.NewSpinner(fmt.Sprintf("Restarting %s", serviceName))
 
-			if err := orch.Restart(ctx, serviceName); err != nil {
-				spinner.Warning(fmt.Sprintf("Could not restart %s", serviceName))
-			} else {
-				spinner.Success(fmt.Sprintf("%s restarted", serviceName))
+				if err := orch.Restart(ctx, serviceName); err != nil {
+					spinner.Warning(fmt.Sprintf("Could not restart %s", serviceName))
+				} else {
+					spinner.Success(fmt.Sprintf("%s restarted", serviceName))
+				}
 			}
-		}
 
-		ui.Blank()
-		ui.Info("Note: If you added models in xatu-cbt, use " +
-			"'xcli lab rebuild xatu-cbt' for full workflow")
+			ui.Blank()
+			ui.Info("Note: If you added models in xatu-cbt, use " +
+				"'xcli lab rebuild xatu-cbt' for full workflow")
 
-	case constants.RepoLabBackend:
-		spinner := ui.NewSpinner("Rebuilding lab-backend")
+		case constants.RepoLabBackend:
+			spinner := ui.NewSpinner("Rebuilding lab-backend")
 
-		if err := orch.Builder().BuildLabBackend(ctx, true); err != nil {
-			spinner.Fail("Failed to rebuild lab-backend")
+			if err := orch.Builder().BuildLabBackend(ctx, true); err != nil {
+				spinner.Fail("Failed to rebuild lab-backend")
 
-			return fmt.Errorf("failed to rebuild lab-backend: %w", err)
-		}
+				return fmt.Errorf("failed to rebuild lab-backend: %w", err)
+			}
 
-		spinner.Success("lab-backend rebuilt successfully")
+			spinner.Success("lab-backend rebuilt successfully")
 
-		spinner = ui.NewSpinner("Restarting lab-backend")
+			spinner = ui.NewSpinner("Restarting lab-backend")
 
-		if err := orch.Restart(ctx, constants.RepoLabBackend); err != nil {
-			spinner.Fail("Could not restart lab-backend")
-			ui.Info("If lab-backend is running, restart it manually:")
-			ui.Info("  xcli lab restart lab-backend")
-		} else {
-			spinner.Success("lab-backend restarted successfully")
-		}
+			if err := orch.Restart(ctx, constants.RepoLabBackend); err != nil {
+				spinner.Fail("Could not restart lab-backend")
+				ui.Info("If lab-backend is running, restart it manually:")
+				ui.Info("  xcli lab restart lab-backend")
+			} else {
+				spinner.Success("lab-backend restarted successfully")
+			}
 
-	case repoLabFrontend:
-		spinner := ui.NewSpinner("Regenerating lab-frontend API types from cbt-api")
+		case repoLabFrontend:
+			spinner := ui.NewSpinner("Regenerating lab-frontend API types from cbt-api")
 
-		if err := orch.Builder().BuildLabFrontend(ctx); err != nil {
-			spinner.Fail("Failed to regenerate lab-frontend types")
+			if err := orch.Builder().BuildLabFrontend(ctx); err != nil {
+				spinner.Fail("Failed to regenerate lab-frontend types")
 
-			return fmt.Errorf("failed to regenerate lab-frontend types: %w", err)
-		}
+				return fmt.Errorf("failed to regenerate lab-frontend types: %w", err)
+			}
 
-		spinner.Success("lab-frontend API types regenerated successfully")
+			spinner.Success("lab-frontend API types regenerated successfully")
 
-		spinner = ui.NewSpinner("Restarting lab-frontend")
+			spinner = ui.NewSpinner("Restarting lab-frontend")
 
-		if err := orch.Restart(ctx, repoLabFrontend); err != nil {
-			spinner.Fail("Could not restart lab-frontend")
-			ui.Info("If lab-frontend is running, restart it manually:")
-			ui.Info("  xcli lab restart lab-frontend")
-		} else {
-			spinner.Success("lab-frontend restarted successfully")
-		}
+			if err := orch.Restart(ctx, repoLabFrontend); err != nil {
+				spinner.Fail("Could not restart lab-frontend")
+				ui.Info("If lab-frontend is running, restart it manually:")
+				ui.Info("  xcli lab restart lab-frontend")
+			} else {
+				spinner.Success("lab-frontend restarted successfully")
+			}
 
-	case "prometheus":
-		if !labCfg.Infrastructure.Observability.Enabled {
-			return fmt.Errorf("observability is not enabled in config")
-		}
+		case "prometheus":
+			if !labCfg.Infrastructure.Observability.Enabled {
+				return fmt.Errorf("observability is not enabled in config")
+			}
 
-		spinner := ui.NewSpinner("Regenerating Prometheus config")
+			spinner := ui.NewSpinner("Regenerating Prometheus config")
 
-		if err := orch.RebuildObservability(ctx, "prometheus"); err != nil {
-			spinner.Fail("Failed to rebuild Prometheus")
+			if err := orch.RebuildObservability(ctx, "prometheus"); err != nil {
+				spinner.Fail("Failed to rebuild Prometheus")
 
-			return fmt.Errorf("failed to rebuild prometheus: %w", err)
-		}
+				return fmt.Errorf("failed to rebuild prometheus: %w", err)
+			}
 
-		spinner.Success("Prometheus config regenerated and container restarted")
+			spinner.Success("Prometheus config regenerated and container restarted")
 
-	case "grafana":
-		if !labCfg.Infrastructure.Observability.Enabled {
-			return fmt.Errorf("observability is not enabled in config")
-		}
+		case "grafana":
+			if !labCfg.Infrastructure.Observability.Enabled {
+				return fmt.Errorf("observability is not enabled in config")
+			}
 
-		spinner := ui.NewSpinner("Regenerating Grafana provisioning and dashboards")
+			spinner := ui.NewSpinner("Regenerating Grafana provisioning and dashboards")
 
-		if err := orch.RebuildObservability(ctx, "grafana"); err != nil {
-			spinner.Fail("Failed to rebuild Grafana")
+			if err := orch.RebuildObservability(ctx, "grafana"); err != nil {
+				spinner.Fail("Failed to rebuild Grafana")
 
-			return fmt.Errorf("failed to rebuild grafana: %w", err)
-		}
+				return fmt.Errorf("failed to rebuild grafana: %w", err)
+			}
 
-		spinner.Success("Grafana provisioning regenerated and container restarted")
-		ui.Info("Custom dashboards loaded from .xcli/custom-dashboards/")
+			spinner.Success("Grafana provisioning regenerated and container restarted")
+			ui.Info("Custom dashboards loaded from .xcli/custom-dashboards/")
 
-	default:
-		return fmt.Errorf(
-			"unknown project: %s\n\nSupported projects: "+
-				"xatu-cbt, cbt, cbt-api, lab-backend, lab-frontend, "+
-				"prometheus, grafana, all",
-			project,
-		)
-	}
+		default:
+			return fmt.Errorf(
+				"unknown project: %s\n\nSupported projects: "+
+					"xatu-cbt, cbt, cbt-api, lab-backend, lab-frontend, "+
+					"prometheus, grafana, all",
+				project,
+			)
+		}
 
-	return nil
+		return nil
+	})
 }
 
 // PrintStatus displays lab stack status.
 func (s *labStack) PrintStatus(ctx context.Context) error {
-	labCfg, cfgPath, err := config.LoadLabConfig(s.configPath)
-	if err != nil {
-		return fmt.Errorf("failed to load config: %w", err)
+	if s.statusAll {
+		return s.printAllInstanceStatus(ctx)
 	}
 
-	orch, err := orchestrator.NewOrchestrator(s.log, labCfg, cfgPath)
-	if err != nil {
-		return fmt.Errorf("failed to create orchestrator: %w", err)
-	}
+	return s.withRuntimeOrchestrator(ctx, lifecycleRuntimeSelected, func(runtime *instance.Runtime, orch *orchestrator.Orchestrator) error {
+		printRuntimeSelection(runtime)
 
-	return orch.Status(ctx)
+		return orch.Status(ctx)
+	})
 }
 
-// Logs shows logs for lab services.
-func (s *labStack) Logs(ctx context.Context, service string, follow bool) error {
-	labCfg, cfgPath, err := config.LoadLabConfig(s.configPath)
+func (s *labStack) printAllInstanceStatus(ctx context.Context) error {
+	registry, err := instance.DefaultRegistry()
 	if err != nil {
-		return fmt.Errorf("failed to load config: %w", err)
+		return err
 	}
 
-	orch, err := orchestrator.NewOrchestrator(s.log, labCfg, cfgPath)
+	result, err := instance.NewReconciler(registry).ReconcileAll(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to create orchestrator: %w", err)
+		return err
 	}
 
-	return orch.Logs(ctx, service, follow)
-}
+	if len(result.Instances) == 0 {
+		ui.Info("No lab instances registered")
 
-// Start starts a specific lab service.
-func (s *labStack) Start(ctx context.Context, service string) error {
-	labCfg, cfgPath, err := config.LoadLabConfig(s.configPath)
-	if err != nil {
-		return fmt.Errorf("failed to load config: %w", err)
+		if result.DockerError != nil {
+			ui.Warning(fmt.Sprintf("Docker reconciliation skipped: %v", result.DockerError))
+		}
+
+		return nil
 	}
 
-	orch, err := orchestrator.NewOrchestrator(s.log, labCfg, cfgPath)
-	if err != nil {
-		return fmt.Errorf("failed to create orchestrator: %w", err)
+	rows := make([][]string, 0, len(result.Instances))
+	for _, item := range result.Instances {
+		rows = append(rows, []string{
+			item.InstanceID,
+			item.Status,
+			boolSummary(item.Live.BackingExists),
+			fmt.Sprintf("%d/%d", trueCount(item.Live.PIDs), len(item.Live.PIDs)),
+			fmt.Sprintf("%d", len(item.Live.DockerResources)),
+			fmt.Sprintf("%d/%d", trueCount(item.Live.Ports), len(item.Live.Ports)),
+			item.Manifest.RootDir,
+			item.Manifest.ConfigPath,
+		})
 	}
 
-	if !orch.IsValidService(service) {
-		ui.Error(fmt.Sprintf("Unknown service: %s", service))
-		fmt.Println("\nAvailable services:")
+	ui.Table([]string{"Instance", "Status", "Live", "PIDs", "Docker", "Ports", "Root", "Config"}, rows)
 
-		for _, svc := range orch.GetValidServices() {
-			fmt.Printf("  - %s\n", svc)
-		}
+	if result.DockerError != nil {
+		ui.Warning(fmt.Sprintf("Docker reconciliation skipped: %v", result.DockerError))
+	}
 
-		return fmt.Errorf("unknown service: %s", service)
+	return nil
+}
+
+func boolSummary(value bool) string {
+	if value {
+		return "yes"
 	}
 
-	spinner := ui.NewSpinner(fmt.Sprintf("Starting %s", service))
+	return "no"
+}
 
-	if err := orch.StartService(ctx, service); err != nil {
-		spinner.Fail(fmt.Sprintf("Failed to start %s", service))
+func trueCount(values map[string]bool) int {
+	count := 0
 
-		return fmt.Errorf("failed to start service: %w", err)
+	for _, value := range values {
+		if value {
+			count++
+		}
 	}
 
-	spinner.Success(fmt.Sprintf("%s started successfully", service))
+	return count
+}
 
-	return nil
+// Logs shows logs for lab services.
+func (s *labStack) Logs(ctx context.Context, service string, follow bool) error {
+	return s.withRuntimeOrchestrator(ctx, lifecycleRuntimeSelected, func(runtime *instance.Runtime, orch *orchestrator.Orchestrator) error {
+		return orch.Logs(ctx, service, follow)
+	})
+}
+
+// Start starts a specific lab service.
+func (s *labStack) Start(ctx context.Context, service string) error {
+	return s.withRuntimeOrchestrator(ctx, lifecycleRuntimeSelected, func(runtime *instance.Runtime, orch *orchestrator.Orchestrator) error {
+		if !orch.IsValidService(service) {
+			ui.Error(fmt.Sprintf("Unknown service: %s", service))
+			fmt.Println("\nAvailable services:")
+
+			for _, svc := range orch.GetValidServices() {
+				fmt.Printf("  - %s\n", svc)
+			}
+
+			return fmt.Errorf("unknown service: %s", service)
+		}
+
+		spinner := ui.NewSpinner(fmt.Sprintf("Starting %s", service))
+
+		if err := orch.StartService(ctx, service); err != nil {
+			spinner.Fail(fmt.Sprintf("Failed to start %s", service))
+
+			return fmt.Errorf("failed to start service: %w", err)
+		}
+
+		spinner.Success(fmt.Sprintf("%s started successfully", service))
+
+		return nil
+	})
 }
 
 // Stop stops a specific lab service.
 func (s *labStack) Stop(ctx context.Context, service string) error {
-	labCfg, cfgPath, err := config.LoadLabConfig(s.configPath)
-	if err != nil {
-		return fmt.Errorf("failed to load config: %w", err)
+	if strings.TrimSpace(service) == "" {
+		return s.Down(ctx)
 	}
 
-	orch, err := orchestrator.NewOrchestrator(s.log, labCfg, cfgPath)
-	if err != nil {
-		return fmt.Errorf("failed to create orchestrator: %w", err)
-	}
+	return s.withRuntimeOrchestrator(ctx, lifecycleRuntimeSelected, func(runtime *instance.Runtime, orch *orchestrator.Orchestrator) error {
+		if !orch.IsValidService(service) {
+			ui.Error(fmt.Sprintf("Unknown service: %s", service))
+			fmt.Println("\nAvailable services:")
 
-	if !orch.IsValidService(service) {
-		ui.Error(fmt.Sprintf("Unknown service: %s", service))
-		fmt.Println("\nAvailable services:")
+			for _, svc := range orch.GetValidServices() {
+				fmt.Printf("  - %s\n", svc)
+			}
 
-		for _, svc := range orch.GetValidServices() {
-			fmt.Printf("  - %s\n", svc)
+			return fmt.Errorf("unknown service: %s", service)
 		}
 
-		return fmt.Errorf("unknown service: %s", service)
-	}
-
-	spinner := ui.NewSpinner(fmt.Sprintf("Stopping %s", service))
+		spinner := ui.NewSpinner(fmt.Sprintf("Stopping %s", service))
 
-	if err := orch.StopService(ctx, service); err != nil {
-		spinner.Fail(fmt.Sprintf("Failed to stop %s", service))
+		if err := orch.StopService(ctx, service); err != nil {
+			spinner.Fail(fmt.Sprintf("Failed to stop %s", service))
 
-		return fmt.Errorf("failed to stop service: %w", err)
-	}
+			return fmt.Errorf("failed to stop service: %w", err)
+		}
 
-	spinner.Success(fmt.Sprintf("%s stopped successfully", service))
+		spinner.Success(fmt.Sprintf("%s stopped successfully", service))
 
-	return nil
+		return nil
+	})
 }
 
 // Restart restarts a specific lab service.
 func (s *labStack) Restart(ctx context.Context, service string) error {
-	labCfg, cfgPath, err := config.LoadLabConfig(s.configPath)
-	if err != nil {
-		return err
-	}
-
-	orch, err := orchestrator.NewOrchestrator(s.log, labCfg, cfgPath)
-	if err != nil {
-		return fmt.Errorf("failed to create orchestrator: %w", err)
-	}
+	return s.withRuntimeOrchestrator(ctx, lifecycleRuntimeSelected, func(runtime *instance.Runtime, orch *orchestrator.Orchestrator) error {
+		if !orch.IsValidService(service) {
+			ui.Error(fmt.Sprintf("Unknown service: %s", service))
+			fmt.Println("\nAvailable services:")
 
-	if !orch.IsValidService(service) {
-		ui.Error(fmt.Sprintf("Unknown service: %s", service))
-		fmt.Println("\nAvailable services:")
+			for _, svc := range orch.GetValidServices() {
+				fmt.Printf("  - %s\n", svc)
+			}
 
-		for _, svc := range orch.GetValidServices() {
-			fmt.Printf("  - %s\n", svc)
+			return fmt.Errorf("unknown service: %s", service)
 		}
 
-		return fmt.Errorf("unknown service: %s", service)
-	}
-
-	spinner := ui.NewSpinner(fmt.Sprintf("Restarting %s", service))
+		spinner := ui.NewSpinner(fmt.Sprintf("Restarting %s", service))
 
-	if err := orch.Restart(ctx, service); err != nil {
-		spinner.Fail(fmt.Sprintf("Failed to restart %s", service))
+		if err := orch.Restart(ctx, service); err != nil {
+			spinner.Fail(fmt.Sprintf("Failed to restart %s", service))
 
-		return fmt.Errorf("failed to restart service: %w", err)
-	}
+			return fmt.Errorf("failed to restart service: %w", err)
+		}
 
-	spinner.Success(fmt.Sprintf("%s restarted successfully", service))
+		spinner.Success(fmt.Sprintf("%s restarted successfully", service))
 
-	return nil
+		return nil
+	})
 }
 
 // runFullRebuild executes the full rebuild and restart workflow.
diff --git a/pkg/stack/lab_instance_test.go b/pkg/stack/lab_instance_test.go
new file mode 100644
index 0000000..1d132bb
--- /dev/null
+++ b/pkg/stack/lab_instance_test.go
@@ -0,0 +1,106 @@
+package stack
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
+	xcligit "github.com/ethpandaops/xcli/pkg/git"
+	"github.com/ethpandaops/xcli/pkg/instance"
+	"github.com/sirupsen/logrus"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLabStackInstanceOverrideLoadsManifestRuntime(t *testing.T) {
+	homeDir := t.TempDir()
+	t.Setenv("HOME", homeDir)
+
+	rootDir := t.TempDir()
+	configPath := filepath.Join(rootDir, config.DefaultConfigFileName)
+	writeLifecycleConfig(t, rootDir, configPath)
+
+	registry, err := instance.DefaultRegistry()
+	require.NoError(t, err)
+
+	manifest := &instance.Manifest{
+		SchemaVersion: instance.SchemaVersion,
+		InstanceID:    "beta",
+		Status:        instance.StatusRunning,
+		RootDir:       rootDir,
+		ConfigPath:    configPath,
+		OverridesPath: filepath.Join(rootDir, constants.CBTOverridesFile),
+		StateDir:      instance.InstanceStateDir(rootDir, "beta"),
+		Mode:          constants.ModeHybrid,
+		Repos:         map[string]xcligit.RepoVersion{},
+		Ports:         instance.PortPlan{LabBackend: 9080},
+		Docker:        instance.NewDockerPlan("beta", configPath),
+		PIDs:          map[string]int{},
+		URLs:          map[string]string{},
+		CreatedAt:     time.Now().UTC(),
+	}
+	require.NoError(t, registry.Save(manifest))
+
+	override := "beta"
+	stack := NewLabStack(logrus.New(), filepath.Join(t.TempDir(), config.DefaultConfigFileName), &override)
+	runtime, err := stack.loadLifecycleRuntime()
+	require.NoError(t, err)
+
+	require.Equal(t, "beta", runtime.InstanceID)
+	require.Equal(t, "xcli-beta", runtime.Docker.ProjectName)
+	require.Equal(t, configPath, runtime.Manifest.ConfigPath)
+	require.Equal(t, 9080, runtime.Ports.LabBackend)
+}
+
+func writeLifecycleConfig(t *testing.T, rootDir, configPath string) {
+	t.Helper()
+
+	reposDir := filepath.Join(rootDir, "repos")
+	for _, repo := range []string{
+		constants.RepoCBT,
+		constants.RepoXatuCBT,
+		constants.RepoCBTAPI,
+		constants.RepoLabBackend,
+		constants.RepoLab,
+	} {
+		require.NoError(t, os.MkdirAll(filepath.Join(reposDir, repo), 0755))
+	}
+
+	content := `
+lab:
+  mode: hybrid
+  repos:
+    cbt: repos/cbt
+    xatuCbt: repos/xatu-cbt
+    cbtApi: repos/cbt-api
+    labBackend: repos/lab-backend
+    lab: repos/lab
+  networks:
+    - name: mainnet
+      enabled: true
+      portOffset: 0
+  infrastructure:
+    clickhouse:
+      xatu:
+        mode: external
+        externalUrl: "http://example.invalid:9000"
+      cbt:
+        mode: local
+    observability:
+      enabled: true
+      prometheusPort: 9090
+      grafanaPort: 3000
+    clickhouseXatuPort: 8125
+    clickhouseCbtPort: 8123
+    redisPort: 6380
+  ports:
+    labBackend: 8080
+    labFrontend: 5173
+    cbtBase: 8081
+    cbtApiBase: 8091
+    cbtFrontendBase: 8085
+`
+	require.NoError(t, os.WriteFile(configPath, []byte(content), 0644))
+}
diff --git a/pkg/stack/xatu.go b/pkg/stack/xatu.go
index 5d0fb3a..ff9e123 100644
--- a/pkg/stack/xatu.go
+++ b/pkg/stack/xatu.go
@@ -7,6 +7,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 
 	"github.com/ethpandaops/xcli/pkg/compose"
 	"github.com/ethpandaops/xcli/pkg/config"
@@ -231,10 +232,12 @@ func (s *xatuStack) Init(ctx context.Context) error {
 		resolvedConfigPath string
 	)
 
-	if _, err := os.Stat(s.configPath); err == nil {
+	configPath := config.EffectiveConfigPath(s.configPath)
+
+	if _, err := os.Stat(configPath); err == nil {
 		s.log.Info("loading existing configuration")
 
-		result, err := config.Load(s.configPath)
+		result, err := config.Load(configPath)
 		if err != nil {
 			return fmt.Errorf("failed to load existing config: %w", err)
 		}
@@ -244,7 +247,7 @@ func (s *xatuStack) Init(ctx context.Context) error {
 	} else {
 		rootCfg = &config.Config{}
 
-		absPath, err := filepath.Abs(s.configPath)
+		absPath, err := filepath.Abs(configPath)
 		if err != nil {
 			return fmt.Errorf("failed to get absolute config path: %w", err)
 		}
@@ -694,6 +697,10 @@ func (s *xatuStack) Start(ctx context.Context, service string) error {
 
 // Stop stops a specific xatu service.
 func (s *xatuStack) Stop(ctx context.Context, service string) error {
+	if strings.TrimSpace(service) == "" {
+		return s.Down(ctx)
+	}
+
 	xatuCfg, _, err := config.LoadXatuConfig(s.configPath)
 	if err != nil {
 		return fmt.Errorf("failed to load config: %w", err)
diff --git a/pkg/workspace/workspace.go b/pkg/workspace/workspace.go
new file mode 100644
index 0000000..27b85df
--- /dev/null
+++ b/pkg/workspace/workspace.go
@@ -0,0 +1,248 @@
+// Package workspace resolves the authoritative xcli workspace root and the
+// paths derived from it.
+package workspace
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
+)
+
+// Workspace describes the authoritative workspace selected for a command.
+type Workspace struct {
+	RootDir       string
+	ConfigPath    string
+	OverridesPath string
+	StateDir      string
+	ConfigExists  bool
+}
+
+// Resolve selects the authoritative workspace for a command.
+//
+// The default config path searches upward only from the current directory. An
+// explicit config path is resolved directly and always wins.
+func Resolve(configPath string, requireConfig bool, checkCWDOverrides bool) (*Workspace, error) {
+	path := config.EffectiveConfigPath(configPath)
+	if path == "" {
+		path = config.DefaultConfigFileName
+	}
+
+	var (
+		resolvedPath string
+		exists       bool
+		err          error
+	)
+
+	defaultPath := isDefaultConfigPath(path)
+	if defaultPath {
+		resolvedPath, exists, err = resolveDefaultConfig()
+	} else {
+		resolvedPath, exists, err = resolveExplicitConfig(path)
+	}
+
+	if err != nil {
+		return nil, err
+	}
+
+	if requireConfig && !exists {
+		if !defaultPath {
+			return nil, fmt.Errorf("config file not found: %s", resolvedPath)
+		}
+
+		return nil, fmt.Errorf(
+			"no %s found searching upward from current directory; pass --config <path> or run xcli lab init",
+			config.DefaultConfigFileName,
+		)
+	}
+
+	rootDir := filepath.Dir(resolvedPath)
+	ws := &Workspace{
+		RootDir:       rootDir,
+		ConfigPath:    resolvedPath,
+		OverridesPath: filepath.Join(rootDir, constants.CBTOverridesFile),
+		StateDir:      filepath.Join(rootDir, ".xcli"),
+		ConfigExists:  exists,
+	}
+
+	if checkCWDOverrides {
+		if err := ws.CheckCWDOverrides(); err != nil {
+			return nil, err
+		}
+	}
+
+	return ws, nil
+}
+
+// LoadConfig resolves and loads the root config from the authoritative
+// workspace.
+func LoadConfig(configPath string, requireConfig bool, checkCWDOverrides bool) (*config.Config, *Workspace, error) {
+	ws, err := Resolve(configPath, requireConfig, checkCWDOverrides)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	result, err := config.Load(ws.ConfigPath)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to load config: %w", err)
+	}
+
+	return result.Config, ws, nil
+}
+
+// LoadLabConfig resolves the workspace, loads the lab config, and converts
+// repository paths to absolute paths relative to the config file directory.
+func LoadLabConfig(configPath string, checkCWDOverrides bool) (*config.LabConfig, *Workspace, error) {
+	rootCfg, ws, err := LoadConfig(configPath, true, checkCWDOverrides)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	if rootCfg.Lab == nil {
+		return nil, nil, fmt.Errorf("lab configuration not found - run 'xcli lab init' first")
+	}
+
+	ResolveLabRepoPaths(rootCfg.Lab, ws.RootDir)
+
+	return rootCfg.Lab, ws, nil
+}
+
+// ResolveLabRepoPaths resolves lab repository paths relative to rootDir.
+func ResolveLabRepoPaths(labCfg *config.LabConfig, rootDir string) {
+	if labCfg == nil {
+		return
+	}
+
+	labCfg.Repos.CBT = resolvePath(rootDir, labCfg.Repos.CBT)
+	labCfg.Repos.XatuCBT = resolvePath(rootDir, labCfg.Repos.XatuCBT)
+	labCfg.Repos.CBTAPI = resolvePath(rootDir, labCfg.Repos.CBTAPI)
+	labCfg.Repos.LabBackend = resolvePath(rootDir, labCfg.Repos.LabBackend)
+	labCfg.Repos.Lab = resolvePath(rootDir, labCfg.Repos.Lab)
+}
+
+// CheckCWDOverrides prevents a .cbt-overrides.yaml in the current working
+// directory from being mistaken for the authoritative workspace override file.
+func (w *Workspace) CheckCWDOverrides() error {
+	cwd, err := os.Getwd()
+	if err != nil {
+		return fmt.Errorf("failed to get current directory: %w", err)
+	}
+
+	cwdOverrides := filepath.Join(cwd, constants.CBTOverridesFile)
+
+	cwdOverrides, err = filepath.Abs(cwdOverrides)
+	if err != nil {
+		return fmt.Errorf("failed to resolve current overrides path: %w", err)
+	}
+
+	if samePath(cwdOverrides, w.OverridesPath) {
+		return nil
+	}
+
+	if _, statErr := os.Stat(cwdOverrides); statErr == nil {
+		return fmt.Errorf(
+			"refusing to continue: current directory contains %s at %s, but the authoritative overrides path for config %s is %s",
+			constants.CBTOverridesFile,
+			cwdOverrides,
+			w.ConfigPath,
+			w.OverridesPath,
+		)
+	} else if !os.IsNotExist(statErr) {
+		return fmt.Errorf("failed to inspect current overrides path %s: %w", cwdOverrides, statErr)
+	}
+
+	return nil
+}
+
+func resolveDefaultConfig() (string, bool, error) {
+	cwd, err := os.Getwd()
+	if err != nil {
+		return "", false, fmt.Errorf("failed to get current directory: %w", err)
+	}
+
+	if found := searchUpward(cwd, config.DefaultConfigFileName); found != "" {
+		return found, true, nil
+	}
+
+	fallback, err := filepath.Abs(filepath.Join(cwd, config.DefaultConfigFileName))
+	if err != nil {
+		return "", false, fmt.Errorf("failed to resolve default config path: %w", err)
+	}
+
+	return fallback, false, nil
+}
+
+func resolveExplicitConfig(path string) (string, bool, error) {
+	absPath, err := filepath.Abs(path)
+	if err != nil {
+		return "", false, fmt.Errorf("failed to resolve config path %q: %w", path, err)
+	}
+
+	_, statErr := os.Stat(absPath)
+	switch {
+	case statErr == nil:
+		return absPath, true, nil
+	case os.IsNotExist(statErr):
+		return absPath, false, nil
+	default:
+		return "", false, fmt.Errorf("failed to inspect config path %s: %w", absPath, statErr)
+	}
+}
+
+func searchUpward(startDir, fileName string) string {
+	currentDir := startDir
+
+	for {
+		configPath := filepath.Join(currentDir, fileName)
+		if _, err := os.Stat(configPath); err == nil {
+			absPath, absErr := filepath.Abs(configPath)
+			if absErr != nil {
+				return configPath
+			}
+
+			return absPath
+		}
+
+		parentDir := filepath.Dir(currentDir)
+		if parentDir == currentDir {
+			return ""
+		}
+
+		currentDir = parentDir
+	}
+}
+
+func resolvePath(rootDir, path string) string {
+	if path == "" {
+		return ""
+	}
+
+	if filepath.IsAbs(path) {
+		return filepath.Clean(path)
+	}
+
+	return filepath.Clean(filepath.Join(rootDir, path))
+}
+
+func isDefaultConfigPath(path string) bool {
+	return path == config.DefaultConfigFileName ||
+		path == "."+string(filepath.Separator)+config.DefaultConfigFileName
+}
+
+func samePath(a, b string) bool {
+	return filepath.Clean(normalizePath(a)) == filepath.Clean(normalizePath(b))
+}
+
+func normalizePath(path string) string {
+	if evaluated, err := filepath.EvalSymlinks(path); err == nil {
+		return evaluated
+	}
+
+	if absPath, err := filepath.Abs(path); err == nil {
+		return absPath
+	}
+
+	return path
+}
diff --git a/pkg/workspace/workspace_test.go b/pkg/workspace/workspace_test.go
new file mode 100644
index 0000000..5d774bc
--- /dev/null
+++ b/pkg/workspace/workspace_test.go
@@ -0,0 +1,145 @@
+package workspace
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/ethpandaops/xcli/pkg/config"
+	"github.com/ethpandaops/xcli/pkg/constants"
+	"github.com/stretchr/testify/require"
+)
+
+func TestResolveDefaultSearchesUpwardOnly(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+
+	origWD, err := os.Getwd()
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		require.NoError(t, os.Chdir(origWD))
+	})
+
+	parent := t.TempDir()
+	child := filepath.Join(parent, "child")
+	require.NoError(t, os.MkdirAll(child, 0755))
+	require.NoError(t, os.WriteFile(filepath.Join(parent, config.DefaultConfigFileName), []byte("lab: {}\n"), 0644))
+	require.NoError(t, os.Chdir(child))
+
+	ws, err := Resolve(config.DefaultConfigFileName, true, false)
+	require.NoError(t, err)
+	require.True(t, samePath(filepath.Join(parent, config.DefaultConfigFileName), ws.ConfigPath))
+	require.True(t, samePath(parent, ws.RootDir))
+}
+
+func TestResolveDefaultDoesNotSearchChildrenOrGlobal(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+
+	origWD, err := os.Getwd()
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		require.NoError(t, os.Chdir(origWD))
+	})
+
+	cwd := t.TempDir()
+	child := filepath.Join(cwd, "child")
+	require.NoError(t, os.MkdirAll(child, 0755))
+	require.NoError(t, os.WriteFile(filepath.Join(child, config.DefaultConfigFileName), []byte("lab: {}\n"), 0644))
+
+	globalRoot := filepath.Join(home, "registered")
+	require.NoError(t, os.MkdirAll(globalRoot, 0755))
+	require.NoError(t, os.WriteFile(filepath.Join(globalRoot, config.DefaultConfigFileName), []byte("lab: {}\n"), 0644))
+	require.NoError(t, config.SaveGlobalConfig(&config.GlobalConfig{XCLIPath: globalRoot}))
+
+	require.NoError(t, os.Chdir(cwd))
+
+	_, err = Resolve(config.DefaultConfigFileName, true, false)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "no .xcli.yaml found searching upward")
+}
+
+func TestResolveExplicitConfigWins(t *testing.T) {
+	origWD, err := os.Getwd()
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		require.NoError(t, os.Chdir(origWD))
+	})
+
+	root := t.TempDir()
+	nested := filepath.Join(root, "nested")
+	require.NoError(t, os.MkdirAll(nested, 0755))
+
+	defaultConfig := filepath.Join(root, config.DefaultConfigFileName)
+	explicitConfig := filepath.Join(root, "custom.yaml")
+
+	require.NoError(t, os.WriteFile(defaultConfig, []byte("lab: {}\n"), 0644))
+	require.NoError(t, os.WriteFile(explicitConfig, []byte("lab: {}\n"), 0644))
+	require.NoError(t, os.Chdir(nested))
+
+	ws, err := Resolve(explicitConfig, true, false)
+	require.NoError(t, err)
+	require.Equal(t, explicitConfig, ws.ConfigPath)
+}
+
+func TestResolveExplicitMissingConfigReportsPath(t *testing.T) {
+	missingPath := filepath.Join(t.TempDir(), "missing.yaml")
+
+	_, err := Resolve(missingPath, true, false)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "config file not found: "+missingPath)
+}
+
+func TestLoadLabConfigResolvesRepoPathsRelativeToConfig(t *testing.T) {
+	origWD, err := os.Getwd()
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		require.NoError(t, os.Chdir(origWD))
+	})
+
+	root := t.TempDir()
+	other := t.TempDir()
+	require.NoError(t, os.Chdir(other))
+
+	configPath := filepath.Join(root, config.DefaultConfigFileName)
+	require.NoError(t, os.WriteFile(configPath, []byte(`
+lab:
+  repos:
+    cbt: ../repos/cbt
+    xatuCbt: ../repos/xatu-cbt
+    cbtApi: ../repos/cbt-api
+    labBackend: ../repos/lab-backend
+    lab: /abs/lab
+  mode: local
+  networks:
+    - name: mainnet
+      enabled: true
+`), 0644))
+
+	labCfg, _, err := LoadLabConfig(configPath, false)
+	require.NoError(t, err)
+	require.Equal(t, filepath.Clean(filepath.Join(root, "../repos/cbt")), labCfg.Repos.CBT)
+	require.Equal(t, filepath.Clean(filepath.Join(root, "../repos/xatu-cbt")), labCfg.Repos.XatuCBT)
+	require.Equal(t, filepath.Clean(filepath.Join(root, "../repos/cbt-api")), labCfg.Repos.CBTAPI)
+	require.Equal(t, filepath.Clean(filepath.Join(root, "../repos/lab-backend")), labCfg.Repos.LabBackend)
+	require.Equal(t, filepath.Clean("/abs/lab"), labCfg.Repos.Lab)
+}
+
+func TestResolveRejectsDifferentCWDOverrides(t *testing.T) {
+	origWD, err := os.Getwd()
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		require.NoError(t, os.Chdir(origWD))
+	})
+
+	root := t.TempDir()
+	child := filepath.Join(root, "child")
+	require.NoError(t, os.MkdirAll(child, 0755))
+	require.NoError(t, os.WriteFile(filepath.Join(root, config.DefaultConfigFileName), []byte("lab: {}\n"), 0644))
+	require.NoError(t, os.WriteFile(filepath.Join(child, constants.CBTOverridesFile), []byte("models: {}\n"), 0644))
+	require.NoError(t, os.Chdir(child))
+
+	_, err = Resolve(config.DefaultConfigFileName, true, true)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "refusing to continue")
+	require.Contains(t, err.Error(), filepath.Join(root, constants.CBTOverridesFile))
+}