fix(shell): support containerized remote Docker controller startup

Author: skulidropek

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

@@ -5,6 +5,7 @@ import type * as Path from "@effect/platform/Path"
 import { Effect } from "effect"
 
 import { composeFilesForMode, prepareControllerRevision, resolveControllerComposeFiles } from "./controller-compose.js"
+import { readCurrentContainerName } from "./controller-hostname.js"
 import {
   runCommandCaptureWithFailureOutput,
   runCommandExitCode,
@@ -461,7 +462,9 @@ export const inspectControllerPublishedPorts = (): Effect.Effect<string, never,
   )
 
 export const resolveCurrentContainerNetworks = (): Effect.Effect<DockerNetworkIps, never, ControllerRuntime> =>
-  inspectContainerNetworks(process.env["HOSTNAME"]?.trim() ?? "")
+  readCurrentContainerName().pipe(
+    Effect.flatMap((containerName) => inspectContainerNetworks(containerName))
+  )
 
 const connectControllerToNetworkBestEffort = (
   networkName: string

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

@@ -0,0 +1,29 @@
+import * as FileSystem from "@effect/platform/FileSystem"
+import { Effect } from "effect"
+
+const readSystemHostname = (): Effect.Effect<string, never, FileSystem.FileSystem> =>
+  FileSystem.FileSystem.pipe(
+    Effect.flatMap((fs) => fs.readFileString("/etc/hostname")),
+    Effect.map((value) => value.trim()),
+    Effect.orElseSucceed(() => "")
+  )
+
+// CHANGE: fall back to the system hostname when HOSTNAME is not exported
+// WHY: containerized runtimes can have an inspectable Docker hostname without a HOSTNAME env variable
+// QUOTE(ТЗ): "Полностью запусти локально и проверь что всё работает"
+// REF: user-request-2026-05-27-pr-351-browser-e2e
+// SOURCE: n/a
+// FORMAT THEOREM: trim(envHostname) != "" -> envHostname; otherwise trim(systemHostname)
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: Docker inspection never receives an empty name when the system hostname is non-empty
+// COMPLEXITY: O(|envHostname| + |systemHostname|)
+export const resolveCurrentContainerName = (
+  envHostname: string | undefined,
+  systemHostname: string
+): string => envHostname?.trim() || systemHostname.trim()
+
+export const readCurrentContainerName = (): Effect.Effect<string, never, FileSystem.FileSystem> =>
+  readSystemHostname().pipe(
+    Effect.map((systemHostname) => resolveCurrentContainerName(process.env["HOSTNAME"], systemHostname))
+  )

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

@@ -102,6 +102,25 @@ export const isRemoteDockerHost = (dockerHost = process.env["DOCKER_HOST"]): boo
   return trimmed.startsWith("tcp://") || trimmed.startsWith("ssh://")
 }
 
