fix(shell): preserve remote and isolated controller bootstrap

Author: skulidropek

ctl

@@ -13,6 +13,7 @@ set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 COMPOSE_FILE="$ROOT/docker-compose.yml"
+COMPOSE_ISOLATED_FILE="$ROOT/docker-compose.isolated.yml"
 CONTAINER_NAME="docker-git-api"
 API_PORT="${DOCKER_GIT_API_PORT:-3334}"
 API_HOST="${DOCKER_GIT_API_BIND_HOST:-127.0.0.1}"
@@ -54,7 +55,11 @@ USAGE
 }
 
 compose() {
-  "${DOCKER_CMD[@]}" compose -f "$COMPOSE_FILE" "$@"
+  local compose_args=(-f "$COMPOSE_FILE")
+  if [[ "${DOCKER_GIT_DOCKER_RUNTIME:-host}" == "isolated" ]]; then
+    compose_args+=(-f "$COMPOSE_ISOLATED_FILE")
+  fi
+  "${DOCKER_CMD[@]}" compose "${compose_args[@]}" "$@"
 }
 
 compute_controller_revision() {

docker-compose.api.isolated.yml

@@ -0,0 +1,7 @@
+services:
+  api:
+    environment:
+      DOCKER_GIT_PROJECT_DOCKER_HOST: ${DOCKER_GIT_PROJECT_DOCKER_HOST:-tcp://host.docker.internal:2375}
+    volumes: !override
+      - docker_git_projects:${DOCKER_GIT_PROJECTS_ROOT:-/home/dev/.docker-git}
+      - docker_git_docker_data:/var/lib/docker

docker-compose.isolated.yml

@@ -0,0 +1,7 @@
+services:
+  api:
+    environment:
+      DOCKER_GIT_PROJECT_DOCKER_HOST: ${DOCKER_GIT_PROJECT_DOCKER_HOST:-tcp://host.docker.internal:2375}
+    volumes: !override
+      - docker_git_projects:${DOCKER_GIT_PROJECTS_ROOT:-/home/dev/.docker-git}
+      - docker_git_docker_data:/var/lib/docker

packages/api/README.md

@@ -16,7 +16,10 @@ container created from this package binds the host socket
 (`/var/run/docker.sock:/var/run/docker.sock`, see `docker-compose.yml`) and
 uses it to spawn per-project containers. `DOCKER_GIT_DOCKER_RUNTIME=isolated`
 is an opt-in fallback for environments that explicitly require an embedded
-controller daemon.
+controller daemon. In isolated mode, start the controller through the host CLI
+or include `docker-compose.isolated.yml`; that overlay removes the host socket
+bind and defaults project containers to the embedded daemon endpoint
+`tcp://host.docker.internal:2375`.
 
 Security note: binding `/var/run/docker.sock` gives the controller container
 root-equivalent control over the host Docker daemon, including the ability to
@@ -59,6 +62,14 @@ docker compose up -d --build
 ./ctl health
 ```
 
+Isolated fallback:
+
+```bash
+DOCKER_GIT_DOCKER_RUNTIME=isolated \
+  docker compose -f docker-compose.yml -f docker-compose.isolated.yml up -d --build
+./ctl health
+```
+
 Default port mapping:
 
 - host: `127.0.0.1:3334`
@@ -73,7 +84,7 @@ Optional env:
 - `DOCKER_GIT_CONTROLLER_PRIVILEGED` (default: `false`; set to `true` only when using `DOCKER_GIT_DOCKER_RUNTIME=isolated`)
 - `DOCKER_GIT_DOCKERD_TCP_HOST` (default: `tcp://0.0.0.0:2375`; reachable only inside Docker networks unless explicitly published)
 - `DOCKER_GIT_DOCKERD_DEFAULT_CGROUPNS_MODE` (default: `host`; keeps nested project containers compatible with cgroup v2 DinD)
-- `DOCKER_GIT_PROJECT_DOCKER_HOST` (default: empty; unset uses host socket in project containers when mounted)
+- `DOCKER_GIT_PROJECT_DOCKER_HOST` (default: empty in host mode; isolated mode defaults to `tcp://host.docker.internal:2375`)
 - `DOCKER_GIT_PROJECT_SSH_BIND_HOST` (default: `0.0.0.0`)
 - `DOCKER_GIT_PROJECTS_ROOT` (container path, default: `/home/dev/.docker-git`)
 - `DOCKER_GIT_PROJECTS_ROOT_VOLUME` (Docker volume name for controller state, default: `docker-git-projects`)

packages/api/scripts/start-controller.sh

@@ -15,6 +15,10 @@ cleanup() {
 trap cleanup EXIT INT TERM
 
 if [[ "$runtime" == "isolated" ]]; then
+  if [[ -z "${DOCKER_GIT_PROJECT_DOCKER_HOST:-}" ]]; then
+    export DOCKER_GIT_PROJECT_DOCKER_HOST="tcp://host.docker.internal:2375"
+  fi
+
   if [[ "$docker_host" != unix://* ]]; then
     echo "DOCKER_GIT_DOCKER_RUNTIME=isolated requires a unix:// DOCKER_HOST for the managed controller daemon." >&2
     exit 1

packages/app/scripts/print-controller-revision.ts

@@ -3,7 +3,13 @@
 import { NodeContext, NodeRuntime } from "@effect/platform-node"
 import { Effect, pipe } from "effect"
 
+import {
+  controllerRevisionForMode,
+  parseControllerBuildSkillerMode,
+  parseControllerGpuMode
+} from "../src/docker-git/controller-compose.ts"
 import { computeLocalControllerRevision } from "../src/docker-git/controller-revision.ts"
+import { parseControllerDockerRuntime } from "../src/docker-git/controller-runtime.ts"
 
 // CHANGE: expose controller revision computation as a reusable Bun script for shell tooling
 // WHY: ctl must inject the same deterministic controller revision into docker compose as the host CLI bootstrap path
@@ -25,9 +31,32 @@ const readComposePath = (): Effect.Effect<string, Error> => {
     : Effect.fail(new Error(usage))
 }
 
+const readControllerRevisionModes = (): Effect.Effect<{
+  readonly buildSkillerMode: "0" | "1"
+  readonly dockerRuntime: "host" | "isolated"
+  readonly gpuMode: "none" | "all"
+}, Error> => {
+  const gpuMode = parseControllerGpuMode(process.env["DOCKER_GIT_CONTROLLER_GPU"])
+  const buildSkillerMode = parseControllerBuildSkillerMode(process.env["DOCKER_GIT_CONTROLLER_BUILD_SKILLER"])
+  const dockerRuntime = parseControllerDockerRuntime(process.env["DOCKER_GIT_DOCKER_RUNTIME"])
+  if (gpuMode === null || buildSkillerMode === null || dockerRuntime === null) {
+    return Effect.fail(new Error("Invalid controller revision mode environment."))
+  }
+  return Effect.succeed({ buildSkillerMode, dockerRuntime, gpuMode })
+}
+
 const main = pipe(
-  readComposePath(),
-  Effect.flatMap((composePath) => computeLocalControllerRevision(composePath)),
+  Effect.all({
+    composePath: readComposePath(),
+    modes: readControllerRevisionModes()
+  }),
+  Effect.flatMap(({ composePath, modes }) =>
+    computeLocalControllerRevision(composePath).pipe(
+      Effect.map((revision) =>
+        controllerRevisionForMode(revision, modes.gpuMode, modes.buildSkillerMode, modes.dockerRuntime)
+      )
+    )
+  ),
   Effect.tap((revision) => Effect.sync(() => process.stdout.write(`${revision}\n`))),
   Effect.asVoid,
   Effect.provide(NodeContext.layer)

packages/app/src/docker-git/controller-compose-runtime.ts

@@ -0,0 +1,57 @@
+import type { PlatformError } from "@effect/platform/Error"
+import * as FileSystem from "@effect/platform/FileSystem"
+import * as Path from "@effect/platform/Path"
+import { Effect } from "effect"
+
+import {
+  type ControllerDockerRuntime,
+  controllerDockerRuntimeEnvKey,
+  parseControllerDockerRuntime
+} from "./controller-runtime.js"
+import { type ControllerBootstrapError, controllerBootstrapError } from "./host-errors.js"
+
+const mapComposePathError = (error: PlatformError): ControllerBootstrapError =>
+  controllerBootstrapError(`Failed to resolve docker-compose.yml path.\nDetails: ${String(error)}`)
+
+export const loadControllerDockerRuntime = (): Effect.Effect<ControllerDockerRuntime, ControllerBootstrapError> => {
+  const raw = process.env[controllerDockerRuntimeEnvKey]
+  const parsed = parseControllerDockerRuntime(raw)
+  if (parsed !== null) {
+    return Effect.succeed(parsed)
+  }
+  return Effect.fail(
+    controllerBootstrapError(
+      `${controllerDockerRuntimeEnvKey} must be unset or one of: host, isolated. Received: ${raw ?? ""}`
+    )
+  )
+}
+
+const isolatedOverlayFileName = (composeFileName: string): string =>
+  composeFileName.endsWith(".yaml")
+    ? `${composeFileName.slice(0, -".yaml".length)}.isolated.yaml`
+    : `${composeFileName.slice(0, -".yml".length)}.isolated.yml`
+
+export const resolveControllerRuntimeOverlayPath = (
+  composePath: string,
+  dockerRuntime: ControllerDockerRuntime
+): Effect.Effect<string | null, ControllerBootstrapError, FileSystem.FileSystem | Path.Path> =>
+  dockerRuntime === "host"
+    ? Effect.succeed(null)
+    : Effect.gen(function*(_) {
+      const fs = yield* _(FileSystem.FileSystem)
+      const path = yield* _(Path.Path)
+      const runtimeOverlayPath = path.join(
+        path.dirname(composePath),
+        isolatedOverlayFileName(path.basename(composePath))
+      )
+      const exists = yield* _(fs.exists(runtimeOverlayPath).pipe(Effect.mapError(mapComposePathError)))
+      return exists
+        ? runtimeOverlayPath
+        : yield* _(
+          Effect.fail(
+            controllerBootstrapError(
+              `${controllerDockerRuntimeEnvKey}=isolated requires ${runtimeOverlayPath}, but it was not found.`
+            )
+          )
+        )
+    })

packages/app/src/docker-git/controller-compose.ts

@@ -4,7 +4,9 @@ import * as FileSystem from "@effect/platform/FileSystem"
 import * as Path from "@effect/platform/Path"
 import { Duration, Effect } from "effect"
 
+import { loadControllerDockerRuntime, resolveControllerRuntimeOverlayPath } from "./controller-compose-runtime.js"
 import { computeLocalControllerRevision, controllerRevisionEnvKey } from "./controller-revision.js"
+import type { ControllerDockerRuntime } from "./controller-runtime.js"
 import { runCommandWithCapturedOutput } from "./frontend-lib/shell/command-runner.js"
 import { findExistingUpwards } from "./frontend-lib/usecases/path-helpers.js"
 import type { ControllerBootstrapError } from "./host-errors.js"
@@ -18,6 +20,7 @@ export type ControllerBuildSkillerMode = "0" | "1"
 export type ControllerComposeFiles = {
   readonly composePath: string
   readonly gpuOverlayPath: string | null
+  readonly runtimeOverlayPath: string | null
 }
 
 const skillerSubmodulePath = "third_party/skiller-desktop-skills-manager"
@@ -47,8 +50,9 @@ export const parseControllerBuildSkillerMode = (raw?: string): ControllerBuildSk
 export const controllerRevisionForMode = (
   sourceRevision: string,
   gpuMode: ControllerGpuMode,
-  buildSkillerMode: ControllerBuildSkillerMode = "1"
-): string => `${sourceRevision}-${gpuMode}-skiller${buildSkillerMode}`
+  buildSkillerMode: ControllerBuildSkillerMode = "1",
+  dockerRuntime: ControllerDockerRuntime = "host"
+): string => `${sourceRevision}-${dockerRuntime}-${gpuMode}-skiller${buildSkillerMode}`
 
 const loadControllerGpuMode = (): Effect.Effect<ControllerGpuMode, ControllerBootstrapError> => {
   const raw = process.env[controllerGpuModeEnvKey]
@@ -187,11 +191,21 @@ export const ensureSkillerSubmoduleInitialized = (
 
 export const composeFilesForMode = (
   composePath: string,
-  gpuOverlayPath: string | null
-): ReadonlyArray<string> =>
-  gpuOverlayPath === null
-    ? ["-f", composePath]
-    : ["-f", composePath, "-f", gpuOverlayPath]
+  gpuOverlayPath: string | null,
+  runtimeOverlayPath: string | null = null
+): ReadonlyArray<string> => [
+  "-f",
+  composePath,
+  ...(runtimeOverlayPath === null ? [] : ["-f", runtimeOverlayPath]),
+  ...(gpuOverlayPath === null ? [] : ["-f", gpuOverlayPath])
+]
+
+export const composeFilesToArgs = (composeFiles: ControllerComposeFiles): ReadonlyArray<string> =>
+  composeFilesForMode(
+    composeFiles.composePath,
+    composeFiles.gpuOverlayPath,
+    composeFiles.runtimeOverlayPath
+  )
 
 const requireGpuOverlayPath = (
   composePath: string
@@ -215,13 +229,14 @@ const composeFilesForGpuMode = (
   gpuMode: ControllerGpuMode
 ): Effect.Effect<ControllerComposeFiles, ControllerBootstrapError, FileSystem.FileSystem | Path.Path> =>
   gpuMode === "none"
-    ? Effect.succeed({ composePath, gpuOverlayPath: null })
+    ? Effect.succeed({ composePath, gpuOverlayPath: null, runtimeOverlayPath: null })
     : requireGpuOverlayPath(composePath).pipe(
-      Effect.map((gpuOverlayPath) => ({ composePath, gpuOverlayPath }))
+      Effect.map((gpuOverlayPath) => ({ composePath, gpuOverlayPath, runtimeOverlayPath: null }))
     )
 
 type ComposePathAndGpuMode = {
   readonly composePath: string
+  readonly dockerRuntime: ControllerDockerRuntime
   readonly gpuMode: ControllerGpuMode
   readonly buildSkillerMode: ControllerBuildSkillerMode
 }
@@ -236,12 +251,12 @@ const withComposePathAndGpuMode = <A, R>(
   composeFilePath().pipe(
     Effect.mapError(mapComposePathError),
     Effect.flatMap((composePath) =>
-      loadControllerGpuMode().pipe(
-        Effect.flatMap((gpuMode) =>
-          loadControllerBuildSkillerMode().pipe(
-            Effect.flatMap((buildSkillerMode) => effect({ buildSkillerMode, composePath, gpuMode }))
-          )
-        )
+      Effect.all({
+        buildSkillerMode: loadControllerBuildSkillerMode(),
+        dockerRuntime: loadControllerDockerRuntime(),
+        gpuMode: loadControllerGpuMode()
+      }).pipe(
+        Effect.flatMap((modes) => effect({ composePath, ...modes }))
       )
     )
   )
@@ -250,16 +265,24 @@ export const resolveControllerComposeFiles = (): Effect.Effect<
   ControllerComposeFiles,
   ControllerBootstrapError,
   FileSystem.FileSystem | Path.Path
-> => withComposePathAndGpuMode(({ composePath, gpuMode }) => composeFilesForGpuMode(composePath, gpuMode))
+> =>
+  withComposePathAndGpuMode(({ composePath, dockerRuntime, gpuMode }) =>
+    Effect.gen(function*(_) {
+      const composeFiles = yield* _(composeFilesForGpuMode(composePath, gpuMode))
+      const runtimeOverlayPath = yield* _(resolveControllerRuntimeOverlayPath(composePath, dockerRuntime))
+      return { ...composeFiles, runtimeOverlayPath }
+    })
+  )
 
 const computeControllerRevision = (
   composePath: string,
   gpuMode: ControllerGpuMode,
-  buildSkillerMode: ControllerBuildSkillerMode
+  buildSkillerMode: ControllerBuildSkillerMode,
+  dockerRuntime: ControllerDockerRuntime
 ): Effect.Effect<string, ControllerBootstrapError, FileSystem.FileSystem | Path.Path> =>
   computeLocalControllerRevision(composePath).pipe(
     Effect.mapError(mapControllerRevisionError),
-    Effect.map((revision) => controllerRevisionForMode(revision, gpuMode, buildSkillerMode))
+    Effect.map((revision) => controllerRevisionForMode(revision, gpuMode, buildSkillerMode, dockerRuntime))
   )
 
 const persistControllerRevision = (revision: string): Effect.Effect<void> =>
@@ -272,13 +295,13 @@ export const prepareControllerRevision = (): Effect.Effect<
   ControllerBootstrapError,
   FileSystem.FileSystem | Path.Path | CommandExecutor.CommandExecutor
 > =>
-  withComposePathAndGpuMode(({ buildSkillerMode, composePath, gpuMode }) =>
+  withComposePathAndGpuMode(({ buildSkillerMode, composePath, dockerRuntime, gpuMode }) =>
     Effect.gen(function*(_) {
       const path = yield* _(Path.Path)
       if (buildSkillerMode === "1") {
         yield* _(ensureSkillerSubmoduleInitialized(path.dirname(composePath)))
       }
-      return yield* _(computeControllerRevision(composePath, gpuMode, buildSkillerMode))
+      return yield* _(computeControllerRevision(composePath, gpuMode, buildSkillerMode, dockerRuntime))
     })
   ).pipe(
     Effect.tap((revision) => persistControllerRevision(revision))

packages/app/src/docker-git/controller-docker.ts

@@ -4,7 +4,7 @@ import type * as FileSystem from "@effect/platform/FileSystem"
 import type * as Path from "@effect/platform/Path"
 import { Effect } from "effect"
 
-import { composeFilesForMode, prepareControllerRevision, resolveControllerComposeFiles } from "./controller-compose.js"
+import { composeFilesToArgs, prepareControllerRevision, resolveControllerComposeFiles } from "./controller-compose.js"
 import { readCurrentContainerName } from "./controller-hostname.js"
 import {
   runCommandCaptureWithFailureOutput,
@@ -30,6 +30,7 @@ export {
   parseControllerBuildSkillerMode,
   parseControllerGpuMode
 } from "./controller-compose.js"
+export { parseControllerDockerRuntime } from "./controller-runtime.js"
 
 export type ControllerRuntime =
   | CommandExecutor.CommandExecutor
@@ -385,7 +386,7 @@ export const runCompose = (
     const composeFiles = yield* _(resolveControllerComposeFiles())
     const invocation = buildDockerInvocation(dockerCommand, [
       "compose",
-      ...composeFilesForMode(composeFiles.composePath, composeFiles.gpuOverlayPath),
+      ...composeFilesToArgs(composeFiles),
       ...args
     ])
     const exitCode = yield* _(

packages/app/src/docker-git/controller-image-revision.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect"
 
-import { composeFilesForMode, resolveControllerComposeFiles } from "./controller-compose.js"
+import { composeFilesToArgs, resolveControllerComposeFiles } from "./controller-compose.js"
 import { type ControllerRuntime, runDockerCapture, runDockerCaptureWithFailureOutput } from "./controller-docker.js"
 import { parseControllerRevisionLabelOutput } from "./controller-revision.js"
 import type { ControllerBootstrapError } from "./host-errors.js"
@@ -131,7 +131,7 @@ const inspectControllerComposeImageName = (): Effect.Effect<
       runDockerCapture(
         [
           "compose",
-          ...composeFilesForMode(composeFiles.composePath, composeFiles.gpuOverlayPath),
+          ...composeFilesToArgs(composeFiles),
           "config",
           "--images"
         ],