localhost-bridge

intent

this skill bridges Docker containers to host localhost services using socat, a TCP forwarding utility. it solves the core networking problem in containerized deployments: containers can't reach services bound to 127.0.0.1 on the host because localhost inside a container routes to the container itself, not the host. use this when your containerized agents, orchestrators, or pipeline components need to talk to host-local services like AI gateways, MCP servers, Ollama, databases, or caches without exposing those services to the public network.

inputs

• Host machine access: must execute all commands on the host where the target service runs. requires passwordless sudo or explicit sudo approval for each command.
• Docker daemon access: ability to run docker inspect, docker network inspect, and docker exec commands. typically requires user to be in the docker group or have sudo docker access.
• socat binary: install via sudo apt-get install -y socat (Debian/Ubuntu) or sudo dnf install -y socat (Fedora/RHEL). must be in /usr/bin/socat.
• systemd: host must use systemd for service management. systemd socket activation must be enabled (usually default).
• UFW firewall (if enabled): if UFW is active, must have permission to add rules via sudo ufw allow. if firewalld or iptables is used instead, adjust firewall commands accordingly.
• Docker network details: container name or ID, target Docker network name, target host service port, target host localhost IP (always 127.0.0.1), and Docker bridge gateway IP for that network.
• No existing socat service on that port: if a socat service already bridges the same port on the same network, this will conflict. check systemctl list-units --type=service | grep socat first.

procedure

1. Identify the Docker bridge gateway IP for your network.

   • Input: container name (e.g., my-agent), Docker network name (e.g., bridge, windmill_default).
   • Run: docker inspect <container_name> --format '{{json .NetworkSettings.Networks}}' | python3 -c "import json,sys; d = json.load(sys.stdin); [print(f'{net}: gateway={info[\"Gateway\"]}') for net, info in d.items()]"
   • Output: list of networks and their gateway IPs, e.g., bridge: gateway=172.17.0.1.
   • Edge case: if container is not running, docker inspect will still work but NetworkSettings may show stale data. restart the container to refresh.

2. Review the socat configuration before deploying.

   • Input: source network name, target service name, port number, gateway IP from step 1.
   • Construct systemd service filename: socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT> (e.g., socat-bridge-ollama-11434).
   • Generate systemd unit file content: ExecStart=/usr/bin/socat TCP-LISTEN:<PORT>,bind=<GATEWAY_IP>,fork,reuseaddr TCP:127.0.0.1:<PORT>.
   • Output: full unit file text, written to stdout.
   • Critical check: confirm bind address is the Docker bridge IP only (e.g., 172.17.0.1), never 0.0.0.0. if 0.0.0.0 appears, stop and reject.

3. Create and enable the systemd service.

   • Input: systemd unit file content from step 2, service name.
   • Run: sudo tee /etc/systemd/system/socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>.service > /dev/null << 'EOF' <unit_file_content> EOF
   • Run: sudo systemctl daemon-reload
   • Run: sudo systemctl enable --now socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>
   • Output: service enabled and started. verify via sudo systemctl status socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT> (should show "active (running)").
   • Edge case: if Docker service has not started, socat will fail to start due to After=docker.service. wait for Docker to be ready and manually restart socat via sudo systemctl restart socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>.

4. Identify the Linux bridge interface for the Docker network.

   • Input: Docker network name from step 1.
   • Run: docker network inspect <network_name> --format '{{.Id}}' | cut -c1-12
   • Output: 12-character bridge ID (e.g., a1b2c3d4e5f6).
   • Note: the actual Linux bridge interface is br-<ID> (e.g., br-a1b2c3d4e5f6).
   • Validation: run ip link show br-<ID> to confirm the bridge exists. if not found, the network may not have created a bridge (rare; indicates a misconfigured network).

5. Add UFW firewall rule scoped to the bridge interface.

   • Input: bridge interface name (e.g., br-a1b2c3d4e5f6) from step 4, port number, source network name, target service name.
   • Precondition: check if UFW is enabled via sudo ufw status. if inactive, skip this step.
   • Run: sudo ufw allow in on br-<ID> to any port <PORT> proto tcp comment "<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>"
   • Output: UFW rule added. verify via sudo ufw show added or sudo ufw status numbered | grep <PORT>.
   • Critical: if this rule is not added and UFW is enabled, packets from the container will be silently dropped, causing 30-second timeouts with no visible error message.
   • Edge case: if UFW is not installed or disabled, skip. if using firewalld or iptables, adapt the command (e.g., sudo firewall-cmd --add-rich-rule 'rule family="ipv4" source address="172.17.0.0/16" inbound port protocol="tcp" port="<PORT>" accept').

