feat(shell): stabilize docker-git networking with shared mode

- add typed network mode config and CLI flags

- ensure shared compose network exists before up

- add safe gc for detached project networks

- extend docs/errors/tests for subnet exhaustion recovery

Author: skulidropek

README.md

@@ -122,6 +122,19 @@ Common toggles:
 - `NPM_CONFIG_CACHE=/home/dev/.docker-git/.cache/packages/npm` (default shared cache)
 - `YARN_CACHE_FOLDER=/home/dev/.docker-git/.cache/packages/yarn` (default shared cache)
 
+## Compose Network Mode
+
+Default mode is shared:
+- `--network-mode shared` (default)
+- Shared compose network name: `--shared-network docker-git-shared`
+
+Shared mode keeps one external Docker network for all docker-git projects, which reduces address pool pressure when many projects are created.
+
+If you need strict per-project isolation:
+- `--network-mode project`
+
+In project mode, each project uses `<service>-net` (Docker-managed bridge network).
+
 ## Troubleshooting
 
 MCP errors in `codex` UI:
@@ -158,6 +171,17 @@ Docker permission error (`/var/run/docker.sock`):
 - Note:
   - Do not run `pnpm run docker-git ...` with `sudo`.
 
+Docker network pool exhausted (`all predefined address pools have been fully subnetted`):
+- Symptom:
+  - `failed to create network ... all predefined address pools have been fully subnetted`
+- Quick recovery:
+  ```bash
+  docker network prune -f
+  ```
+- Long-term fix:
+  - Configure Docker daemon `default-address-pools` in `/etc/docker/daemon.json`.
+  - Prefer `docker-git` shared network mode (`--network-mode shared`).
+
 Clone auth error (`Invalid username or token`):
 - Symptom:
   - `remote: Invalid username or token. Password authentication is not supported for Git operations.`

packages/app/src/docker-git/cli/parser-options.ts

