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):

yaml

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):

yaml

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:

yaml

# 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