Add command to show and switch global runtime setting

Author: nezhar

README.md

@@ -82,6 +82,7 @@ This repository contains an initial v1 implementation with:
 - `vp list`
 - `vp config init`
 - `vp config show`
+- `vp config runtime`
 - `vp config path`
 - `vp version`
 

docs/configuration.md

@@ -7,7 +7,7 @@ VibePod merges configuration from four sources in order, with each layer overrid
 3. **Project config** — `.vibepod/config.yaml` in the current directory
 4. **Environment variables** — override specific keys at runtime
 
-Run `vp config path` to print the exact paths in use, and `vp config show` to print the fully merged result.
+Run `vp config path` to print the exact paths in use, `vp config show` to print the fully merged result, and `vp config runtime` to view or change the saved global container runtime.
 
 ## Full reference
 
@@ -160,6 +160,24 @@ VP_IMAGE_NAMESPACE=myorg vp run claude
 
 For end-to-end examples (extending a base image and assigning a brand-new image to an agent), see [Agents > Image customization workflows](agents/index.md#image-customization-workflows).
 
+## Runtime preference
+
+Use `vp config runtime` to inspect the saved global runtime preference:
+
+```bash
+vp config runtime
+```
+
+Set it explicitly without editing YAML by hand:
+
+```bash
+vp config runtime podman
+vp config runtime docker
+vp config runtime auto
+```
+
+This updates `container_runtime` in the global config file (`~/.config/vibepod/config.yaml` by default).
+
 ## Project-level config
 
 Use `vp config init` in your repository to create `.vibepod/config.yaml` automatically when it does not already exist:

docs/podman.md

@@ -46,7 +46,13 @@ This is useful in CI or shell profiles where you always want a specific runtime.
 
 ### 3. Global config
 
-Add `container_runtime` to `~/.config/vibepod/config.yaml`:
+Set the saved global runtime with the CLI:
+
+```bash
+vp config runtime podman
+```
+
+This writes `container_runtime` to `~/.config/vibepod/config.yaml`:
 
 ```yaml
 container_runtime: podman
@@ -56,6 +62,10 @@ When VibePod prompts you to choose a runtime interactively, it saves your answer
 
 Set it back to `auto` to re-enable detection:
 
+```bash
+vp config runtime auto
+```
+
 ```yaml
 container_runtime: auto
 ```

src/vibepod/commands/config.py

@@ -10,14 +10,15 @@
 import typer
 import yaml
 
-from vibepod.constants import SUPPORTED_AGENTS
+from vibepod.constants import RUNTIME_AUTO, SUPPORTED_AGENTS, SUPPORTED_RUNTIMES
 from vibepod.core.allowed_dirs import (
     add_allowed_dir,
     is_protected_dir,
     load_allowed_dirs,
     remove_allowed_dir,
 )
 from vibepod.core.config import get_config, get_global_config_path, get_project_config_path
+from vibepod.core.runtime import get_saved_runtime_preference, save_runtime_preference
 from vibepod.utils.console import console, error, success
 
 app = typer.Typer(help="Manage configuration")
@@ -116,6 +117,48 @@ def show(
     console.print(dumped)
 
 
+@app.command("runtime")
+def runtime(
+    value: Annotated[
+        str | None,
+        typer.Argument(help="Default global runtime: auto, docker, or podman"),
+    ] = None,
+) -> None:
+    """Show or set the saved default container runtime."""
+    if value is None:
+        try:
+            print(get_saved_runtime_preference())
+        except (OSError, ValueError) as exc:
+            error(str(exc))
+            raise typer.Exit(1) from exc
+        except yaml.YAMLError as exc:
+            error(f"Failed to parse global config at {get_global_config_path()}: {exc}")
+            raise typer.Exit(1) from exc
+        return
+
+    allowed = (RUNTIME_AUTO, *SUPPORTED_RUNTIMES)
+    normalized = value.strip().lower()
+    if normalized not in allowed:
+        error(f"Unknown runtime '{value}'. Supported: {', '.join(allowed)}")
+        raise typer.Exit(1)
+
+    try:
+        save_runtime_preference(normalized)
+    except OSError as exc:
+        error(f"Failed to update global config at {get_global_config_path()}: {exc}")
+        raise typer.Exit(1) from exc
+    except ValueError as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+    except yaml.YAMLError as exc:
+        error(f"Failed to parse global config at {get_global_config_path()}: {exc}")
+        raise typer.Exit(1) from exc
+
+    success(
+        f"Set default container runtime to '{normalized}' in {get_global_config_path()}"
+    )
+
+
 @app.command("path")
 def path(
     global_only: Annotated[

src/vibepod/core/docker.py

@@ -59,7 +59,7 @@ def get_manager(
 
     try:
         runtime_name, socket_url = resolve_runtime(override=runtime_override, config=config)
-    except RuntimeError as exc:
+    except (RuntimeError, ValueError) as exc:
         raise DockerClientError(str(exc)) from exc
 
     return DockerManager(base_url=socket_url, runtime=runtime_name)

src/vibepod/core/runtime.py

@@ -22,6 +22,10 @@
 DEFAULT_RUNTIME_PROBE_TIMEOUT = 10.0
 
 
+def _allowed_runtime_preferences() -> tuple[str, ...]:
+    return (RUNTIME_AUTO, *SUPPORTED_RUNTIMES)
+
+
 def _socket_candidates() -> list[tuple[str, str]]:
     """Return (runtime_name, socket_url) pairs to probe.
 
@@ -96,8 +100,41 @@ def detect_available_runtimes() -> dict[str, str]:
     return found
 
 
+def get_saved_runtime_preference() -> str:
+    """Return the saved global ``container_runtime`` preference."""
+    config_path = get_config_root() / "config.yaml"
+    if not config_path.exists():
+        return RUNTIME_AUTO
+
+    content = config_path.read_text(encoding="utf-8")
+    if not content.strip():
+        return RUNTIME_AUTO
+
+    loaded = yaml.safe_load(content)
+    if loaded is None:
+        return RUNTIME_AUTO
+    if not isinstance(loaded, dict):
+        raise ValueError(f"Global config must contain a YAML mapping: {config_path}")
+
+    saved = loaded.get("container_runtime", RUNTIME_AUTO)
+    runtime = str(saved).strip().lower() or RUNTIME_AUTO
+    if runtime not in _allowed_runtime_preferences():
+        raise ValueError(
+            f"Unknown container runtime '{runtime}'. "
+            f"Supported: {', '.join(_allowed_runtime_preferences())}"
+        )
+    return runtime
+
+
 def save_runtime_preference(runtime: str) -> None:
     """Persist *runtime* as ``container_runtime`` in the global config file."""
+    normalized = runtime.strip().lower()
+    if normalized not in _allowed_runtime_preferences():
+        raise ValueError(
+            f"Unknown container runtime '{normalized}'. "
+            f"Supported: {', '.join(_allowed_runtime_preferences())}"
+        )
+
     config_path = get_config_root() / "config.yaml"
     config_path.parent.mkdir(parents=True, exist_ok=True)
 
@@ -106,10 +143,13 @@ def save_runtime_preference(runtime: str) -> None:
         content = config_path.read_text(encoding="utf-8")
         if content.strip():
             loaded = yaml.safe_load(content)
-            if isinstance(loaded, dict):
-                existing = loaded
+            if loaded is None:
+                loaded = {}
+            if not isinstance(loaded, dict):
+                raise ValueError(f"Global config must contain a YAML mapping: {config_path}")
+            existing = loaded
 
-    existing["container_runtime"] = runtime
+    existing["container_runtime"] = normalized
     config_path.write_text(yaml.safe_dump(existing, sort_keys=False), encoding="utf-8")
 
 

tests/test_config.py

@@ -264,3 +264,43 @@ def test_list_allowed_dirs_empty(monkeypatch, tmp_path: Path) -> None:
     result = runner.invoke(app, ["config", "list-allowed-dirs"])
     assert result.exit_code == 0
     assert "No directories" in result.stdout
+
+
+# ---------------------------------------------------------------------------
+# runtime subcommand tests
+# ---------------------------------------------------------------------------
+
+
+def test_config_runtime_shows_saved_global_runtime(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("VP_CONFIG_DIR", str(tmp_path))
+
+    result = runner.invoke(app, ["config", "runtime"])
+
+    assert result.exit_code == 0
+    assert result.stdout.strip() == "auto"
+
+
+def test_config_runtime_updates_global_config(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("VP_CONFIG_DIR", str(tmp_path))
+    global_config = tmp_path / "config.yaml"
+    global_config.write_text("default_agent: codex\n", encoding="utf-8")
+
+    result = runner.invoke(app, ["config", "runtime", "podman"])
+
+    assert result.exit_code == 0
+    loaded = yaml.safe_load(global_config.read_text(encoding="utf-8"))
+    assert loaded == {
+        "default_agent": "codex",
+        "container_runtime": "podman",
+    }
+    assert "Set default container runtime to 'podman'" in result.stdout
+
+
+def test_config_runtime_rejects_unknown_value(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("VP_CONFIG_DIR", str(tmp_path))
+
+    result = runner.invoke(app, ["config", "runtime", "nerdctl"])
+
+    assert result.exit_code == 1
+    assert "Supported: auto, docker, podman" in result.stdout
+    assert not (tmp_path / "config.yaml").exists()

tests/test_runtime.py

@@ -8,6 +8,7 @@
 import pytest
 from rich.prompt import Prompt
 
+from vibepod.core import docker as docker_core
 from vibepod.core import runtime
 
 
@@ -104,3 +105,18 @@ def test_resolve_runtime_rejects_unavailable_prompt_choice(monkeypatch) -> None:
 
     with pytest.raises(RuntimeError, match="not available"):
         runtime.resolve_runtime()
+
+
+def test_get_manager_wraps_runtime_preference_errors(monkeypatch) -> None:
+    def _raise_runtime_preference_error(**kwargs) -> tuple[str, str]:
+        del kwargs
+        raise ValueError("Global config must contain a YAML mapping: /tmp/config.yaml")
+
+    monkeypatch.setattr(
+        runtime,
+        "resolve_runtime",
+        _raise_runtime_preference_error,
+    )
+
+    with pytest.raises(docker_core.DockerClientError, match="Global config must contain"):
+        docker_core.get_manager()