+// CHANGE: allow remote Docker bootstrap when the current runtime is inspectable on that daemon
+// WHY: containerized hosts often reach Docker through tcp://host.docker.internal while sharing daemon networks
+// QUOTE(ТЗ): "Надо проверить запускается ли сервер теперь"
+// REF: user-request-2026-05-27-pr-351-browser-e2e
+// SOURCE: n/a
+// FORMAT THEOREM: remote(dockerHost) ∧ noExplicitApi ∧ empty(networks) -> require_explicit_api
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: remote Docker is allowed only when network-derived controller candidates can be constructed
+// COMPLEXITY: O(k) where k = |currentContainerNetworks|
+export const shouldRequireExplicitApiUrlForRemoteDocker = (
+  dockerHost: string | undefined,
+  explicitApiBaseUrl: string | undefined,
+  currentContainerNetworks: DockerNetworkIps
+): boolean =>
+  isRemoteDockerHost(dockerHost) &&
+  explicitApiBaseUrl === undefined &&
+  Object.keys(currentContainerNetworks).length === 0
+
 export const buildApiBaseUrlCandidates = ({
   cachedApiBaseUrl,
   controllerNetworks,

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

@@ -19,10 +19,10 @@ import {
   buildApiBaseUrlCandidates,
   type DockerNetworkIps,
   formatNetworkIps,
-  isRemoteDockerHost,
   resolveApiPort,
   resolveConfiguredApiBaseUrl,
   resolveExplicitApiBaseUrl,
+  shouldRequireExplicitApiUrlForRemoteDocker,
   trimTrailingSlashes
 } from "./controller-reachability.js"
 import {
@@ -98,9 +98,17 @@ const waitForReachableApiBaseUrl = (
     })
   )
 
-const failIfRemoteDockerWithoutApiUrl = (): Effect.Effect<void, ControllerBootstrapError> => {
+const failIfRemoteDockerWithoutApiUrl = (
+  currentContainerNetworks: DockerNetworkIps
+): Effect.Effect<void, ControllerBootstrapError> => {
   const explicitApiBaseUrl = resolveExplicitApiBaseUrl()
-  if (!isRemoteDockerHost() || explicitApiBaseUrl !== undefined) {
+  if (
+    !shouldRequireExplicitApiUrlForRemoteDocker(
+      process.env["DOCKER_HOST"],
+      explicitApiBaseUrl,
+      currentContainerNetworks
+    )
+  ) {
     return Effect.void
   }
 
@@ -266,7 +274,6 @@ const startAndRememberController = (
 // COMPLEXITY: O(1) compose + O(k) health checks
 export const ensureControllerReady = (): Effect.Effect<void, ControllerBootstrapError, ControllerRuntime> =>
   Effect.gen(function*(_) {
-    yield* _(failIfRemoteDockerWithoutApiUrl())
     const explicitApiBaseUrl = resolveExplicitApiBaseUrl()
     const localControllerRevision = yield* _(prepareLocalControllerRevision())
     const forceRecreateForResourceLimits = shouldForceRecreateForControllerResourceLimits()
@@ -300,6 +307,7 @@ export const ensureControllerReady = (): Effect.Effect<void, ControllerBootstrap
     }
 
     const bootstrapContext = yield* _(loadControllerBootstrapContext())
+    yield* _(failIfRemoteDockerWithoutApiUrl(bootstrapContext.currentContainerNetworks))
     const reusedExistingController = yield* _(reuseReachableControllerIfPossible(bootstrapContext))
     if (reusedExistingController) {
       return
@@ -309,14 +317,14 @@ export const ensureControllerReady = (): Effect.Effect<void, ControllerBootstrap
 
 export const restartController = (): Effect.Effect<void, ControllerBootstrapError, ControllerRuntime> =>
   Effect.gen(function*(_) {
-    yield* _(failIfRemoteDockerWithoutApiUrl())
     const explicitApiBaseUrl = resolveExplicitApiBaseUrl()
     if (explicitApiBaseUrl !== undefined) {
       yield* _(ensureControllerReady())
       return
     }
 
     const bootstrapContext = yield* _(loadControllerBootstrapContext())
+    yield* _(failIfRemoteDockerWithoutApiUrl(bootstrapContext.currentContainerNetworks))
     const forceRecreateController = true
     const buildController = shouldBuildControllerImage({
       currentControllerRevision: bootstrapContext.currentControllerRevision,

packages/app/tests/docker-git/controller.test.ts

@@ -11,6 +11,8 @@ import {
   parseControllerBuildSkillerMode,
   parseControllerGpuMode
 } from "../../src/docker-git/controller-docker.js"
+import { resolveCurrentContainerName } from "../../src/docker-git/controller-hostname.js"
+import { shouldRequireExplicitApiUrlForRemoteDocker } from "../../src/docker-git/controller-reachability.js"
 import {
   parseControllerRevisionEnvOutput,
   parseControllerRevisionLabelOutput,
@@ -121,6 +123,37 @@ describe("controller reachability", () => {
       expect(isRemoteDockerHost("ssh://docker@example.test")).toBe(true)
     }))
 
+  it.effect("requires an explicit API URL only for non-inspectable remote Docker hosts", () =>
+    Effect.sync(() => {
+      expect(
+        shouldRequireExplicitApiUrlForRemoteDocker("tcp://docker.example.test:2376", undefined, {})
+      ).toBe(true)
+      expect(
+        shouldRequireExplicitApiUrlForRemoteDocker(
+          "tcp://docker.example.test:2376",
+          makeHttpUrl("api.example.test", "3334"),
+          {}
+        )
+      ).toBe(false)
+      expect(
+        shouldRequireExplicitApiUrlForRemoteDocker(
+          "tcp://host.docker.internal:2375",
+          undefined,
+          { bridge: joinIp("172", "17", "0", "2") }
+        )
+      ).toBe(false)
+      expect(
+        shouldRequireExplicitApiUrlForRemoteDocker("unix:///var/run/docker.sock", undefined, {})
+      ).toBe(false)
+    }))
+
+  it.effect("resolves the current container name from HOSTNAME or OS hostname", () =>
+    Effect.sync(() => {
+      expect(resolveCurrentContainerName(" env-container ", "os-container")).toBe("env-container")
+      expect(resolveCurrentContainerName("", " os-container ")).toBe("os-container")
+      expect(resolveCurrentContainerName(undefined, " os-container ")).toBe("os-container")
+    }))
+
   it.effect("parses controller revision from container env output", () =>
     Effect.sync(() => {
       const parsed = parseControllerRevisionEnvOutput(

scripts/e2e/browser-command.sh

@@ -17,6 +17,7 @@ STATE_PATH="$ROOT/.orch/state/browser-frontend.json"
 FAILURE_DUMPED=0
 BROWSER_PID=""
 BROWSER_STARTUP_ATTEMPTS="${DOCKER_GIT_E2E_BROWSER_STARTUP_ATTEMPTS:-240}"
+RESOLVED_API_BASE_URL=""
 
 export DOCKER_GIT_PROJECTS_ROOT="$ROOT"
 export DOCKER_GIT_PROJECTS_ROOT_VOLUME="docker-git-e2e-browser-$RUN_ID-projects"
@@ -129,6 +130,55 @@ wait_for_http_contains() {
   fail "timed out waiting for endpoint: $url"
 }
 
+read_logged_api_base_url() {
+  if [[ ! -f "$BROWSER_LOG" ]]; then
+    return 1
+  fi
+
+  local line=""
+  local url=""
+  line="$(grep -F " for API http" "$BROWSER_LOG" | tail -n 1 || true)"
+  if [[ -z "$line" ]]; then
+    return 1
+  fi
+
+  url="${line##* for API }"
+  url="${url%% *}"
+  url="${url%.}"
+  if [[ -z "$url" ]]; then
+    return 1
+  fi
+
+  printf '%s\n' "$url"
+}
+
+wait_for_controller_health() {
+  local attempts="${1:-90}"
+  local local_url="http://127.0.0.1:${DOCKER_GIT_API_PORT}"
+  local logged_url=""
+  local body=""
+
+  for _ in $(seq 1 "$attempts"); do
+    logged_url="$(read_logged_api_base_url || true)"
+    for candidate in "$local_url" "$logged_url"; do
+      if [[ -z "$candidate" ]]; then
+        continue
+      fi
+      if body="$(curl -fsS --connect-timeout 2 --max-time 5 "${candidate}/health" 2>/dev/null)" \
+        && grep -Fq -- '"ok":true' <<<"$body"; then
+        RESOLVED_API_BASE_URL="$candidate"
+        return 0
+      fi
+    done
+    if ! browser_alive; then
+      fail "browser command exited before controller became ready: ${logged_url:-$local_url}"
+    fi
+    sleep 2
+  done
+
+  fail "timed out waiting for controller endpoint: ${logged_url:-$local_url}"
+}
+
 trap 'on_error $LINENO' ERR
 trap cleanup EXIT
 
@@ -148,7 +198,7 @@ fi
 BROWSER_PID="$!"
 
 wait_for_log_line "Ensuring docker-git API controller is current."
-wait_for_http_contains "http://127.0.0.1:${DOCKER_GIT_API_PORT}/health" '"ok":true' "$BROWSER_STARTUP_ATTEMPTS"
+wait_for_controller_health "$BROWSER_STARTUP_ATTEMPTS"
 wait_for_http_contains "http://127.0.0.1:${DOCKER_GIT_WEB_PORT}/" "<title>docker-git browser</title>" "$BROWSER_STARTUP_ATTEMPTS"
 wait_for_http_contains "http://127.0.0.1:${DOCKER_GIT_WEB_PORT}/api/health" '"ok":true' "$BROWSER_STARTUP_ATTEMPTS"
 wait_for_log_line "docker-git web runtime listening on http://"
@@ -160,7 +210,7 @@ docker ps --format '{{.Names}}' | grep -qx "$DOCKER_GIT_API_CONTAINER_NAME" \
 
 grep -Fq -- "\"port\": \"$DOCKER_GIT_WEB_PORT\"" "$STATE_PATH" \
   || fail "expected runtime state to record web port $DOCKER_GIT_WEB_PORT"
-grep -Fq -- "\"apiBaseUrl\": \"http://127.0.0.1:$DOCKER_GIT_API_PORT\"" "$STATE_PATH" \
-  || fail "expected runtime state to record API base URL http://127.0.0.1:$DOCKER_GIT_API_PORT"
+grep -Fq -- "\"apiBaseUrl\": \"$RESOLVED_API_BASE_URL\"" "$STATE_PATH" \
+  || fail "expected runtime state to record API base URL $RESOLVED_API_BASE_URL"
 
 echo "e2e/browser-command: bun run docker-git -- browser startup verified" >&2