diff --git a/packages/_example/package.json b/packages/_example/package.json
index f13c73d853..33af906b2c 100644
--- a/packages/_example/package.json
+++ b/packages/_example/package.json
@@ -51,7 +51,8 @@
     "db:executor:up": "cd ../workflow-executor/example && docker compose up -d",
     "db:executor:down": "cd ../workflow-executor/example && docker compose down",
     "db:executor:reset": "cd ../workflow-executor/example && docker compose down -v && docker compose up -d",
-    "executor:docker": "docker compose --env-file ../workflow-executor/example/.env.executors -f ../workflow-executor/example/docker-compose.executors.yml up"
+    "start:with-executor:multiple-instance": "concurrently --kill-others --names 'agent,executors' \"yarn start\" \"bash scripts/start-docker-executors.sh executors\"",
+    "start:with-executor:multiple-instance:build": "concurrently --kill-others --names 'agent,executors' \"yarn start\" \"bash scripts/start-docker-executors.sh executors:build\""
   },
   "devDependencies": {
     "@types/node": "^20.12.12",
diff --git a/packages/_example/scripts/start-docker-executors.sh b/packages/_example/scripts/start-docker-executors.sh
new file mode 100644
index 0000000000..22af3d53e4
--- /dev/null
+++ b/packages/_example/scripts/start-docker-executors.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Starts the multi-instance docker executors (nginx gateway on :3400), configured ENTIRELY from
+# packages/_example/.env. Invoked by the start:with-executor:multiple-instance[:build] scripts.
+#
+# The executor example's own `executors` script stays config-agnostic (pure `docker compose up`):
+# this wrapper sources _example/.env, translates host-local URLs so the containers can reach the
+# host, waits for the agent, then delegates. Run standalone from the executor example dir to use
+# that package's own .env instead.
+set -euo pipefail
+set -a
+# shellcheck disable=SC1091
+source .env
+
+# localhost / 127.0.0.1 -> host.docker.internal (containers reach services on the host).
+to_host() {
+  local v="${1/localhost/host.docker.internal}"
+  echo "${v/127.0.0.1/host.docker.internal}"
+}
+
+AGENT_URL="$(to_host "$EXECUTOR_AGENT_URL")"
+DATABASE_URL="$(to_host "$EXECUTOR_DATABASE_URL")"
+FOREST_SERVER_URL="$(to_host "${FOREST_SERVER_URL:-}")"
+
+# Executors probe AGENT_URL on startup — wait for the host agent first (avoids restart noise).
+until curl -s "$EXECUTOR_AGENT_URL" >/dev/null 2>&1; do sleep 1; done
+
+# Exported vars above are inherited by docker compose interpolation in the example package.
+yarn workspace workflow-executor-example "${1:-executors}"
diff --git a/packages/workflow-executor/example/docker-compose.executors.yml b/packages/workflow-executor/example/docker-compose.executors.yml
index 7df7b7f339..4a61ff6764 100644
--- a/packages/workflow-executor/example/docker-compose.executors.yml
+++ b/packages/workflow-executor/example/docker-compose.executors.yml
@@ -2,14 +2,17 @@
 # single Postgres run store (so the write-ahead idempotency log is shared across
 # instances). The store is YOUR existing local Postgres, reached via DATABASE_URL.
 #
-#   cp .env.executors.example .env.executors   # fill in secrets + DATABASE_URL
-#   docker compose --env-file .env.executors -f docker-compose.executors.yml up --build
+# Config comes entirely from packages/_example/.env — there is nothing to edit here.
+# Run it via the example package script, which sources that .env, remaps
+# EXECUTOR_AGENT_URL/EXECUTOR_DATABASE_URL -> AGENT_URL/DATABASE_URL and rewrites
+# localhost -> host.docker.internal so the containers can reach your host:
+#
+#   yarn workspace workflow-executor-example executors[:build]
+#   # or, with the agent, from packages/_example:
+#   yarn start:with-executor:multiple-instance[:build]
 #
 # Point your agent at the gateway: workflowExecutorUrl: "http://localhost:3400".
 # Your agent must be running on the host (executors probe AGENT_URL on startup).
-#
-# DATABASE_URL must use host.docker.internal (NOT localhost) to reach a Postgres
-# running on your host, e.g. postgres://user:pass@host.docker.internal:5432/db
 
 name: workflow-executor-gateway
 
@@ -28,12 +31,20 @@ x-executor-common: &executor-common
   restart: unless-stopped
   extra_hosts:
     - "host.docker.internal:host-gateway"
+    # Forest local-dev domains resolve to 127.0.0.1 via the host's /etc/hosts (the orchestrator
+    # runs on the host). Inside containers 127.0.0.1 is the container itself, so map them to the
+    # host. Inert for non-dev setups (prod api.forestadmin.com is unaffected).
+    - "api.development.forestadmin.com:host-gateway"
+    - "app.development.forestadmin.com:host-gateway"
+    - "static.development.forestadmin.com:host-gateway"
 
 services:
   executor-1:
     <<: *executor-common
     build:
-      context: ../..
+      # Repo root (relative to this compose file): the Dockerfile does `COPY . .` over the
+      # whole monorepo, so the build context must be the root, not packages/.
+      context: ../../..
       dockerfile: packages/workflow-executor/Dockerfile
     environment: *executor-env
 
diff --git a/packages/workflow-executor/example/package.json b/packages/workflow-executor/example/package.json
index 78118aa86a..47ea0a0ac2 100644
--- a/packages/workflow-executor/example/package.json
+++ b/packages/workflow-executor/example/package.json
@@ -10,7 +10,9 @@
     "db:up": "docker compose up -d",
     "db:down": "docker compose down",
     "db:reset": "docker compose down -v && docker compose up -d",
-    "db:psql": "docker compose exec postgres psql -U executor -d workflow_executor"
+    "db:psql": "docker compose exec postgres psql -U executor -d workflow_executor",
+    "executors": "docker compose -f docker-compose.executors.yml up",
+    "executors:build": "docker compose -f docker-compose.executors.yml up --build"
   },
   "dependencies": {
     "@forestadmin/workflow-executor": "*"