Remove the LocalStack CLI Requirement: Lifecycle via Docker API + REST

[HarshCasper]

Summary

• drop the requirement to install the localstack or lstk CLI: lifecycle, logs, extensions, and ephemeral instances now run through the Docker Engine API (dockerode) and LocalStack's REST APIs
• start creates the localstack-main container directly with the same spec the CLI produced (pro image, ports 4566/443/4510–4560, docker socket + volume mounts, env forwarding); the default volume dir matches the CLI's per-OS path, so existing state carries over
• restart reuses the running container's image, name, and volume instead of resetting to defaults, so externally started runtimes (lstk, docker-compose, custom names) keep their state; startup crashes are reported with the container's log tail
• read logs via the Docker API (feeds localstack-logs-analysis and the IAM analyzer), and manage extensions by running the container's own extension manager over docker exec plus an in-place runtime restart — this also repairs extension venvs created by older images, a case the CLI fails on
• call the LocalStack platform API directly for ephemeral instances and the extensions marketplace, replacing CLI output scraping with real JSON and status codes
• slim the Docker image to a node base (~1.1 GB): no localstack CLI, docker CLI, or awscli; DooD state moves to the localstack-mcp named volume, retiring the identical-path XDG_CACHE_HOME mount (old configs that still set it keep their state)
• new config knobs documented in README/server.json: LOCALSTACK_IMAGE_NAME, LOCALSTACK_VOLUME_DIR, GATEWAY_LISTEN, DOCKER_HOST; wizard drops the lifecycle-CLI prerequisite and deprecates --cache-dir; CI now runs the type-check and unit tests

[maximkasy]

Reviewed the full diff, and also built the branch and ran it live on Windows (Docker Desktop) — details at the bottom. Overall: strong PR, right architecture. Going CLI-free removes an entire class of environment bugs — including one we just hit where the official PyInstaller-frozen Windows CLI ignores PYTHONIOENCODING and charmap-crashes on piped emoji output; with this PR nothing Python is ever spawned, so that whole category is gone. I'd merge this after the items below.

Would fix before merge

1. Restart confirmation can report success prematurely / wait unnecessarily — restartRuntimeInPlace (localstack.utils.ts ~596–608): when the initial getSessionInfo() returns null, the !before fallback treats missing session info as proof the restart completed. Conversely, a fast restart where the gateway never blips and session_id/uptime don't visibly change waits the full 120s despite having succeeded. Suggest requiring an explicit signal (gateway downtime OR session change) and treating before == null as "unknown", plus validating the restart POST response, rather than defaulting to success.

2. pip install specifiers are unvalidated — localstack-extensions.ts ~176: tool-provided name/source go straight to pip install inside the container. The exec-array kills shell injection, but pip itself accepts git+https://… URLs, local paths, and option syntax — and this container has the docker socket mounted, so container compromise ≈ host compromise. Tool args come from an LLM, so treating them as untrusted matters here. A conservative allowlist regex for package names and restricting source to known git hosts would cover it:

const EXTENSION_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*(\[[A-Za-z0-9,._-]+\])?(==[A-Za-z0-9.*+!-]+)?$/;
if (name && !EXTENSION_NAME_RE.test(name)) {
  return ResponseBuilder.error("Invalid extension name", `"${name}" is not a valid extension package name.`);
}

3. Snowflake Pro gate skipped on start — localstack-management.ts ~73–76: the license check is deferred to onReady, so an unlicensed user pulls the full image and starts the container before hearing "no". Moving requireProFeature(ProFeature.SNOWFLAKE) into the preflight for start too fails fast.

4. status service=snowflake probes the Snowflake endpoint even when the AWS stack is running — localstack-management.ts ~287–319: reports "Snowflake health check did not pass", which reads as a Snowflake failure rather than "a different stack is running". recreateOverrides() already detects the stack from the container image — reusing that here would give an accurate message.

Should fix (small, non-blocking)

5. DOCKER_SOCK handling — container-spec.logic.ts ~381: the value isn't validated or normalizeBindPath()-ed, and when a bad path makes container creation fail, describeDockerConnectivityError matches docker.sock in the message and reports "Docker daemon is not reachable" — misleading, since the daemon is fine and the socket mount source is what's wrong. Validating existence when DOCKER_SOCK is explicitly set + a specific error message would fix the last of the "opaque errors" class. (For the record: the default works fine on Docker Desktop — verified live on Windows — the gap is rootless/custom-socket Linux setups.)

6. Venv-repair result ignored — extensions.logic.ts ~28 + localstack-extensions.ts ~106: the repair script hardcodes /opt/code/localstack/.venv/bin/python and its exec result (exit code/stderr) is discarded. On a custom image with a different layout it fails silently and the user gets an unrelated extension-manager error. Checking the exit code and surfacing it in the failure detail is enough.

