diff --git a/.env.example b/.env.example
index b29a06d..4c8b626 100644
--- a/.env.example
+++ b/.env.example
@@ -8,3 +8,6 @@ BRAVE_API_KEY=
 # add-project.sh sets this automatically (default: $HOME/src); projects
 # outside this directory need an extra volume mount (see README).
 # PROJECTS_ROOT=/home/you/src
+
+# Only needed on hosts where the default docker bridge has no internet access:
+# BUILD_NETWORK=host
diff --git a/AGENTS.md b/AGENTS.md
index 565e5ab..b8121c0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -40,9 +40,11 @@ Global client configs only carry the shared tools (fetch/context7/brave-search).
 
 ## Gotchas
 
-- **Host docker networking is partly broken**: the default docker0 bridge has NO egress
-  (DNS/TCP fail); custom compose networks work fine. That is why builds use
-  `network: host` in the compose file — keep it.
+- **Host docker networking**: the Arch host's default docker0 bridge has NO egress
+  (DNS/TCP fail), so there `BUILD_NETWORK=host` is set in `.env`. On hosts with a
+  working bridge leave it unset — newer compose delegates builds to buildx bake, which
+  rejects `network: host` ("Pass --allow=network.host...") and compose cannot grant
+  the entitlement.
 - `opencode mcp list` can print "No MCP servers configured" for a few seconds after
   `opencode reload` (daemon reconnects asynchronously). Retry before assuming breakage.
 - After changing client configs, crush/opencode sessions must be restarted/reloaded;
diff --git a/README.md b/README.md
index baa96a8..8640358 100644
--- a/README.md
+++ b/README.md
@@ -256,9 +256,12 @@ docker compose ps                    # both services "Up"
 
   then run `docker compose up -d mcp-codebase-index` and register the project with
   `./add-project.sh /opt/code/whatever`.
-- **Docker build fails with `Temporary failure resolving ...`** — on this host the default
-  docker bridge has no internet access; builds already run with `network: host` in the
-  compose file. If it still fails, check your firewall.
+- **Docker build fails with `Temporary failure resolving ...`** — the default docker
+  bridge has no internet access on that host. Add `BUILD_NETWORK=host` to `.env` and
+  rebuild. Note that recent `docker compose` versions delegate builds to buildx bake,
+  which refuses `network: host` builds with "Pass `--allow=network.host`..." unless the
+  host really needs it — on machines with working bridge networking leave `BUILD_NETWORK`
+  unset (or set it to `default`). If it still fails, check your firewall.
 - **`brave-search` tools fail** — missing/invalid `BRAVE_API_KEY` in `.env`.
 - **Index seems stale** — re-run the project's index:
   `./add-project.sh ~/src/git/my-project` (safe to repeat), or ask the AI to run
diff --git a/docker-compose.yml b/docker-compose.yml
index 1f8256d..6339b80 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -10,7 +10,11 @@ services:
   mcp:
     build:
       context: .
-      network: host
+      # BUILD_NETWORK=host in .env for hosts where the default docker bridge has
+      # no egress (see README troubleshooting). Default (bridge) works everywhere
+      # else; buildx refuses `network: host` builds unless the network.host
+      # entitlement is granted, which `docker compose build` cannot pass.
+      network: ${BUILD_NETWORK:-default}
     image: chodak166/mcp-supergateway:latest
     container_name: mcp-gateway
     ports:
@@ -37,7 +41,11 @@ services:
   mcp-codebase-index:
     build:
       context: .
-      network: host
+      # BUILD_NETWORK=host in .env for hosts where the default docker bridge has
+      # no egress (see README troubleshooting). Default (bridge) works everywhere
+      # else; buildx refuses `network: host` builds unless the network.host
+      # entitlement is granted, which `docker compose build` cannot pass.
+      network: ${BUILD_NETWORK:-default}
     image: chodak166/mcp-supergateway:latest
     container_name: mcp-codebase-index
     # Run as the image's `node` user (uid 1000) so index data written into the