feat(dev): add docker-free local mode (./dev.sh local)

Stand up the full backend as host processes with embedded datastores — no
Docker daemon required — as a lighter alternative to the container stack.

`./dev.sh local` (also `make dev-local` / `python -m scripts.dev_local`) provisions:
- Postgres via bundled pgserver (unix socket) and Redis via bundled redislite
- a Temporal dev server + UI and the agentex worker (--no-temporal to skip)
- a local mongod, required for the full stack (--no-mongo / --lean to skip)
- an optional OpenTelemetry collector (--no-otel to skip)
then runs migrations, supervises uvicorn + the worker, and tears everything down
cleanly on SIGINT/SIGTERM. --lean is a minimal Postgres+Redis+API stack; --ephemeral
uses a throwaway data dir. The runner is a small scripts/dev_local package
(config / services / supervise / runner) so the pure config/env layer stays testable.

App-side changes to make the no-Docker path robust (all no-ops when Mongo is
configured, as it always is in Docker/prod):
- The Temporal worker no longer crashes when MongoDB is unavailable — the Mongo CRUD
  adapter tolerates an unset database and errors only on real use, so the worker
  degrades like the API instead of taking down the stack.
- Skip the Mongo connection entirely when MONGODB_URI is unset, removing a ~20s
  startup hang against the implicit localhost:27017 default.
- In local mode the backend rewrites agents' host.docker.internal ACP host to loopback
  (AGENTEX_ACP_HOST_OVERRIDE), so default-scaffolded agents work without manifest edits.

Also fix a frontend dev-server process leak in dev.sh (kill the whole make→npm→next
tree and sweep orphans; report status by listening port), correct the MongoDB and
OpenTelemetry install commands, and document local mode in README and CLAUDE.md.

Author: aringuyen3

.gitignore

@@ -43,6 +43,9 @@ tmp
 # Dev script logs
 .dev-logs/
 
+# Local (no-Docker) dev datastore data
+agentex/.dev-local/
+
 ### PYTHON
 
 # Byte-compiled / optimized / DLL files

CLAUDE.md

@@ -55,6 +55,26 @@ Other commands:
 ./dev.sh restart            # Restart all services
 ```
 
+Docker-free local mode (host processes + embedded datastores, no Docker):
+```bash
+./dev.sh local              # whole stack without Docker (or: make dev-local)
+./dev.sh local --lean       # Postgres + Redis + API only
+./dev.sh local --no-mongo   # run without MongoDB
+```
+
+> **MongoDB is required for the full local stack** — the Temporal worker builds
+> Mongo-backed repositories at startup, so a missing/unreachable Mongo makes the
+> runner fail fast (with an install message) rather than crash the worker. `./dev.sh
+> local` auto-installs `mongod`; `make dev-local` / direct `python -m scripts.dev_local`
+> do not, so install `mongod` yourself or pass `--no-mongo`/`--lean` there. In local
+> mode the Temporal UI is on :8233 (Docker mode uses :8080).
+>
+> Agents register their ACP URL as `host.docker.internal` (for a Docker backend), which
+> a host-process backend can't resolve. Local mode sets `AGENTEX_ACP_HOST_OVERRIDE=127.0.0.1`
+> and the backend rewrites `host.docker.internal` → that value when dialing agents
+> (`src/utils/acp_url.py`, applied in the ACP request path + Temporal healthcheck), so
+> default-scaffolded agents work without manifest edits.
+
 **Then in a separate terminal - Agent Development:**
 ```bash
 agentex init                # Create a new agent

README.md

