fix: stabilize docker sandbox shell startup (#209)

* fix: stabilize docker sandbox shell startup

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: preserve container path in sandbox startup

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: centdix

.webmux.example.yaml

@@ -108,6 +108,8 @@ profiles:
     yolo: true
 
     # Required when `runtime: docker`.
+    # Custom images should expose `claude` or `codex` on the container PATH
+    # via the image itself, e.g. `ENV PATH=/your/tool/bin:$PATH`.
     image: example-sandbox-image
 
     envPassthrough:

README.md

@@ -130,6 +130,8 @@ profiles:
       You are running inside a sandboxed container.
       Backend port: ${PORT}. Frontend port: ${FRONTEND_PORT}.
 
+Custom sandbox images should make `claude` or `codex` available on the container's normal `PATH` (for example with `ENV PATH=/your/tool/bin:$PATH`). webmux does not rely on login-shell dotfiles like `.bashrc` to discover agent binaries inside the container.
+
 integrations:
   github:
     autoRemoveOnMerge: true

backend/src/__tests__/agent-service.test.ts

@@ -59,20 +59,45 @@ describe("agent-service command builders", () => {
     );
     const agent = buildDockerAgentPaneCommand({
       agent: "codex",
-      containerName: "wm-feature-container",
-      worktreePath: "/repos/feature",
       runtimeEnvPath: "/repos/main/.git/worktrees/feature/webmux/runtime.env",
       yolo: true,
       prompt: "ship the fix",
     });
 
-    expect(shell).toContain("docker exec -it -w '/repos/feature' 'wm-feature-container' bash -lc");
+    expect(shell).toContain("docker exec -it -w '/repos/feature' 'wm-feature-container' /bin/sh -c");
     expect(shell).toContain("/bin/zsh");
+    expect(shell).toContain('export PATH="$PATH:/root/.local/bin:/usr/local/bin:/root/.bun/bin:/root/.cargo/bin"');
     expect(agent).toContain("codex --yolo");
     expect(agent).toContain("ship the fix");
+    expect(agent).toContain('export PATH="$PATH:/root/.local/bin:/usr/local/bin:/root/.bun/bin:/root/.cargo/bin"');
+    expect(agent).not.toContain("docker exec");
     expect(agent).not.toContain("agent-stopped");
   });
 
