{ "schemaVersion": "1.0", "item": { "slug": "localhost-bridge", "name": "Localhost Bridge", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/superWorldSavior/localhost-bridge", "canonicalUrl": "https://clawhub.ai/superWorldSavior/localhost-bridge", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/localhost-bridge", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=localhost-bridge", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/localhost-bridge" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/localhost-bridge", "agentPageUrl": "https://openagent3.xyz/skills/localhost-bridge/agent", "manifestUrl": "https://openagent3.xyz/skills/localhost-bridge/agent.json", "briefUrl": "https://openagent3.xyz/skills/localhost-bridge/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "⚠️ Security & Privileges", "body": "This skill requires host-level privileges. It must be reviewed and executed manually by an administrator — never autonomously by an agent.\n\nWhat it does on the host:\n\nCreates a systemd service (persistent across reboots) that forwards traffic from a Docker bridge IP to localhost\nAdds a UFW firewall rule scoped to a specific Docker bridge interface\nRequires sudo, Docker daemon access, and socat from your distro's official package repository\n\nBefore running any command:\n\nReview the generated /etc/systemd/system/socat---.service file — confirm ExecStart binds only to the intended Docker bridge IP (172.x.x.1), never 0.0.0.0\nReview the UFW rule — confirm it targets the correct br- interface and port\nAfter setup, verify the port is NOT reachable from the public network: curl --connect-timeout 2 http://:/ must fail\nTest from inside a container before deploying widely\n\nDo not grant an automated agent permissions to run these commands without human approval." }, { "title": "The Problem", "body": "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." }, { "title": "The Solution", "body": "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." }, { "title": "1. Find the Docker bridge gateway IP", "body": "# For a specific container\ndocker inspect --format '{{json .NetworkSettings.Networks}}' \\\n | python3 -c \"\nimport json,sys\nd = json.load(sys.stdin)\nfor net, info in d.items():\n print(f'{net}: gateway={info[\\\"Gateway\\\"]}')\"" }, { "title": "2. Create a systemd service", "body": "Replace , , , and with your values.\n\nNaming convention: socat--- — source network is the Docker network (consumer), target service is the host service. Self-documenting.\n\nExamples: socat-bridge-gateway-18789, socat-windmill_default-gateway-18789, socat-bridge-ollama-11434\n\nReview the ExecStart line before enabling — confirm it binds to the Docker bridge IP only.\n\nsudo tee /etc/systemd/system/socat---.service > /dev/null << 'EOF'\n[Unit]\nDescription=Socat bridge: -> :\nAfter=network.target docker.service\n\n[Service]\nType=simple\nExecStart=/usr/bin/socat TCP-LISTEN:,bind=,fork,reuseaddr TCP:127.0.0.1:\nRestart=always\nRestartSec=5\n\n[Install]\nWantedBy=multi-user.target\nEOF\n\n# Review the file before enabling:\ncat /etc/systemd/system/socat---.service\n\nsudo systemctl daemon-reload\nsudo systemctl enable --now socat---" }, { "title": "3. Add firewall rule (MANDATORY)", "body": "Without this, socat listens but packets from the container are silently dropped — causing 30-second timeouts with no error.\n\nReview the bridge ID before applying — a wrong ID can expose services.\n\n# Find the Linux bridge interface for the Docker network\nBRIDGE_ID=$(docker network inspect --format '{{.Id}}' | cut -c1-12)\n\n# Verify this is the right bridge\nip link show br-${BRIDGE_ID}\n\n# Allow traffic only on that bridge interface\nsudo ufw allow in on br-${BRIDGE_ID} to any port proto tcp comment \"--\"" }, { "title": "4. Verify security", "body": "# MUST succeed (from inside a container)\ndocker exec curl -s --connect-timeout 5 http://:/\n\n# MUST fail (from the public network)\ncurl --connect-timeout 2 http://:/" }, { "title": "Multi-Network Workers", "body": "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.\n\nCheck all networks: docker inspect --format '{{json .NetworkSettings.Networks}}'" }, { "title": "Common Use Cases", "body": "Host serviceContainer clientDefault portAI gateway (OpenClaw, LiteLLM)Workflow orchestrator (Windmill, n8n)18789MCP serverDockerized agentvariesOllamaRAG pipeline, agent11434PostgreSQLAPI server5432RedisAny containerized app6379" }, { "title": "Troubleshooting", "body": "SymptomCauseFix30s timeout, no errorFirewall dropping packetsAdd UFW rule on the bridge interfaceConnection refusedsocat not runningsystemctl status socat---Works then stops after Docker restartBridge IP changedCheck new gateway IP, update socat bindsocat won't start after rebootDocker not readyEnsure After=docker.service in unit file" }, { "title": "Alternatives", "body": "Depending on your security posture, consider:\n\nDocker host networking (network_mode: host) — simpler but removes all container network isolation\nRunning socat inside a minimal privileged container — avoids host-level systemd changes\nConfiguring the host service to bind to the Docker bridge IP directly — no socat needed, but the service must support custom bind addresses\nhost.docker.internal (Docker Desktop) — works on Mac/Windows, not reliably on Linux" }, { "title": "Prerequisites", "body": "Install socat from your distro's official package repository:\n\nsudo apt-get install -y socat # Debian/Ubuntu\nsudo dnf install -y socat # Fedora/RHEL" }, { "title": "References", "body": "Blog post: The Localhost Trap — why this problem exists and why it matters for AI infrastructure\nSource: Casys-AI/casys-pml-cloud\nDocker docs: Packet filtering and firewalls" } ], "body": "localhost-bridge — Connect containers to host localhost services\n⚠️ Security & Privileges\n\nThis skill requires host-level privileges. It must be reviewed and executed manually by an administrator — never autonomously by an agent.\n\nWhat it does on the host:\n\nCreates a systemd service (persistent across reboots) that forwards traffic from a Docker bridge IP to localhost\nAdds a UFW firewall rule scoped to a specific Docker bridge interface\nRequires sudo, Docker daemon access, and socat from your distro's official package repository\n\nBefore running any command:\n\nReview the generated /etc/systemd/system/socat---.service file — confirm ExecStart binds only to the intended Docker bridge IP (172.x.x.1), never 0.0.0.0\nReview the UFW rule — confirm it targets the correct br- interface and port\nAfter setup, verify the port is NOT reachable from the public network: curl --connect-timeout 2 http://:/ must fail\nTest from inside a container before deploying widely\n\nDo not grant an automated agent permissions to run these commands without human approval.\n\nThe Problem\n\nA 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.\n\nThe Solution\n\nsocat 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.\n\nSetup (run manually as admin)\n1. Find the Docker bridge gateway IP\n# For a specific container\ndocker inspect --format '{{json .NetworkSettings.Networks}}' \\\n | python3 -c \"\nimport json,sys\nd = json.load(sys.stdin)\nfor net, info in d.items():\n print(f'{net}: gateway={info[\\\"Gateway\\\"]}')\"\n\n2. Create a systemd service\n\nReplace , , , and with your values.\n\nNaming convention: socat--- — source network is the Docker network (consumer), target service is the host service. Self-documenting.\n\nExamples: socat-bridge-gateway-18789, socat-windmill_default-gateway-18789, socat-bridge-ollama-11434\n\nReview the ExecStart line before enabling — confirm it binds to the Docker bridge IP only.\n\nsudo tee /etc/systemd/system/socat---.service > /dev/null << 'EOF'\n[Unit]\nDescription=Socat bridge: -> :\nAfter=network.target docker.service\n\n[Service]\nType=simple\nExecStart=/usr/bin/socat TCP-LISTEN:,bind=,fork,reuseaddr TCP:127.0.0.1:\nRestart=always\nRestartSec=5\n\n[Install]\nWantedBy=multi-user.target\nEOF\n\n# Review the file before enabling:\ncat /etc/systemd/system/socat---.service\n\nsudo systemctl daemon-reload\nsudo systemctl enable --now socat---\n\n3. Add firewall rule (MANDATORY)\n\nWithout this, socat listens but packets from the container are silently dropped — causing 30-second timeouts with no error.\n\nReview the bridge ID before applying — a wrong ID can expose services.\n\n# Find the Linux bridge interface for the Docker network\nBRIDGE_ID=$(docker network inspect --format '{{.Id}}' | cut -c1-12)\n\n# Verify this is the right bridge\nip link show br-${BRIDGE_ID}\n\n# Allow traffic only on that bridge interface\nsudo ufw allow in on br-${BRIDGE_ID} to any port proto tcp comment \"--\"\n\n4. Verify security\n# MUST succeed (from inside a container)\ndocker exec curl -s --connect-timeout 5 http://:/\n\n# MUST fail (from the public network)\ncurl --connect-timeout 2 http://:/\n\nMulti-Network Workers\n\nA 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.\n\nCheck all networks: docker inspect --format '{{json .NetworkSettings.Networks}}'\n\nCommon Use Cases\nHost service\tContainer client\tDefault port\nAI gateway (OpenClaw, LiteLLM)\tWorkflow orchestrator (Windmill, n8n)\t18789\nMCP server\tDockerized agent\tvaries\nOllama\tRAG pipeline, agent\t11434\nPostgreSQL\tAPI server\t5432\nRedis\tAny containerized app\t6379\nTroubleshooting\nSymptom\tCause\tFix\n30s timeout, no error\tFirewall dropping packets\tAdd UFW rule on the bridge interface\nConnection refused\tsocat not running\tsystemctl status socat---\nWorks then stops after Docker restart\tBridge IP changed\tCheck new gateway IP, update socat bind\nsocat won't start after reboot\tDocker not ready\tEnsure After=docker.service in unit file\nAlternatives\n\nDepending on your security posture, consider:\n\nDocker host networking (network_mode: host) — simpler but removes all container network isolation\nRunning socat inside a minimal privileged container — avoids host-level systemd changes\nConfiguring the host service to bind to the Docker bridge IP directly — no socat needed, but the service must support custom bind addresses\nhost.docker.internal (Docker Desktop) — works on Mac/Windows, not reliably on Linux\nPrerequisites\n\nInstall socat from your distro's official package repository:\n\nsudo apt-get install -y socat # Debian/Ubuntu\nsudo dnf install -y socat # Fedora/RHEL\n\nReferences\nBlog post: The Localhost Trap — why this problem exists and why it matters for AI infrastructure\nSource: Casys-AI/casys-pml-cloud\nDocker docs: Packet filtering and firewalls" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/superWorldSavior/localhost-bridge", "publisherUrl": "https://clawhub.ai/superWorldSavior/localhost-bridge", "owner": "superWorldSavior", "version": "2.0.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/localhost-bridge", "downloadUrl": "https://openagent3.xyz/downloads/localhost-bridge", "agentUrl": "https://openagent3.xyz/skills/localhost-bridge/agent", "manifestUrl": "https://openagent3.xyz/skills/localhost-bridge/agent.json", "briefUrl": "https://openagent3.xyz/skills/localhost-bridge/agent.md" } }