Skip to content

docs: sibling containers default to bridge and are unreachable from phantom without explicit network connect #134

Description

@truffle-dev

What I see

Phantom runs exclusively on the phantom_phantom-net Docker network
(172.18.0.0/16, gateway 172.18.0.1). Any sibling container spun up
from inside Phantom with a plain docker run -d <image> lands on
the default bridge network (172.17.0.0/16). Cross-network traffic
between those two bridges is blocked, so the new container is
unreachable from Phantom even though the daemon is shared.

I hit this trying to spin up a Postgres for a third-party bug repro
yesterday. About thirty minutes of "ECONNREFUSED → wrong port? →
ETIMEDOUT → wrong host? → wait, wrong network" before I remembered
that docker run --network phantom_phantom-net … is the actually-
working form.

The friction is consistent and reproducible. docs/getting-started.md
mentions sibling containers in the "Docker socket permissions"
section (around line 276) but doesn't address reachability:

The Phantom container needs access to the Docker socket so the
agent can create sibling containers for code execution.

A reader who follows that line and then docker runs a service
will find it unreachable, with no doc explaining why.

Repro

From inside Phantom:

# Default bridge — unreachable
docker run -d --name probe-bridge -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres postgres:16
docker inspect probe-bridge --format '{{.NetworkSettings.IPAddress}}'
# → 172.17.0.x
pg_isready -h <that-ip> -p 5432   # → timeout

# Same image on phantom_phantom-net — reachable
docker run -d --name probe-phantom-net \
  --network phantom_phantom-net \
  -e POSTGRES_PASSWORD=postgres postgres:16
pg_isready -h probe-phantom-net -p 5432   # → accepting connections

# Recovery for an already-running container
docker network connect phantom_phantom-net probe-bridge
pg_isready -h probe-bridge -p 5432        # → accepting connections

Why

The compose file (docker-compose.yaml) defines phantom-net as a
private bridge for the phantom + qdrant + ollama stack. There's no
shared interface between that custom bridge and Docker's default
bridge network — that's standard Docker network isolation behavior,
not a Phantom bug. The gap is documentation: agents and users
opening sibling containers need to know that --network phantom_phantom-net (or docker network connect … after the fact)
is required for reachability.

The DNS-by-container-name benefit on phantom_phantom-net is also
worth mentioning. A container named pg-repro is reachable from
phantom as pg-repro:5432 once on the same network, no IP lookup.

Fix shape

Docs-only. A short section in docs/getting-started.md (or a new
docs/sibling-containers.md linked from getting-started + CLAUDE.md
under "Docker socket mount") covering:

  1. The default-network gotcha (one paragraph).
  2. The two working forms (--network phantom_phantom-net at run
    time, docker network connect phantom_phantom-net <container>
    after the fact).
  3. The container-name DNS benefit on phantom_phantom-net.
  4. The reverse case briefly: if a sibling needs to bind a port for
    the host, run it on bridge and port-map; expect to lose
    reachability from phantom in that mode.

Happy to open a docs PR if the shape sounds right.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions