fix: address review feedback on DinD configuration

- Export getLocalDockerEnv() and use it in host-iptables.ts for all
  docker CLI calls (network inspect/create/rm) so they target the
  local daemon when DOCKER_HOST points at an external TCP daemon
- Forward full set of Docker client env vars into agent container
  (DOCKER_TLS_VERIFY, DOCKER_CERT_PATH, DOCKER_CONTEXT, etc.) not
  just DOCKER_HOST, so TLS-authenticated DinD daemons work
- Update warning message to describe auto-redirect behavior instead
  of reusing old fatal error text
- Validate --docker-host flag is a unix:// URI; reject TCP/SSH
- Remove extra blank line before Troubleshooting in docs/environment
- Update host-iptables tests for new env option in docker calls

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: lpcox

docs/environment.md

@@ -246,8 +246,6 @@ The DinD TCP address (e.g., `tcp://localhost:2375`) typically refers to the runn
 - **`--enable-host-access`** — allows the agent to reach `host.docker.internal` and set `DOCKER_HOST=tcp://host.docker.internal:2375` inside the agent.
 - **`--enable-dind`** — mounts the local Docker socket (`/var/run/docker.sock`) directly into the agent container (only works when using the local daemon, not a remote DinD TCP socket).
 
-
-
 ## Troubleshooting
 
 **Variable not accessible:** Use `sudo -E` or pass explicitly with `--env VAR="$VAR"`

src/cli.ts

@@ -1615,9 +1615,8 @@ program
     // agent workload can still reach the DinD daemon.
     const dockerHostCheck = checkDockerHost();
     if (!dockerHostCheck.valid) {
-      logger.warn(`⚠️  ${dockerHostCheck.error}`);
-      logger.warn('   AWF will use the local Docker socket for its own containers.');
-      logger.warn('   The original DOCKER_HOST is forwarded into the agent container.');
+      logger.warn('⚠️  External DOCKER_HOST detected. AWF will redirect its own Docker calls to the local socket.');
+      logger.warn('   The original DOCKER_HOST (and related Docker client env vars) are forwarded into the agent container.');
     }
 
     // Parse domains from both --allow-domains flag and --allow-domains-file
@@ -1924,6 +1923,11 @@ program
 
     // Apply --docker-host override for AWF's own container operations.
     // This must be called before startContainers/stopContainers/runAgentCommand.
+    if (config.awfDockerHost && !config.awfDockerHost.startsWith('unix://')) {
+      logger.error(`❌ --docker-host must be a unix:// socket URI, got: ${config.awfDockerHost}`);
+      logger.error('   Example: --docker-host unix:///run/user/1000/docker.sock');
+      process.exit(1);
+    }
     setAwfDockerHost(config.awfDockerHost);
 
     // Parse and validate --agent-timeout

src/docker-manager.ts

