🤖 feat: add DockerRuntime support

- Add DockerRuntime implementation (docker exec-based runtime)
- Add runtime parsing/config support for docker
- Keep container naming compatible with existing workspaces

---
_Generated with `mux` • Model: `openai:gpt-5.2` • Thinking: `xhigh`_

Author: ammar-agent

docs/system-prompt.mdx

@@ -47,11 +47,11 @@ When the user asks you to remember something:
 /**
  * Build environment context XML block describing the workspace.
  * @param workspacePath - Workspace directory path
- * @param runtimeType - Runtime type: "local", "worktree", or "ssh"
+ * @param runtimeType - Runtime type: "local", "worktree", "ssh", or "docker"
  */
 function buildEnvironmentContext(
   workspacePath: string,
-  runtimeType: "local" | "worktree" | "ssh"
+  runtimeType: "local" | "worktree" | "ssh" | "docker"
 ): string {
   if (runtimeType === "local") {
     // Local runtime works directly in project directory - may or may not be git
@@ -78,6 +78,19 @@ You are in a clone of a git repository at ${workspacePath}
 `;
   }
 
+  if (runtimeType === "docker") {
+    // Docker runtime runs in an isolated container
+    return `
+<environment>
+You are in a clone of a git repository at ${workspacePath} inside a Docker container
+
+- This IS a git repository - run git commands directly (no cd needed)
+- Tools run here automatically inside the container
+- You are meant to do your work isolated from the user and other agents
+</environment>
+`;
+  }
+
   // Worktree runtime creates a git worktree locally
   return `
 <environment>

src/browser/components/ChatInput/useCreationWorkspace.test.tsx

@@ -550,6 +550,7 @@ function createDraftSettingsHarness(
   initial?: Partial<{
     runtimeMode: RuntimeMode;
     sshHost: string;
+    dockerImage: string;
     trunkBranch: string;
     runtimeString?: string | undefined;
     defaultRuntimeMode?: RuntimeMode;
@@ -559,12 +560,14 @@ function createDraftSettingsHarness(
     runtimeMode: initial?.runtimeMode ?? "local",
     defaultRuntimeMode: initial?.defaultRuntimeMode ?? "worktree",
     sshHost: initial?.sshHost ?? "",
+    dockerImage: initial?.dockerImage ?? "",
     trunkBranch: initial?.trunkBranch ?? "main",
     runtimeString: initial?.runtimeString,
   } satisfies {
     runtimeMode: RuntimeMode;
     defaultRuntimeMode: RuntimeMode;
     sshHost: string;
+    dockerImage: string;
     trunkBranch: string;
     runtimeString: string | undefined;
   };
@@ -592,18 +595,24 @@ function createDraftSettingsHarness(
     state.sshHost = host;
   });
 
+  const setDockerImage = mock((image: string) => {
+    state.dockerImage = image;
+  });
+
   return {
     state,
     setRuntimeMode,
     setDefaultRuntimeMode,
     setSshHost,
+    setDockerImage,
     setTrunkBranch,
     getRuntimeString,
     snapshot(): {
       settings: DraftWorkspaceSettings;
       setRuntimeMode: typeof setRuntimeMode;
       setDefaultRuntimeMode: typeof setDefaultRuntimeMode;
       setSshHost: typeof setSshHost;
+      setDockerImage: typeof setDockerImage;
       setTrunkBranch: typeof setTrunkBranch;
       getRuntimeString: typeof getRuntimeString;
     } {
@@ -614,13 +623,15 @@ function createDraftSettingsHarness(
         runtimeMode: state.runtimeMode,
         defaultRuntimeMode: state.defaultRuntimeMode,
         sshHost: state.sshHost,
+        dockerImage: state.dockerImage ?? "",
         trunkBranch: state.trunkBranch,
       };
       return {
         settings,
         setRuntimeMode,
         setDefaultRuntimeMode,
         setSshHost,
+        setDockerImage,
         setTrunkBranch,
         getRuntimeString,
       };

src/browser/components/RuntimeIconSelector.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 import { cn } from "@/common/lib/utils";
 import { RUNTIME_MODE, type RuntimeMode } from "@/common/types/runtime";
-import { SSHIcon, WorktreeIcon, LocalIcon } from "./icons/RuntimeIcons";
+import { SSHIcon, WorktreeIcon, LocalIcon, DockerIcon } from "./icons/RuntimeIcons";
 import { Tooltip, TooltipTrigger, TooltipContent } from "./ui/tooltip";
 
 interface RuntimeIconSelectorProps {
@@ -36,6 +36,11 @@ const RUNTIME_STYLES = {
     active:
       "bg-[var(--color-runtime-local)]/30 text-foreground border-[var(--color-runtime-local)]/60",
   },
+  docker: {
+    idle: "bg-transparent text-muted border-[var(--color-runtime-docker)]/30 hover:border-[var(--color-runtime-docker)]/50",
+    active:
+      "bg-[var(--color-runtime-docker)]/20 text-[var(--color-runtime-docker-text)] border-[var(--color-runtime-docker)]/60",
+  },
 } as const;
 
 const RUNTIME_INFO: Record<RuntimeMode, { label: string; description: string }> = {
@@ -51,6 +56,10 @@ const RUNTIME_INFO: Record<RuntimeMode, { label: string; description: string }>
     label: "SSH",
     description: "Remote clone on SSH host",
   },
+  docker: {
+    label: "Docker",
+    description: "Isolated container per workspace",
+  },
 };
 
 interface RuntimeIconButtonProps {
@@ -74,7 +83,9 @@ function RuntimeIconButton(props: RuntimeIconButtonProps) {
       ? SSHIcon
       : props.mode === RUNTIME_MODE.WORKTREE
         ? WorktreeIcon
-        : LocalIcon;
+        : props.mode === RUNTIME_MODE.DOCKER
+          ? DockerIcon
+          : LocalIcon;
 
   return (
     <Tooltip>
@@ -127,7 +138,12 @@ function RuntimeIconButton(props: RuntimeIconButtonProps) {
  * Each tooltip has a "Default for project" checkbox to persist the preference.
  */
 export function RuntimeIconSelector(props: RuntimeIconSelectorProps) {
-  const modes: RuntimeMode[] = [RUNTIME_MODE.LOCAL, RUNTIME_MODE.WORKTREE, RUNTIME_MODE.SSH];
+  const modes: RuntimeMode[] = [
+    RUNTIME_MODE.LOCAL,
+    RUNTIME_MODE.WORKTREE,
+    RUNTIME_MODE.SSH,
+    RUNTIME_MODE.DOCKER,
+  ];
   const disabledModes = props.disabledModes ?? [];
 
   return (

src/browser/components/icons/RuntimeIcons.tsx

@@ -73,3 +73,28 @@ export function LocalIcon({ size = 10, className }: IconProps) {
     </svg>
   );
 }
+
+/** Container/box icon for Docker runtime */
+export function DockerIcon({ size = 10, className }: IconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-label="Docker Runtime"
+      className={className}
+    >
+      {/* Container box with stacked layers */}
+      <rect x="2" y="6" width="12" height="8" rx="1" />
+      <line x1="2" y1="10" x2="14" y2="10" />
+      <line x1="5" y1="3" x2="5" y2="6" />
+      <line x1="8" y1="2" x2="8" y2="6" />
+      <line x1="11" y1="3" x2="11" y2="6" />
+    </svg>
+  );
+}

src/browser/hooks/useDraftWorkspaceSettings.ts

@@ -5,14 +5,17 @@ import { useMode } from "@/browser/contexts/ModeContext";
 import { getDefaultModel } from "./useModelsFromSettings";
 import {
   type RuntimeMode,
+  type ParsedRuntime,
   parseRuntimeModeAndHost,
   buildRuntimeString,
+  RUNTIME_MODE,
 } from "@/common/types/runtime";
 import {
   getModelKey,
   getRuntimeKey,
   getTrunkBranchKey,
   getLastSshHostKey,
+  getLastDockerImageKey,
   getProjectScopeId,
 } from "@/common/constants/storage";
 import type { UIMode } from "@/common/types/mode";
@@ -33,7 +36,10 @@ export interface DraftWorkspaceSettings {
   runtimeMode: RuntimeMode;
   /** Persisted default runtime for this project (used to initialize selection) */
   defaultRuntimeMode: RuntimeMode;
+  /** SSH host (persisted separately from mode) */
   sshHost: string;
+  /** Docker image (persisted separately from mode) */
+  dockerImage: string;
   trunkBranch: string;
 }
 
@@ -57,6 +63,7 @@ export function useDraftWorkspaceSettings(
   /** Set the default runtime mode for this project (persists via checkbox) */
   setDefaultRuntimeMode: (mode: RuntimeMode) => void;
   setSshHost: (host: string) => void;
+  setDockerImage: (image: string) => void;
   setTrunkBranch: (branch: string) => void;
   getRuntimeString: () => string | undefined;
 } {
@@ -78,8 +85,9 @@ export function useDraftWorkspaceSettings(
     { listener: true }
   );
 
-  // Parse default runtime string into mode (worktree when undefined)
-  const { mode: defaultRuntimeMode } = parseRuntimeModeAndHost(defaultRuntimeString);
+  // Parse default runtime string into mode (worktree when undefined or invalid)
+  const parsedDefault = parseRuntimeModeAndHost(defaultRuntimeString);
+  const defaultRuntimeMode: RuntimeMode = parsedDefault?.mode ?? RUNTIME_MODE.WORKTREE;
 
   // Currently selected runtime mode for this session (initialized from default)
   // This allows user to select a different runtime without changing the default
@@ -105,6 +113,13 @@ export function useDraftWorkspaceSettings(
     { listener: true }
   );
 
+  // Project-scoped Docker image preference (persisted separately from runtime mode)
+  const [lastDockerImage, setLastDockerImage] = usePersistedState<string>(
+    getLastDockerImageKey(projectPath),
+    "",
+    { listener: true }
+  );
+
   // Initialize trunk branch from backend recommendation or first branch
   useEffect(() => {
     if (!trunkBranch && branches.length > 0) {
@@ -113,14 +128,31 @@ export function useDraftWorkspaceSettings(
     }
   }, [branches, recommendedTrunk, trunkBranch, setTrunkBranch]);
 
+  // Build ParsedRuntime from mode + stored host/image
+  const buildParsedRuntime = (mode: RuntimeMode): ParsedRuntime | null => {
+    switch (mode) {
+      case RUNTIME_MODE.LOCAL:
+        return { mode: "local" };
+      case RUNTIME_MODE.WORKTREE:
+        return { mode: "worktree" };
+      case RUNTIME_MODE.SSH:
+        return lastSshHost ? { mode: "ssh", host: lastSshHost } : null;
+      case RUNTIME_MODE.DOCKER:
+        return lastDockerImage ? { mode: "docker", image: lastDockerImage } : null;
+      default:
+        return null;
+    }
+  };
+
   // Setter for selected runtime mode (changes current selection, does not persist)
   const setRuntimeMode = (newMode: RuntimeMode) => {
     setSelectedRuntimeMode(newMode);
   };
 
   // Setter for default runtime mode (persists via checkbox in tooltip)
   const setDefaultRuntimeMode = (newMode: RuntimeMode) => {
-    const newRuntimeString = buildRuntimeString(newMode, lastSshHost);
+    const parsed = buildParsedRuntime(newMode);
+    const newRuntimeString = parsed ? buildRuntimeString(parsed) : undefined;
     setDefaultRuntimeString(newRuntimeString);
     // Also update selection to match new default
     setSelectedRuntimeMode(newMode);
@@ -131,9 +163,15 @@ export function useDraftWorkspaceSettings(
     setLastSshHost(newHost);
   };
 
+  // Setter for Docker image (persisted separately so it's remembered across mode switches)
+  const setDockerImage = (newImage: string) => {
+    setLastDockerImage(newImage);
+  };
+
   // Helper to get runtime string for IPC calls (uses selected mode, not default)
   const getRuntimeString = (): string | undefined => {
-    return buildRuntimeString(selectedRuntimeMode, lastSshHost);
+    const parsed = buildParsedRuntime(selectedRuntimeMode);
+    return parsed ? buildRuntimeString(parsed) : undefined;
   };
 
   return {
@@ -144,11 +182,13 @@ export function useDraftWorkspaceSettings(
       runtimeMode: selectedRuntimeMode,
       defaultRuntimeMode,
       sshHost: lastSshHost,
+      dockerImage: lastDockerImage,
       trunkBranch,
     },
     setRuntimeMode,
     setDefaultRuntimeMode,
     setSshHost,
+    setDockerImage,
     setTrunkBranch,
     getRuntimeString,
   };

src/browser/styles/globals.css

@@ -78,6 +78,8 @@
     --color-runtime-worktree: #a855f7;
     --color-runtime-worktree-text: #c084fc; /* purple-400 */
     --color-runtime-local: hsl(0 0% 60%); /* matches --color-muted-foreground */
+    --color-runtime-docker: #2496ed; /* Docker blue */
+    --color-runtime-docker-text: #54b3f4;
 
     /* Background & Layout */
     --color-background: hsl(0 0% 12%);
@@ -336,6 +338,8 @@
   --color-runtime-worktree: #a855f7;
   --color-runtime-worktree-text: #c084fc;
   --color-runtime-local: hsl(210 14% 48%); /* matches --color-muted-foreground */
+  --color-runtime-docker: #2496ed; /* Docker blue */
+  --color-runtime-docker-text: #0d7cc4;
 
   --color-background: hsl(210 33% 98%);
   --color-background-secondary: hsl(210 36% 95%);
@@ -575,6 +579,8 @@
   --color-runtime-worktree: #6c71c4; /* violet */
   --color-runtime-worktree-text: #6c71c4;
   --color-runtime-local: #839496; /* base0 */
+  --color-runtime-docker: #2aa198; /* cyan */
+  --color-runtime-docker-text: #2aa198;
 
   /* Background & Layout - Solarized base colors */
   --color-background: #fdf6e3; /* base3 */
@@ -784,6 +790,8 @@
   --color-runtime-worktree: #6c71c4; /* violet */
   --color-runtime-worktree-text: #6c71c4;
   --color-runtime-local: #839496; /* base0 */
+  --color-runtime-docker: #2aa198; /* cyan */
+  --color-runtime-docker-text: #2aa198;
 
   /* Background & Layout - Solarized dark base colors
      Palette reference:

src/browser/utils/chatCommands.test.ts

@@ -98,12 +98,37 @@ describe("parseRuntimeString", () => {
     });
   });
 
-  test("throws error for unknown runtime type", () => {
+  test("parses docker runtime with image", () => {
+    const result = parseRuntimeString("docker ubuntu:22.04", workspaceName);
+    expect(result).toEqual({
+      type: "docker",
+      image: "ubuntu:22.04",
+    });
+  });
+
+  test("parses docker with registry image", () => {
+    const result = parseRuntimeString("docker ghcr.io/myorg/dev:latest", workspaceName);
+    expect(result).toEqual({
+      type: "docker",
+      image: "ghcr.io/myorg/dev:latest",
+    });
+  });
+
+  test("throws error for docker without image", () => {
     expect(() => parseRuntimeString("docker", workspaceName)).toThrow(
-      "Unknown runtime type: 'docker'. Use 'ssh <host>', 'worktree', or 'local'"
+      "Docker runtime requires image"
     );
+    expect(() => parseRuntimeString("docker ", workspaceName)).toThrow(
+      "Docker runtime requires image"
+    );
+  });
+
+  test("throws error for unknown runtime type", () => {
     expect(() => parseRuntimeString("remote", workspaceName)).toThrow(
-      "Unknown runtime type: 'remote'. Use 'ssh <host>', 'worktree', or 'local'"
+      "Unknown runtime type: 'remote'. Use 'ssh <host>', 'docker <image>', 'worktree', or 'local'"
+    );
+    expect(() => parseRuntimeString("kubernetes", workspaceName)).toThrow(
+      "Unknown runtime type: 'kubernetes'. Use 'ssh <host>', 'docker <image>', 'worktree', or 'local'"
     );
   });
 });