plano/skills/rules/deploy-docker.md

title	impact	impactDescription	tags
Understand Plano's Docker Network Topology for Agent URL Configuration	HIGH	Using `localhost` for agent URLs inside Docker always fails — Plano runs in a container and cannot reach host services via localhost	deployment, docker, networking, agents, urls

Understand Plano's Docker Network Topology for Agent URL Configuration

Plano runs inside a Docker container managed by planoai up. Services running on your host machine (agent servers, filter servers, databases) are not accessible as localhost from inside the container. Use Docker's special hostname host.docker.internal to reach host services.

Docker network rules:

• localhost / 127.0.0.1 inside the container → Plano's own container (not your host)
• host.docker.internal → Your host machine's loopback interface
• Container name or docker network hostname → Other Docker containers
• External domain / IP → Reachable if Docker has network access

Incorrect (using localhost — agent unreachable from inside container):

version: v0.3.0

agents:
  - id: weather_agent
    url: http://localhost:8001       # Wrong: this is Plano's own container

  - id: flight_agent
    url: http://127.0.0.1:8002      # Wrong: same issue

filters:
  - id: input_guards
    url: http://localhost:10500      # Wrong: filter server unreachable

Correct (using host.docker.internal for host-side services):

version: v0.3.0

agents:
  - id: weather_agent
    url: http://host.docker.internal:8001    # Correct: reaches host port 8001

  - id: flight_agent
    url: http://host.docker.internal:8002    # Correct: reaches host port 8002

filters:
  - id: input_guards
    url: http://host.docker.internal:10500   # Correct: reaches filter server on host

endpoints:
  internal_api:
    endpoint: host.docker.internal            # Correct for internal API on host
    protocol: http

Production deployment patterns:

# Kubernetes / Docker Compose — use service names
agents:
  - id: weather_agent
    url: http://weather-service:8001    # Kubernetes service DNS

# External cloud services — use full domain
agents:
  - id: cloud_agent
    url: https://my-agent.us-east-1.amazonaws.com/v1

# Custom TLS (self-signed or internal CA)
overrides:
  upstream_tls_ca_path: /etc/ssl/certs/internal-ca.pem

Ports exposed by Plano's container:

• All port values from your listeners blocks are automatically mapped
• 9901 — Envoy admin interface (for advanced debugging)
• 12001 — Plano internal management API

Reference: https://github.com/katanemo/archgw