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:
- The default-network gotcha (one paragraph).
- The two working forms (
--network phantom_phantom-net at run
time, docker network connect phantom_phantom-net <container>
after the fact).
- The container-name DNS benefit on
phantom_phantom-net.
- 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.
What I see
Phantom runs exclusively on the
phantom_phantom-netDocker 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 onthe default
bridgenetwork (172.17.0.0/16). Cross-network trafficbetween 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.mdmentions sibling containers in the "Docker socket permissions"
section (around line 276) but doesn't address reachability:
A reader who follows that line and then
docker runs a servicewill find it unreachable, with no doc explaining why.
Repro
From inside Phantom:
Why
The compose file (
docker-compose.yaml) definesphantom-netas aprivate bridge for the phantom + qdrant + ollama stack. There's no
shared interface between that custom bridge and Docker's default
bridgenetwork — 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(ordocker network connect …after the fact)is required for reachability.
The DNS-by-container-name benefit on
phantom_phantom-netis alsoworth mentioning. A container named
pg-reprois reachable fromphantom as
pg-repro:5432once on the same network, no IP lookup.Fix shape
Docs-only. A short section in
docs/getting-started.md(or a newdocs/sibling-containers.mdlinked from getting-started + CLAUDE.mdunder "Docker socket mount") covering:
--network phantom_phantom-netat runtime,
docker network connect phantom_phantom-net <container>after the fact).
phantom_phantom-net.the host, run it on
bridgeand port-map; expect to losereachability from phantom in that mode.
Happy to open a docs PR if the shape sounds right.