🤖 feat: add Docker runtime support

Add Docker runtime for running workspaces in isolated containers.

Key features:
- One container per workspace (mux-{project}-{workspace})
- Fixed paths inside container: /src for workspace, /tmp/mux-bashes for background processes
- Container lifecycle managed by mux (created on workspace creation, destroyed on deletion)
- Project sync via git bundle (docker cp to transfer)

New files:
- DockerRuntime.ts: Main runtime implementation with exec, file ops, workspace management
- DockerRuntime.test.ts: Basic unit tests

Schema changes:
- Added 'docker' to RuntimeModeSchema enum
- Docker config: { type: 'docker', image: string }

Frontend updates:
- DockerIcon component
- Docker runtime in selector with cyan/docker-blue colors
- /new -r docker <image> syntax support

Usage: /new my-feature -r docker ubuntu:22.04

_Generated with mux_

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/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/styles/globals.css

@@ -76,6 +76,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%);
@@ -323,6 +325,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%);
@@ -555,6 +559,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 */
@@ -770,6 +776,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'"
     );
   });
 });

src/browser/utils/chatCommands.ts

@@ -16,7 +16,7 @@ import type {
 } from "@/common/types/message";
 import type { FrontendWorkspaceMetadata } from "@/common/types/workspace";
 import type { RuntimeConfig } from "@/common/types/runtime";
-import { RUNTIME_MODE, SSH_RUNTIME_PREFIX } from "@/common/types/runtime";
+import { RUNTIME_MODE, SSH_RUNTIME_PREFIX, DOCKER_RUNTIME_PREFIX } from "@/common/types/runtime";
 import { CUSTOM_EVENTS, createCustomEvent } from "@/common/constants/events";
 import { WORKSPACE_ONLY_COMMANDS } from "@/constants/slashCommands";
 import type { Toast } from "@/browser/components/ChatInputToast";
@@ -439,6 +439,7 @@ async function handleForkCommand(
  * Parse runtime string from -r flag into RuntimeConfig for backend
  * Supports formats:
  * - "ssh <host>" or "ssh <user@host>" -> SSH runtime
+ * - "docker <image>" -> Docker container runtime
  * - "worktree" -> Worktree runtime (git worktrees)
  * - "local" -> Local runtime (project-dir, no isolation)
  * - undefined -> Worktree runtime (default)
@@ -482,7 +483,22 @@ export function parseRuntimeString(
     };
   }
 
-  throw new Error(`Unknown runtime type: '${runtime}'. Use 'ssh <host>', 'worktree', or 'local'`);
+  // Parse "docker <image>" format
+  if (lowerTrimmed === RUNTIME_MODE.DOCKER || lowerTrimmed.startsWith(DOCKER_RUNTIME_PREFIX)) {
+    const imagePart = trimmed.slice(DOCKER_RUNTIME_PREFIX.length - 1).trim(); // Preserve original case for image
+    if (!imagePart) {
+      throw new Error("Docker runtime requires image (e.g., 'docker ubuntu:22.04')");
+    }
+
+    return {
+      type: RUNTIME_MODE.DOCKER,
+      image: imagePart,
+    };
+  }
+
+  throw new Error(
+    `Unknown runtime type: '${runtime}'. Use 'ssh <host>', 'docker <image>', 'worktree', or 'local'`
+  );
 }
 
 export interface CreateWorkspaceOptions {

src/browser/utils/ui/runtimeBadge.ts

@@ -24,3 +24,19 @@ export function extractSshHostname(runtimeConfig?: RuntimeConfig): string | null
 
   return hostname || null;
 }
+
+/**
+ * Extract Docker image from Docker runtime config.
+ * Returns null if runtime is not Docker.
+ *
+ * Examples:
+ * - "ubuntu:22.04" -> "ubuntu:22.04"
+ * - "ghcr.io/myorg/dev-image:latest" -> "ghcr.io/myorg/dev-image:latest"
+ */
+export function extractDockerImage(runtimeConfig?: RuntimeConfig): string | null {
+  if (!runtimeConfig?.type || runtimeConfig.type !== "docker") {
+    return null;
+  }
+
+  return runtimeConfig.image || null;
+}

src/common/orpc/schemas/runtime.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 
-export const RuntimeModeSchema = z.enum(["local", "worktree", "ssh"]);
+export const RuntimeModeSchema = z.enum(["local", "worktree", "ssh", "docker"]);
 
 /**
  * Runtime configuration union type.
@@ -56,4 +56,9 @@ export const RuntimeConfigSchema = z.union([
       .meta({ description: "Path to SSH private key (if not using ~/.ssh/config or ssh-agent)" }),
     port: z.number().optional().meta({ description: "SSH port (default: 22)" }),
   }),
+  // Docker runtime - each workspace runs in its own container
+  z.object({
+    type: z.literal("docker"),
+    image: z.string().meta({ description: "Docker image to use (e.g., ubuntu:22.04)" }),
+  }),
 ]);

src/common/types/runtime.ts

@@ -14,20 +14,27 @@ export const RUNTIME_MODE = {
   LOCAL: "local" as const,
   WORKTREE: "worktree" as const,
   SSH: "ssh" as const,
+  DOCKER: "docker" as const,
 } as const;
 
 /** Runtime string prefix for SSH mode (e.g., "ssh hostname") */
 export const SSH_RUNTIME_PREFIX = "ssh ";
 
