localhost-bridge — Connect containers to host localhost services
⚠️ Security & Privileges
This skill requires host-level privileges. It must be reviewed and executed manually by an administrator — never autonomously by an agent.
What it does on the host:
- - Creates a systemd service (persistent across reboots) that forwards traffic from a Docker bridge IP to localhost
- Adds a UFW firewall rule scoped to a specific Docker bridge interface
- Requires sudo, Docker daemon access, and socat from your distro's official package repository
Before running any command:
- 1. Review the generated
/etc/systemd/system/socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>.service file — confirm ExecStart binds only to the intended Docker bridge IP (172.x.x.1), never 0.0.0.0 - Review the UFW rule — confirm it targets the correct
br-<ID> interface and port - After setup, verify the port is NOT reachable from the public network:
curl --connect-timeout 2 http://<PUBLIC_IP>:<PORT>/ must fail - Test from inside a container before deploying widely
Do not grant an automated agent permissions to run these commands without human approval.
The Problem
A service on the host listens on 127.0.0.1 (AI gateway, MCP server, Ollama, database...). A Docker container needs to reach it. localhost inside the container points to the container itself, not the host. Requests either timeout silently (firewall drops packets) or get connection refused.
The Solution
INLINECODE6 listens on the Docker bridge gateway IP and forwards to host loopback. Combined with a scoped firewall rule, this gives containers access without exposing the service externally.
Setup (run manually as admin)
1. Find the Docker bridge gateway IP
CODEBLOCK0
2. Create a systemd service
Replace <GATEWAY_IP>, <PORT>, <SOURCE_NETWORK>, and <TARGET_SERVICE> with your values.
Naming convention: socat-<source_network>-<target_service>-<port> — source network is the Docker network (consumer), target service is the host service. Self-documenting.
Examples: socat-bridge-gateway-18789, socat-windmill_default-gateway-18789, INLINECODE14
Review the ExecStart line before enabling — confirm it binds to the Docker bridge IP only.
CODEBLOCK1
3. Add firewall rule (MANDATORY)
Without this, socat listens but packets from the container are silently dropped — causing 30-second timeouts with no error.
Review the bridge ID before applying — a wrong ID can expose services.
CODEBLOCK2
4. Verify security
CODEBLOCK3
Multi-Network Workers
A container can be on multiple Docker networks. Each has its own bridge IP. You need a socat instance + firewall rule for each network the container uses. In practice, one network is usually enough.
Check all networks: INLINECODE15
Common Use Cases
| Host service | Container client | Default port |
|---|
| AI gateway (OpenClaw, LiteLLM) | Workflow orchestrator (Windmill, n8n) | 18789 |
| MCP server |
Dockerized agent | varies |
| Ollama | RAG pipeline, agent | 11434 |
| PostgreSQL | API server | 5432 |
| Redis | Any containerized app | 6379 |
Troubleshooting
| Symptom | Cause | Fix |
|---|
| 30s timeout, no error | Firewall dropping packets | Add UFW rule on the bridge interface |
| Connection refused |
socat not running |
systemctl status socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT> |
| Works then stops after Docker restart | Bridge IP changed | Check new gateway IP, update socat bind |
| socat won't start after reboot | Docker not ready | Ensure
After=docker.service in unit file |
Alternatives
Depending on your security posture, consider:
- - Docker host networking (
network_mode: host) — simpler but removes all container network isolation - Running socat inside a minimal privileged container — avoids host-level systemd changes
- Configuring the host service to bind to the Docker bridge IP directly — no socat needed, but the service must support custom bind addresses
host.docker.internal (Docker Desktop) — works on Mac/Windows, not reliably on Linux
Prerequisites
Install socat from your distro's official package repository:
CODEBLOCK4
References
localhost-bridge — 将容器连接到主机本地服务
⚠️ 安全与权限
此技能需要主机级权限。 必须由管理员审核并手动执行——绝不能由代理自动执行。
它在主机上执行的操作：
- - 创建一个 systemd 服务（重启后持久化），将流量从 Docker 桥接 IP 转发到本地主机
- 添加一条限定于特定 Docker 桥接接口的 UFW 防火墙规则
- 需要 sudo、Docker 守护进程访问权限以及来自发行版官方软件包的 socat
在执行任何命令之前：
- 1. 检查生成的 /etc/systemd/system/socat-NETWORK>-SERVICE>-.service 文件——确认 ExecStart 仅绑定到预期的 Docker 桥接 IP（172.x.x.1），绝不能是 0.0.0.0
- 检查 UFW 规则——确认它针对正确的 br- 接口和端口
- 设置完成后，验证该端口无法从公共网络访问：curl --connect-timeout 2 http://:/ 必须失败
- 在广泛部署前，从容器内部进行测试
未经人工批准，不得授予自动化代理执行这些命令的权限。
问题描述
主机上的某个服务监听在 127.0.0.1（AI 网关、MCP 服务器、Ollama、数据库等）。Docker 容器需要访问该服务。容器内部的 localhost 指向容器自身，而非主机。请求要么静默超时（防火墙丢弃数据包），要么连接被拒绝。
解决方案
socat 监听 Docker 桥接网关 IP 并将流量转发到主机回环地址。结合限定范围的防火墙规则，这使容器能够访问服务，同时不会将服务暴露到外部。
设置（以管理员身份手动执行）
1. 查找 Docker 桥接网关 IP
bash
针对特定容器
docker inspect
--format {{json .NetworkSettings.Networks}} \
| python3 -c
import json,sys
d = json.load(sys.stdin)
for net, info in d.items():
print(f{net}: gateway={info[\Gateway\]})
2. 创建 systemd 服务
将 IP>、、NETWORK> 和 替换为你的实际值。
命名规范： socat-network>-service>-——源网络是 Docker 网络（消费者），目标服务是主机服务。自文档化。
示例：socat-bridge-gateway-18789、socat-windmill_default-gateway-18789、socat-bridge-ollama-11434
在启用前检查 ExecStart 行——确认它仅绑定到 Docker 桥接 IP。
bash
sudo tee /etc/systemd/system/socat-NETWORK>-SERVICE>-.service > /dev/null << EOF
[Unit]
Description=Socat bridge: NETWORK> -> SERVICE>:
After=network.target docker.service
[Service]
Type=simple
ExecStart=/usr/bin/socat TCP-LISTEN:,bind=,fork,reuseaddr TCP:127.0.0.1:
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
EOF
在启用前检查文件：
cat /etc/systemd/system/socat-NETWORK>-SERVICE>-.service
sudo systemctl daemon-reload
sudo systemctl enable --now socat-NETWORK>-SERVICE>-
3. 添加防火墙规则（必须执行）
如果不添加此规则，socat 会监听，但来自容器的数据包会被静默丢弃——导致 30 秒超时且无错误信息。
在应用前检查桥接 ID——错误的 ID 可能会暴露服务。
bash
查找 Docker 网络的 Linux 桥接接口
BRIDGEID=$(docker network inspect name> --format {{.Id}} | cut -c1-12)
验证这是正确的桥接
ip link show br-${BRIDGE_ID}
仅允许该桥接接口上的流量
sudo ufw allow in on br-${BRIDGEID} to any port proto tcp comment NETWORK>--
4. 验证安全性
bash
必须成功（从容器内部）
docker exec name> curl -s --connect-timeout 5 http://IP>:/
必须失败（从公共网络）
curl --connect-timeout 2 http://:/
多网络工作节点
一个容器可以位于多个 Docker 网络上。每个网络都有自己的桥接 IP。你需要为容器使用的每个网络创建一个 socat 实例和防火墙规则。实际上，一个网络通常就足够了。
检查所有网络：docker inspect --format {{json .NetworkSettings.Networks}}
常见用例
| 主机服务 | 容器客户端 | 默认端口 |
|---|
| AI 网关（OpenClaw、LiteLLM） | 工作流编排器（Windmill、n8n） | 18789 |
| MCP 服务器 |
Docker 化代理 | 可变 |
| Ollama | RAG 流水线、代理 | 11434 |
| PostgreSQL | API 服务器 | 5432 |
| Redis | 任何容器化应用 | 6379 |
故障排除
| 症状 | 原因 | 修复 |
|---|
| 30 秒超时，无错误 | 防火墙丢弃数据包 | 在桥接接口上添加 UFW 规则 |
| 连接被拒绝 |
socat 未运行 | systemctl status socat-NETWORK>-SERVICE>- |
| 运行后因 Docker 重启停止 | 桥接 IP 已更改 | 检查新网关 IP，更新 socat 绑定 |
| socat 重启后无法启动 | Docker 未就绪 | 确保单元文件中包含 After=docker.service |
替代方案
根据你的安全策略，可以考虑：
- - Docker 主机网络（network_mode: host）——更简单，但移除了所有容器网络隔离
- 在最小权限容器中运行 socat——避免主机级 systemd 更改
- 配置主机服务直接绑定到 Docker 桥接 IP——无需 socat，但服务必须支持自定义绑定地址
- host.docker.internal（Docker Desktop）——适用于 Mac/Windows，在 Linux 上不可靠
前提条件
从发行版官方软件包仓库安装 socat：
bash
sudo apt-get install -y socat # Debian/Ubuntu
sudo dnf install -y socat # Fedora/RHEL
参考资料