@@ -65,7 +65,7 @@ export function setAwfDockerHost(host: string | undefined): void {
  * The original DOCKER_HOST value is NOT removed from the agent container's
  * environment — see generateDockerCompose for the passthrough logic.
  */
-function getLocalDockerEnv(): NodeJS.ProcessEnv {
+export function getLocalDockerEnv(): NodeJS.ProcessEnv {
   const env = { ...process.env };
 
   if (awfDockerHostOverride !== undefined) {
@@ -828,10 +828,23 @@ export function generateDockerCompose(
     if (process.env.ACTIONS_ID_TOKEN_REQUEST_URL) environment.ACTIONS_ID_TOKEN_REQUEST_URL = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
     if (process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN) environment.ACTIONS_ID_TOKEN_REQUEST_TOKEN = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
 
-    // Forward DOCKER_HOST so the agent workload can reach a DinD daemon or custom Docker socket.
-    // AWF itself uses the local socket (see getLocalDockerEnv), but the agent container should
-    // inherit the original value so docker commands inside the agent work as expected.
-    if (process.env.DOCKER_HOST) environment.DOCKER_HOST = process.env.DOCKER_HOST;
+    // Forward Docker client environment so the agent workload can reach the same DinD daemon,
+    // custom Docker socket, or TCP endpoint as the parent process. DOCKER_HOST alone is not
+    // sufficient for TLS/authenticated daemons; the companion Docker client variables must also
+    // be preserved so docker commands inside the agent work as expected.
+    const dockerClientEnvVars = [
+      'DOCKER_HOST',
+      'DOCKER_TLS',
+      'DOCKER_TLS_VERIFY',
+      'DOCKER_CERT_PATH',
+      'DOCKER_CONTEXT',
+      'DOCKER_CONFIG',
+      'DOCKER_API_VERSION',
+      'DOCKER_DEFAULT_PLATFORM',
+    ] as const;
+    for (const dockerEnvVar of dockerClientEnvVars) {
+      if (process.env[dockerEnvVar]) environment[dockerEnvVar] = process.env[dockerEnvVar]!;
+    }
 
   }
 

src/host-iptables.test.ts

@@ -5,6 +5,11 @@ import execa from 'execa';
 jest.mock('execa');
 const mockedExeca = execa as jest.MockedFunction<typeof execa>;
 
+// Mock getLocalDockerEnv to return a predictable env for assertions
+jest.mock('./docker-manager', () => ({
+  getLocalDockerEnv: () => process.env,
+}));
+
 // Mock logger to avoid console output during tests
 jest.mock('./logger', () => ({
   logger: {
@@ -41,8 +46,8 @@ describe('host-iptables', () => {
       });
 
       // Should only check if network exists, not create it
-      expect(mockedExeca).toHaveBeenCalledWith('docker', ['network', 'inspect', 'awf-net']);
-      expect(mockedExeca).not.toHaveBeenCalledWith('docker', expect.arrayContaining(['network', 'create']));
+      expect(mockedExeca).toHaveBeenCalledWith('docker', ['network', 'inspect', 'awf-net'], { env: expect.any(Object) });
+      expect(mockedExeca).not.toHaveBeenCalledWith('docker', expect.arrayContaining(['network', 'create']), expect.anything());
     });
 
     it('should create network when it does not exist', async () => {
@@ -65,7 +70,7 @@ describe('host-iptables', () => {
         proxyIp: '172.30.0.30',
       });
 
-      expect(mockedExeca).toHaveBeenCalledWith('docker', ['network', 'inspect', 'awf-net']);
+      expect(mockedExeca).toHaveBeenCalledWith('docker', ['network', 'inspect', 'awf-net'], { env: expect.any(Object) });
       expect(mockedExeca).toHaveBeenCalledWith('docker', [
         'network',
         'create',
@@ -74,7 +79,7 @@ describe('host-iptables', () => {
         '172.30.0.0/24',
         '--opt',
         'com.docker.network.bridge.name=fw-bridge',
-      ]);
+      ], { env: expect.any(Object) });
     });
   });
 
@@ -1101,7 +1106,7 @@ describe('host-iptables', () => {
 
       await cleanupFirewallNetwork();
 
-      expect(mockedExeca).toHaveBeenCalledWith('docker', ['network', 'rm', 'awf-net'], { reject: false });
+      expect(mockedExeca).toHaveBeenCalledWith('docker', ['network', 'rm', 'awf-net'], { reject: false, env: expect.any(Object) });
     });
 
     it('should not throw on errors (best-effort cleanup)', async () => {

src/host-iptables.ts

@@ -2,6 +2,7 @@ import execa from 'execa';
 import { logger } from './logger';
 import { API_PROXY_PORTS } from './types';
 import { DEFAULT_DNS_SERVERS } from './dns-resolver';
+import { getLocalDockerEnv } from './docker-manager';
 
 const NETWORK_NAME = 'awf-net';
 const CHAIN_NAME = 'FW_WRAPPER';
@@ -71,7 +72,7 @@ async function getNetworkBridgeName(): Promise<string | null> {
       NETWORK_NAME,
       '-f',
       '{{index .Options "com.docker.network.bridge.name"}}',
-    ]);
+    ], { env: getLocalDockerEnv() });
     const bridgeName = stdout.trim();
     return bridgeName || null;
   } catch (error) {
@@ -89,7 +90,7 @@ export async function getDockerBridgeGateway(): Promise<string | null> {
     const { stdout } = await execa('docker', [
       'network', 'inspect', 'bridge',
       '-f', '{{(index .IPAM.Config 0).Gateway}}',
-    ]);
+    ], { env: getLocalDockerEnv() });
     const gateway = stdout.trim();
     if (!gateway) return null;
     // Validate IPv4 format before using in iptables rules
@@ -173,7 +174,7 @@ export async function ensureFirewallNetwork(): Promise<{
   // Check if network already exists
   let networkExists = false;
   try {
-    await execa('docker', ['network', 'inspect', NETWORK_NAME]);
+    await execa('docker', ['network', 'inspect', NETWORK_NAME], { env: getLocalDockerEnv() });
     networkExists = true;
     logger.debug(`Network '${NETWORK_NAME}' already exists`);
   } catch {
@@ -191,7 +192,7 @@ export async function ensureFirewallNetwork(): Promise<{
       NETWORK_SUBNET,
       '--opt',
       'com.docker.network.bridge.name=fw-bridge',
-    ]);
+    ], { env: getLocalDockerEnv() });
     logger.success(`Created network '${NETWORK_NAME}' with bridge 'fw-bridge'`);
   }
 
@@ -693,7 +694,7 @@ export async function cleanupFirewallNetwork(): Promise<void> {
   logger.debug(`Removing firewall network '${NETWORK_NAME}'...`);
 
   try {
-    await execa('docker', ['network', 'rm', NETWORK_NAME], { reject: false });
+    await execa('docker', ['network', 'rm', NETWORK_NAME], { reject: false, env: getLocalDockerEnv() });
     logger.debug('Firewall network removed');
   } catch (error) {
     logger.debug('Error removing firewall network:', error);