+/** Runtime string prefix for Docker mode (e.g., "docker ubuntu:22.04") */
+export const DOCKER_RUNTIME_PREFIX = "docker ";
+
 export type RuntimeConfig = z.infer<typeof RuntimeConfigSchema>;
 
 /**
- * Parse runtime string from localStorage or UI input into mode and host
+ * Parse runtime string from localStorage or UI input into mode and host/image
  * Format: "ssh <host>" -> { mode: "ssh", host: "<host>" }
  *         "ssh" -> { mode: "ssh", host: "" }
+ *         "docker <image>" -> { mode: "docker", host: "<image>" }
+ *         "docker" -> { mode: "docker", host: "" }
  *         "worktree" -> { mode: "worktree", host: "" }
  *         "local" or undefined -> { mode: "local", host: "" }
  *
+ * Note: For Docker, "host" field stores the image name for consistency.
  * Use this for UI state management (localStorage, form inputs)
  */
 export function parseRuntimeModeAndHost(runtime: string | null | undefined): {
@@ -60,6 +67,17 @@ export function parseRuntimeModeAndHost(runtime: string | null | undefined): {
     return { mode: RUNTIME_MODE.SSH, host: "" };
   }
 
+  // Check for "docker <image>" format
+  if (lowerTrimmed.startsWith(DOCKER_RUNTIME_PREFIX)) {
+    const image = trimmed.substring(DOCKER_RUNTIME_PREFIX.length).trim();
+    return { mode: RUNTIME_MODE.DOCKER, host: image };
+  }
+
+  // Plain "docker" without image
+  if (lowerTrimmed === RUNTIME_MODE.DOCKER) {
+    return { mode: RUNTIME_MODE.DOCKER, host: "" };
+  }
+
   // Try to parse as a plain mode
   const modeResult = RuntimeModeSchema.safeParse(lowerTrimmed);
   if (modeResult.success) {
@@ -71,15 +89,20 @@ export function parseRuntimeModeAndHost(runtime: string | null | undefined): {
 }
 
 /**
- * Build runtime string for storage/IPC from mode and host
- * Returns: "ssh <host>" for SSH, "local" for local, undefined for worktree (default)
+ * Build runtime string for storage/IPC from mode and host/image
+ * Returns: "ssh <host>" for SSH, "docker <image>" for Docker, "local" for local, undefined for worktree (default)
  */
 export function buildRuntimeString(mode: RuntimeMode, host: string): string | undefined {
   if (mode === RUNTIME_MODE.SSH) {
     const trimmedHost = host.trim();
     // Persist SSH mode even without a host so UI remains in SSH state
     return trimmedHost ? `${SSH_RUNTIME_PREFIX}${trimmedHost}` : "ssh";
   }
+  if (mode === RUNTIME_MODE.DOCKER) {
+    const trimmedImage = host.trim();
+    // Persist Docker mode even without an image so UI remains in Docker state
+    return trimmedImage ? `${DOCKER_RUNTIME_PREFIX}${trimmedImage}` : "docker";
+  }
   if (mode === RUNTIME_MODE.LOCAL) {
     return "local";
   }
@@ -96,6 +119,15 @@ export function isSSHRuntime(
   return config?.type === "ssh";
 }
 
+/**
+ * Type guard to check if a runtime config is Docker
+ */
+export function isDockerRuntime(
+  config: RuntimeConfig | undefined
+): config is Extract<RuntimeConfig, { type: "docker" }> {
+  return config?.type === "docker";
+}
+
 /**
  * Type guard to check if a runtime config uses worktree semantics.
  * This includes both explicit "worktree" type AND legacy "local" with srcBaseDir.

src/common/utils/runtimeCompatibility.ts

@@ -19,13 +19,14 @@ import type { RuntimeConfig } from "@/common/types/runtime";
  * - "local" with srcBaseDir: Legacy worktree config (for backward compat)
  * - "worktree": Explicit worktree runtime
  * - "ssh": Remote SSH runtime
+ * - "docker": Docker container runtime
  */
 export function isIncompatibleRuntimeConfig(config: RuntimeConfig | undefined): boolean {
   if (!config) {
     return false;
   }
   // All known types are compatible
-  const knownTypes = ["local", "worktree", "ssh"];
+  const knownTypes = ["local", "worktree", "ssh", "docker"];
   if (!knownTypes.includes(config.type)) {
     // Unknown type from a future version
     return true;