Localhost Bridge

Bridge Docker containers to host localhost services via socat. Solves the #1 networking issue in containerized AI agent deployments: containers can't reach s...

Security Scan

The instructions themselves match the stated purpose, but the skill asks an administrator to perform persistent, high-privilege host changes while the registry metadata does not declare those requirements — this mismatch and the potential for persistent host modification justify caution.

Purpose & Capability

SKILL.md clearly requires sudo, Docker daemon access, and the socat package to create systemd services and UFW rules on the host. The registry metadata (required binaries/env/config) lists none of these requirements, creating an incoherence between what the skill claims to need and what it actually instructs an admin to do.

Instruction Scope

The runtime instructions are explicit and scoped to the stated purpose (bind socat to a Docker bridge IP, add a scoped UFW rule, create a systemd unit). The doc repeatedly warns that an administrator must review the generated unit and firewall rules before enabling them.

Install Mechanism

This is an instruction-only skill with no install spec or code files — nothing is downloaded or written by the skill itself beyond what an admin runs. That minimizes code-distribution risk.

Credentials

The actions require host-level privileges (sudo to write systemd units, modify UFW) and Docker daemon access. Those privileged requirements are reasonable for the described task but are not declared in the registry metadata, which understates the level of credential/privilege access needed.

Persistence & Privilege

The setup creates persistent system changes (systemd service + UFW rule) which affect host networking. While always:false is correctly set, the platform metadata also allows agent invocation by default; because the SKILL.md warns it must not be run autonomously, there is a policy mismatch — ensure automated agents are NOT given sudo/host access before enabling.

What to consider before installing

This skill appears to implement what it claims (using socat + firewall + systemd to let containers reach host-local services), but it requires high privileges and makes persistent host network changes — do not let an agent run it autonomously. Before installing or following the instructions: (1) only run these commands as a trusted administrator on a controlled host; (2) manually inspect the generated /etc/systemd/system/socat-*.service ExecStart line and confirm it binds only to the intended Docker bridge IP (never 0.0.0.0); (3) inspect the UFW rule and bridge interface name before enabling it; (4) test from inside a container and verify the port is NOT reachable from the public network; (5) prefer documented alternatives (host networking or a scoped privileged container) if you cannot safely manage sudo/systemd/UFW; and (6) ask the skill publisher to update registry metadata to explicitly list required binaries/privileges (sudo, docker, socat) so the privilege requirements are transparent. If you want higher confidence, request an explicit example unit and firewall rule for your environment and confirm there are no steps that would open services to the public internet.

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
2. Review the UFW rule — confirm it targets the correct br-<ID> interface and port
3. After setup, verify the port is NOT reachable from the public network: curl --connect-timeout 2 http://<PUBLIC_IP>:<PORT>/ must fail
4. 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

socat 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

# For a specific container
docker inspect <container_name> --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. 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, socat-bridge-ollama-11434

Review the ExecStart line before enabling — confirm it binds to the Docker bridge IP only.

sudo tee /etc/systemd/system/socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>.service > /dev/null << 'EOF'
[Unit]
Description=Socat bridge: <SOURCE_NETWORK> -> <TARGET_SERVICE>:<PORT>
After=network.target docker.service

[Service]
Type=simple
ExecStart=/usr/bin/socat TCP-LISTEN:<PORT>,bind=<GATEWAY_IP>,fork,reuseaddr TCP:127.0.0.1:<PORT>
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# Review the file before enabling:
cat /etc/systemd/system/socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>.service

sudo systemctl daemon-reload
sudo systemctl enable --now socat-<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>

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.

# Find the Linux bridge interface for the Docker network
BRIDGE_ID=$(docker network inspect <network_name> --format '{{.Id}}' | cut -c1-12)

# Verify this is the right bridge
ip link show br-${BRIDGE_ID}

# Allow traffic only on that bridge interface
sudo ufw allow in on br-${BRIDGE_ID} to any port <PORT> proto tcp comment "<SOURCE_NETWORK>-<TARGET_SERVICE>-<PORT>"

4. Verify security

# MUST succeed (from inside a container)
docker exec <container_name> curl -s --connect-timeout 5 http://<GATEWAY_IP>:<PORT>/

# MUST fail (from the public network)
curl --connect-timeout 2 http://<PUBLIC_IP>:<PORT>/

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: docker inspect <container> --format '{{json .NetworkSettings.Networks}}'

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:

sudo apt-get install -y socat  # Debian/Ubuntu
sudo dnf install -y socat      # Fedora/RHEL

References

• Blog post: The Localhost Trap — why this problem exists and why it matters for AI infrastructure
• Source: Casys-AI/casys-pml-cloud
• Docker docs: Packet filtering and firewalls