mirror of
https://github.com/katanemo/plano.git
synced 2026-04-26 01:06:25 +02:00
743d074184
Some checks are pending
CI / pre-commit (push) Waiting to run
CI / plano-tools-tests (push) Waiting to run
CI / native-smoke-test (push) Waiting to run
CI / docker-build (push) Waiting to run
CI / validate-config (push) Waiting to run
CI / security-scan (push) Blocked by required conditions
CI / test-prompt-gateway (push) Blocked by required conditions
CI / test-model-alias-routing (push) Blocked by required conditions
CI / test-responses-api-with-state (push) Blocked by required conditions
CI / e2e-plano-tests (3.10) (push) Blocked by required conditions
CI / e2e-plano-tests (3.11) (push) Blocked by required conditions
CI / e2e-plano-tests (3.12) (push) Blocked by required conditions
CI / e2e-plano-tests (3.13) (push) Blocked by required conditions
CI / e2e-plano-tests (3.14) (push) Blocked by required conditions
CI / e2e-demo-preference (push) Blocked by required conditions
CI / e2e-demo-currency (push) Blocked by required conditions
Publish docker image (latest) / build-arm64 (push) Waiting to run
Publish docker image (latest) / build-amd64 (push) Waiting to run
Publish docker image (latest) / create-manifest (push) Blocked by required conditions
Build and Deploy Documentation / build (push) Waiting to run
* feat: add initial documentation for Plano Agent Skills * feat: readme with examples * feat: add detailed skills documentation and examples for Plano --------- Co-authored-by: Adil Hafeez <adil.hafeez@gmail.com>
80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
---
|
|
title: Understand Plano's Docker Network Topology for Agent URL Configuration
|
|
impact: HIGH
|
|
impactDescription: Using `localhost` for agent URLs inside Docker always fails — Plano runs in a container and cannot reach host services via localhost
|
|
tags: 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):**
|
|
|
|
```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
|