7. Pre-start stale-container cleanup can block up to 120s — localstack.utils.ts ~418–424: removeContainer + waitForRemoval each default to 60s; if the daemon hangs, start blocks 2 minutes before erroring. Short fail-fast timeouts (~10s) for this pre-start path would be kinder.

Tests (both fail on real Windows machines today; CI hides it because jest runs on Linux only)

8. launchRuntime test doesn't isolate MAIN_CONTAINER_NAME — any machine with that env var set user-wide (i.e. anyone who used the old workaround this project is fixing!) fails localstack.utils.test.ts ("expected localstack-main, received localstack-aws"). Reproduced here. Fix is the same env cleanup docker.client.test.ts already does in beforeEach:

delete process.env.MAIN_CONTAINER_NAME;
delete process.env.LOCALSTACK_MAIN_CONTAINER_NAME;

9. antigravityConfigPath uses bare path.join — paths.logic.ts:27: every other resolver in this file uses the pathFor(ctx) platform-flavor helper so the injected-platform tests pass on any host OS; this one (from #51) uses the host's path and fails on Windows. One-liner since this PR already touches the file:

export function antigravityConfigPath(ctx: ClientContext): string {
  return pathFor(ctx).join(ctx.homeDir, ".gemini", "config", "mcp_config.json");
}

Checked and fine (so nobody re-raises these)

• DOCKER_HOST env handling: docker-modem reads it (incl. npipe) — the dockerode client doesn't need explicit options.
• Auth token forwarded into the container: by design; the runtime needs it and the CLI does the same.
• Token leakage via HTTP errors: HttpError never captures request headers; analytics redacts sensitive keys.
• Image-pull vs readiness-poll timeouts: sequential, not shared — pull can't starve the poll.
• Transient Dead container record after stop: races the AutoRemove, self-clears in seconds — cosmetic.

Live verification (Windows 11, Docker Desktop, real pro token)

• Full lifecycle, zero CLI: start → healthy localstack-main with correct spec (pro image; 4566/443/4510–4560 all bound to 127.0.0.1; docker.sock + volume mounts; env parity incl. GATEWAY_LISTEN, EXTERNAL_SERVICE_PORTS_*) → aws-client s3 mb (in-container awslocal) → restart (preserved image/name) → logs via Docker API → stop with full removal → start again cleanly.
• Volume-path parity confirmed empirically: the spec's Windows default (%LOCALAPPDATA%\cache\localstack\volume) is byte-identical to the directory the real pip CLI created on this machine — existing state genuinely carries over.
• Externally-managed container accepted: raw docker run with a custom name (my-custom-ls) — status/aws-client/logs/stop all worked against it via the image+port fallback, and stop removed it cleanly.
• tsc clean, build clean (14 tools), 191/193 tests (the 2 failures are items 8–9 above).

Nice work — the restart-preserving-overrides design and the container-spec parity are genuinely careful. 🚢

[skyrpex]

I'm totally onboard to making tools (the MCP in this case) as lightweight as possible. The LocalStack CLI is meant to help users managing LocalStack instances, but the underlying technology is quite simple: create a docker container, some status checks, etc. There's no reason to depend on an external CLI (external in the sense that isn't bundled in the MCP itself), or increasing the bundle size by megabytes just for reusing logic that's quite simple to maintain. The complexity turns out to be very high otherwise (something we learnt when building the LocalStack Toolkit 😄).

[maximkasy]

Re-validated the branch after the review-fix commits — everything checks out. Approving. ✅

What I ran (Windows 11, Docker Desktop, real pro token, head 69e8649):

• tsc clean, 230/230 tests across 23 suites — both Windows-host test failures from my review are fixed, and the suites now isolate themselves from user-wide env vars (MAIN_CONTAINER_NAME etc.), so they pass on machines that still carry the old workaround.
• Full live lifecycle with zero CLI: start → aws-client → start again (clean already-running short-circuit) → restart of a 21-hour-old container (came back healthy, image/name preserved) → stop with full removal, no leftovers.
• Probed two of the fixes live:
  • status service=snowflake while the AWS stack runs now says exactly what's going on ("the running container is the AWS stack — the Snowflake emulator is not running") instead of a misleading health-check failure.
  • extensions install with git+https://evil.example.com/pkg.git is rejected with a clear Invalid Extension Target error before anything reaches pip.
• Code-read the rest: the restart logic now requires an explicit signal (unreachable streak or session change — the !before false-success path is gone), DOCKER_SOCK is validated with a precise error, venv-repair failures surface, pre-start housekeeping fails fast, and the container-spec builder is hardened against env aliasing.
• CI: build / mcp-direct-tests / smoke all green.

On the Snowflake Pro gate: your pushback was right — there's no gateway to ask before a container exists, so gating start at preflight can't work; scoping the check to the actually-running stack is the better design.

Nice work turning the review around this thoroughly. 🚢