6. Test from inside the container.

   • Input: container name, gateway IP from step 1, port number.
   • Run: docker exec <container_name> curl -s --connect-timeout 5 http://<GATEWAY_IP>:<PORT>/
   • Expected output: HTTP response from the target service (e.g., 200 OK, service-specific output). if timeout or connection refused, socat is not running or firewall rule is missing.
   • If test fails: check sudo systemctl status socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT> for socat errors. check sudo ufw status | grep <PORT> to confirm rule is present.

7. Verify the service is not reachable from the public network.

   • Input: public IP or hostname of the host, port number.
   • Run: curl --connect-timeout 2 http://<PUBLIC_IP>:<PORT>/
   • Expected output: timeout or connection refused. if you get a 200 OK or service response, the firewall rule failed or socat is binding to 0.0.0.0 instead of the bridge IP. stop and investigate.
   • Security check: this confirms the service is not accidentally exposed externally.

decision points

• If container is on multiple Docker networks: you need a separate socat service + UFW rule for each network. check all networks via docker inspect <container> --format '{{json .NetworkSettings.Networks}}'. if the container has 2 networks (e.g., bridge and custom), create two separate socat services (e.g., socat-bridge-ollama-11434 and socat-custom-ollama-11434).

• If UFW is not installed or disabled: skip step 5 entirely. socat will still work, but will be accessible to any process on the host with network access to the bridge interface (less isolated, but acceptable in trusted environments).

• If using firewalld or iptables instead of UFW: adapt the firewall command in step 5. for firewalld, use sudo firewall-cmd --permanent --add-rich-rule 'rule family="ipv4" source address="<BRIDGE_NETWORK>" inbound port protocol="tcp" port="<PORT>" accept'. for iptables, use sudo iptables -A DOCKER-USER -i br-<ID> -p tcp --dport <PORT> -j ACCEPT.

• If Docker bridge IP changes after container restart: socat will no longer work because it binds to a stale IP. docker can reassign bridge IPs if the container is recreated or if docker daemon restarts. either (a) use --ip flag when starting the container to pin the IP, or (b) automate bridge IP discovery by running step 1 periodically and restarting socat if the IP changes.

• If test in step 6 times out: firewall rule is missing or UFW silently dropped the rule (e.g., due to interface name mismatch). first verify the bridge interface name with ip link show br-<ID>. then verify the rule was added with sudo ufw show added. if the interface name is wrong, delete the rule with sudo ufw delete allow in on br-<WRONG_ID> to any port <PORT> proto tcp and re-run step 5 with the correct interface.

• If socat fails to start after Docker restart: the After=docker.service dependency may not be enough if docker takes time to initialize the bridge. manually restart socat via sudo systemctl restart socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT> or increase the restart delay by adding StartLimitInterval=30s and StartLimitBurst=5 to the [Service] section.

output contract

• systemd service file: created at /etc/systemd/system/socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>.service. file must be readable via cat /etc/systemd/system/socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>.service and must contain ExecStart=/usr/bin/socat TCP-LISTEN:<PORT>,bind=<GATEWAY_IP>,fork,reuseaddr TCP:127.0.0.1:<PORT>.

• systemd service enabled: service must appear in systemctl list-units --type=service | grep socat and must show enabled via systemctl is-enabled socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>.

• systemd service running: sudo systemctl status socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT> must show active (running) and PID must be present.

• UFW rule added (if UFW enabled): rule must appear in sudo ufw status numbered with comment matching <SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT> and must specify the correct bridge interface (e.g., in on br-a1b2c3d4e5f6).

• socat listening on bridge IP: verify via sudo netstat -tlnp | grep socat or sudo ss -tlnp | grep socat. output must show socat listening on <GATEWAY_IP>:<PORT> (e.g., 172.17.0.1:11434), NOT 0.0.0.0:<PORT>.

outcome signal

• From inside the container: docker exec <container_name> curl -s --connect-timeout 5 http://<GATEWAY_IP>:<PORT>/ returns a 200 or 2xx status code and service response (e.g., Ollama returns JSON, PostgreSQL rejects HTTP but tcp connection succeeds, etc.). no timeout. no connection refused.

• From the host: curl -s --connect-timeout 5 http://127.0.0.1:<PORT>/ works (if service is up), confirming socat is proxying correctly.

• From the public network: curl --connect-timeout 2 http://<PUBLIC_IP>:<PORT>/ times out or returns connection refused, confirming the service is not exposed externally.

• systemd logs: sudo journalctl -u socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT> -n 20 shows no error messages (or only initial startup messages like "listening on :").

• Docker container can now reach the host service: application logs inside the container show successful connections to the host service (e.g., AI agent connecting to Ollama, workflow orchestrator connecting to AI gateway, pipeline connecting to PostgreSQL).

credits: skill authored by Erwan Lee Pesle (superWorldSavior). original blog post and source at casys.ai.