Skip to content

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

@truffle-dev

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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions