fix(shell): prepare host-backed controller builds (#351)

* fix(shell): prepare host-backed controller builds

- Default controller runtime to host Docker with socket mount

- Initialize the pinned Skiller submodule before controller revision/build

- Include Skiller inputs in controller revision hashing

* test(shell): cover controller compose preparation

* fix(shell): support containerized remote Docker controller startup

* fix(shell): preserve remote and isolated controller bootstrap

* fix(shell): make isolated controller fallback self-contained

* fix(shell): address controller runtime review comments

---------

Co-authored-by: skulidropek <66840575+skulidropek@users.noreply.github.com>

Author: rikohomeless

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,8 @@
+services:
+  api:
+    privileged: ${DOCKER_GIT_CONTROLLER_PRIVILEGED:-true}
+    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.api.yml

@@ -11,11 +11,11 @@ services:
     environment:
       DOCKER_GIT_API_PORT: ${DOCKER_GIT_API_PORT:-3334}
       DOCKER_GIT_CONTROLLER_REV: ${DOCKER_GIT_CONTROLLER_REV:-unknown}
-      DOCKER_GIT_DOCKER_RUNTIME: ${DOCKER_GIT_DOCKER_RUNTIME:-isolated}
+      DOCKER_GIT_DOCKER_RUNTIME: ${DOCKER_GIT_DOCKER_RUNTIME:-host}
       DOCKER_HOST: ${DOCKER_GIT_CONTROLLER_DOCKER_HOST:-unix:///var/run/docker.sock}
       DOCKER_GIT_DOCKERD_TCP_HOST: ${DOCKER_GIT_DOCKERD_TCP_HOST:-tcp://0.0.0.0:2375}
       DOCKER_GIT_DOCKERD_DEFAULT_CGROUPNS_MODE: ${DOCKER_GIT_DOCKERD_DEFAULT_CGROUPNS_MODE:-host}
-      DOCKER_GIT_PROJECT_DOCKER_HOST: ${DOCKER_GIT_PROJECT_DOCKER_HOST:-tcp://host.docker.internal:2375}
+      DOCKER_GIT_PROJECT_DOCKER_HOST: ${DOCKER_GIT_PROJECT_DOCKER_HOST:-}
       DOCKER_GIT_PROJECT_SSH_BIND_HOST: ${DOCKER_GIT_PROJECT_SSH_BIND_HOST:-0.0.0.0}
       DOCKER_GIT_PROJECTS_ROOT: ${DOCKER_GIT_PROJECTS_ROOT:-/home/dev/.docker-git}
       DOCKER_GIT_PROJECTS_ROOT_VOLUME: ${DOCKER_GIT_PROJECTS_ROOT_VOLUME:-docker-git-projects}
@@ -36,7 +36,8 @@ services:
     volumes:
       - docker_git_projects:${DOCKER_GIT_PROJECTS_ROOT:-/home/dev/.docker-git}
       - docker_git_docker_data:/var/lib/docker
-    privileged: true
+      - /var/run/docker.sock:/var/run/docker.sock
+    privileged: ${DOCKER_GIT_CONTROLLER_PRIVILEGED:-false}
     cgroup: host
     init: true
     restart: unless-stopped

docker-compose.isolated.yml

@@ -0,0 +1,8 @@
+services:
+  api:
+    privileged: ${DOCKER_GIT_CONTROLLER_PRIVILEGED:-true}
+    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.yml

@@ -11,11 +11,11 @@ services:
     environment:
       DOCKER_GIT_API_PORT: ${DOCKER_GIT_API_PORT:-3334}
       DOCKER_GIT_CONTROLLER_REV: ${DOCKER_GIT_CONTROLLER_REV:-unknown}
-      DOCKER_GIT_DOCKER_RUNTIME: ${DOCKER_GIT_DOCKER_RUNTIME:-isolated}
+      DOCKER_GIT_DOCKER_RUNTIME: ${DOCKER_GIT_DOCKER_RUNTIME:-host}
       DOCKER_HOST: ${DOCKER_GIT_CONTROLLER_DOCKER_HOST:-unix:///var/run/docker.sock}
       DOCKER_GIT_DOCKERD_TCP_HOST: ${DOCKER_GIT_DOCKERD_TCP_HOST:-tcp://0.0.0.0:2375}
       DOCKER_GIT_DOCKERD_DEFAULT_CGROUPNS_MODE: ${DOCKER_GIT_DOCKERD_DEFAULT_CGROUPNS_MODE:-host}
-      DOCKER_GIT_PROJECT_DOCKER_HOST: ${DOCKER_GIT_PROJECT_DOCKER_HOST:-tcp://host.docker.internal:2375}
+      DOCKER_GIT_PROJECT_DOCKER_HOST: ${DOCKER_GIT_PROJECT_DOCKER_HOST:-}
       DOCKER_GIT_PROJECT_SSH_BIND_HOST: ${DOCKER_GIT_PROJECT_SSH_BIND_HOST:-0.0.0.0}
       DOCKER_GIT_PROJECTS_ROOT: ${DOCKER_GIT_PROJECTS_ROOT:-/home/dev/.docker-git}
       DOCKER_GIT_PROJECTS_ROOT_VOLUME: ${DOCKER_GIT_PROJECTS_ROOT_VOLUME:-docker-git-projects}
@@ -36,7 +36,8 @@ services:
     volumes:
       - docker_git_projects:${DOCKER_GIT_PROJECTS_ROOT:-/home/dev/.docker-git}
       - docker_git_docker_data:/var/lib/docker
-    privileged: true
+      - /var/run/docker.sock:/var/run/docker.sock
+    privileged: ${DOCKER_GIT_CONTROLLER_PRIVILEGED:-false}
     cgroup: host
     init: true
     restart: unless-stopped

packages/api/Dockerfile

@@ -150,7 +150,7 @@ LABEL io.prover-coder-ai.docker-git.controller-build-skiller=$DOCKER_GIT_CONTROL
 ENV DOCKER_GIT_CONTROLLER_REV=$DOCKER_GIT_CONTROLLER_REV
 ENV DOCKER_GIT_CONTROLLER_BUILD_SKILLER=$DOCKER_GIT_CONTROLLER_BUILD_SKILLER
 ENV DOCKER_GIT_API_PORT=3334
-ENV DOCKER_GIT_DOCKER_RUNTIME=isolated
+ENV DOCKER_GIT_DOCKER_RUNTIME=host
 ENV DOCKER_HOST=unix:///var/run/docker.sock
 EXPOSE 3334
 

packages/api/README.md

@@ -5,17 +5,27 @@ HTTP API for docker-git orchestration (projects, agents, logs/events, federation
 This is now the intended controller plane:
 - the API runs inside `docker-git-api`
 - `.docker-git` state lives in the Docker volume `docker-git-projects`
-- the API starts an isolated Docker daemon inside the controller by default
-- child project containers no longer depend on host bind mounts for bootstrap auth/env
-- the host `/var/run/docker.sock` is not mounted into the controller or project containers
+- the API uses the host Docker daemon by default via `/var/run/docker.sock`
+- child project containers use host-backed Docker unless an explicit
+  `DOCKER_GIT_PROJECT_DOCKER_HOST` is provided
 
 ## Runtime contract: host-Docker-backed
 
-`docker-git` is host-Docker-backed, not isolated. The controller container
-created from this package binds the host socket
+`docker-git` is host-Docker-backed by default. The primary controller
+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. There is no Docker-in-Docker
-runtime; the daemon is always the host's daemon.
+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. 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
+create containers and mount host paths. This is an intended trade-off for the
+host-backed architecture; run the controller only in trusted environments and
+review the threat model before exposing the API.
 
 The host CLI (`packages/app`) also talks to that same daemon directly when
 it bootstraps the controller. Three failure modes look identical at first
@@ -52,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`
@@ -61,12 +79,13 @@ Optional env:
 
 - `DOCKER_GIT_API_BIND_HOST` (default: `127.0.0.1`)
 - `DOCKER_GIT_API_PORT` (default: `3334`)
-- `DOCKER_GIT_DOCKER_RUNTIME` (default: `isolated`; starts a managed Docker daemon in `docker-git-api`)
+- `DOCKER_GIT_DOCKER_RUNTIME` (default: `host`; set to `isolated` as an optional fallback to use an embedded controller daemon)
 - `DOCKER_GIT_CONTROLLER_DOCKER_HOST` (default: `unix:///var/run/docker.sock`; socket path inside the controller)
+- `DOCKER_GIT_CONTROLLER_PRIVILEGED` (default: `false` in host mode; isolated overlays default it to `true` for the embedded Docker daemon)
 - `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: `tcp://host.docker.internal:2375`; lets project containers use the isolated daemon)
-- `DOCKER_GIT_PROJECT_SSH_BIND_HOST` (default: `0.0.0.0` in controller mode; project SSH binds inside the isolated controller runtime)
+- `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`)
 - `DOCKER_GIT_FEDERATION_PUBLIC_ORIGIN` (optional public ActivityPub origin)

packages/api/scripts/start-controller.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-runtime="${DOCKER_GIT_DOCKER_RUNTIME:-isolated}"
+runtime="${DOCKER_GIT_DOCKER_RUNTIME:-host}"
 docker_host="${DOCKER_HOST:-unix:///var/run/docker.sock}"
 dockerd_pid=""
 
@@ -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,67 @@
+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): Effect.Effect<string, ControllerBootstrapError> => {
+  if (composeFileName.endsWith(".yaml")) {
+    return Effect.succeed(`${composeFileName.slice(0, -".yaml".length)}.isolated.yaml`)
+  }
+  if (composeFileName.endsWith(".yml")) {
+    return Effect.succeed(`${composeFileName.slice(0, -".yml".length)}.isolated.yml`)
+  }
+  return Effect.fail(
+    controllerBootstrapError(
+      `${controllerDockerRuntimeEnvKey}=isolated requires a .yml or .yaml compose file. Received: ${composeFileName}`
+    )
+  )
+}
+
+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 overlayFileName = yield* _(isolatedOverlayFileName(path.basename(composePath)))
+      const runtimeOverlayPath = path.join(
+        path.dirname(composePath),
+        overlayFileName
+      )
+      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.`
+            )
+          )
+        )
+    })