feat(dev): run agentex locally without Docker by aringuyen3 · Pull Request #353 · scaleapi/scale-agentex

aringuyen3 · 2026-07-09T14:48:57Z

What

Adds a docker-free local mode that runs the full agentex backend as host processes
with embedded datastores — a lighter alternative to the Docker Compose stack, closer
to a one-command langgraph dev-style workflow.

./dev.sh local                    # whole stack, no Docker
./dev.sh local --lean             # Postgres + Redis + API + MongoDB only (no Temporal/OTel)
./dev.sh local --no-temporal      # skip Temporal + the worker
./dev.sh local --mongo-uri <uri>  # use an external MongoDB instead of a local mongod

Also available as make dev-local and python -m scripts.dev_local.

Why

Standing up a local environment previously required the full Docker stack. This lets a
developer run the backend with a single command and no Docker daemon:

Postgres via bundled pgserver (unix socket) and Redis via bundled redislite
a Temporal dev server + Web UI and the agentex worker
a local mongod — always started; the stack requires it (the Temporal worker builds
Mongo-backed repositories at boot)
an optional OpenTelemetry collector

It runs migrations, supervises uvicorn + the worker, and tears everything down cleanly
on Ctrl-C / SIGTERM. --ephemeral uses a throwaway data dir; --mongo-uri points at an
existing MongoDB instead of launching a local mongod.

App-side change

Safe no-op wherever the backend runs in Docker / staging / prod (the env var it keys on
is unset there):

ACP host rewrite for local mode. Agents register their ACP URL at
host.docker.internal (the SDK default, so a Docker backend can reach an agent on
the host), which a host-process backend can't resolve. The runner sets
AGENTEX_ACP_HOST_OVERRIDE=127.0.0.1 and the backend rewrites only that sentinel host
to the override when dialing agents — in the ACP request path, the agent-API-key proxy
path, and the Temporal healthcheck. When the env var is unset, the stored URL is used
verbatim. 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 (brew trust first) and OpenTelemetry (release binary; not in
Homebrew) install commands.
Add a dev-local uv dependency group (pgserver, redislite, greenlet) pulled only
for local mode.
Document local mode in README.md and CLAUDE.md.

Contract note

The runner is a package (scripts/dev_local/), so the direct invocation is
python -m scripts.dev_local (not python scripts/dev_local.py). ./dev.sh local and
make dev-local are unchanged for callers.

Testing

Manually exercised on macOS (Docker stopped):

Full stack and --lean — the API passes /healthz within ~1s and /readyz reports
Postgres, Redis, and MongoDB all healthy; the Temporal worker stays up; teardown frees
all ports with no orphaned processes.
Fail-fast path: full mode with mongod absent aborts with an actionable install message
(or point at an external instance with --mongo-uri).
Booted end-to-end via python -m scripts.dev_local; agents scaffolded by agentex init
connect without manifest edits (ACP host rewrite).
TODO: test on Windows environment

greptile-apps · 2026-07-09T15:03:09Z

+        if raw is None and agent.production_deployment_id:
            deployment = await self.deployment_repo.get(
                id=agent.production_deployment_id
            )
-            if deployment.acp_url:
-                return deployment.acp_url
+            raw = deployment.acp_url
+
+        # Legacy fallback to the agent's own URL.
+        if raw is None:
+            raw = agent.acp_url

-        # Legacy fallback
-        if agent.acp_url:
-            return agent.acp_url
+        if raw is None:
+            raise ClientError(f"Agent {agent.id} does not have an ACP URL configured")

-        raise ClientError(f"Agent {agent.id} does not have an ACP URL configured")
+        return resolve_acp_url(raw)


Empty-string deployment.acp_url bypasses the agent.acp_url fallback

The old code guarded with if deployment.acp_url: (truthy), so a deployment whose acp_url column was persisted as "" would be skipped and the code would fall through to the agent's own URL. The new code only checks is None, so an empty string from the deployment is assigned to raw, and resolve_acp_url("") returns "" (the function short-circuits on not url). The result is the caller receives "" and the subsequent HTTP dial fails instead of gracefully falling back to agent.acp_url. If any existing deployment rows have an empty-string rather than NULL acp_url, this is a live regression.

Prompt To Fix With AI