@@ -20,6 +20,8 @@ interface ValueOptionSpec {
     | "envProjectPath"
     | "codexAuthPath"
     | "codexHome"
+    | "dockerNetworkMode"
+    | "dockerSharedNetworkName"
     | "archivePath"
     | "scrapMode"
     | "label"
@@ -51,6 +53,8 @@ const valueOptionSpecs: ReadonlyArray<ValueOptionSpec> = [
   { flag: "--env-project", key: "envProjectPath" },
   { flag: "--codex-auth", key: "codexAuthPath" },
   { flag: "--codex-home", key: "codexHome" },
+  { flag: "--network-mode", key: "dockerNetworkMode" },
+  { flag: "--shared-network", key: "dockerSharedNetworkName" },
   { flag: "--archive", key: "archivePath" },
   { flag: "--mode", key: "scrapMode" },
   { flag: "--label", key: "label" },
@@ -102,6 +106,8 @@ const valueFlagUpdaters: { readonly [K in ValueKey]: (raw: RawOptions, value: st
   envProjectPath: (raw, value) => ({ ...raw, envProjectPath: value }),
   codexAuthPath: (raw, value) => ({ ...raw, codexAuthPath: value }),
   codexHome: (raw, value) => ({ ...raw, codexHome: value }),
+  dockerNetworkMode: (raw, value) => ({ ...raw, dockerNetworkMode: value }),
+  dockerSharedNetworkName: (raw, value) => ({ ...raw, dockerSharedNetworkName: value }),
   archivePath: (raw, value) => ({ ...raw, archivePath: value }),
   scrapMode: (raw, value) => ({ ...raw, scrapMode: value }),
   label: (raw, value) => ({ ...raw, label: value }),

packages/app/src/docker-git/cli/usage.ts

@@ -47,6 +47,8 @@ Options:
   --env-project <path>      Host path to project env file (default: ./.orch/env/project.env)
   --codex-auth <path>       Host path for Codex auth cache (default: <projectsRoot>/.orch/auth/codex)
   --codex-home <path>       Container path for Codex auth (default: /home/dev/.codex)
+  --network-mode <mode>     Compose network mode: shared|project (default: shared)
+  --shared-network <name>   Shared Docker network name when network-mode=shared (default: docker-git-shared)
   --out-dir <path>          Output directory (default: <projectsRoot>/<org>/<repo>[/issue-<id>|/pr-<id>])
   --project-dir <path>      Project directory for attach (default: .)
   --archive <path>          Scrap snapshot directory (default: .orch/scrap/session)

packages/app/src/docker-git/menu-actions.ts

@@ -9,6 +9,7 @@ import {
   listProjectStatus,
   listRunningProjectItems
 } from "@effect-template/lib/usecases/projects"
+import { gcProjectNetworkByTemplate } from "@effect-template/lib/usecases/docker-network-gc"
 import { runDockerComposeUpWithPortCheck } from "@effect-template/lib/usecases/projects-up"
 import { Effect, Match, pipe } from "effect"
 
@@ -149,8 +150,10 @@ const handleMenuAction = (
       withProjectConfig(state, setMessage, () =>
         runDockerComposeLogs(state.activeDir ?? state.cwd))),
     Match.when({ _tag: "Down" }, () =>
-      withProjectConfig(state, setMessage, () =>
-        runDockerComposeDown(state.activeDir ?? state.cwd))),
+      withProjectConfig(state, setMessage, (config) =>
+        runDockerComposeDown(state.activeDir ?? state.cwd).pipe(
+          Effect.zipRight(gcProjectNetworkByTemplate(state.activeDir ?? state.cwd, config.template))
+        ))),
     Match.when({ _tag: "DownAll" }, () =>
       pipe(
         downAllDockerGitProjects,

packages/app/tests/docker-git/parser-network-options.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "@effect/vitest"
+import { Effect, Either } from "effect"
+
+import { parseArgs } from "../../src/docker-git/cli/parser.js"
+
+describe("parseArgs network options", () => {
+  it.effect("parses create network mode options", () =>
+    Effect.sync(() => {
+      const parsed = parseArgs([
+        "create",
+        "--repo-url",
+        "https://github.com/org/repo.git",
+        "--network-mode",
+        "project",
+        "--shared-network",
+        "ignored-shared-network"
+      ])
+      if (Either.isLeft(parsed)) {
+        throw new Error(`unexpected parse error: ${parsed.left._tag}`)
+      }
+      const command = parsed.right
+      if (command._tag !== "Create") {
+        throw new Error("expected Create command")
+      }
+      expect(command.config.dockerNetworkMode).toBe("project")
+      expect(command.config.dockerSharedNetworkName).toBe("ignored-shared-network")
+    }))
+
+  it.effect("fails on invalid network mode", () =>
+    Effect.sync(() => {
+      const command = parseArgs([
+        "create",
+        "--repo-url",
+        "https://github.com/org/repo.git",
+        "--network-mode",
+        "invalid"
+      ])
+      Either.match(command, {
+        onLeft: (error) => {
+          expect(error._tag).toBe("InvalidOption")
+        },
+        onRight: () => {
+          throw new Error("expected parse error")
+        }
+      })
+    }))
+})

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

@@ -71,6 +71,8 @@ const expectCreateDefaults = (command: CreateCommand) => {
   expect(command.outDir).toBe(".docker-git/org/repo")
   expect(command.runUp).toBe(true)
   expect(command.forceEnv).toBe(false)
+  expect(command.config.dockerNetworkMode).toBe("shared")
+  expect(command.config.dockerSharedNetworkName).toBe("docker-git-shared")
 }
 
 const expandDefaultTargetDir = (path: string): string => expandContainerHome(defaultTemplateConfig.sshUser, path)

packages/lib/src/core/command-builders.ts

@@ -7,6 +7,7 @@ import {
   defaultTemplateConfig,
   deriveRepoPathParts,
   deriveRepoSlug,
+  isDockerNetworkMode,
   type ParseError,
   resolveRepoInput
 } from "./domain.js"
@@ -32,6 +33,20 @@ const parsePort = (value: string): Either.Either<number, ParseError> => {
   return Either.right(parsed)
 }
 
+const parseDockerNetworkMode = (
+  value: string | undefined
+): Either.Either<CreateCommand["config"]["dockerNetworkMode"], ParseError> => {
+  const candidate = value?.trim() ?? defaultTemplateConfig.dockerNetworkMode
+  if (isDockerNetworkMode(candidate)) {
+    return Either.right(candidate)
+  }
+  return Either.left({
+    _tag: "InvalidOption",
+    option: "--network-mode",
+    reason: "expected one of: shared, project"
+  })
+}
+
 export const nonEmpty = (
   option: string,
   value: string | undefined,
@@ -210,6 +225,10 @@ export const buildCreateCommand = (
     const gitTokenLabel = normalizeGitTokenLabel(raw.gitTokenLabel)
     const codexAuthLabel = normalizeAuthLabel(raw.codexTokenLabel)
     const claudeAuthLabel = normalizeAuthLabel(raw.claudeTokenLabel)
+    const dockerNetworkMode = yield* _(parseDockerNetworkMode(raw.dockerNetworkMode))
+    const dockerSharedNetworkName = yield* _(
+      nonEmpty("--shared-network", raw.dockerSharedNetworkName, defaultTemplateConfig.dockerSharedNetworkName)
+    )
 
     return {
       _tag: "Create",
@@ -238,6 +257,8 @@ export const buildCreateCommand = (
         codexAuthPath: paths.codexAuthPath,
         codexSharedAuthPath: paths.codexSharedAuthPath,
         codexHome: paths.codexHome,
+        dockerNetworkMode,
+        dockerSharedNetworkName,
         enableMcpPlaywright,
         pnpmVersion: defaultTemplateConfig.pnpmVersion
       }

packages/lib/src/core/command-options.ts

@@ -25,6 +25,8 @@ export interface RawOptions {
   readonly envProjectPath?: string
   readonly codexAuthPath?: string
   readonly codexHome?: string
+  readonly dockerNetworkMode?: string
+  readonly dockerSharedNetworkName?: string
   readonly enableMcpPlaywright?: boolean
   readonly archivePath?: string
   readonly scrapMode?: string

packages/lib/src/core/domain.ts

@@ -2,6 +2,12 @@ export type { MenuAction, ParseError } from "./menu.js"
 export { parseMenuSelection } from "./menu.js"
 export { deriveRepoPathParts, deriveRepoSlug, resolveRepoInput } from "./repo.js"
 
+export type DockerNetworkMode = "shared" | "project"
+
+export const defaultDockerNetworkMode: DockerNetworkMode = "shared"
+
+export const defaultDockerSharedNetworkName = "docker-git-shared"
+
 export interface TemplateConfig {
   readonly containerName: string
   readonly serviceName: string
@@ -22,6 +28,8 @@ export interface TemplateConfig {
   readonly codexAuthPath: string
   readonly codexSharedAuthPath: string
   readonly codexHome: string
+  readonly dockerNetworkMode: DockerNetworkMode
+  readonly dockerSharedNetworkName: string
   readonly enableMcpPlaywright: boolean
   readonly pnpmVersion: string
 }
@@ -262,6 +270,36 @@ export type Command =
   | StateCommand
   | AuthCommand
 
+// CHANGE: validate docker network mode values at the CLI/config boundary
+// WHY: keep compose network behavior explicit and type-safe
+// QUOTE(ТЗ): "Что бы среды были изолированы?"
+// REF: user-request-2026-02-20-networks
+// SOURCE: n/a
+// FORMAT THEOREM: ∀x: isDockerNetworkMode(x) -> x ∈ {"shared","project"}
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: returns true only for known modes
+// COMPLEXITY: O(1)
+export const isDockerNetworkMode = (value: string): value is DockerNetworkMode =>
+  value === "shared" || value === "project"
+
+// CHANGE: derive compose network name from typed template config
+// WHY: keep network naming deterministic across template generation and runtime checks
+// QUOTE(ТЗ): "Если я хочу уникальную сеть на каждый контейнер?"
+// REF: user-request-2026-02-20-networks
+// SOURCE: n/a
+// FORMAT THEOREM: ∀cfg: resolveComposeNetworkName(cfg) = n -> deterministic(n)
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: shared mode always resolves to dockerSharedNetworkName; project mode to "<service>-net"
+// COMPLEXITY: O(1)
+export const resolveComposeNetworkName = (
+  config: Pick<TemplateConfig, "serviceName" | "dockerNetworkMode" | "dockerSharedNetworkName">
+): string =>
+  config.dockerNetworkMode === "shared"
+    ? config.dockerSharedNetworkName
+    : `${config.serviceName}-net`
+
 export const defaultTemplateConfig = {
   containerName: "dev-ssh",
   serviceName: "dev",
@@ -277,6 +315,8 @@ export const defaultTemplateConfig = {
   codexAuthPath: "./.docker-git/.orch/auth/codex",
   codexSharedAuthPath: "./.docker-git/.orch/auth/codex",
   codexHome: "/home/dev/.codex",
+  dockerNetworkMode: defaultDockerNetworkMode,
+  dockerSharedNetworkName: defaultDockerSharedNetworkName,
   enableMcpPlaywright: false,
   pnpmVersion: "10.27.0"
 }

packages/lib/src/core/templates/docker-compose.ts

@@ -1,6 +1,7 @@
-import type { TemplateConfig } from "../domain.js"
+import { resolveComposeNetworkName, type TemplateConfig } from "../domain.js"
 
 type ComposeFragments = {
+  readonly networkMode: TemplateConfig["dockerNetworkMode"]
   readonly networkName: string
   readonly maybeGitTokenLabelEnv: string
   readonly maybeCodexAuthLabelEnv: string
@@ -62,7 +63,8 @@ const buildPlaywrightFragments = (
 }
 
 const buildComposeFragments = (config: TemplateConfig): ComposeFragments => {
-  const networkName = `${config.serviceName}-net`
+  const networkMode = config.dockerNetworkMode
+  const networkName = resolveComposeNetworkName(config)
   const forkRepoUrl = config.forkRepoUrl ?? ""
   const gitTokenLabel = config.gitTokenLabel?.trim() ?? ""
   const codexAuthLabel = config.codexAuthLabel?.trim() ?? ""
@@ -73,6 +75,7 @@ const buildComposeFragments = (config: TemplateConfig): ComposeFragments => {
   const playwright = buildPlaywrightFragments(config, networkName)
 
   return {
+    networkMode,
     networkName,
     maybeGitTokenLabelEnv,
     maybeCodexAuthLabelEnv,
@@ -115,8 +118,15 @@ ${fragments.maybePlaywrightEnv}${fragments.maybeDependsOn}    env_file:
       - ${fragments.networkName}
 ${fragments.maybeBrowserService}`
 
-const renderComposeNetworks = (networkName: string): string =>
-  `networks:
+const renderComposeNetworks = (
+  networkMode: TemplateConfig["dockerNetworkMode"],
+  networkName: string
+): string =>
+  networkMode === "shared"
+    ? `networks:
+  ${networkName}:
+    external: true`
+    : `networks:
   ${networkName}:
     driver: bridge`
 
@@ -129,7 +139,7 @@ export const renderDockerCompose = (config: TemplateConfig): string => {
   const fragments = buildComposeFragments(config)
   return [
     renderComposeServices(config, fragments),
-    renderComposeNetworks(fragments.networkName),
+    renderComposeNetworks(fragments.networkMode, fragments.networkName),
     renderComposeVolumes(config, fragments.maybeBrowserVolume)
   ].join("\n\n")
 }