@@ -105,37 +105,72 @@ To do this, you just need to spin up the [Agentex Server](https://github.com/sca
 
 ### Quick Start (Recommended)
 
-Just run one command:
+Just run one command — no Docker required:
 
 ```bash
-./dev.sh
+./dev.sh local
 ```
 
 That's it. This will automatically:
 - Install Homebrew, uv, Node.js, and agentex-sdk if missing (macOS)
 - Install all backend and frontend dependencies
-- Start all Docker services (Postgres, Redis, MongoDB, Temporal)
-- Start the backend API and frontend dev server
+- Start the backend API and frontend dev server as host processes
+- Provision embedded datastores — bundled Postgres + Redis, an auto-downloaded Temporal
+  dev server, a local MongoDB, and an optional OTel collector
 - Wait for everything to be healthy
 
-> **Note:** Make sure Docker Desktop or Rancher Desktop is running before you start.
+> Prefer containers? `./dev.sh` runs the same stack with Docker instead (needs Docker
+> Desktop or Rancher Desktop) — see [Other commands](#other-commands) below. See
+> [Docker-free local mode](#docker-free-local-mode) for `local` flags and details.
 
 Once ready:
 | Service | URL |
 |---------|-----|
 | Frontend UI | http://localhost:3000 |
 | Backend API | http://localhost:5003 |
 | Swagger Docs | http://localhost:5003/swagger |
-| Temporal UI | http://localhost:8080 |
+| Temporal UI | http://localhost:8233 |
 
-**Other commands:**
+> With `./dev.sh` (Docker) the Temporal UI is on http://localhost:8080 instead.
+
+#### Other commands
 ```bash
+./dev.sh           # Start everything with Docker instead (containers; needs Docker Desktop/Rancher)
 ./dev.sh stop      # Stop all services
 ./dev.sh status    # Check service status
 ./dev.sh logs      # View all logs
 ./dev.sh restart   # Restart all services
 ```
 
+#### Docker-free local mode
+
+`./dev.sh local` accepts flags to trim the stack:
+
+```bash
+./dev.sh local                # whole stack, no Docker
+./dev.sh local --lean         # Postgres + Redis + API only (no Temporal/Mongo/OTel)
+./dev.sh local --no-mongo     # run without MongoDB
+./dev.sh local --no-temporal  # skip Temporal + the worker
+```
+
+> **MongoDB is required for the full local stack.** The Temporal worker needs it, so
+> `./dev.sh local` auto-installs `mongod` (via Homebrew) and startup **fails fast**
+> with an install message if it can't be made available. To run without it, use
+> `--no-mongo` (or `--lean`) — message persistence is then off and `/readyz` reports
+> Mongo down, but nothing crashes. The OTel collector is optional; if it's absent the
+> runner continues without telemetry. In local mode the Temporal UI is at
+> http://localhost:8233 (not :8080). Same `stop` / `status` / `logs` / `restart`
+> commands apply.
+
+**Connecting agents in local mode.** Agents scaffolded by `agentex init` register their
+ACP URL as `http://host.docker.internal:<port>` (so a *Docker* backend can reach an
+agent on the host). A host-process backend can't resolve that name, so local mode sets
+`AGENTEX_ACP_HOST_OVERRIDE=127.0.0.1` and the backend automatically rewrites
+`host.docker.internal` → `127.0.0.1` when dialing agents (and their healthchecks). So a
+default-scaffolded agent works with `./dev.sh local` **without editing its manifest**.
+(You can still set `local_development.agent.host_address: localhost` in the manifest if
+you prefer; both work.)
+
 Then skip ahead to [Create Your First Agent](#create-your-first-agent).
 
 ---

agentex/Makefile

@@ -41,9 +41,18 @@ dev: install-dev ## Start development server with Docker Compose
 	@echo "🚀 Starting development server with Docker Compose..."
 	docker compose up --build
 
+dev-local: install-dev ## Start development server locally (no Docker)
+	@echo "🚀 Starting development server locally without Docker..."
+	@echo "ℹ️  MongoDB is REQUIRED for the full stack. If 'mongod' is not on your PATH,"
+	@echo "   install it (brew tap mongodb/brew && brew install mongodb-community) or run"
+	@echo "   with ARGS=\"--no-mongo\". (Unlike './dev.sh local', make does not auto-install it.)"
+	uv sync --group dev --group dev-local
+	uv run python -m scripts.dev_local $(ARGS)
+
 dev-stop: ## Stop development server
 	@echo "Stopping dev server"
 	docker compose down
+# 	TODO: Add support for stopping local dev server
 
 dev-wipe: ## Stop dev server and wipe DB
 	@echo "Stopping dev server and wiping DB"

agentex/pyproject.toml

@@ -43,6 +43,14 @@ dev = [
     "vulture>=2.14",
     "ruff>=0.3.4",
 ]
+dev-local = [
+    "pgserver>=0.1.4",
+    "redislite>=6.2.912183",
+    # SQLAlchemy's async engine needs greenlet at runtime. SQLAlchemy auto-installs
+    # it on linux x86_64 (docker/prod) but NOT on macOS arm64, so the local runner
+    # must pull it explicitly or /readyz and engine teardown fail.
+    "greenlet>=3.2.3",
+]
 test = [
     "pytest>=8.3.3,<9",
     "pytest-asyncio>=1.0.0,<2",
@@ -52,6 +60,9 @@ test = [
     "factory-boy>=3.3.0,<4", # for test data factories
     "greenlet>=3.2.3",
     "asyncpg>=0.29.0",
+    # Embedded datastores for dev_local.py tests (no testcontainers/docker needed)
+    "pgserver>=0.1.4",
+    "redislite>=6.2.912183",
 ]
 
 [tool.hatch.build.targets.sdist]

agentex/scripts/dev_local/__init__.py

@@ -0,0 +1,49 @@
+"""Run the agentex backend locally as host processes, with no Docker.
+
+The engine behind `./dev.sh local` / `make dev-local`: it provisions embedded datastores,
+runs migrations, and supervises uvicorn (plus a Temporal worker), tearing everything down
+on Ctrl-C / SIGTERM. Postgres/Redis/Temporal need no system install (bundled /
+auto-downloaded). MongoDB is REQUIRED for the full stack — the Temporal worker builds
+Mongo-backed repositories at boot, so a missing/unreachable mongod fails fast instead of
+crashing the worker. The OTel collector is optional. Use --no-mongo (or --lean, which also
+turns off temporal/otel) to run without MongoDB.
+
+Modules: `config` (pure, unit-testable), `services` (provisioning), `supervise`
+(subprocess plumbing), `runner` (orchestration).
+"""
+
+from scripts.dev_local.config import (
+    LOOPBACK,
+    DevLocalConfig,
+    build_arg_parser,
+    build_env,
+    resolve_config,
+)
+from scripts.dev_local.runner import main, run
+from scripts.dev_local.services import (
+    provision_mongo,
+    provision_otel,
+    provision_postgres,
+    provision_redis,
+    provision_temporal,
+    teardown_redis,
+)
+from scripts.dev_local.supervise import run_migrations, wait_for_health
+
+__all__ = [
+    "LOOPBACK",
+    "DevLocalConfig",
+    "build_arg_parser",
+    "resolve_config",
+    "build_env",
+    "provision_postgres",
+    "provision_redis",
+    "provision_temporal",
+    "provision_mongo",
+    "provision_otel",
+    "teardown_redis",
+    "run_migrations",
+    "wait_for_health",
+    "run",
+    "main",
+]

agentex/scripts/dev_local/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point: `python -m scripts.dev_local` (used by `./dev.sh local` / `make dev-local`)."""
+
+from scripts.dev_local.runner import main
+
+if __name__ == "__main__":
+    main()