This is a comment left during a code review. Path: agentex/src/domain/use_cases/agents_acp_use_case.py Line: 336-349 Comment: **Empty-string `deployment.acp_url` bypasses the `agent.acp_url` fallback** The old code guarded with `if deployment.acp_url:` (truthy), so a deployment whose `acp_url` column was persisted as `""` would be skipped and the code would fall through to the agent's own URL. The new code only checks `is None`, so an empty string from the deployment is assigned to `raw`, and `resolve_acp_url("")` returns `""` (the function short-circuits on `not url`). The result is the caller receives `""` and the subsequent HTTP dial fails instead of gracefully falling back to `agent.acp_url`. If any existing deployment rows have an empty-string rather than NULL `acp_url`, this is a live regression. How can I resolve this? If you propose a fix, please make it concise.

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.

danielmillerp · 2026-07-13T17:14:02Z

+        raw = acp_url_override
+
+        # Prefer the production deployment's URL when there's no explicit override.
+        if raw is None and agent.production_deployment_id:


@smoreinis can you take a look here just make sure it doesn't conflict with the preview workflow?

danielmillerp · 2026-07-13T17:17:34Z

        """
+        # In docker-free local mode, rewrite host.docker.internal -> the host-reachable
+        # override so the healthcheck matches how the request path dials the agent.
+        acp_url = resolve_acp_url(acp_url)


just making sure, no other places we need to do conversion right?

danielmillerp · 2026-07-13T17:18:32Z

-        if acp_url_override:
-            return acp_url_override
+        """Resolve the ACP URL for an agent, optionally overriding with a specific URL.



did we lose the override?

danielmillerp · 2026-07-13T17:19:03Z

+    Returns the URL unchanged when the override env var is unset or the URL does
+    not use the Docker sentinel host, so it is safe to call on every ACP dial.
+    """
+    override = os.environ.get(_ACP_HOST_OVERRIDE_ENV)


is this where the override moved?

danielmillerp · 2026-07-13T17:22:36Z

 # Development Server
 #

 dev: install-dev ## Start development server with Docker Compose


these are both technically local maybe rename to something more meaningful?

danielmillerp · 2026-07-13T17:22:52Z

+
+> **MongoDB is required for the full local stack** and is always started — 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.


ty for adding here

danielmillerp

lots of small questions! also as far as testing on PC, not super sure. A lot of our clients do use PCs and I know there are Scaliens who have PCs. What problems do you anticipate?

levilentz

Overall this is rad.

One UX suggestion: in addition dev.sh, I think this would be really nice to have in the agentex CLI. I.E. you can run a single agent inline. therefore to start running a single agent you can start quick rather than having both the agentex backend and cli running. then this setup would be suitable for someone testing a multiagent flow.

Not sure if that is possible given the abstraction and integration, but wanted to throw it out there as a north star.

danielmillerp · 2026-07-15T18:54:09Z

Overall this is rad.

One UX suggestion: in addition dev.sh, I think this would be really nice to have in the agentex CLI. I.E. you can run a single agent inline. therefore to start running a single agent you can start quick rather than having both the agentex backend and cli running. then this setup would be suitable for someone testing a multiagent flow.

Not sure if that is possible given the abstraction and integration, but wanted to throw it out there as a north star.

+1 to that!

aringuyen3 requested a review from a team as a code owner July 9, 2026 14:48

greptile-apps Bot reviewed Jul 9, 2026

View reviewed changes

aringuyen3 force-pushed the aringuyen/run-local-no-docker branch from 356b3eb to aa8bb61 Compare July 13, 2026 16:34

danielmillerp reviewed Jul 13, 2026

View reviewed changes

levilentz reviewed Jul 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(dev): run agentex locally without Docker #353

feat(dev): run agentex locally without Docker #353
aringuyen3 wants to merge 1 commit into
mainfrom
aringuyen/run-local-no-docker

aringuyen3 commented Jul 9, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot Jul 9, 2026

Uh oh!

danielmillerp Jul 13, 2026

Uh oh!

danielmillerp Jul 13, 2026

Uh oh!

danielmillerp Jul 13, 2026

Uh oh!

danielmillerp Jul 13, 2026

Uh oh!

danielmillerp Jul 13, 2026

Uh oh!

danielmillerp Jul 13, 2026

Uh oh!

danielmillerp left a comment

Uh oh!

levilentz left a comment •

edited

Loading

Uh oh!

danielmillerp commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

aringuyen3 commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

App-side change

Also

Contract note

Testing

Uh oh!

greptile-apps Bot Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

danielmillerp Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

danielmillerp Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

danielmillerp Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

danielmillerp Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

danielmillerp Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

danielmillerp Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

danielmillerp left a comment

Choose a reason for hiding this comment

Uh oh!

levilentz left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danielmillerp commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aringuyen3 commented Jul 9, 2026 •

edited

Loading

levilentz left a comment •

edited

Loading