+  it("defaults docker shell commands to /bin/bash instead of the host shell path", () => {
+    const shell = buildDockerShellCommand(
+      "wm-feature-container",
+      "/repos/feature",
+      "/repos/main/.git/worktrees/feature/webmux/runtime.env",
+    );
+
+    expect(shell).toContain("/bin/bash");
+    expect(shell).not.toContain(" /bin/sh -lc ");
+    expect(shell).toContain('export PATH="$PATH:/root/.local/bin:/usr/local/bin:/root/.bun/bin:/root/.cargo/bin"');
+  });
+
+  it("falls back to /bin/sh when the preferred docker shell is unavailable", () => {
+    const shell = buildDockerShellCommand(
+      "wm-feature-container",
+      "/repos/feature",
+      "/repos/main/.git/worktrees/feature/webmux/runtime.env",
+      "/missing/bash",
+    );
+
+    expect(shell).toContain("/missing/bash");
+    expect(shell).toContain("elif [ -x /bin/sh ]; then exec /bin/sh -i;");
+  });
+
   it("uses codex resume --last on resume without replaying the initial prompt", () => {
     const command = buildAgentPaneCommand({
       agent: "codex",

backend/src/__tests__/lifecycle-service.test.ts

@@ -37,6 +37,7 @@ function run(args: string[], cwd: string): string {
 
 class FakeTmuxGateway implements TmuxGateway {
   private readonly windows = new Map<string, TmuxWindowSummary>();
+  readonly createdWindows: Array<{ sessionName: string; windowName: string; cwd: string; command?: string }> = [];
   readonly commands: Array<{ target: string; command: string }> = [];
 
   ensureServer(): void {}
@@ -52,6 +53,7 @@ class FakeTmuxGateway implements TmuxGateway {
   }
 
   createWindow(opts: { sessionName: string; windowName: string; cwd: string; command?: string }): void {
+    this.createdWindows.push({ ...opts });
     this.windows.set(this.key(opts.sessionName, opts.windowName), {
       sessionName: opts.sessionName,
       windowName: opts.windowName,
@@ -972,6 +974,27 @@ describe("LifecycleService", () => {
     expect(state?.session.exists).toBe(true);
   });
 
+  it("starts one-pane docker agent sessions without nesting docker exec inside the container shell", async () => {
+    const repoRoot = await initRepo();
+    const runtime = new ProjectRuntime();
+    const tmux = new FakeTmuxGateway();
+    const docker = new FakeDockerGateway();
+    const lifecycle = makeLifecycleService(repoRoot, tmux, runtime, docker);
+
+    await lifecycle.createWorktree({
+      branch: "feature-sandbox-agent",
+      profile: "sandbox",
+    });
+
+    const windowCommand = tmux.createdWindows[0]?.command;
+    const agentCommand = tmux.commands[0]?.command;
+
+    expect(windowCommand).toContain("docker exec -it");
+    expect(windowCommand).toContain("wm-feature-sandbox-agent-container");
+    expect(agentCommand).toContain("claude");
+    expect(agentCommand).not.toContain("docker exec");
+  });
+
   it("reports backend creation phases in order until the worktree is ready", async () => {
     const repoRoot = await initRepo();
     const runtime = new ProjectRuntime();

backend/src/services/agent-service.ts

@@ -2,6 +2,8 @@ import type { AgentKind } from "../domain/config";
 
 export type AgentLaunchMode = "fresh" | "resume";
 
+const DOCKER_PATH_FALLBACK = "/root/.local/bin:/usr/local/bin:/root/.bun/bin:/root/.cargo/bin";
+
 function quoteShell(value: string): string {
   return `'${value.replaceAll("'", "'\\''")}'`;
 }
@@ -10,6 +12,10 @@ function buildRuntimeBootstrap(runtimeEnvPath: string): string {
   return `set -a; . ${quoteShell(runtimeEnvPath)}; set +a`;
 }
 
+function buildDockerRuntimeBootstrap(runtimeEnvPath: string): string {
+  return `${buildRuntimeBootstrap(runtimeEnvPath)}; export PATH="$PATH:${DOCKER_PATH_FALLBACK}"`;
+}
+
 function buildAgentInvocation(input: {
   agent: AgentKind;
   yolo?: boolean;
@@ -49,16 +55,16 @@ function buildAgentCommand(input: {
   systemPrompt?: string;
   prompt?: string;
   launchMode?: AgentLaunchMode;
-}): string {
-  return `${buildRuntimeBootstrap(input.runtimeEnvPath)}; ${buildAgentInvocation(input)}`;
+}, bootstrap = buildRuntimeBootstrap): string {
+  return `${bootstrap(input.runtimeEnvPath)}; ${buildAgentInvocation(input)}`;
 }
 
 function buildDockerExecCommand(
   containerName: string,
   worktreePath: string,
   command: string,
 ): string {
-  return `docker exec -it -w ${quoteShell(worktreePath)} ${quoteShell(containerName)} bash -lc ${quoteShell(command)}`;
+  return `docker exec -it -w ${quoteShell(worktreePath)} ${quoteShell(containerName)} /bin/sh -c ${quoteShell(command)}`;
 }
 
 export function buildManagedShellCommand(
@@ -83,28 +89,22 @@ export function buildDockerShellCommand(
   containerName: string,
   worktreePath: string,
   runtimeEnvPath: string,
-  shellPath = Bun.env.SHELL || "/bin/bash",
+  shellPath = "/bin/bash",
 ): string {
   return buildDockerExecCommand(
     containerName,
     worktreePath,
-    `${buildRuntimeBootstrap(runtimeEnvPath)}; exec ${quoteShell(shellPath)} -i`,
+    `${buildDockerRuntimeBootstrap(runtimeEnvPath)}; if [ -x ${quoteShell(shellPath)} ]; then exec ${quoteShell(shellPath)} -i; elif [ -x /bin/sh ]; then exec /bin/sh -i; else echo 'webmux: no shell found in container' >&2; exit 127; fi`,
   );
 }
 
 export function buildDockerAgentPaneCommand(input: {
   agent: AgentKind;
-  containerName: string;
-  worktreePath: string;
   runtimeEnvPath: string;
   yolo?: boolean;
   systemPrompt?: string;
   prompt?: string;
   launchMode?: AgentLaunchMode;
 }): string {
-  return buildDockerExecCommand(
-    input.containerName,
-    input.worktreePath,
-    buildAgentCommand(input),
-  );
+  return buildAgentCommand(input, buildDockerRuntimeBootstrap);
 }

backend/src/services/lifecycle-service.ts

@@ -634,8 +634,6 @@ export class LifecycleService {
           ? {
               agent: buildDockerAgentPaneCommand({
                 agent: input.agent,
-                containerName,
-                worktreePath: input.worktreePath,
                 runtimeEnvPath: input.initialized.paths.runtimeEnvPath,
                 yolo: input.profile.yolo === true,
                 systemPrompt,