From 8e4eca8a0574774edcfdad22701fa475fc7aa72e Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Tue, 17 Nov 2026 12:17:48 +0100 Subject: [PATCH 1/7] Name the LocalStack container like lstk: localstack-{stack} The container the start action creates is now named localstack-aws, localstack-snowflake or localstack-azure, lstk's default name per emulator type, instead of the legacy CLI's localstack-main. lstk and the MCP server can then manage each other's emulator. - Detection looks for the three lstk names and the legacy localstack-main. When several run, it prefers the one that publishes the configured gateway port. - Start reports a conflict when a container under another known name publishes a host port it needs. A second emulator on its own ports may keep running. - Stop's stale-container cleanup covers the requested stack's name and localstack-main, or only MAIN_CONTAINER_NAME when it is set. Fixes #25. Refs #10. Co-Authored-By: Claude Opus 5.5 --- README.md | 48 ++++---- data/evals/gemini-comprehensive.json | 2 +- docs/DOCKER.md | 22 ++-- server.json | 2 +- src/lib/docker/docker.client.test.ts | 51 ++++++++- src/lib/docker/docker.client.ts | 59 +++++++--- .../localstack/container-spec.logic.test.ts | 43 ++++++- src/lib/localstack/container-spec.logic.ts | 58 ++++++++-- src/lib/localstack/localstack.utils.test.ts | 106 +++++++++++++++++- src/lib/localstack/localstack.utils.ts | 23 ++++ src/lib/logs/log-retriever.test.ts | 2 +- src/tools-tests/localstack-management.test.ts | 58 ++++++++-- src/tools/localstack-management.ts | 35 +++--- 13 files changed, 416 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index 4ab0b40..98071c7 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ This server provides your AI with dedicated tools for managing your LocalStack e | [`localstack-cloud-pods`](./src/tools/localstack-cloud-pods.ts) | Manages remote LocalStack Cloud Pods for development workflows | - Save current state as a Cloud Pod
- Load previously saved Cloud Pods instantly
- Delete Cloud Pods from remote cloud-backed storage
- Use this for managed remote state snapshots, not local export/import files
- Requires a valid LocalStack Auth Token | | [`localstack-state-management`](./src/tools/localstack-state-management.ts) | Manages local file-based LocalStack state export/import workflows | - Export LocalStack state to a local file on disk through the LocalStack State REST API
- Import LocalStack state from a local file
- Inspect current LocalStack state as JSON metamodel data
- Reset all state or only selected services
- Supports service-level granularity for export, reset, and inspect
- Use this for local disk workflows; use Cloud Pods for remote cloud-backed snapshots
- Requires a valid LocalStack Auth Token | | [`localstack-extensions`](./src/tools/localstack-extensions.ts) | Installs, uninstalls, lists, and discovers LocalStack Extensions | - Manage installed extensions (`list`, `install`, `uninstall`) inside the running container
- Browse the LocalStack Extensions marketplace (`available`)
- Requires a valid LocalStack Auth Token | -| [`localstack-ephemeral-instances`](./src/tools/localstack-ephemeral-instances.ts) | Manages cloud-hosted LocalStack Ephemeral Instances | - Create temporary cloud-hosted LocalStack instances and get an endpoint URL
- List available ephemeral instances, fetch logs, and delete instances
- Supports lifetime, extension preload, Cloud Pod preload, and custom env vars on create
- Requires a valid LocalStack Auth Token | +| [`localstack-ephemeral-instances`](./src/tools/localstack-ephemeral-instances.ts) | Manages cloud-hosted LocalStack Ephemeral Instances | - Create temporary cloud-hosted LocalStack instances and get an endpoint URL
- List available ephemeral instances, fetch logs, and delete instances
- Supports lifetime, extension preload, Cloud Pod preload, and custom env vars on create
- Requires a valid LocalStack Auth Token | | [`localstack-aws-client`](./src/tools/localstack-aws-client.ts) | Runs AWS CLI commands inside the LocalStack for AWS container | - Executes commands via `awslocal` inside the running container
- Sanitizes commands to block shell chaining
- Auto-detects LocalStack coverage errors and links to docs | | [`localstack-azure-client`](./src/tools/localstack-azure-client.ts) | Runs Azure CLI (`az`) commands against the LocalStack for Azure emulator | - Runs the Azure CLI installed on your machine with its own profile, never your Azure login
- Blocks shell syntax and commands that would change the profile, install software or never end
- Uses the extensions you installed with `az extension add`
- Requires the Azure CLI and a valid LocalStack Auth Token | | [`localstack-aws-replicator`](./src/tools/localstack-aws-replicator.ts) | Replicates external AWS resources into a running LocalStack instance | - Start single-resource replication jobs with a resource type and identifier or ARN
- Start batch replication jobs, such as SSM parameters under a path prefix
- Poll job status by job ID and list existing jobs
- List resource types supported by the running Replicator extension
- Reads source AWS credentials from the MCP server environment and supports optional target account or region overrides | @@ -207,28 +207,28 @@ See **[docs/DOCKER.md](./docs/DOCKER.md)** for the run command, MCP client confi ## LocalStack configuration -| Variable Name | Description | Default Value | -| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -| `LOCALSTACK_AUTH_TOKEN` (**required**) | The LocalStack Auth Token to use for the MCP server | None | -| `LOCALSTACK_HOSTNAME` | Host name of the LocalStack gateway the tools call; in Docker, `host.docker.internal`. The Azure tool always calls `azure.localhost.localstack.cloud` (127.0.0.1), so it needs a local gateway. | `localhost` | -| `LOCALSTACK_PORT` | Port of the LocalStack gateway the tools call. | `4566` | -| `MAIN_CONTAINER_NAME` | The explicit LocalStack container name to use for Docker-based tools. When unset, the server auto-detects standard LocalStack containers such as `localstack-main` and `localstack-aws`, then LocalStack Docker images. | Auto-detect | -| `LOCALSTACK_IMAGE_NAME` / `IMAGE_NAME` | Docker image the `start` action launches for the AWS stack. `LOCALSTACK_IMAGE_NAME` wins when both are set (beware: bare `IMAGE_NAME` is a common CI variable). | `localstack/localstack-pro:latest` | -| `LOCALSTACK_VOLUME_DIR` | Host directory mounted at `/var/lib/localstack` in the LocalStack container. Defaults to the same per-OS cache path the LocalStack CLI used (state carries over); inside Docker it defaults to the `localstack-mcp` named volume. | Per-OS cache dir | -| `GATEWAY_LISTEN` | Override the gateway port bindings for `start` (comma-separated `[host]:port`). When set, the implicit `443` binding is skipped. | `:4566,:443` | -| `DOCKER_HOST` | Docker daemon endpoint used for all container operations (`unix://`, `npipe://`, `tcp://`). | Platform default socket | -| `DOCKER_SOCK` | Host path of the Docker socket mounted into the LocalStack container (for Lambda). Validated to exist when set explicitly. | `/var/run/docker.sock` | -| `EXTERNAL_SERVICE_PORTS_START` / `_END` | Inclusive host port range published for external services on `start`. Validated (1–65535, start ≤ end). | `4510` / `4560` | -| `MCP_ANALYTICS_DISABLED` | Disable MCP analytics when set to `1` | `0` | -| `APP_INSPECTOR` | Set to `1` in the LocalStack container environment to enable App Inspector by default across restarts. The MCP tool can also toggle App Inspector at runtime with `set-status`. | `0` | -| `AWS_ACCESS_KEY_ID` (**required for AWS Replicator tool**) | Source AWS access key used by AWS Replicator to read external AWS resources | None | -| `AWS_SECRET_ACCESS_KEY` (**required for AWS Replicator tool**) | Source AWS secret access key used by AWS Replicator to read external AWS resources | None | -| `AWS_DEFAULT_REGION` (**required for AWS Replicator tool**) | Source AWS region used by AWS Replicator | None | -| `LOCALSTACK_AZURE_IMAGE_NAME` | Docker image the `start` action launches for the Azure stack (default `localstack/localstack-azure:latest`). | Latest Azure image | -| `LOCALSTACK_AZ_PATH` | The `az` launcher, or the Azure CLI's Python, for the Azure tool. | Found on `PATH` | -| `LOCALSTACK_AZ_CONFIG_DIR` | The Azure tool's own Azure CLI profile directory (default `~/.localstack/azure/mcp-config-`); it must not overlap your `~/.azure`. | Under `~/.localstack/azure` | -| `LOCALSTACK_AZ_WORKDIR` | The directory the Azure tool runs `az` in; relative file paths resolve against it. | The server's working directory | -| `LOCALSTACK_AZ_TIMEOUT_SECONDS` | Time limit for one Azure CLI command (5–3600). | `300` | +| Variable Name | Description | Default Value | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | +| `LOCALSTACK_AUTH_TOKEN` (**required**) | The LocalStack Auth Token to use for the MCP server | None | +| `LOCALSTACK_HOSTNAME` | Host name of the LocalStack gateway the tools call; in Docker, `host.docker.internal`. The Azure tool always calls `azure.localhost.localstack.cloud` (127.0.0.1), so it needs a local gateway. | `localhost` | +| `LOCALSTACK_PORT` | Port of the LocalStack gateway the tools call. | `4566` | +| `MAIN_CONTAINER_NAME` | The LocalStack container name for Docker-based tools and for the container `start` creates. When unset, `start` uses lstk's name for the stack (`localstack-aws`, `localstack-snowflake` or `localstack-azure`), and the tools find a container by those names or the older `localstack-main`, then by LocalStack image. | lstk's name per stack | +| `LOCALSTACK_IMAGE_NAME` / `IMAGE_NAME` | Docker image the `start` action launches for the AWS stack. `LOCALSTACK_IMAGE_NAME` wins when both are set (beware: bare `IMAGE_NAME` is a common CI variable). | `localstack/localstack-pro:latest` | +| `LOCALSTACK_VOLUME_DIR` | Host directory mounted at `/var/lib/localstack` in the LocalStack container. Defaults to the same per-OS cache path the LocalStack CLI used (state carries over); inside Docker it defaults to the `localstack-mcp` named volume. | Per-OS cache dir | +| `GATEWAY_LISTEN` | Override the gateway port bindings for `start` (comma-separated `[host]:port`). When set, the implicit `443` binding is skipped. | `:4566,:443` | +| `DOCKER_HOST` | Docker daemon endpoint used for all container operations (`unix://`, `npipe://`, `tcp://`). | Platform default socket | +| `DOCKER_SOCK` | Host path of the Docker socket mounted into the LocalStack container (for Lambda). Validated to exist when set explicitly. | `/var/run/docker.sock` | +| `EXTERNAL_SERVICE_PORTS_START` / `_END` | Inclusive host port range published for external services on `start`. Validated (1–65535, start ≤ end). | `4510` / `4560` | +| `MCP_ANALYTICS_DISABLED` | Disable MCP analytics when set to `1` | `0` | +| `APP_INSPECTOR` | Set to `1` in the LocalStack container environment to enable App Inspector by default across restarts. The MCP tool can also toggle App Inspector at runtime with `set-status`. | `0` | +| `AWS_ACCESS_KEY_ID` (**required for AWS Replicator tool**) | Source AWS access key used by AWS Replicator to read external AWS resources | None | +| `AWS_SECRET_ACCESS_KEY` (**required for AWS Replicator tool**) | Source AWS secret access key used by AWS Replicator to read external AWS resources | None | +| `AWS_DEFAULT_REGION` (**required for AWS Replicator tool**) | Source AWS region used by AWS Replicator | None | +| `LOCALSTACK_AZURE_IMAGE_NAME` | Docker image the `start` action launches for the Azure stack (default `localstack/localstack-azure:latest`). | Latest Azure image | +| `LOCALSTACK_AZ_PATH` | The `az` launcher, or the Azure CLI's Python, for the Azure tool. | Found on `PATH` | +| `LOCALSTACK_AZ_CONFIG_DIR` | The Azure tool's own Azure CLI profile directory (default `~/.localstack/azure/mcp-config-`); it must not overlap your `~/.azure`. | Under `~/.localstack/azure` | +| `LOCALSTACK_AZ_WORKDIR` | The directory the Azure tool runs `az` in; relative file paths resolve against it. | The server's working directory | +| `LOCALSTACK_AZ_TIMEOUT_SECONDS` | Time limit for one Azure CLI command (5–3600). | `300` | See **[docs/AZURE.md](./docs/AZURE.md)** for how the Azure tool runs the Azure CLI. @@ -239,7 +239,7 @@ Since v0.6.0 the MCP server no longer uses (or requires) the `localstack` CLI. T - `~/.localstack/*.env` config profiles and `DOCKER_FLAGS` are **not** read at start. Pass configuration through the `envVars` argument of the `localstack-management` start action, or set `LOCALSTACK_`-prefixed variables in the MCP server's environment (LocalStack aliases `LOCALSTACK_` to `` natively). - Besides `LOCALSTACK_*`/`PROVIDER_OVERRIDE_*`, only a curated set of common unprefixed config variables is forwarded from the host environment (`DEBUG`, `LS_LOG`, `SERVICES`, `PERSISTENCE`, `EAGER_SERVICE_LOADING`, `ENFORCE_IAM`, `IAM_SOFT_MODE`, `EXTENSION_AUTO_INSTALL`, `APP_INSPECTOR`, `DNS_ADDRESS`, `MAIN_DOCKER_NETWORK`, and the `LAMBDA_*`/`CFN_*`/`SNOWFLAKE_*`/`SF_*` families). - Port 443 is published by default. If something else uses port 443 locally, set `GATEWAY_LISTEN=:4566` to skip it. -- If you previously used `lstk`, note the container the server creates is named `localstack-main` (externally started `localstack-aws` containers are still detected and managed; `restart` preserves their name, image, and volume). +- The container the server creates has the name lstk gives it: `localstack-aws`, `localstack-snowflake` or `localstack-azure`. With lstk's default config (no `tag` or `container_name`), `lstk stop` and `lstk status` find it; the server finds a container lstk started by name, or by image and gateway port. Earlier versions named it `localstack-main`; a running `localstack-main` is still detected and managed, and `restart` keeps its name, image and volume. For AWS Replicator-specific source credentials, you can use the `AWS_REPLICATOR_SOURCE_` prefixed variants instead of the unprefixed variants. Do not mix the prefixed and unprefixed source credential groups; when any `AWS_REPLICATOR_SOURCE_` variable is set, the Replicator tool reads the source configuration only from that group. diff --git a/data/evals/gemini-comprehensive.json b/data/evals/gemini-comprehensive.json index a03bc9c..8239aff 100644 --- a/data/evals/gemini-comprehensive.json +++ b/data/evals/gemini-comprehensive.json @@ -307,7 +307,7 @@ }, { "id": "scenario-snowflake-full-flow", - "description": "localstack-snowflake-client: start emulator, check connection, run SQL. Runs LAST: the Snowflake stack and the AWS stack cannot run at the same time (both own the localstack-main container), so the AWS emulator must be stopped first and this case leaves the Snowflake emulator running.", + "description": "localstack-snowflake-client: start emulator, check connection, run SQL. Runs LAST: the Snowflake stack and the AWS stack cannot run at the same time (both publish the gateway port), so the AWS emulator must be stopped first and this case leaves the Snowflake emulator running.", "mode": "mcp_host", "scenario": "Work with the LocalStack Snowflake emulator: 1) Using the LocalStack management tool with service set to snowflake, start the Snowflake emulator. If it reports that it is already running, continue to step 2. If starting fails because a LocalStack container is already running, that container is the AWS emulator: stop it with the management tool, then start the Snowflake emulator with service snowflake again. If a start attempt times out, keep checking the Snowflake status with the management tool (service snowflake) until it reports ready — do not give up on a timeout. 2) Use the LocalStack Snowflake client to check the connection to the emulator. 3) Use the LocalStack Snowflake client to execute the SQL file data/sample-sql/snowflake_test.sql. 4) Run the query SHOW TABLES IN demo_db.public and tell me whether the customers table exists.", "mcpHostConfig": { diff --git a/docs/DOCKER.md b/docs/DOCKER.md index 0b2be46..7645360 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -12,7 +12,7 @@ The image is multi-arch (`linux/amd64` and `linux/arm64`). The container talks to your **host Docker daemon** through the bind-mounted `/var/run/docker.sock`. When you ask the server to start LocalStack, it creates a -**sibling** `localstack-main` container on the host (not nested inside the MCP +**sibling** `localstack-aws` container on the host (not nested inside the MCP container) directly via the Docker API. Stop/restart operations act on the detected sibling container the same way. The MCP server and the IaC CLIs reach that sibling over the host gateway. @@ -22,7 +22,7 @@ MCP client ── stdio ──► docker run … (MCP server) │ /var/run/docker.sock (mounted) ▼ host Docker daemon - └─ localstack-main (sibling, publishes :4566 on the host) + └─ localstack-aws (sibling, publishes :4566 on the host) ``` Because LocalStack is a sibling container, one thing must be configured at run time: @@ -118,7 +118,7 @@ that still pass `--add-host s3.host.docker.internal:host-gateway` keep working. - **Extra host aliases.** Include the aliases shown in the quick-start command. - **First cold start** of LocalStack can take up to ~2 minutes while the image is pulled and the runtime initializes; subsequent starts reuse the persisted volume. -- **Persistence across MCP restarts.** The sibling `localstack-main` keeps running +- **Persistence across MCP restarts.** The sibling `localstack-aws` keeps running on the host even if your editor restarts the MCP container — reconnecting finds your stack still up. State persists in the `localstack-mcp` named volume (or `LOCALSTACK_VOLUME_DIR` if you set one). @@ -129,14 +129,14 @@ that still pass `--add-host s3.host.docker.internal:host-gateway` keep working. ## Troubleshooting -| Symptom | Cause / fix | -| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Tools report `LocalStack Not Running` after `start` | Check `LOCALSTACK_HOSTNAME=host.docker.internal` is set and `--add-host` is present (Linux). | -| `Auth Token Required` | `LOCALSTACK_AUTH_TOKEN` must be passed through (every tool requires it). | -| `Docker Not Available` / daemon unreachable | Ensure `/var/run/docker.sock` is mounted (or pass `DOCKER_HOST` for a non-default daemon). | -| `LocalStack container not found` or `Could not find a running LocalStack container named "localstack-main"` | Set `MAIN_CONTAINER_NAME` if you use a custom LocalStack container name. | -| State disappeared after upgrading the image | Old configs stored state under `$XDG_CACHE_HOME/localstack/volume` — keep that env var, or point `LOCALSTACK_VOLUME_DIR` at the old directory. | -| MCP server containers pile up over time | Older images did not exit when the client disconnected. Pull the latest image, then remove strays with `docker ps -aq --filter ancestor=localstack/localstack-mcp-server \| xargs docker rm -f`. | +| Symptom | Cause / fix | +| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Tools report `LocalStack Not Running` after `start` | Check `LOCALSTACK_HOSTNAME=host.docker.internal` is set and `--add-host` is present (Linux). | +| `Auth Token Required` | `LOCALSTACK_AUTH_TOKEN` must be passed through (every tool requires it). | +| `Docker Not Available` / daemon unreachable | Ensure `/var/run/docker.sock` is mounted (or pass `DOCKER_HOST` for a non-default daemon). | +| `LocalStack container not found` or `Could not find a running LocalStack container named "localstack-aws" or …` | Set `MAIN_CONTAINER_NAME` if you use a custom LocalStack container name. | +| State disappeared after upgrading the image | Old configs stored state under `$XDG_CACHE_HOME/localstack/volume` — keep that env var, or point `LOCALSTACK_VOLUME_DIR` at the old directory. | +| MCP server containers pile up over time | Older images did not exit when the client disconnected. Pull the latest image, then remove strays with `docker ps -aq --filter ancestor=localstack/localstack-mcp-server \| xargs docker rm -f`. | ## Validating an image yourself diff --git a/server.json b/server.json index 15a43d8..53555f8 100644 --- a/server.json +++ b/server.json @@ -124,7 +124,7 @@ "name": "GATEWAY_LISTEN" }, { - "description": "Explicit LocalStack container name for Docker-based tools and the container created by start. Defaults to localstack-main (auto-detection covers common names).", + "description": "Explicit LocalStack container name for Docker-based tools and the container created by start. Defaults to lstk's name for the stack: localstack-aws, localstack-snowflake or localstack-azure (detection also finds the older localstack-main).", "isRequired": false, "format": "string", "isSecret": false, diff --git a/src/lib/docker/docker.client.test.ts b/src/lib/docker/docker.client.test.ts index 51cdc3b..8dc862f 100644 --- a/src/lib/docker/docker.client.test.ts +++ b/src/lib/docker/docker.client.test.ts @@ -93,7 +93,7 @@ describe("DockerApiClient", () => { ); }); - test("findLocalStackContainer returns id when found", async () => { + test("findLocalStackContainer still finds a container under the legacy localstack-main name", async () => { const mocks = getDockerMocks(); mocks.listContainers.mockResolvedValueOnce([ { Id: "abc123", Names: ["/localstack-main"], Image: "localstack/localstack:latest" }, @@ -286,10 +286,57 @@ describe("DockerApiClient", () => { const client = new DockerApiClient(); await expect(client.findLocalStackContainer()).rejects.toThrow( - /Could not find a running LocalStack container named "localstack-main"/i + /Could not find a running LocalStack container named "localstack-aws" or "localstack-snowflake" or "localstack-azure" or "localstack-main"/i ); }); + test("findLocalStackContainer matches lstk's per-stack names for images it does not recognize", async () => { + // lstk names containers localstack-{type}; snowflake-next is a preview image lstk + // runs with --image, which the image fallback does not know. + for (const name of ["localstack-snowflake", "localstack-azure"]) { + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { Id: `${name}-id`, Names: [`/${name}`], Image: "localstack/snowflake-next:latest" }, + ]); + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).resolves.toBe(`${name}-id`); + } + }); + + test("findLocalStackContainer picks the known name on the configured gateway port", async () => { + // lstk can run localstack-aws on 4566 and localstack-snowflake on 4567 at once. + process.env.LOCALSTACK_PORT = "4567"; + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { + Id: "aws", + Names: ["/localstack-aws"], + Image: "localstack/localstack-pro:latest", + Ports: [{ PrivatePort: 4566, PublicPort: 4566, Type: "tcp" }], + }, + { + Id: "snow", + Names: ["/localstack-snowflake"], + Image: "localstack/snowflake:latest", + Ports: [{ PrivatePort: 4566, PublicPort: 4567, Type: "tcp" }], + }, + ]); + + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).resolves.toBe("snow"); + }); + + test("findLocalStackContainer prefers lstk's localstack-aws over the legacy localstack-main", async () => { + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { Id: "legacy", Names: ["/localstack-main"], Image: "registry.example/ls:1" }, + { Id: "lstk", Names: ["/localstack-aws"], Image: "registry.example/ls:1" }, + ]); + + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).resolves.toBe("lstk"); + }); + test("stopContainer stops the container via the Docker API", async () => { const mocks = getDockerMocks(); mocks.stop.mockResolvedValueOnce(undefined); diff --git a/src/lib/docker/docker.client.ts b/src/lib/docker/docker.client.ts index a4ef3bb..053e9b8 100644 --- a/src/lib/docker/docker.client.ts +++ b/src/lib/docker/docker.client.ts @@ -1,7 +1,11 @@ import { PassThrough } from "stream"; import { createRequire } from "node:module"; import { LOCALSTACK_PORT } from "../../core/config"; -import type { LocalStackContainerSpec } from "../localstack/container-spec.logic"; +import { + configuredContainerName, + KNOWN_CONTAINER_NAMES, + type LocalStackContainerSpec, +} from "../localstack/container-spec.logic"; export interface ContainerExecResult { stdout: string; @@ -15,6 +19,8 @@ export interface ContainerStateInfo { state: string; image?: string; running: boolean; + /** Host ports the container publishes (only known for a running container). */ + publicPorts: number[]; } /** @@ -191,12 +197,25 @@ export class DockerApiClient { ); } - private findByKnownLocalStackName( - containers: T[] - ): T | undefined { - return ["localstack-main", "localstack-aws"] - .map((name) => containers.find((c) => this.matchesConfiguredContainerName(c, name))) - .find(Boolean); + /** + * The running container under a known LocalStack name. lstk can run several stacks + * side by side, each under its own name and port, so when more than one known name is + * running, the one publishing the configured gateway port wins; otherwise name order. + */ + private findByKnownLocalStackName< + T extends { + Names?: string[]; + Ports?: Array<{ PrivatePort?: number; PublicPort?: number; Type?: string }>; + }, + >(containers: T[]): T | undefined { + const known = KNOWN_CONTAINER_NAMES.map((name) => + containers.find((c) => this.matchesConfiguredContainerName(c, name)) + ).filter((c): c is T => Boolean(c)); + if (known.length > 1) { + const byGatewayPort = known.find((c) => this.publishesConfiguredGatewayPort(c)); + if (byGatewayPort) return byGatewayPort; + } + return known[0]; } async findLocalStackContainer(): Promise { @@ -209,16 +228,11 @@ export class DockerApiClient { Ports?: Array<{ PrivatePort?: number; PublicPort?: number; Type?: string }>; }>; - const explicitName = ( - process.env.MAIN_CONTAINER_NAME || - process.env.LOCALSTACK_MAIN_CONTAINER_NAME || - "" - ).trim(); - const configuredName = explicitName || "localstack-main"; + const explicitName = configuredContainerName(process.env); if (explicitName) { const byConfiguredName = (running || []).find((c) => - this.matchesConfiguredContainerName(c, configuredName) + this.matchesConfiguredContainerName(c, explicitName) ); if (byConfiguredName) return byConfiguredName.Id as string; } @@ -248,9 +262,11 @@ export class DockerApiClient { } } + const lookedFor = explicitName ? [explicitName] : KNOWN_CONTAINER_NAMES; throw new LocalStackContainerNotFoundError( - `Could not find a running LocalStack container named "${configuredName}". ` + - `Set MAIN_CONTAINER_NAME to your container name if it is custom.` + `Could not find a running LocalStack container named ${lookedFor + .map((name) => `"${name}"`) + .join(" or ")}. ` + `Set MAIN_CONTAINER_NAME to your container name if it is custom.` ); } @@ -578,7 +594,13 @@ export class DockerApiClient { (this.docker.listContainers as any)({ all: true, filters: { name: [name] } }), 10000, "Docker container list" - )) as Array<{ Id: string; Names?: string[]; State?: string; Image?: string }>; + )) as Array<{ + Id: string; + Names?: string[]; + State?: string; + Image?: string; + Ports?: Array<{ PublicPort?: number }>; + }>; const match = (containers || []).find((container) => this.matchesConfiguredContainerName(container, name) @@ -590,6 +612,9 @@ export class DockerApiClient { state: match.State || "unknown", image: match.Image, running: match.State === "running", + publicPorts: (match.Ports || []) + .map((port) => port.PublicPort) + .filter((port): port is number => typeof port === "number"), }; } diff --git a/src/lib/localstack/container-spec.logic.test.ts b/src/lib/localstack/container-spec.logic.test.ts index 3990cea..8d9a074 100644 --- a/src/lib/localstack/container-spec.logic.test.ts +++ b/src/lib/localstack/container-spec.logic.test.ts @@ -2,6 +2,7 @@ import { buildLocalStackContainerSpec, detectAiAgent, parseGatewayListen, + stackContainerNames, resolveContainerName, resolveImage, resolveVolume, @@ -74,9 +75,32 @@ test("the Azure emulator's LS_AZURE_ settings reach the Azure stack only; the Az }); describe("resolveContainerName", () => { - test("defaults to localstack-main and honors MAIN_CONTAINER_NAME", () => { - expect(resolveContainerName({})).toBe("localstack-main"); - expect(resolveContainerName({ MAIN_CONTAINER_NAME: "my-ls" })).toBe("my-ls"); + test("defaults to lstk's localstack-{stack} name", () => { + // lstk's ContainerConfig.defaultName: "localstack-" + emulator type (internal/config/containers.go). + expect(resolveContainerName({}, "aws")).toBe("localstack-aws"); + expect(resolveContainerName({}, "snowflake")).toBe("localstack-snowflake"); + expect(resolveContainerName({}, "azure")).toBe("localstack-azure"); + }); + + test("honors MAIN_CONTAINER_NAME for every stack", () => { + for (const stack of ["aws", "snowflake", "azure"] as const) { + expect(resolveContainerName({ MAIN_CONTAINER_NAME: "my-ls" }, stack)).toBe("my-ls"); + expect(resolveContainerName({ LOCALSTACK_MAIN_CONTAINER_NAME: "ls2" }, stack)).toBe("ls2"); + } + }); +}); + +describe("stackContainerNames", () => { + test("lists the stack's lstk name and the legacy localstack-main when nothing is configured", () => { + expect(stackContainerNames({}, "aws")).toEqual(["localstack-aws", "localstack-main"]); + expect(stackContainerNames({}, "snowflake")).toEqual([ + "localstack-snowflake", + "localstack-main", + ]); + }); + + test("lists only the configured name when MAIN_CONTAINER_NAME is set", () => { + expect(stackContainerNames({ MAIN_CONTAINER_NAME: " my-ls " }, "azure")).toEqual(["my-ls"]); }); }); @@ -352,7 +376,7 @@ describe("buildLocalStackContainerSpec", () => { expect(env.LOCALSTACK_IMAGE_NAME).toBeUndefined(); expect(env.UNRELATED_VAR).toBeUndefined(); expect(env.LOCALSTACK_AUTH_TOKEN).toBe("ls-real-token"); - expect(env.MAIN_CONTAINER_NAME).toBe("localstack-main"); + expect(env.MAIN_CONTAINER_NAME).toBe("localstack-aws"); expect(env.DOCKER_HOST).toBe("unix:///var/run/docker.sock"); expect(env.LOCALSTACK_CLIENT_NAME).toBe("localstack-mcp-server"); expect(env.LOCALSTACK_CLIENT_VERSION).toBe("0.5.0"); @@ -439,10 +463,17 @@ describe("buildLocalStackContainerSpec", () => { expect(buildLocalStackContainerSpec(baseInput()).HostConfig.AutoRemove).toBe(true); }); - test("snowflake stack: snowflake image, same container name", () => { + test("snowflake stack: snowflake image, lstk's snowflake container name", () => { const spec = buildLocalStackContainerSpec(baseInput({ stack: "snowflake" })); expect(spec.Image).toBe("localstack/snowflake:latest"); - expect(spec.name).toBe("localstack-main"); + expect(spec.name).toBe("localstack-snowflake"); + expect(envMap(spec).MAIN_CONTAINER_NAME).toBe("localstack-snowflake"); + }); + + test("azure stack: lstk's azure container name", () => { + const spec = buildLocalStackContainerSpec(baseInput({ stack: "azure" })); + expect(spec.name).toBe("localstack-azure"); + expect(envMap(spec).MAIN_CONTAINER_NAME).toBe("localstack-azure"); }); test("restart recreation can pin the original image and name", () => { diff --git a/src/lib/localstack/container-spec.logic.ts b/src/lib/localstack/container-spec.logic.ts index d71afe2..c47b251 100644 --- a/src/lib/localstack/container-spec.logic.ts +++ b/src/lib/localstack/container-spec.logic.ts @@ -1,12 +1,13 @@ /** * Pure builder for the LocalStack container spec (dockerode `createContainer` options). * - * Replicates what `localstack start` used to assemble via the Python CLI so the MCP - * server can create the runtime with no CLI installed. Behavioral anchors (verified - * against the 2026.x `localstack_cli` wheel source): + * Builds the runtime container without any CLI installed. The container name follows + * lstk (`internal/config/containers.go`, `ContainerConfig.defaultName`); the other + * behavioral anchors were verified against the 2026.x `localstack_cli` wheel source: * - image `localstack/localstack-pro:latest` (pro unconditional), `--stack snowflake` * ⇒ `localstack/snowflake:latest` - * - container name `localstack-main`, also injected as `MAIN_CONTAINER_NAME` env + * - container name `localstack-{stack}` (lstk's default: `localstack-aws`, + * `localstack-snowflake`, `localstack-azure`), also injected as `MAIN_CONTAINER_NAME` env * - ports 4566, 443 (only when GATEWAY_LISTEN is unset) and the external service * range 4510–4560 inclusive; bind host 127.0.0.1 on a host, 0.0.0.0 in Docker * - volume dir → /var/lib/localstack, docker socket → /var/run/docker.sock @@ -14,7 +15,6 @@ * only in the port bindings, never inside the container */ -export const DEFAULT_CONTAINER_NAME = "localstack-main"; export const DEFAULT_AWS_IMAGE = "localstack/localstack-pro:latest"; export const DEFAULT_SNOWFLAKE_IMAGE = "localstack/snowflake:latest"; export const DEFAULT_AZURE_IMAGE = "localstack/localstack-azure:latest"; @@ -91,6 +91,24 @@ const AI_AGENT_DETECTORS: Array<[string, string[]]> = [ export type LocalStackStack = "aws" | "snowflake" | "azure"; +/** lstk's default container name per stack (`localstack-{type}`). */ +export const DEFAULT_CONTAINER_NAMES: Readonly> = { + aws: "localstack-aws", + snowflake: "localstack-snowflake", + azure: "localstack-azure", +}; + +/** The name earlier versions of this server (and the legacy CLI) gave the container. */ +export const LEGACY_CONTAINER_NAME = "localstack-main"; + +/** Names a LocalStack container may have when no MAIN_CONTAINER_NAME is configured. */ +export const KNOWN_CONTAINER_NAMES: readonly string[] = [ + DEFAULT_CONTAINER_NAMES.aws, + DEFAULT_CONTAINER_NAMES.snowflake, + DEFAULT_CONTAINER_NAMES.azure, + LEGACY_CONTAINER_NAME, +]; + export type VolumeResolution = { type: "bind"; source: string } | { type: "volume"; name: string }; export interface GatewayListenEntry { @@ -151,14 +169,37 @@ export function stackFromImage(image?: string): LocalStackStack | undefined { return "aws"; } -export function resolveContainerName(hostEnv: Record): string { +/** The container name the user configured (MAIN_CONTAINER_NAME), or undefined. */ +export function configuredContainerName( + hostEnv: Record +): string | undefined { return ( hostEnv.MAIN_CONTAINER_NAME?.trim() || hostEnv.LOCALSTACK_MAIN_CONTAINER_NAME?.trim() || - DEFAULT_CONTAINER_NAME + undefined ); } +/** The name for a new container of this stack: the configured one, else lstk's default. */ +export function resolveContainerName( + hostEnv: Record, + stack: LocalStackStack +): string { + return configuredContainerName(hostEnv) || DEFAULT_CONTAINER_NAMES[stack]; +} + +/** + * Names a stopped container of this stack may hold: the configured name, else the + * stack's lstk name and the legacy `localstack-main`. + */ +export function stackContainerNames( + hostEnv: Record, + stack: LocalStackStack +): string[] { + const configured = configuredContainerName(hostEnv); + return configured ? [configured] : [DEFAULT_CONTAINER_NAMES[stack], LEGACY_CONTAINER_NAME]; +} + function parsePort(text: string, context: string): number { const port = Number(text); if (!Number.isInteger(port) || port < 1 || port > 65535) { @@ -463,7 +504,8 @@ function buildEnv(input: ContainerSpecInput, ports: ResolvedPorts, name: string) } export function buildLocalStackContainerSpec(input: ContainerSpecInput): LocalStackContainerSpec { - const name = input.containerNameOverride?.trim() || resolveContainerName(input.hostEnv); + const name = + input.containerNameOverride?.trim() || resolveContainerName(input.hostEnv, input.stack); const image = input.imageOverride?.trim() || resolveImage(input.stack, input.hostEnv); const ports = resolvePorts(input); diff --git a/src/lib/localstack/localstack.utils.test.ts b/src/lib/localstack/localstack.utils.test.ts index 84de421..50caecb 100644 --- a/src/lib/localstack/localstack.utils.test.ts +++ b/src/lib/localstack/localstack.utils.test.ts @@ -294,7 +294,7 @@ describe("localstack.utils", () => { expect(client.createAndStartContainer).toHaveBeenCalledTimes(1); const spec = client.createAndStartContainer.mock.calls[0][0]; expect(spec.Image).toBe("localstack/localstack-pro:latest"); - expect(spec.name).toBe("localstack-main"); + expect(spec.name).toBe("localstack-aws"); }); test("pulls the image when missing", async () => { @@ -330,6 +330,110 @@ describe("localstack.utils", () => { expect(client.createAndStartContainer).not.toHaveBeenCalled(); }); + test("reports a conflict when another stack's container runs under its own lstk name", async () => { + // Each stack has its own name, so starting Snowflake must still notice a running + // localstack-aws: both publish the gateway port. + const { client } = mockDockerClient({ + findContainerByNameAnyState: jest.fn(async (name: string) => + name === "localstack-aws" + ? { + id: "aws-1", + name, + state: "running", + running: true, + image: "localstack/localstack-pro:latest", + publicPorts: [4566, 443], + } + : null + ), + }); + const getStatus = jest.fn().mockResolvedValue({ isRunning: false }); + + const result = await launchRuntime({ + ...launchDefaults, + stack: "snowflake", + processLabel: "Snowflake emulator", + getStatus, + dockerClient: client, + }); + const text = result.content[0].text; + expect(text).toContain('named "localstack-aws"'); + expect(text).toContain("action: stop"); + expect(client.createAndStartContainer).not.toHaveBeenCalled(); + }); + + test("reports a conflict when a container runs under the legacy localstack-main name", async () => { + const { client } = mockDockerClient({ + findContainerByNameAnyState: jest.fn(async (name: string) => + name === "localstack-main" + ? { + id: "old-1", + name, + state: "running", + running: true, + image: "localstack/localstack-pro:latest", + publicPorts: [4566], + } + : null + ), + }); + const getStatus = jest.fn().mockResolvedValue({ isRunning: false }); + + const result = await launchRuntime({ ...launchDefaults, getStatus, dockerClient: client }); + expect(result.content[0].text).toContain('named "localstack-main"'); + expect(client.createAndStartContainer).not.toHaveBeenCalled(); + }); + + test("starts beside another stack's container that publishes other ports", async () => { + // lstk runs stacks side by side on their own ports; only a shared host port conflicts. + const { client } = mockDockerClient({ + findContainerByNameAnyState: jest.fn(async (name: string) => + name === "localstack-aws" + ? { + id: "aws-1", + name, + state: "running", + running: true, + image: "localstack/localstack-pro:latest", + publicPorts: [5566], + } + : null + ), + }); + const getStatus = jest + .fn() + .mockResolvedValueOnce({ isRunning: false }) + .mockResolvedValue({ isRunning: true, isReady: true }); + + const result = await launchRuntime({ + ...launchDefaults, + stack: "snowflake", + processLabel: "Snowflake emulator", + getStatus, + dockerClient: client, + }); + expect(result.content[0].text).toContain("started successfully"); + expect(client.createAndStartContainer.mock.calls[0][0].name).toBe("localstack-snowflake"); + }); + + test("leaves stopped containers of other names alone", async () => { + const { client } = mockDockerClient({ + findContainerByNameAnyState: jest.fn(async (name: string) => + name === "localstack-main" + ? { id: "old-stopped", name, state: "exited", running: false } + : null + ), + }); + const getStatus = jest + .fn() + .mockResolvedValueOnce({ isRunning: false }) + .mockResolvedValue({ isRunning: true, isReady: true }); + + const result = await launchRuntime({ ...launchDefaults, getStatus, dockerClient: client }); + expect(result.content[0].text).toContain("started successfully"); + expect(client.removeContainer).not.toHaveBeenCalled(); + }); + test("names an Azure container as the Azure emulator in the conflict message", async () => { const { client } = mockDockerClient({ findContainerByNameAnyState: jest.fn().mockResolvedValue({ diff --git a/src/lib/localstack/localstack.utils.ts b/src/lib/localstack/localstack.utils.ts index 17e2ef4..29b15b7 100644 --- a/src/lib/localstack/localstack.utils.ts +++ b/src/lib/localstack/localstack.utils.ts @@ -15,7 +15,9 @@ import { } from "../docker/docker.client"; import { buildLocalStackContainerSpec, + KNOWN_CONTAINER_NAMES, resolveContainerName, + type LocalStackContainerSpec, resolveVolume, stackFromImage, type LocalStackStack, @@ -352,6 +354,15 @@ function tailLines(text: string, lines: number): string { return allLines.slice(-lines).join("\n"); } +/** Host ports a container spec publishes. */ +function specHostPorts(spec: LocalStackContainerSpec): Set { + return new Set( + Object.values(spec.HostConfig.PortBindings) + .flat() + .map((binding) => Number(binding.HostPort)) + ); +} + function conflictResponse(processLabel: string, containerName: string, image?: string) { const stack = stackFromImage(image); const otherStack = @@ -476,6 +487,10 @@ async function launchRuntimeInner( // Fail fast (or clean up) when the container name is taken. A running container is // an actionable conflict; a stopped one is a stale leftover we remove ourselves. + // Each stack has its own default name (lstk's `localstack-{type}`), so a running + // container under another known name (another stack, or the legacy `localstack-main`) + // is a conflict too when it publishes a host port this start binds. One on other + // ports (a second emulator on its own GATEWAY_LISTEN) may keep running. // Short timeouts: this is pre-start housekeeping — a hung daemon should surface // as an error in seconds, not block the start for two minutes. try { @@ -487,6 +502,14 @@ async function launchRuntimeInner( await docker.removeContainer(existing.id, 10000); await docker.waitForRemoval(existing.id, 10000); } + const boundHostPorts = specHostPorts(spec); + for (const name of KNOWN_CONTAINER_NAMES) { + if (name === spec.name) continue; + const other = await docker.findContainerByNameAnyState(name); + if (other?.running && other.publicPorts.some((port) => boundHostPorts.has(port))) { + return conflictResponse(processLabel, name, other.image); + } + } } catch (error) { return ResponseBuilder.error( "Docker lookup failed", diff --git a/src/lib/logs/log-retriever.test.ts b/src/lib/logs/log-retriever.test.ts index a95bd50..a58d798 100644 --- a/src/lib/logs/log-retriever.test.ts +++ b/src/lib/logs/log-retriever.test.ts @@ -51,7 +51,7 @@ describe("LocalStackLogRetriever", () => { .fn() .mockRejectedValue( new actual.LocalStackContainerNotFoundError( - 'Could not find a running LocalStack container named "localstack-main".' + 'Could not find a running LocalStack container named "localstack-aws".' ) ), }); diff --git a/src/tools-tests/localstack-management.test.ts b/src/tools-tests/localstack-management.test.ts index 5404fca..dce7ce0 100644 --- a/src/tools-tests/localstack-management.test.ts +++ b/src/tools-tests/localstack-management.test.ts @@ -86,20 +86,62 @@ describe("localstack-management", () => { findLocalStackContainer: jest .fn() .mockRejectedValue(new LocalStackContainerNotFoundError("none running")), - findContainerByNameAnyState: jest.fn().mockResolvedValue({ - id: "stale-1", - name: "localstack-main", - state: "exited", - running: false, - }), + findContainerByNameAnyState: jest.fn(async (name: string) => + name === "localstack-snowflake" + ? { id: "stale-1", name, state: "exited", running: false } + : null + ), removeContainer, waitForRemoval, }); - const result = await localstackManagement({ action: "stop", service: "aws" } as any); + const result = await localstackManagement({ action: "stop", service: "snowflake" } as any); + expect(removeContainer).toHaveBeenCalledTimes(1); expect(removeContainer).toHaveBeenCalledWith("stale-1"); expect(waitForRemoval).toHaveBeenCalledWith("stale-1"); - expect(text(result)).toContain("Removed stopped LocalStack container"); + expect(text(result)).toContain('Removed stopped LocalStack container "localstack-snowflake"'); + }); + + test("stop leaves a stopped container of another stack alone", async () => { + const { LocalStackContainerNotFoundError } = jest.requireActual("../lib/docker/docker.client"); + const removeContainer = jest.fn().mockResolvedValue(undefined); + const findContainerByNameAnyState = jest.fn(async (name: string) => + name === "localstack-snowflake" + ? { id: "stale-1", name, state: "exited", running: false, publicPorts: [] } + : null + ); + mockDocker({ + findLocalStackContainer: jest + .fn() + .mockRejectedValue(new LocalStackContainerNotFoundError("none running")), + findContainerByNameAnyState, + removeContainer, + }); + mockedGetStatus.mockResolvedValue({ isRunning: false, isReady: false }); + + await localstackManagement({ action: "stop", service: "aws" } as any); + expect(findContainerByNameAnyState.mock.calls.map(([name]) => name)).toEqual([ + "localstack-aws", + "localstack-main", + ]); + expect(removeContainer).not.toHaveBeenCalled(); + }); + + test("stop looks only under MAIN_CONTAINER_NAME when it is set", async () => { + process.env.MAIN_CONTAINER_NAME = "my-ls"; + const { LocalStackContainerNotFoundError } = jest.requireActual("../lib/docker/docker.client"); + const findContainerByNameAnyState = jest.fn().mockResolvedValue(null); + mockDocker({ + findLocalStackContainer: jest + .fn() + .mockRejectedValue(new LocalStackContainerNotFoundError("none running")), + findContainerByNameAnyState, + }); + mockedGetStatus.mockResolvedValue({ isRunning: false, isReady: false }); + + await localstackManagement({ action: "stop", service: "aws" } as any); + expect(findContainerByNameAnyState).toHaveBeenCalledTimes(1); + expect(findContainerByNameAnyState).toHaveBeenCalledWith("my-ls"); }); test("stop reports nothing to do when no container exists and the gateway is down", async () => { diff --git a/src/tools/localstack-management.ts b/src/tools/localstack-management.ts index cab5aae..ffd99a6 100644 --- a/src/tools/localstack-management.ts +++ b/src/tools/localstack-management.ts @@ -5,14 +5,17 @@ import { getLocalStackStatus, getSnowflakeEmulatorStatus, launchRuntime, - resolveContainerName, } from "../lib/localstack/localstack.utils"; import { DockerApiClient, isLocalStackContainerNotFoundError, type ContainerMetadata, } from "../lib/docker/docker.client"; -import { stackFromImage, type VolumeResolution } from "../lib/localstack/container-spec.logic"; +import { + stackContainerNames, + stackFromImage, + type VolumeResolution, +} from "../lib/localstack/container-spec.logic"; import { runPreflights, requireProFeature, @@ -96,7 +99,7 @@ export default async function localstackManagement({ case "start": return await handleStart({ envVars, service }); case "stop": - return await handleStop(); + return await handleStop({ service }); case "restart": return await handleRestart({ envVars, service }); case "status": @@ -196,7 +199,7 @@ async function handleStart({ // Handle stop action — stop the detected container via the Docker API. Also cleans up // stopped/stale containers occupying a LocalStack name, so start's conflict advice // ("stop it first") always has a working recovery path. -async function handleStop() { +async function handleStop({ service }: { service: Service }) { const dockerClient = new DockerApiClient(); let containerId: string; try { @@ -209,15 +212,21 @@ async function handleStop() { ); } - // No RUNNING container found — check for a stale stopped one holding the name. + // No RUNNING container found — check for stale stopped ones holding this stack's name. try { - const stale = await dockerClient.findContainerByNameAnyState( - resolveContainerName(process.env) - ); - if (stale && !stale.running) { - await dockerClient.removeContainer(stale.id); - await dockerClient.waitForRemoval(stale.id); - return ResponseBuilder.markdown(`🛑 Removed stopped LocalStack container "${stale.name}".`); + const removed: string[] = []; + for (const name of stackContainerNames(process.env, service)) { + const stale = await dockerClient.findContainerByNameAnyState(name); + if (stale && !stale.running) { + await dockerClient.removeContainer(stale.id); + await dockerClient.waitForRemoval(stale.id); + removed.push(`"${stale.name}"`); + } + } + if (removed.length > 0) { + return ResponseBuilder.markdown( + `🛑 Removed stopped LocalStack container${removed.length > 1 ? "s" : ""} ${removed.join(", ")}.` + ); } } catch { // fall through to the gateway-based reporting below @@ -249,7 +258,7 @@ async function handleStop() { // Handle restart action — stop the running container, then start fresh (applies any // new envVars). The recreate reuses the original container's image, name, and volume -// so an externally-provisioned runtime (lstk's localstack-aws, custom names/images) +// so an externally-provisioned runtime (a legacy localstack-main, custom names/images) // is not silently replaced by our defaults — that would strand its state. async function handleRestart({ envVars, From 1158f493b7b36149baad62f4a32507e4a9019cd8 Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Tue, 17 Nov 2026 13:57:58 +0100 Subject: [PATCH 2/7] Keep localstack-main as the default container name; also find lstk's Per review feedback, start names the container localstack-main again for every stack. lstk's names (localstack-aws, localstack-snowflake, localstack-azure) become aliases: detection, the start conflict check and stop's stale-container cleanup also look for them. Co-Authored-By: Claude Opus 5.5 --- README.md | 46 ++++++++--------- data/evals/gemini-comprehensive.json | 2 +- docs/DOCKER.md | 22 ++++----- server.json | 2 +- src/lib/docker/docker.client.test.ts | 10 ++-- .../localstack/container-spec.logic.test.ts | 37 +++++--------- src/lib/localstack/container-spec.logic.ts | 49 +++++++++---------- src/lib/localstack/localstack.utils.test.ts | 20 ++++---- src/lib/localstack/localstack.utils.ts | 8 +-- src/lib/logs/log-retriever.test.ts | 2 +- src/tools-tests/localstack-management.test.ts | 2 +- src/tools/localstack-management.ts | 2 +- 12 files changed, 94 insertions(+), 108 deletions(-) diff --git a/README.md b/README.md index 98071c7..7976caf 100644 --- a/README.md +++ b/README.md @@ -207,28 +207,28 @@ See **[docs/DOCKER.md](./docs/DOCKER.md)** for the run command, MCP client confi ## LocalStack configuration -| Variable Name | Description | Default Value | -| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | -| `LOCALSTACK_AUTH_TOKEN` (**required**) | The LocalStack Auth Token to use for the MCP server | None | -| `LOCALSTACK_HOSTNAME` | Host name of the LocalStack gateway the tools call; in Docker, `host.docker.internal`. The Azure tool always calls `azure.localhost.localstack.cloud` (127.0.0.1), so it needs a local gateway. | `localhost` | -| `LOCALSTACK_PORT` | Port of the LocalStack gateway the tools call. | `4566` | -| `MAIN_CONTAINER_NAME` | The LocalStack container name for Docker-based tools and for the container `start` creates. When unset, `start` uses lstk's name for the stack (`localstack-aws`, `localstack-snowflake` or `localstack-azure`), and the tools find a container by those names or the older `localstack-main`, then by LocalStack image. | lstk's name per stack | -| `LOCALSTACK_IMAGE_NAME` / `IMAGE_NAME` | Docker image the `start` action launches for the AWS stack. `LOCALSTACK_IMAGE_NAME` wins when both are set (beware: bare `IMAGE_NAME` is a common CI variable). | `localstack/localstack-pro:latest` | -| `LOCALSTACK_VOLUME_DIR` | Host directory mounted at `/var/lib/localstack` in the LocalStack container. Defaults to the same per-OS cache path the LocalStack CLI used (state carries over); inside Docker it defaults to the `localstack-mcp` named volume. | Per-OS cache dir | -| `GATEWAY_LISTEN` | Override the gateway port bindings for `start` (comma-separated `[host]:port`). When set, the implicit `443` binding is skipped. | `:4566,:443` | -| `DOCKER_HOST` | Docker daemon endpoint used for all container operations (`unix://`, `npipe://`, `tcp://`). | Platform default socket | -| `DOCKER_SOCK` | Host path of the Docker socket mounted into the LocalStack container (for Lambda). Validated to exist when set explicitly. | `/var/run/docker.sock` | -| `EXTERNAL_SERVICE_PORTS_START` / `_END` | Inclusive host port range published for external services on `start`. Validated (1–65535, start ≤ end). | `4510` / `4560` | -| `MCP_ANALYTICS_DISABLED` | Disable MCP analytics when set to `1` | `0` | -| `APP_INSPECTOR` | Set to `1` in the LocalStack container environment to enable App Inspector by default across restarts. The MCP tool can also toggle App Inspector at runtime with `set-status`. | `0` | -| `AWS_ACCESS_KEY_ID` (**required for AWS Replicator tool**) | Source AWS access key used by AWS Replicator to read external AWS resources | None | -| `AWS_SECRET_ACCESS_KEY` (**required for AWS Replicator tool**) | Source AWS secret access key used by AWS Replicator to read external AWS resources | None | -| `AWS_DEFAULT_REGION` (**required for AWS Replicator tool**) | Source AWS region used by AWS Replicator | None | -| `LOCALSTACK_AZURE_IMAGE_NAME` | Docker image the `start` action launches for the Azure stack (default `localstack/localstack-azure:latest`). | Latest Azure image | -| `LOCALSTACK_AZ_PATH` | The `az` launcher, or the Azure CLI's Python, for the Azure tool. | Found on `PATH` | -| `LOCALSTACK_AZ_CONFIG_DIR` | The Azure tool's own Azure CLI profile directory (default `~/.localstack/azure/mcp-config-`); it must not overlap your `~/.azure`. | Under `~/.localstack/azure` | -| `LOCALSTACK_AZ_WORKDIR` | The directory the Azure tool runs `az` in; relative file paths resolve against it. | The server's working directory | -| `LOCALSTACK_AZ_TIMEOUT_SECONDS` | Time limit for one Azure CLI command (5–3600). | `300` | +| Variable Name | Description | Default Value | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | +| `LOCALSTACK_AUTH_TOKEN` (**required**) | The LocalStack Auth Token to use for the MCP server | None | +| `LOCALSTACK_HOSTNAME` | Host name of the LocalStack gateway the tools call; in Docker, `host.docker.internal`. The Azure tool always calls `azure.localhost.localstack.cloud` (127.0.0.1), so it needs a local gateway. | `localhost` | +| `LOCALSTACK_PORT` | Port of the LocalStack gateway the tools call. | `4566` | +| `MAIN_CONTAINER_NAME` | The LocalStack container name for Docker-based tools and for the container `start` creates. When unset, `start` names it `localstack-main`, and the tools find a container named `localstack-main` or one of lstk's names (`localstack-aws`, `localstack-snowflake`, `localstack-azure`), then by LocalStack image. | Auto-detect | +| `LOCALSTACK_IMAGE_NAME` / `IMAGE_NAME` | Docker image the `start` action launches for the AWS stack. `LOCALSTACK_IMAGE_NAME` wins when both are set (beware: bare `IMAGE_NAME` is a common CI variable). | `localstack/localstack-pro:latest` | +| `LOCALSTACK_VOLUME_DIR` | Host directory mounted at `/var/lib/localstack` in the LocalStack container. Defaults to the same per-OS cache path the LocalStack CLI used (state carries over); inside Docker it defaults to the `localstack-mcp` named volume. | Per-OS cache dir | +| `GATEWAY_LISTEN` | Override the gateway port bindings for `start` (comma-separated `[host]:port`). When set, the implicit `443` binding is skipped. | `:4566,:443` | +| `DOCKER_HOST` | Docker daemon endpoint used for all container operations (`unix://`, `npipe://`, `tcp://`). | Platform default socket | +| `DOCKER_SOCK` | Host path of the Docker socket mounted into the LocalStack container (for Lambda). Validated to exist when set explicitly. | `/var/run/docker.sock` | +| `EXTERNAL_SERVICE_PORTS_START` / `_END` | Inclusive host port range published for external services on `start`. Validated (1–65535, start ≤ end). | `4510` / `4560` | +| `MCP_ANALYTICS_DISABLED` | Disable MCP analytics when set to `1` | `0` | +| `APP_INSPECTOR` | Set to `1` in the LocalStack container environment to enable App Inspector by default across restarts. The MCP tool can also toggle App Inspector at runtime with `set-status`. | `0` | +| `AWS_ACCESS_KEY_ID` (**required for AWS Replicator tool**) | Source AWS access key used by AWS Replicator to read external AWS resources | None | +| `AWS_SECRET_ACCESS_KEY` (**required for AWS Replicator tool**) | Source AWS secret access key used by AWS Replicator to read external AWS resources | None | +| `AWS_DEFAULT_REGION` (**required for AWS Replicator tool**) | Source AWS region used by AWS Replicator | None | +| `LOCALSTACK_AZURE_IMAGE_NAME` | Docker image the `start` action launches for the Azure stack (default `localstack/localstack-azure:latest`). | Latest Azure image | +| `LOCALSTACK_AZ_PATH` | The `az` launcher, or the Azure CLI's Python, for the Azure tool. | Found on `PATH` | +| `LOCALSTACK_AZ_CONFIG_DIR` | The Azure tool's own Azure CLI profile directory (default `~/.localstack/azure/mcp-config-`); it must not overlap your `~/.azure`. | Under `~/.localstack/azure` | +| `LOCALSTACK_AZ_WORKDIR` | The directory the Azure tool runs `az` in; relative file paths resolve against it. | The server's working directory | +| `LOCALSTACK_AZ_TIMEOUT_SECONDS` | Time limit for one Azure CLI command (5–3600). | `300` | See **[docs/AZURE.md](./docs/AZURE.md)** for how the Azure tool runs the Azure CLI. @@ -239,7 +239,7 @@ Since v0.6.0 the MCP server no longer uses (or requires) the `localstack` CLI. T - `~/.localstack/*.env` config profiles and `DOCKER_FLAGS` are **not** read at start. Pass configuration through the `envVars` argument of the `localstack-management` start action, or set `LOCALSTACK_`-prefixed variables in the MCP server's environment (LocalStack aliases `LOCALSTACK_` to `` natively). - Besides `LOCALSTACK_*`/`PROVIDER_OVERRIDE_*`, only a curated set of common unprefixed config variables is forwarded from the host environment (`DEBUG`, `LS_LOG`, `SERVICES`, `PERSISTENCE`, `EAGER_SERVICE_LOADING`, `ENFORCE_IAM`, `IAM_SOFT_MODE`, `EXTENSION_AUTO_INSTALL`, `APP_INSPECTOR`, `DNS_ADDRESS`, `MAIN_DOCKER_NETWORK`, and the `LAMBDA_*`/`CFN_*`/`SNOWFLAKE_*`/`SF_*` families). - Port 443 is published by default. If something else uses port 443 locally, set `GATEWAY_LISTEN=:4566` to skip it. -- The container the server creates has the name lstk gives it: `localstack-aws`, `localstack-snowflake` or `localstack-azure`. With lstk's default config (no `tag` or `container_name`), `lstk stop` and `lstk status` find it; the server finds a container lstk started by name, or by image and gateway port. Earlier versions named it `localstack-main`; a running `localstack-main` is still detected and managed, and `restart` keeps its name, image and volume. +- The container the server creates is named `localstack-main`. A container lstk started (`localstack-aws`, `localstack-snowflake` or `localstack-azure`) is detected and managed too: `stop` and `status` act on it, `restart` keeps its name, image and volume, and `start` reports it as a conflict when it holds the ports `start` needs. For AWS Replicator-specific source credentials, you can use the `AWS_REPLICATOR_SOURCE_` prefixed variants instead of the unprefixed variants. Do not mix the prefixed and unprefixed source credential groups; when any `AWS_REPLICATOR_SOURCE_` variable is set, the Replicator tool reads the source configuration only from that group. diff --git a/data/evals/gemini-comprehensive.json b/data/evals/gemini-comprehensive.json index 8239aff..a03bc9c 100644 --- a/data/evals/gemini-comprehensive.json +++ b/data/evals/gemini-comprehensive.json @@ -307,7 +307,7 @@ }, { "id": "scenario-snowflake-full-flow", - "description": "localstack-snowflake-client: start emulator, check connection, run SQL. Runs LAST: the Snowflake stack and the AWS stack cannot run at the same time (both publish the gateway port), so the AWS emulator must be stopped first and this case leaves the Snowflake emulator running.", + "description": "localstack-snowflake-client: start emulator, check connection, run SQL. Runs LAST: the Snowflake stack and the AWS stack cannot run at the same time (both own the localstack-main container), so the AWS emulator must be stopped first and this case leaves the Snowflake emulator running.", "mode": "mcp_host", "scenario": "Work with the LocalStack Snowflake emulator: 1) Using the LocalStack management tool with service set to snowflake, start the Snowflake emulator. If it reports that it is already running, continue to step 2. If starting fails because a LocalStack container is already running, that container is the AWS emulator: stop it with the management tool, then start the Snowflake emulator with service snowflake again. If a start attempt times out, keep checking the Snowflake status with the management tool (service snowflake) until it reports ready — do not give up on a timeout. 2) Use the LocalStack Snowflake client to check the connection to the emulator. 3) Use the LocalStack Snowflake client to execute the SQL file data/sample-sql/snowflake_test.sql. 4) Run the query SHOW TABLES IN demo_db.public and tell me whether the customers table exists.", "mcpHostConfig": { diff --git a/docs/DOCKER.md b/docs/DOCKER.md index 7645360..cfa7349 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -12,7 +12,7 @@ The image is multi-arch (`linux/amd64` and `linux/arm64`). The container talks to your **host Docker daemon** through the bind-mounted `/var/run/docker.sock`. When you ask the server to start LocalStack, it creates a -**sibling** `localstack-aws` container on the host (not nested inside the MCP +**sibling** `localstack-main` container on the host (not nested inside the MCP container) directly via the Docker API. Stop/restart operations act on the detected sibling container the same way. The MCP server and the IaC CLIs reach that sibling over the host gateway. @@ -22,7 +22,7 @@ MCP client ── stdio ──► docker run … (MCP server) │ /var/run/docker.sock (mounted) ▼ host Docker daemon - └─ localstack-aws (sibling, publishes :4566 on the host) + └─ localstack-main (sibling, publishes :4566 on the host) ``` Because LocalStack is a sibling container, one thing must be configured at run time: @@ -118,7 +118,7 @@ that still pass `--add-host s3.host.docker.internal:host-gateway` keep working. - **Extra host aliases.** Include the aliases shown in the quick-start command. - **First cold start** of LocalStack can take up to ~2 minutes while the image is pulled and the runtime initializes; subsequent starts reuse the persisted volume. -- **Persistence across MCP restarts.** The sibling `localstack-aws` keeps running +- **Persistence across MCP restarts.** The sibling `localstack-main` keeps running on the host even if your editor restarts the MCP container — reconnecting finds your stack still up. State persists in the `localstack-mcp` named volume (or `LOCALSTACK_VOLUME_DIR` if you set one). @@ -129,14 +129,14 @@ that still pass `--add-host s3.host.docker.internal:host-gateway` keep working. ## Troubleshooting -| Symptom | Cause / fix | -| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Tools report `LocalStack Not Running` after `start` | Check `LOCALSTACK_HOSTNAME=host.docker.internal` is set and `--add-host` is present (Linux). | -| `Auth Token Required` | `LOCALSTACK_AUTH_TOKEN` must be passed through (every tool requires it). | -| `Docker Not Available` / daemon unreachable | Ensure `/var/run/docker.sock` is mounted (or pass `DOCKER_HOST` for a non-default daemon). | -| `LocalStack container not found` or `Could not find a running LocalStack container named "localstack-aws" or …` | Set `MAIN_CONTAINER_NAME` if you use a custom LocalStack container name. | -| State disappeared after upgrading the image | Old configs stored state under `$XDG_CACHE_HOME/localstack/volume` — keep that env var, or point `LOCALSTACK_VOLUME_DIR` at the old directory. | -| MCP server containers pile up over time | Older images did not exit when the client disconnected. Pull the latest image, then remove strays with `docker ps -aq --filter ancestor=localstack/localstack-mcp-server \| xargs docker rm -f`. | +| Symptom | Cause / fix | +| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Tools report `LocalStack Not Running` after `start` | Check `LOCALSTACK_HOSTNAME=host.docker.internal` is set and `--add-host` is present (Linux). | +| `Auth Token Required` | `LOCALSTACK_AUTH_TOKEN` must be passed through (every tool requires it). | +| `Docker Not Available` / daemon unreachable | Ensure `/var/run/docker.sock` is mounted (or pass `DOCKER_HOST` for a non-default daemon). | +| `LocalStack container not found` or `Could not find a running LocalStack container named "localstack-main"` | The server looks for `localstack-main` and lstk's `localstack-aws`, `localstack-snowflake` and `localstack-azure`. Set `MAIN_CONTAINER_NAME` if you use another name. | +| State disappeared after upgrading the image | Old configs stored state under `$XDG_CACHE_HOME/localstack/volume` — keep that env var, or point `LOCALSTACK_VOLUME_DIR` at the old directory. | +| MCP server containers pile up over time | Older images did not exit when the client disconnected. Pull the latest image, then remove strays with `docker ps -aq --filter ancestor=localstack/localstack-mcp-server \| xargs docker rm -f`. | ## Validating an image yourself diff --git a/server.json b/server.json index 53555f8..421ae1c 100644 --- a/server.json +++ b/server.json @@ -124,7 +124,7 @@ "name": "GATEWAY_LISTEN" }, { - "description": "Explicit LocalStack container name for Docker-based tools and the container created by start. Defaults to lstk's name for the stack: localstack-aws, localstack-snowflake or localstack-azure (detection also finds the older localstack-main).", + "description": "Explicit LocalStack container name for Docker-based tools and the container created by start. Defaults to localstack-main; detection also finds lstk's localstack-aws, localstack-snowflake and localstack-azure.", "isRequired": false, "format": "string", "isSecret": false, diff --git a/src/lib/docker/docker.client.test.ts b/src/lib/docker/docker.client.test.ts index 8dc862f..407bb02 100644 --- a/src/lib/docker/docker.client.test.ts +++ b/src/lib/docker/docker.client.test.ts @@ -93,7 +93,7 @@ describe("DockerApiClient", () => { ); }); - test("findLocalStackContainer still finds a container under the legacy localstack-main name", async () => { + test("findLocalStackContainer returns id when found", async () => { const mocks = getDockerMocks(); mocks.listContainers.mockResolvedValueOnce([ { Id: "abc123", Names: ["/localstack-main"], Image: "localstack/localstack:latest" }, @@ -286,7 +286,7 @@ describe("DockerApiClient", () => { const client = new DockerApiClient(); await expect(client.findLocalStackContainer()).rejects.toThrow( - /Could not find a running LocalStack container named "localstack-aws" or "localstack-snowflake" or "localstack-azure" or "localstack-main"/i + /Could not find a running LocalStack container named "localstack-main" or "localstack-aws" or "localstack-snowflake" or "localstack-azure"/i ); }); @@ -326,15 +326,15 @@ describe("DockerApiClient", () => { await expect(client.findLocalStackContainer()).resolves.toBe("snow"); }); - test("findLocalStackContainer prefers lstk's localstack-aws over the legacy localstack-main", async () => { + test("findLocalStackContainer prefers localstack-main over lstk's localstack-aws", async () => { const mocks = getDockerMocks(); mocks.listContainers.mockResolvedValueOnce([ - { Id: "legacy", Names: ["/localstack-main"], Image: "registry.example/ls:1" }, { Id: "lstk", Names: ["/localstack-aws"], Image: "registry.example/ls:1" }, + { Id: "mcp", Names: ["/localstack-main"], Image: "registry.example/ls:1" }, ]); const client = new DockerApiClient(); - await expect(client.findLocalStackContainer()).resolves.toBe("lstk"); + await expect(client.findLocalStackContainer()).resolves.toBe("mcp"); }); test("stopContainer stops the container via the Docker API", async () => { diff --git a/src/lib/localstack/container-spec.logic.test.ts b/src/lib/localstack/container-spec.logic.test.ts index 8d9a074..3c45688 100644 --- a/src/lib/localstack/container-spec.logic.test.ts +++ b/src/lib/localstack/container-spec.logic.test.ts @@ -75,28 +75,22 @@ test("the Azure emulator's LS_AZURE_ settings reach the Azure stack only; the Az }); describe("resolveContainerName", () => { - test("defaults to lstk's localstack-{stack} name", () => { - // lstk's ContainerConfig.defaultName: "localstack-" + emulator type (internal/config/containers.go). - expect(resolveContainerName({}, "aws")).toBe("localstack-aws"); - expect(resolveContainerName({}, "snowflake")).toBe("localstack-snowflake"); - expect(resolveContainerName({}, "azure")).toBe("localstack-azure"); - }); - - test("honors MAIN_CONTAINER_NAME for every stack", () => { - for (const stack of ["aws", "snowflake", "azure"] as const) { - expect(resolveContainerName({ MAIN_CONTAINER_NAME: "my-ls" }, stack)).toBe("my-ls"); - expect(resolveContainerName({ LOCALSTACK_MAIN_CONTAINER_NAME: "ls2" }, stack)).toBe("ls2"); - } + test("defaults to localstack-main and honors MAIN_CONTAINER_NAME", () => { + expect(resolveContainerName({})).toBe("localstack-main"); + expect(resolveContainerName({ MAIN_CONTAINER_NAME: "my-ls" })).toBe("my-ls"); + expect(resolveContainerName({ LOCALSTACK_MAIN_CONTAINER_NAME: "ls2" })).toBe("ls2"); }); }); describe("stackContainerNames", () => { - test("lists the stack's lstk name and the legacy localstack-main when nothing is configured", () => { - expect(stackContainerNames({}, "aws")).toEqual(["localstack-aws", "localstack-main"]); + test("lists localstack-main and the stack's lstk name when nothing is configured", () => { + // lstk's ContainerConfig.defaultName: "localstack-" + emulator type (internal/config/containers.go). + expect(stackContainerNames({}, "aws")).toEqual(["localstack-main", "localstack-aws"]); expect(stackContainerNames({}, "snowflake")).toEqual([ - "localstack-snowflake", "localstack-main", + "localstack-snowflake", ]); + expect(stackContainerNames({}, "azure")).toEqual(["localstack-main", "localstack-azure"]); }); test("lists only the configured name when MAIN_CONTAINER_NAME is set", () => { @@ -376,7 +370,7 @@ describe("buildLocalStackContainerSpec", () => { expect(env.LOCALSTACK_IMAGE_NAME).toBeUndefined(); expect(env.UNRELATED_VAR).toBeUndefined(); expect(env.LOCALSTACK_AUTH_TOKEN).toBe("ls-real-token"); - expect(env.MAIN_CONTAINER_NAME).toBe("localstack-aws"); + expect(env.MAIN_CONTAINER_NAME).toBe("localstack-main"); expect(env.DOCKER_HOST).toBe("unix:///var/run/docker.sock"); expect(env.LOCALSTACK_CLIENT_NAME).toBe("localstack-mcp-server"); expect(env.LOCALSTACK_CLIENT_VERSION).toBe("0.5.0"); @@ -463,17 +457,10 @@ describe("buildLocalStackContainerSpec", () => { expect(buildLocalStackContainerSpec(baseInput()).HostConfig.AutoRemove).toBe(true); }); - test("snowflake stack: snowflake image, lstk's snowflake container name", () => { + test("snowflake stack: snowflake image, same container name", () => { const spec = buildLocalStackContainerSpec(baseInput({ stack: "snowflake" })); expect(spec.Image).toBe("localstack/snowflake:latest"); - expect(spec.name).toBe("localstack-snowflake"); - expect(envMap(spec).MAIN_CONTAINER_NAME).toBe("localstack-snowflake"); - }); - - test("azure stack: lstk's azure container name", () => { - const spec = buildLocalStackContainerSpec(baseInput({ stack: "azure" })); - expect(spec.name).toBe("localstack-azure"); - expect(envMap(spec).MAIN_CONTAINER_NAME).toBe("localstack-azure"); + expect(spec.name).toBe("localstack-main"); }); test("restart recreation can pin the original image and name", () => { diff --git a/src/lib/localstack/container-spec.logic.ts b/src/lib/localstack/container-spec.logic.ts index c47b251..0864623 100644 --- a/src/lib/localstack/container-spec.logic.ts +++ b/src/lib/localstack/container-spec.logic.ts @@ -1,13 +1,12 @@ /** * Pure builder for the LocalStack container spec (dockerode `createContainer` options). * - * Builds the runtime container without any CLI installed. The container name follows - * lstk (`internal/config/containers.go`, `ContainerConfig.defaultName`); the other - * behavioral anchors were verified against the 2026.x `localstack_cli` wheel source: + * Replicates what `localstack start` used to assemble via the Python CLI so the MCP + * server can create the runtime with no CLI installed. Behavioral anchors (verified + * against the 2026.x `localstack_cli` wheel source): * - image `localstack/localstack-pro:latest` (pro unconditional), `--stack snowflake` * ⇒ `localstack/snowflake:latest` - * - container name `localstack-{stack}` (lstk's default: `localstack-aws`, - * `localstack-snowflake`, `localstack-azure`), also injected as `MAIN_CONTAINER_NAME` env + * - container name `localstack-main`, also injected as `MAIN_CONTAINER_NAME` env * - ports 4566, 443 (only when GATEWAY_LISTEN is unset) and the external service * range 4510–4560 inclusive; bind host 127.0.0.1 on a host, 0.0.0.0 in Docker * - volume dir → /var/lib/localstack, docker socket → /var/run/docker.sock @@ -91,22 +90,26 @@ const AI_AGENT_DETECTORS: Array<[string, string[]]> = [ export type LocalStackStack = "aws" | "snowflake" | "azure"; -/** lstk's default container name per stack (`localstack-{type}`). */ -export const DEFAULT_CONTAINER_NAMES: Readonly> = { +/** The name the start action gives a new container when MAIN_CONTAINER_NAME is unset. */ +export const DEFAULT_CONTAINER_NAME = "localstack-main"; + +/** + * lstk's default container name per stack (`localstack-{type}`, from + * `ContainerConfig.defaultName` in lstk's `internal/config/containers.go`). The server + * does not create containers under these names, but finds and manages ones lstk started. + */ +export const LSTK_CONTAINER_NAMES: Readonly> = { aws: "localstack-aws", snowflake: "localstack-snowflake", azure: "localstack-azure", }; -/** The name earlier versions of this server (and the legacy CLI) gave the container. */ -export const LEGACY_CONTAINER_NAME = "localstack-main"; - /** Names a LocalStack container may have when no MAIN_CONTAINER_NAME is configured. */ export const KNOWN_CONTAINER_NAMES: readonly string[] = [ - DEFAULT_CONTAINER_NAMES.aws, - DEFAULT_CONTAINER_NAMES.snowflake, - DEFAULT_CONTAINER_NAMES.azure, - LEGACY_CONTAINER_NAME, + DEFAULT_CONTAINER_NAME, + LSTK_CONTAINER_NAMES.aws, + LSTK_CONTAINER_NAMES.snowflake, + LSTK_CONTAINER_NAMES.azure, ]; export type VolumeResolution = { type: "bind"; source: string } | { type: "volume"; name: string }; @@ -180,24 +183,21 @@ export function configuredContainerName( ); } -/** The name for a new container of this stack: the configured one, else lstk's default. */ -export function resolveContainerName( - hostEnv: Record, - stack: LocalStackStack -): string { - return configuredContainerName(hostEnv) || DEFAULT_CONTAINER_NAMES[stack]; +/** The name for a new container: the configured one, else `localstack-main`. */ +export function resolveContainerName(hostEnv: Record): string { + return configuredContainerName(hostEnv) || DEFAULT_CONTAINER_NAME; } /** - * Names a stopped container of this stack may hold: the configured name, else the - * stack's lstk name and the legacy `localstack-main`. + * Names a stopped container of this stack may hold: the configured name, else + * `localstack-main` and the stack's lstk name. */ export function stackContainerNames( hostEnv: Record, stack: LocalStackStack ): string[] { const configured = configuredContainerName(hostEnv); - return configured ? [configured] : [DEFAULT_CONTAINER_NAMES[stack], LEGACY_CONTAINER_NAME]; + return configured ? [configured] : [DEFAULT_CONTAINER_NAME, LSTK_CONTAINER_NAMES[stack]]; } function parsePort(text: string, context: string): number { @@ -504,8 +504,7 @@ function buildEnv(input: ContainerSpecInput, ports: ResolvedPorts, name: string) } export function buildLocalStackContainerSpec(input: ContainerSpecInput): LocalStackContainerSpec { - const name = - input.containerNameOverride?.trim() || resolveContainerName(input.hostEnv, input.stack); + const name = input.containerNameOverride?.trim() || resolveContainerName(input.hostEnv); const image = input.imageOverride?.trim() || resolveImage(input.stack, input.hostEnv); const ports = resolvePorts(input); diff --git a/src/lib/localstack/localstack.utils.test.ts b/src/lib/localstack/localstack.utils.test.ts index 50caecb..d19313c 100644 --- a/src/lib/localstack/localstack.utils.test.ts +++ b/src/lib/localstack/localstack.utils.test.ts @@ -294,7 +294,7 @@ describe("localstack.utils", () => { expect(client.createAndStartContainer).toHaveBeenCalledTimes(1); const spec = client.createAndStartContainer.mock.calls[0][0]; expect(spec.Image).toBe("localstack/localstack-pro:latest"); - expect(spec.name).toBe("localstack-aws"); + expect(spec.name).toBe("localstack-main"); }); test("pulls the image when missing", async () => { @@ -330,9 +330,9 @@ describe("localstack.utils", () => { expect(client.createAndStartContainer).not.toHaveBeenCalled(); }); - test("reports a conflict when another stack's container runs under its own lstk name", async () => { - // Each stack has its own name, so starting Snowflake must still notice a running - // localstack-aws: both publish the gateway port. + test("reports a conflict when an lstk container runs under its own name", async () => { + // lstk names the container localstack-aws, so the localstack-main name check alone + // would miss it; both publish the gateway port. const { client } = mockDockerClient({ findContainerByNameAnyState: jest.fn(async (name: string) => name === "localstack-aws" @@ -362,10 +362,10 @@ describe("localstack.utils", () => { expect(client.createAndStartContainer).not.toHaveBeenCalled(); }); - test("reports a conflict when a container runs under the legacy localstack-main name", async () => { + test("reports a conflict when lstk's Azure container holds the gateway port", async () => { const { client } = mockDockerClient({ findContainerByNameAnyState: jest.fn(async (name: string) => - name === "localstack-main" + name === "localstack-azure" ? { id: "old-1", name, @@ -380,7 +380,7 @@ describe("localstack.utils", () => { const getStatus = jest.fn().mockResolvedValue({ isRunning: false }); const result = await launchRuntime({ ...launchDefaults, getStatus, dockerClient: client }); - expect(result.content[0].text).toContain('named "localstack-main"'); + expect(result.content[0].text).toContain('named "localstack-azure"'); expect(client.createAndStartContainer).not.toHaveBeenCalled(); }); @@ -413,14 +413,14 @@ describe("localstack.utils", () => { dockerClient: client, }); expect(result.content[0].text).toContain("started successfully"); - expect(client.createAndStartContainer.mock.calls[0][0].name).toBe("localstack-snowflake"); + expect(client.createAndStartContainer.mock.calls[0][0].name).toBe("localstack-main"); }); test("leaves stopped containers of other names alone", async () => { const { client } = mockDockerClient({ findContainerByNameAnyState: jest.fn(async (name: string) => - name === "localstack-main" - ? { id: "old-stopped", name, state: "exited", running: false } + name === "localstack-aws" + ? { id: "lstk-stopped", name, state: "exited", running: false, publicPorts: [] } : null ), }); diff --git a/src/lib/localstack/localstack.utils.ts b/src/lib/localstack/localstack.utils.ts index 29b15b7..eeecca1 100644 --- a/src/lib/localstack/localstack.utils.ts +++ b/src/lib/localstack/localstack.utils.ts @@ -487,10 +487,10 @@ async function launchRuntimeInner( // Fail fast (or clean up) when the container name is taken. A running container is // an actionable conflict; a stopped one is a stale leftover we remove ourselves. - // Each stack has its own default name (lstk's `localstack-{type}`), so a running - // container under another known name (another stack, or the legacy `localstack-main`) - // is a conflict too when it publishes a host port this start binds. One on other - // ports (a second emulator on its own GATEWAY_LISTEN) may keep running. + // lstk names its containers `localstack-{type}`, so a running container under + // another known name is a conflict too when it publishes a host port this start + // binds. One on other ports (a second emulator on its own GATEWAY_LISTEN) may keep + // running. // Short timeouts: this is pre-start housekeeping — a hung daemon should surface // as an error in seconds, not block the start for two minutes. try { diff --git a/src/lib/logs/log-retriever.test.ts b/src/lib/logs/log-retriever.test.ts index a58d798..a95bd50 100644 --- a/src/lib/logs/log-retriever.test.ts +++ b/src/lib/logs/log-retriever.test.ts @@ -51,7 +51,7 @@ describe("LocalStackLogRetriever", () => { .fn() .mockRejectedValue( new actual.LocalStackContainerNotFoundError( - 'Could not find a running LocalStack container named "localstack-aws".' + 'Could not find a running LocalStack container named "localstack-main".' ) ), }); diff --git a/src/tools-tests/localstack-management.test.ts b/src/tools-tests/localstack-management.test.ts index dce7ce0..ab8a95c 100644 --- a/src/tools-tests/localstack-management.test.ts +++ b/src/tools-tests/localstack-management.test.ts @@ -121,8 +121,8 @@ describe("localstack-management", () => { await localstackManagement({ action: "stop", service: "aws" } as any); expect(findContainerByNameAnyState.mock.calls.map(([name]) => name)).toEqual([ - "localstack-aws", "localstack-main", + "localstack-aws", ]); expect(removeContainer).not.toHaveBeenCalled(); }); diff --git a/src/tools/localstack-management.ts b/src/tools/localstack-management.ts index ffd99a6..9638202 100644 --- a/src/tools/localstack-management.ts +++ b/src/tools/localstack-management.ts @@ -258,7 +258,7 @@ async function handleStop({ service }: { service: Service }) { // Handle restart action — stop the running container, then start fresh (applies any // new envVars). The recreate reuses the original container's image, name, and volume -// so an externally-provisioned runtime (a legacy localstack-main, custom names/images) +// so an externally-provisioned runtime (lstk's localstack-aws, custom names/images) // is not silently replaced by our defaults — that would strand its state. async function handleRestart({ envVars, From 25bb0c225d834d322df8099aa86657e69eca8f8a Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Wed, 18 Nov 2026 14:29:58 +0100 Subject: [PATCH 3/7] Match lstk's tagged and custom-named containers by its label lstk names a container localstack-{type}-{tag} when the tag is not latest, and users can set any container_name. Recognize those names only with the cloud.localstack.lstk=true label lstk sets, because LocalStack names its Lambda containers after its own container (localstack-aws-dev-lambda-...). - Detection, the start conflict check and the stop cleanup share one ranking: localstack-main, lstk's latest names, tagged names, then any other lstk container. - A LocalStack image on the gateway port beats a known container off it. - The stop cleanup removes lstk's names only when they carry the label. - Restart keeps lstk's labels. - The conflict message names shared ports and same-stack containers. - The README documents lstk's container_name = "localstack-main" and the separate state directories. Co-Authored-By: Claude Opus 5.5 --- README.md | 67 ++++--- docs/DOCKER.md | 2 +- server.json | 2 +- src/lib/docker/docker.client.test.ts | 167 +++++++++++++++++- src/lib/docker/docker.client.ts | 123 ++++++++++--- .../localstack/container-spec.logic.test.ts | 98 +++++++++- src/lib/localstack/container-spec.logic.ts | 99 ++++++++--- src/lib/localstack/localstack.utils.test.ts | 134 +++++++++----- src/lib/localstack/localstack.utils.ts | 89 +++++++--- src/tools-tests/localstack-management.test.ts | 67 ++++--- src/tools/localstack-management.ts | 17 +- 11 files changed, 694 insertions(+), 171 deletions(-) diff --git a/README.md b/README.md index 7976caf..4a4b4fa 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ This server provides your AI with dedicated tools for managing your LocalStack e | [`localstack-cloud-pods`](./src/tools/localstack-cloud-pods.ts) | Manages remote LocalStack Cloud Pods for development workflows | - Save current state as a Cloud Pod
- Load previously saved Cloud Pods instantly
- Delete Cloud Pods from remote cloud-backed storage
- Use this for managed remote state snapshots, not local export/import files
- Requires a valid LocalStack Auth Token | | [`localstack-state-management`](./src/tools/localstack-state-management.ts) | Manages local file-based LocalStack state export/import workflows | - Export LocalStack state to a local file on disk through the LocalStack State REST API
- Import LocalStack state from a local file
- Inspect current LocalStack state as JSON metamodel data
- Reset all state or only selected services
- Supports service-level granularity for export, reset, and inspect
- Use this for local disk workflows; use Cloud Pods for remote cloud-backed snapshots
- Requires a valid LocalStack Auth Token | | [`localstack-extensions`](./src/tools/localstack-extensions.ts) | Installs, uninstalls, lists, and discovers LocalStack Extensions | - Manage installed extensions (`list`, `install`, `uninstall`) inside the running container
- Browse the LocalStack Extensions marketplace (`available`)
- Requires a valid LocalStack Auth Token | -| [`localstack-ephemeral-instances`](./src/tools/localstack-ephemeral-instances.ts) | Manages cloud-hosted LocalStack Ephemeral Instances | - Create temporary cloud-hosted LocalStack instances and get an endpoint URL
- List available ephemeral instances, fetch logs, and delete instances
- Supports lifetime, extension preload, Cloud Pod preload, and custom env vars on create
- Requires a valid LocalStack Auth Token | +| [`localstack-ephemeral-instances`](./src/tools/localstack-ephemeral-instances.ts) | Manages cloud-hosted LocalStack Ephemeral Instances | - Create temporary cloud-hosted LocalStack instances and get an endpoint URL
- List available ephemeral instances, fetch logs, and delete instances
- Supports lifetime, extension preload, Cloud Pod preload, and custom env vars on create
- Requires a valid LocalStack Auth Token | | [`localstack-aws-client`](./src/tools/localstack-aws-client.ts) | Runs AWS CLI commands inside the LocalStack for AWS container | - Executes commands via `awslocal` inside the running container
- Sanitizes commands to block shell chaining
- Auto-detects LocalStack coverage errors and links to docs | | [`localstack-azure-client`](./src/tools/localstack-azure-client.ts) | Runs Azure CLI (`az`) commands against the LocalStack for Azure emulator | - Runs the Azure CLI installed on your machine with its own profile, never your Azure login
- Blocks shell syntax and commands that would change the profile, install software or never end
- Uses the extensions you installed with `az extension add`
- Requires the Azure CLI and a valid LocalStack Auth Token | | [`localstack-aws-replicator`](./src/tools/localstack-aws-replicator.ts) | Replicates external AWS resources into a running LocalStack instance | - Start single-resource replication jobs with a resource type and identifier or ARN
- Start batch replication jobs, such as SSM parameters under a path prefix
- Poll job status by job ID and list existing jobs
- List resource types supported by the running Replicator extension
- Reads source AWS credentials from the MCP server environment and supports optional target account or region overrides | @@ -207,28 +207,28 @@ See **[docs/DOCKER.md](./docs/DOCKER.md)** for the run command, MCP client confi ## LocalStack configuration -| Variable Name | Description | Default Value | -| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -| `LOCALSTACK_AUTH_TOKEN` (**required**) | The LocalStack Auth Token to use for the MCP server | None | -| `LOCALSTACK_HOSTNAME` | Host name of the LocalStack gateway the tools call; in Docker, `host.docker.internal`. The Azure tool always calls `azure.localhost.localstack.cloud` (127.0.0.1), so it needs a local gateway. | `localhost` | -| `LOCALSTACK_PORT` | Port of the LocalStack gateway the tools call. | `4566` | -| `MAIN_CONTAINER_NAME` | The LocalStack container name for Docker-based tools and for the container `start` creates. When unset, `start` names it `localstack-main`, and the tools find a container named `localstack-main` or one of lstk's names (`localstack-aws`, `localstack-snowflake`, `localstack-azure`), then by LocalStack image. | Auto-detect | -| `LOCALSTACK_IMAGE_NAME` / `IMAGE_NAME` | Docker image the `start` action launches for the AWS stack. `LOCALSTACK_IMAGE_NAME` wins when both are set (beware: bare `IMAGE_NAME` is a common CI variable). | `localstack/localstack-pro:latest` | -| `LOCALSTACK_VOLUME_DIR` | Host directory mounted at `/var/lib/localstack` in the LocalStack container. Defaults to the same per-OS cache path the LocalStack CLI used (state carries over); inside Docker it defaults to the `localstack-mcp` named volume. | Per-OS cache dir | -| `GATEWAY_LISTEN` | Override the gateway port bindings for `start` (comma-separated `[host]:port`). When set, the implicit `443` binding is skipped. | `:4566,:443` | -| `DOCKER_HOST` | Docker daemon endpoint used for all container operations (`unix://`, `npipe://`, `tcp://`). | Platform default socket | -| `DOCKER_SOCK` | Host path of the Docker socket mounted into the LocalStack container (for Lambda). Validated to exist when set explicitly. | `/var/run/docker.sock` | -| `EXTERNAL_SERVICE_PORTS_START` / `_END` | Inclusive host port range published for external services on `start`. Validated (1–65535, start ≤ end). | `4510` / `4560` | -| `MCP_ANALYTICS_DISABLED` | Disable MCP analytics when set to `1` | `0` | -| `APP_INSPECTOR` | Set to `1` in the LocalStack container environment to enable App Inspector by default across restarts. The MCP tool can also toggle App Inspector at runtime with `set-status`. | `0` | -| `AWS_ACCESS_KEY_ID` (**required for AWS Replicator tool**) | Source AWS access key used by AWS Replicator to read external AWS resources | None | -| `AWS_SECRET_ACCESS_KEY` (**required for AWS Replicator tool**) | Source AWS secret access key used by AWS Replicator to read external AWS resources | None | -| `AWS_DEFAULT_REGION` (**required for AWS Replicator tool**) | Source AWS region used by AWS Replicator | None | -| `LOCALSTACK_AZURE_IMAGE_NAME` | Docker image the `start` action launches for the Azure stack (default `localstack/localstack-azure:latest`). | Latest Azure image | -| `LOCALSTACK_AZ_PATH` | The `az` launcher, or the Azure CLI's Python, for the Azure tool. | Found on `PATH` | -| `LOCALSTACK_AZ_CONFIG_DIR` | The Azure tool's own Azure CLI profile directory (default `~/.localstack/azure/mcp-config-`); it must not overlap your `~/.azure`. | Under `~/.localstack/azure` | -| `LOCALSTACK_AZ_WORKDIR` | The directory the Azure tool runs `az` in; relative file paths resolve against it. | The server's working directory | -| `LOCALSTACK_AZ_TIMEOUT_SECONDS` | Time limit for one Azure CLI command (5–3600). | `300` | +| Variable Name | Description | Default Value | +| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | +| `LOCALSTACK_AUTH_TOKEN` (**required**) | The LocalStack Auth Token to use for the MCP server | None | +| `LOCALSTACK_HOSTNAME` | Host name of the LocalStack gateway the tools call; in Docker, `host.docker.internal`. The Azure tool always calls `azure.localhost.localstack.cloud` (127.0.0.1), so it needs a local gateway. | `localhost` | +| `LOCALSTACK_PORT` | Port of the LocalStack gateway the tools call. | `4566` | +| `MAIN_CONTAINER_NAME` | Container name for Docker-based tools and the container `start` creates. When unset, `start` uses `localstack-main`; the tools find it, lstk's containers, then LocalStack images ([lstk](#using-lstk)). | Auto-detect | +| `LOCALSTACK_IMAGE_NAME` / `IMAGE_NAME` | Docker image the `start` action launches for the AWS stack. `LOCALSTACK_IMAGE_NAME` wins when both are set (beware: bare `IMAGE_NAME` is a common CI variable). | `localstack/localstack-pro:latest` | +| `LOCALSTACK_VOLUME_DIR` | Host directory mounted at `/var/lib/localstack` in the LocalStack container. Defaults to the same per-OS cache path the LocalStack CLI used (state carries over); inside Docker it defaults to the `localstack-mcp` named volume. | Per-OS cache dir | +| `GATEWAY_LISTEN` | Override the gateway port bindings for `start` (comma-separated `[host]:port`). When set, the implicit `443` binding is skipped. | `:4566,:443` | +| `DOCKER_HOST` | Docker daemon endpoint used for all container operations (`unix://`, `npipe://`, `tcp://`). | Platform default socket | +| `DOCKER_SOCK` | Host path of the Docker socket mounted into the LocalStack container (for Lambda). Validated to exist when set explicitly. | `/var/run/docker.sock` | +| `EXTERNAL_SERVICE_PORTS_START` / `_END` | Inclusive host port range published for external services on `start`. Validated (1–65535, start ≤ end). | `4510` / `4560` | +| `MCP_ANALYTICS_DISABLED` | Disable MCP analytics when set to `1` | `0` | +| `APP_INSPECTOR` | Set to `1` in the LocalStack container environment to enable App Inspector by default across restarts. The MCP tool can also toggle App Inspector at runtime with `set-status`. | `0` | +| `AWS_ACCESS_KEY_ID` (**required for AWS Replicator tool**) | Source AWS access key used by AWS Replicator to read external AWS resources | None | +| `AWS_SECRET_ACCESS_KEY` (**required for AWS Replicator tool**) | Source AWS secret access key used by AWS Replicator to read external AWS resources | None | +| `AWS_DEFAULT_REGION` (**required for AWS Replicator tool**) | Source AWS region used by AWS Replicator | None | +| `LOCALSTACK_AZURE_IMAGE_NAME` | Docker image the `start` action launches for the Azure stack (default `localstack/localstack-azure:latest`). | Latest Azure image | +| `LOCALSTACK_AZ_PATH` | The `az` launcher, or the Azure CLI's Python, for the Azure tool. | Found on `PATH` | +| `LOCALSTACK_AZ_CONFIG_DIR` | The Azure tool's own Azure CLI profile directory (default `~/.localstack/azure/mcp-config-`); it must not overlap your `~/.azure`. | Under `~/.localstack/azure` | +| `LOCALSTACK_AZ_WORKDIR` | The directory the Azure tool runs `az` in; relative file paths resolve against it. | The server's working directory | +| `LOCALSTACK_AZ_TIMEOUT_SECONDS` | Time limit for one Azure CLI command (5–3600). | `300` | See **[docs/AZURE.md](./docs/AZURE.md)** for how the Azure tool runs the Azure CLI. @@ -239,10 +239,29 @@ Since v0.6.0 the MCP server no longer uses (or requires) the `localstack` CLI. T - `~/.localstack/*.env` config profiles and `DOCKER_FLAGS` are **not** read at start. Pass configuration through the `envVars` argument of the `localstack-management` start action, or set `LOCALSTACK_`-prefixed variables in the MCP server's environment (LocalStack aliases `LOCALSTACK_` to `` natively). - Besides `LOCALSTACK_*`/`PROVIDER_OVERRIDE_*`, only a curated set of common unprefixed config variables is forwarded from the host environment (`DEBUG`, `LS_LOG`, `SERVICES`, `PERSISTENCE`, `EAGER_SERVICE_LOADING`, `ENFORCE_IAM`, `IAM_SOFT_MODE`, `EXTENSION_AUTO_INSTALL`, `APP_INSPECTOR`, `DNS_ADDRESS`, `MAIN_DOCKER_NETWORK`, and the `LAMBDA_*`/`CFN_*`/`SNOWFLAKE_*`/`SF_*` families). - Port 443 is published by default. If something else uses port 443 locally, set `GATEWAY_LISTEN=:4566` to skip it. -- The container the server creates is named `localstack-main`. A container lstk started (`localstack-aws`, `localstack-snowflake` or `localstack-azure`) is detected and managed too: `stop` and `status` act on it, `restart` keeps its name, image and volume, and `start` reports it as a conflict when it holds the ports `start` needs. +- The container the server creates is named `localstack-main`, not lstk's `localstack-aws`. See [Using lstk](#using-lstk). For AWS Replicator-specific source credentials, you can use the `AWS_REPLICATOR_SOURCE_` prefixed variants instead of the unprefixed variants. Do not mix the prefixed and unprefixed source credential groups; when any `AWS_REPLICATOR_SOURCE_` variable is set, the Replicator tool reads the source configuration only from that group. +### Using lstk + +[lstk](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/) names its container `localstack-{type}`, such as `localstack-aws`, or `localstack-{type}-{tag}` when it runs a pinned tag. The server names the container it creates `localstack-main`. It finds lstk's containers under these names, or under any name by the `cloud.localstack.lstk` label lstk sets. + +To have both tools manage one container, set lstk's [`container_name`](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/configuration/) to `localstack-main`: + +```toml +[[containers]] +type = "aws" +port = "4566" +container_name = "localstack-main" +``` + +Then lstk finds the container by name, whichever tool started it. + +Without that setting, the server still finds and manages lstk's container: `stop` and `status` act on it, `restart` keeps its name, image, volume and lstk's labels (the gateway moves to `LOCALSTACK_PORT`, where the tools reach it), and `start` reports it as a conflict when it holds a port `start` needs. lstk, for its part, falls back to the first running container with a standard LocalStack image that publishes port 4566, so it may find the server's container, or another one when several run. + +The two tools keep state in different directories, even under one container name. lstk uses `/lstk/volume/`, which does not change with `container_name`, and the server uses the LocalStack CLI's `/localstack/volume`. To share state, point one at the other: set `volume` in lstk's config, or `LOCALSTACK_VOLUME_DIR` for the server. + ## Contributing Built on the [XMCP](https://github.com/basementstudio/xmcp) framework, you can add new tools by adding a new file to the `src/tools` directory and documenting it in the `manifest.json` file. diff --git a/docs/DOCKER.md b/docs/DOCKER.md index cfa7349..ca4a5d2 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -134,7 +134,7 @@ that still pass `--add-host s3.host.docker.internal:host-gateway` keep working. | Tools report `LocalStack Not Running` after `start` | Check `LOCALSTACK_HOSTNAME=host.docker.internal` is set and `--add-host` is present (Linux). | | `Auth Token Required` | `LOCALSTACK_AUTH_TOKEN` must be passed through (every tool requires it). | | `Docker Not Available` / daemon unreachable | Ensure `/var/run/docker.sock` is mounted (or pass `DOCKER_HOST` for a non-default daemon). | -| `LocalStack container not found` or `Could not find a running LocalStack container named "localstack-main"` | The server looks for `localstack-main` and lstk's `localstack-aws`, `localstack-snowflake` and `localstack-azure`. Set `MAIN_CONTAINER_NAME` if you use another name. | +| `LocalStack container not found` or `Could not find a running LocalStack container named "localstack-main"` | The server finds `localstack-main`, `localstack-{type}` and containers lstk started. Set `MAIN_CONTAINER_NAME` for another name ([lstk](../README.md#using-lstk)). | | State disappeared after upgrading the image | Old configs stored state under `$XDG_CACHE_HOME/localstack/volume` — keep that env var, or point `LOCALSTACK_VOLUME_DIR` at the old directory. | | MCP server containers pile up over time | Older images did not exit when the client disconnected. Pull the latest image, then remove strays with `docker ps -aq --filter ancestor=localstack/localstack-mcp-server \| xargs docker rm -f`. | diff --git a/server.json b/server.json index 421ae1c..d245d77 100644 --- a/server.json +++ b/server.json @@ -124,7 +124,7 @@ "name": "GATEWAY_LISTEN" }, { - "description": "Explicit LocalStack container name for Docker-based tools and the container created by start. Defaults to localstack-main; detection also finds lstk's localstack-aws, localstack-snowflake and localstack-azure.", + "description": "Explicit LocalStack container name for Docker-based tools and the container created by start. Defaults to localstack-main; detection also finds containers lstk started, such as localstack-aws.", "isRequired": false, "format": "string", "isSecret": false, diff --git a/src/lib/docker/docker.client.test.ts b/src/lib/docker/docker.client.test.ts index 407bb02..c82dbd3 100644 --- a/src/lib/docker/docker.client.test.ts +++ b/src/lib/docker/docker.client.test.ts @@ -286,7 +286,7 @@ describe("DockerApiClient", () => { const client = new DockerApiClient(); await expect(client.findLocalStackContainer()).rejects.toThrow( - /Could not find a running LocalStack container named "localstack-main" or "localstack-aws" or "localstack-snowflake" or "localstack-azure"/i + /Could not find a running LocalStack container named "localstack-main", "localstack-aws", "localstack-snowflake" or "localstack-azure", or a container lstk started/i ); }); @@ -303,8 +303,169 @@ describe("DockerApiClient", () => { } }); + test("findLocalStackContainer matches lstk's names with a pinned tag", async () => { + // lstk names the container localstack-{type}-{tag} when the tag is not "latest". + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { Id: "other", Names: ["/localstack-gcp"], Image: "localstack/snowflake-next:latest" }, + { + Id: "snow-tagged", + Names: ["/localstack-snowflake-1.4"], + Image: "localstack/snowflake-next:1.4", + Labels: { "cloud.localstack.lstk": "true" }, + }, + ]); + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).resolves.toBe("snow-tagged"); + }); + + test("findLocalStackContainer skips Lambda containers named after a tagged lstk container", async () => { + // LocalStack names Lambda containers "-lambda-...", without lstk's label. + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { + Id: "fn", + Names: ["/localstack-aws-dev-lambda-fn-1234"], + Image: "public.ecr.aws/lambda/python:3.13", + }, + { + Id: "lstk-dev", + Names: ["/localstack-aws-dev"], + Image: "sha256:a4a2ec94512d", + Labels: { "cloud.localstack.lstk": "true" }, + }, + ]); + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).resolves.toBe("lstk-dev"); + }); + + test("findLocalStackContainer finds an lstk container with a custom container_name", async () => { + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { + Id: "custom", + Names: ["/my-ls"], + Image: "registry.example/ls:1", + Labels: { "cloud.localstack.lstk": "true" }, + }, + ]); + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).resolves.toBe("custom"); + }); + + test("findLocalStackContainer prefers lstk's latest name over a tagged one", async () => { + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { + Id: "tagged", + Names: ["/localstack-aws-2026.4"], + Image: "registry.example/ls:1", + Labels: { "cloud.localstack.lstk": "true" }, + }, + { Id: "latest", Names: ["/localstack-aws"], Image: "registry.example/ls:1" }, + ]); + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).resolves.toBe("latest"); + }); + + test("listKnownLocalStackContainers returns known names in any state, in detection order", async () => { + const mocks = getDockerMocks(); + const custom = { + Id: "c", + Names: ["/my-ls"], + State: "exited", + Labels: { "cloud.localstack.lstk": "true" }, + }; + mocks.listContainers.mockImplementation(async (opts: any) => + opts.filters?.label ? [custom, byName.find((c) => c.Id === "a")] : byName + ); + const byName: any[] = [ + { Id: "s", Names: ["/localstack-snowflake"], State: "exited" }, + { Id: "x", Names: ["/localstack-mcp-server-1"], State: "running" }, + { Id: "fn", Names: ["/localstack-aws-2026.4-lambda-fn-1"], State: "created" }, + { + Id: "a", + Names: ["/localstack-aws-2026.4"], + State: "running", + Image: "localstack/localstack-pro:2026.4", + Labels: { "cloud.localstack.lstk": "true" }, + Ports: [{ PrivatePort: 4566, PublicPort: 4566, Type: "tcp" }, { PrivatePort: 53 }], + }, + { Id: "m", Names: ["/localstack-main"], State: "created" }, + ]; + const client = new DockerApiClient(); + const found = await client.listKnownLocalStackContainers(); + expect(mocks.listContainers).toHaveBeenCalledWith({ + all: true, + filters: { name: ["localstack-"] }, + }); + expect(mocks.listContainers).toHaveBeenCalledWith({ + all: true, + filters: { label: ["cloud.localstack.lstk=true"] }, + }); + expect(found).toEqual([ + { + id: "m", + name: "localstack-main", + state: "created", + image: undefined, + running: false, + publicPorts: [], + }, + { + id: "a", + name: "localstack-aws-2026.4", + state: "running", + image: "localstack/localstack-pro:2026.4", + running: true, + labels: { "cloud.localstack.lstk": "true" }, + publicPorts: [4566], + }, + { + id: "s", + name: "localstack-snowflake", + state: "exited", + image: undefined, + running: false, + publicPorts: [], + }, + { + id: "c", + name: "my-ls", + state: "exited", + image: undefined, + running: false, + labels: { "cloud.localstack.lstk": "true" }, + publicPorts: [], + }, + ]); + }); + + test("findLocalStackContainer prefers a LocalStack image on the gateway port over a known name off it", async () => { + // The HTTP tools talk to the gateway port (4566), so Docker actions must target the + // container behind it, not lstk's container from another project on 4567. + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { + Id: "lstk-other-project", + Names: ["/localstack-aws-4.0"], + Image: "localstack/localstack-pro:4.0", + Labels: { "cloud.localstack.lstk": "true" }, + Ports: [{ PrivatePort: 4566, PublicPort: 4567, Type: "tcp" }], + }, + { + Id: "compose", + Names: ["/my-ls"], + Image: "localstack/localstack-pro:latest", + Ports: [{ PrivatePort: 4566, PublicPort: 4566, Type: "tcp" }], + }, + ]); + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).resolves.toBe("compose"); + }); + test("findLocalStackContainer picks the known name on the configured gateway port", async () => { - // lstk can run localstack-aws on 4566 and localstack-snowflake on 4567 at once. + // lstk in two projects can run localstack-aws on 4566 and localstack-snowflake on 4567. process.env.LOCALSTACK_PORT = "4567"; const mocks = getDockerMocks(); mocks.listContainers.mockResolvedValueOnce([ @@ -381,6 +542,7 @@ describe("DockerApiClient", () => { Config: { Image: "localstack/localstack-pro:latest", Env: ["MAIN_CONTAINER_NAME=localstack-aws"], + Labels: { "cloud.localstack.lstk": "true" }, }, Mounts: [ { @@ -397,6 +559,7 @@ describe("DockerApiClient", () => { name: "localstack-aws", image: "localstack/localstack-pro:latest", env: ["MAIN_CONTAINER_NAME=localstack-aws"], + labels: { "cloud.localstack.lstk": "true" }, mounts: [ { type: "bind", diff --git a/src/lib/docker/docker.client.ts b/src/lib/docker/docker.client.ts index 053e9b8..90216a3 100644 --- a/src/lib/docker/docker.client.ts +++ b/src/lib/docker/docker.client.ts @@ -3,7 +3,9 @@ import { createRequire } from "node:module"; import { LOCALSTACK_PORT } from "../../core/config"; import { configuredContainerName, - KNOWN_CONTAINER_NAMES, + KNOWN_CONTAINER_NAMES_DESCRIPTION, + knownContainerNameRank, + LSTK_MANAGED_LABEL, type LocalStackContainerSpec, } from "../localstack/container-spec.logic"; @@ -21,6 +23,17 @@ export interface ContainerStateInfo { running: boolean; /** Host ports the container publishes (only known for a running container). */ publicPorts: number[]; + labels?: Record; +} + +/** The fields of a Docker container list entry the client reads. */ +interface DockerContainerSummary { + Id: string; + Names?: string[]; + State?: string; + Image?: string; + Labels?: Record; + Ports?: Array<{ PublicPort?: number }>; } /** @@ -112,6 +125,7 @@ export interface ContainerMetadata { image?: string; env?: string[]; mounts?: ContainerMountInfo[]; + labels?: Record; } export class LocalStackContainerNotFoundError extends Error { @@ -197,20 +211,46 @@ export class DockerApiClient { ); } + /** The container's first name that the server recognizes, and its detection rank. */ + private knownName(container: { + Names?: string[]; + Labels?: Record; + }): { name: string; rank: number } | undefined { + return (container.Names || []) + .map((n) => this.normalizeContainerName(n)) + .map((name) => ({ name, rank: knownContainerNameRank(name, container.Labels) })) + .filter((entry): entry is { name: string; rank: number } => entry.rank !== undefined) + .sort((a, b) => a.rank - b.rank)[0]; + } + + /** Containers under a known name, in detection order (see `knownContainerNameRank`). */ + private sortByKnownName }>( + containers: T[] + ): Array<{ container: T; name: string }> { + return containers + .map((container) => ({ container, known: this.knownName(container) })) + .filter( + (entry): entry is { container: T; known: { name: string; rank: number } } => + entry.known !== undefined + ) + .sort((a, b) => a.known.rank - b.known.rank) + .map(({ container, known }) => ({ container, name: known.name })); + } + /** - * The running container under a known LocalStack name. lstk can run several stacks - * side by side, each under its own name and port, so when more than one known name is - * running, the one publishing the configured gateway port wins; otherwise name order. + * The running container under a known LocalStack name. Several can run at once, for + * example lstk in two projects whose `.lstk/config.toml` set different ports, or a + * `localstack-main` beside them. When more than one runs, the one publishing the + * configured gateway port wins; otherwise detection order. */ private findByKnownLocalStackName< T extends { Names?: string[]; + Labels?: Record; Ports?: Array<{ PrivatePort?: number; PublicPort?: number; Type?: string }>; }, >(containers: T[]): T | undefined { - const known = KNOWN_CONTAINER_NAMES.map((name) => - containers.find((c) => this.matchesConfiguredContainerName(c, name)) - ).filter((c): c is T => Boolean(c)); + const known = this.sortByKnownName(containers).map(({ container }) => container); if (known.length > 1) { const byGatewayPort = known.find((c) => this.publishesConfiguredGatewayPort(c)); if (byGatewayPort) return byGatewayPort; @@ -225,6 +265,7 @@ export class DockerApiClient { Id: string; Names?: string[]; Image?: string; + Labels?: Record; Ports?: Array<{ PrivatePort?: number; PublicPort?: number; Type?: string }>; }>; @@ -239,10 +280,14 @@ export class DockerApiClient { if (!explicitName) { const byKnownName = this.findByKnownLocalStackName(running || []); - if (byKnownName) return byKnownName.Id as string; - const localstackImages = (running || []).filter((c) => this.hasLocalStackImage(c)); const byGatewayPort = localstackImages.find((c) => this.publishesConfiguredGatewayPort(c)); + // A known container off the gateway port loses to a LocalStack image on it: the + // HTTP tools talk to the gateway port, so Docker actions must target that container. + if (byKnownName && !this.publishesConfiguredGatewayPort(byKnownName) && byGatewayPort) { + return byGatewayPort.Id as string; + } + if (byKnownName) return byKnownName.Id as string; if (byGatewayPort) return byGatewayPort.Id as string; const explicitPort = Boolean(process.env.LOCALSTACK_PORT?.trim()); @@ -262,11 +307,10 @@ export class DockerApiClient { } } - const lookedFor = explicitName ? [explicitName] : KNOWN_CONTAINER_NAMES; + const lookedFor = explicitName ? `"${explicitName}"` : KNOWN_CONTAINER_NAMES_DESCRIPTION; throw new LocalStackContainerNotFoundError( - `Could not find a running LocalStack container named ${lookedFor - .map((name) => `"${name}"`) - .join(" or ")}. ` + `Set MAIN_CONTAINER_NAME to your container name if it is custom.` + `Could not find a running LocalStack container named ${lookedFor}. ` + + `Set MAIN_CONTAINER_NAME to your container name if it is custom.` ); } @@ -278,6 +322,7 @@ export class DockerApiClient { name: this.normalizeContainerName(inspect?.Name), image: inspect?.Config?.Image, env: inspect?.Config?.Env, + labels: inspect?.Config?.Labels || undefined, mounts: (inspect?.Mounts || []).map( (mount: { Type?: string; Name?: string; Source?: string; Destination?: string }) => ({ type: mount.Type, @@ -594,30 +639,58 @@ export class DockerApiClient { (this.docker.listContainers as any)({ all: true, filters: { name: [name] } }), 10000, "Docker container list" - )) as Array<{ - Id: string; - Names?: string[]; - State?: string; - Image?: string; - Ports?: Array<{ PublicPort?: number }>; - }>; + )) as Array; const match = (containers || []).find((container) => this.matchesConfiguredContainerName(container, name) ); if (!match) return null; + return this.toStateInfo(match, name); + } + + private toStateInfo(container: DockerContainerSummary, name: string): ContainerStateInfo { return { - id: match.Id, + id: container.Id, name, - state: match.State || "unknown", - image: match.Image, - running: match.State === "running", - publicPorts: (match.Ports || []) + state: container.State || "unknown", + image: container.Image, + running: container.State === "running", + labels: container.Labels, + publicPorts: (container.Ports || []) .map((port) => port.PublicPort) .filter((port): port is number => typeof port === "number"), }; } + /** + * Containers in any state that the server recognizes (`localstack-main` and lstk's + * containers, see `knownContainerNameRank`), in detection order. Ignores + * MAIN_CONTAINER_NAME; callers that honor it look the configured name up directly. + * Two filtered lists, merged: names containing `localstack-`, and lstk's label (an + * lstk container with a custom name has no common prefix). + */ + async listKnownLocalStackContainers(): Promise { + const list = (filters: Record) => + this.withDockerRequestTimeout( + (this.docker.listContainers as any)({ all: true, filters }) as Promise< + DockerContainerSummary[] + >, + 10000, + "Docker container list" + ); + const [byName, byLabel] = await Promise.all([ + list({ name: ["localstack-"] }), + list({ label: [`${LSTK_MANAGED_LABEL}=true`] }), + ]); + const unique = new Map(); + for (const container of [...(byName || []), ...(byLabel || [])]) { + unique.set(container.Id, container); + } + return this.sortByKnownName([...unique.values()]).map(({ container, name }) => + this.toStateInfo(container, name) + ); + } + /** Remove a container, tolerating it already being gone. */ async removeContainer(containerId: string, requestTimeoutMs = 60000): Promise { const container = this.docker.getContainer(containerId); diff --git a/src/lib/localstack/container-spec.logic.test.ts b/src/lib/localstack/container-spec.logic.test.ts index 3c45688..15177b8 100644 --- a/src/lib/localstack/container-spec.logic.test.ts +++ b/src/lib/localstack/container-spec.logic.test.ts @@ -2,7 +2,9 @@ import { buildLocalStackContainerSpec, detectAiAgent, parseGatewayListen, - stackContainerNames, + isStackContainerName, + knownContainerNameRank, + lstkContainerStack, resolveContainerName, resolveImage, resolveVolume, @@ -82,19 +84,89 @@ describe("resolveContainerName", () => { }); }); -describe("stackContainerNames", () => { - test("lists localstack-main and the stack's lstk name when nothing is configured", () => { - // lstk's ContainerConfig.defaultName: "localstack-" + emulator type (internal/config/containers.go). - expect(stackContainerNames({}, "aws")).toEqual(["localstack-main", "localstack-aws"]); - expect(stackContainerNames({}, "snowflake")).toEqual([ +describe("lstk container names", () => { + // lstk's ContainerConfig.defaultName (internal/config/containers.go): + // "localstack-{type}", or "localstack-{type}-{tag}" when the tag is not "latest". + const lstk = { "cloud.localstack.lstk": "true" }; + + test("recognizes lstk's latest names without a label", () => { + expect(lstkContainerStack("localstack-aws")).toBe("aws"); + expect(lstkContainerStack("localstack-snowflake")).toBe("snowflake"); + expect(lstkContainerStack("localstack-azure")).toBe("azure"); + }); + + test("recognizes a tagged name only with lstk's label", () => { + expect(lstkContainerStack("localstack-aws-2026.4", lstk)).toBe("aws"); + expect(lstkContainerStack("localstack-snowflake-1.2.3", lstk)).toBe("snowflake"); + expect(lstkContainerStack("localstack-azure-2026.4", lstk)).toBe("azure"); + // LocalStack names Lambda containers after its own container, so the same shape + // without lstk's label is not an emulator. + expect(lstkContainerStack("localstack-aws-dev-lambda-fn-1234")).toBeUndefined(); + expect(lstkContainerStack("localstack-aws-2026.4")).toBeUndefined(); + }); + + test("ignores names lstk does not derive", () => { + for (const name of [ + "localstack-main", + "localstack", + "localstack-awsx", + "localstack-aws-", + "my-localstack-aws", + "localstack-gcp", + ]) { + expect(lstkContainerStack(name, lstk)).toBeUndefined(); + } + }); + + test("ranks localstack-main, lstk's names by stack (latest first), then custom lstk names", () => { + const containers: Array<[string, Record | undefined]> = [ + ["my-ls", lstk], + ["localstack-azure-2026.4", lstk], + ["localstack-aws-2026.4", lstk], + ["localstack-snowflake", undefined], + ["localstack-aws", undefined], + ["localstack-main", undefined], + ["localstack-azure", undefined], + ]; + const ranked = [...containers] + .sort(([a, la], [b, lb]) => knownContainerNameRank(a, la)! - knownContainerNameRank(b, lb)!) + .map(([name]) => name); + expect(ranked).toEqual([ "localstack-main", + "localstack-aws", + "localstack-aws-2026.4", "localstack-snowflake", + "localstack-azure", + "localstack-azure-2026.4", + "my-ls", ]); - expect(stackContainerNames({}, "azure")).toEqual(["localstack-main", "localstack-azure"]); + expect(knownContainerNameRank("my-ls")).toBeUndefined(); + expect(knownContainerNameRank("localstack-main-lambda-fn-1234")).toBeUndefined(); + expect(knownContainerNameRank("localstack-aws-dev-lambda-fn-1234")).toBeUndefined(); + }); +}); + +describe("isStackContainerName", () => { + test("accepts localstack-main and the stack's labeled lstk names when nothing is configured", () => { + const lstk = { "cloud.localstack.lstk": "true" }; + expect(isStackContainerName({}, "aws", "localstack-main")).toBe(true); + expect(isStackContainerName({}, "aws", "localstack-aws", lstk)).toBe(true); + expect(isStackContainerName({}, "snowflake", "localstack-snowflake", lstk)).toBe(true); + // Without lstk's label, lstk did not create it (for example a compose service). + expect(isStackContainerName({}, "aws", "localstack-aws")).toBe(false); + expect( + isStackContainerName({}, "aws", "localstack-aws-2026.4", { "cloud.localstack.lstk": "true" }) + ).toBe(true); + expect(isStackContainerName({}, "aws", "localstack-aws-dev-lambda-fn-1234")).toBe(false); + expect(isStackContainerName({}, "aws", "localstack-snowflake")).toBe(false); + expect(isStackContainerName({}, "azure", "localstack-aws")).toBe(false); }); - test("lists only the configured name when MAIN_CONTAINER_NAME is set", () => { - expect(stackContainerNames({ MAIN_CONTAINER_NAME: " my-ls " }, "azure")).toEqual(["my-ls"]); + test("accepts only the configured name when MAIN_CONTAINER_NAME is set", () => { + const env = { MAIN_CONTAINER_NAME: " my-ls " }; + expect(isStackContainerName(env, "azure", "my-ls")).toBe(true); + expect(isStackContainerName(env, "azure", "localstack-main")).toBe(false); + expect(isStackContainerName(env, "azure", "localstack-azure")).toBe(false); }); }); @@ -230,6 +302,14 @@ describe("buildLocalStackContainerSpec", () => { expect(spec.HostConfig.PortBindings["443/tcp"][0].HostIp).toBe("0.0.0.0"); }); + test("a recreate keeps the original container's labels", () => { + const spec = buildLocalStackContainerSpec( + baseInput({ labelsOverride: { "cloud.localstack.lstk": "true" } }) + ); + expect(spec.Labels).toEqual({ "cloud.localstack.lstk": "true" }); + expect(buildLocalStackContainerSpec(baseInput()).Labels).toBeUndefined(); + }); + test("LOCALSTACK_PORT changes only the host side of the gateway mapping", () => { const spec = buildLocalStackContainerSpec(baseInput({ hostEnv: { LOCALSTACK_PORT: "4567" } })); expect(spec.HostConfig.PortBindings["4566/tcp"]).toEqual([ diff --git a/src/lib/localstack/container-spec.logic.ts b/src/lib/localstack/container-spec.logic.ts index 0864623..08e493e 100644 --- a/src/lib/localstack/container-spec.logic.ts +++ b/src/lib/localstack/container-spec.logic.ts @@ -93,24 +93,66 @@ export type LocalStackStack = "aws" | "snowflake" | "azure"; /** The name the start action gives a new container when MAIN_CONTAINER_NAME is unset. */ export const DEFAULT_CONTAINER_NAME = "localstack-main"; +/** Stacks in the order their lstk names are preferred during detection. */ +const LSTK_STACKS: readonly LocalStackStack[] = ["aws", "snowflake", "azure"]; + /** - * lstk's default container name per stack (`localstack-{type}`, from - * `ContainerConfig.defaultName` in lstk's `internal/config/containers.go`). The server - * does not create containers under these names, but finds and manages ones lstk started. + * lstk's derived container name: `localstack-{type}` for the `latest` tag, else + * `localstack-{type}-{tag}` (`ContainerConfig.defaultName` in lstk's + * `internal/config/containers.go`). The server does not create containers under these + * names, but finds and manages ones lstk started. */ -export const LSTK_CONTAINER_NAMES: Readonly> = { - aws: "localstack-aws", - snowflake: "localstack-snowflake", - azure: "localstack-azure", -}; - -/** Names a LocalStack container may have when no MAIN_CONTAINER_NAME is configured. */ -export const KNOWN_CONTAINER_NAMES: readonly string[] = [ - DEFAULT_CONTAINER_NAME, - LSTK_CONTAINER_NAMES.aws, - LSTK_CONTAINER_NAMES.snowflake, - LSTK_CONTAINER_NAMES.azure, -]; +const LSTK_CONTAINER_NAME = /^localstack-(aws|snowflake|azure)(?:-([A-Za-z0-9_.-]+))?$/; + +/** + * The label lstk puts on every container it creates (`managedLabelKey` in lstk's + * `internal/runtime/docker.go`). A name alone cannot tell a tagged lstk container + * (`localstack-aws-dev`) from the Lambda containers LocalStack starts under its own + * name plus a suffix (`localstack-aws-dev-lambda-...`), so names other than the exact + * ones below count only with this label. + */ +export const LSTK_MANAGED_LABEL = "cloud.localstack.lstk"; + +export type ContainerLabels = Record | undefined; + +/** How the known names are described to users, for example in "not found" errors. */ +export const KNOWN_CONTAINER_NAMES_DESCRIPTION = + `"${DEFAULT_CONTAINER_NAME}", "localstack-aws", "localstack-snowflake" or ` + + `"localstack-azure", or a container lstk started under another name`; + +function isLstkManaged(labels: ContainerLabels): boolean { + return labels?.[LSTK_MANAGED_LABEL] === "true"; +} + +/** + * The stack an lstk container belongs to, judged by its name: `localstack-{type}`, or + * `localstack-{type}-{tag}` when lstk's label is present. Undefined otherwise. + */ +export function lstkContainerStack( + name: string, + labels?: ContainerLabels +): LocalStackStack | undefined { + const match = LSTK_CONTAINER_NAME.exec(name); + if (!match || (match[2] && !isLstkManaged(labels))) return undefined; + return match[1] as LocalStackStack; +} + +/** + * Detection order of a container when MAIN_CONTAINER_NAME is unset: lower wins. + * `localstack-main` first, then lstk's names by stack (the `latest` name before a + * tagged one), then any other container lstk started (a custom `container_name`). + * Undefined for a container the server does not recognize. + */ +export function knownContainerNameRank(name: string, labels?: ContainerLabels): number | undefined { + if (name === DEFAULT_CONTAINER_NAME) return 0; + const stack = lstkContainerStack(name, labels); + if (stack) { + const tagged = name !== `localstack-${stack}`; + return 1 + LSTK_STACKS.indexOf(stack) * 2 + (tagged ? 1 : 0); + } + if (isLstkManaged(labels)) return 1 + LSTK_STACKS.length * 2; + return undefined; +} export type VolumeResolution = { type: "bind"; source: string } | { type: "volume"; name: string }; @@ -132,6 +174,8 @@ export interface ContainerSpecInput { /** Overrides for restart-in-place recreation: reuse the original container's identity. */ imageOverride?: string; containerNameOverride?: string; + /** Labels of the original container to keep, such as lstk's. */ + labelsOverride?: Record; } export interface PortBindingEntry { @@ -145,6 +189,7 @@ export interface LocalStackContainerSpec { Image: string; Env: string[]; ExposedPorts: Record>; + Labels?: Record; HostConfig: { AutoRemove: boolean; PortBindings: Record>; @@ -189,15 +234,22 @@ export function resolveContainerName(hostEnv: Record } /** - * Names a stopped container of this stack may hold: the configured name, else - * `localstack-main` and the stack's lstk name. + * Whether a stopped container belongs to the stack, so `stop` may remove it: the + * configured name, else `localstack-main` and the stack's lstk containers. lstk's names + * need lstk's label here even without a tag: removing is riskier than detecting, and a + * `localstack-aws` without the label was not created by lstk (for example a compose + * service), so it is not ours to clean up. */ -export function stackContainerNames( +export function isStackContainerName( hostEnv: Record, - stack: LocalStackStack -): string[] { + stack: LocalStackStack, + name: string, + labels?: ContainerLabels +): boolean { const configured = configuredContainerName(hostEnv); - return configured ? [configured] : [DEFAULT_CONTAINER_NAME, LSTK_CONTAINER_NAMES[stack]]; + if (configured) return name === configured; + if (name === DEFAULT_CONTAINER_NAME) return true; + return isLstkManaged(labels) && lstkContainerStack(name, labels) === stack; } function parsePort(text: string, context: string): number { @@ -538,6 +590,9 @@ export function buildLocalStackContainerSpec(input: ContainerSpecInput): LocalSt Image: image, Env: buildEnv(input, ports, name), ExposedPorts: exposedPorts, + ...(input.labelsOverride && Object.keys(input.labelsOverride).length > 0 + ? { Labels: input.labelsOverride } + : {}), HostConfig: { AutoRemove: true, PortBindings: portBindings, diff --git a/src/lib/localstack/localstack.utils.test.ts b/src/lib/localstack/localstack.utils.test.ts index d19313c..e3b69b1 100644 --- a/src/lib/localstack/localstack.utils.test.ts +++ b/src/lib/localstack/localstack.utils.test.ts @@ -67,6 +67,7 @@ function mockDockerClient(overrides: Record = {}) { const client = { ping: jest.fn().mockResolvedValue(undefined), findContainerByNameAnyState: jest.fn().mockResolvedValue(null), + listKnownLocalStackContainers: jest.fn().mockResolvedValue([]), findLocalStackContainer: jest.fn().mockResolvedValue("container-123"), inspectContainer: jest .fn() @@ -334,18 +335,16 @@ describe("localstack.utils", () => { // lstk names the container localstack-aws, so the localstack-main name check alone // would miss it; both publish the gateway port. const { client } = mockDockerClient({ - findContainerByNameAnyState: jest.fn(async (name: string) => - name === "localstack-aws" - ? { - id: "aws-1", - name, - state: "running", - running: true, - image: "localstack/localstack-pro:latest", - publicPorts: [4566, 443], - } - : null - ), + listKnownLocalStackContainers: jest.fn().mockResolvedValue([ + { + id: "aws-1", + name: "localstack-aws", + state: "running", + running: true, + image: "localstack/localstack-pro:latest", + publicPorts: [4566, 443], + }, + ]), }); const getStatus = jest.fn().mockResolvedValue({ isRunning: false }); @@ -362,20 +361,44 @@ describe("localstack.utils", () => { expect(client.createAndStartContainer).not.toHaveBeenCalled(); }); + test("reports a conflict when lstk runs a pinned tag on the gateway port", async () => { + // lstk appends the tag to the name when it is not "latest". + const { client } = mockDockerClient({ + listKnownLocalStackContainers: jest.fn().mockResolvedValue([ + { + id: "aws-tagged", + name: "localstack-aws-2026.4", + state: "running", + running: true, + image: "localstack/localstack-pro:2026.4", + publicPorts: [4566, 443], + }, + ]), + }); + const getStatus = jest.fn().mockResolvedValue({ isRunning: false }); + + const result = await launchRuntime({ ...launchDefaults, getStatus, dockerClient: client }); + const text = result.content[0].text; + expect(text).toContain('named "localstack-aws-2026.4"'); + expect(text).toContain( + "it runs the AWS emulator too and holds ports 443, 4566 that this start needs" + ); + expect(text).toContain("`lstk stop`"); + expect(client.createAndStartContainer).not.toHaveBeenCalled(); + }); + test("reports a conflict when lstk's Azure container holds the gateway port", async () => { const { client } = mockDockerClient({ - findContainerByNameAnyState: jest.fn(async (name: string) => - name === "localstack-azure" - ? { - id: "old-1", - name, - state: "running", - running: true, - image: "localstack/localstack-pro:latest", - publicPorts: [4566], - } - : null - ), + listKnownLocalStackContainers: jest.fn().mockResolvedValue([ + { + id: "old-1", + name: "localstack-azure", + state: "running", + running: true, + image: "localstack/localstack-pro:latest", + publicPorts: [4566], + }, + ]), }); const getStatus = jest.fn().mockResolvedValue({ isRunning: false }); @@ -387,18 +410,16 @@ describe("localstack.utils", () => { test("starts beside another stack's container that publishes other ports", async () => { // lstk runs stacks side by side on their own ports; only a shared host port conflicts. const { client } = mockDockerClient({ - findContainerByNameAnyState: jest.fn(async (name: string) => - name === "localstack-aws" - ? { - id: "aws-1", - name, - state: "running", - running: true, - image: "localstack/localstack-pro:latest", - publicPorts: [5566], - } - : null - ), + listKnownLocalStackContainers: jest.fn().mockResolvedValue([ + { + id: "aws-1", + name: "localstack-aws", + state: "running", + running: true, + image: "localstack/localstack-pro:latest", + publicPorts: [5566], + }, + ]), }); const getStatus = jest .fn() @@ -418,11 +439,15 @@ describe("localstack.utils", () => { test("leaves stopped containers of other names alone", async () => { const { client } = mockDockerClient({ - findContainerByNameAnyState: jest.fn(async (name: string) => - name === "localstack-aws" - ? { id: "lstk-stopped", name, state: "exited", running: false, publicPorts: [] } - : null - ), + listKnownLocalStackContainers: jest.fn().mockResolvedValue([ + { + id: "lstk-stopped", + name: "localstack-aws", + state: "exited", + running: false, + publicPorts: [], + }, + ]), }); const getStatus = jest .fn() @@ -721,6 +746,33 @@ describe("localstack.utils", () => { }); }); + test("keeps an lstk container's labels", () => { + // A tagged or custom lstk name counts only with lstk's label. The gateway port is + // not kept: the server's tools reach the gateway on LOCALSTACK_PORT only. + expect( + deriveRecreateOverrides( + { + id: "x", + name: "localstack-aws-2026.4", + image: "localstack/localstack-pro:2026.4", + labels: { + "cloud.localstack.lstk": "true", + "cloud.localstack.lstk.image-override": "true", + maintainer: "LocalStack Team", + }, + }, + "aws" + ) + ).toEqual({ + imageOverride: "localstack/localstack-pro:2026.4", + containerNameOverride: "localstack-aws-2026.4", + labelsOverride: { + "cloud.localstack.lstk": "true", + "cloud.localstack.lstk.image-override": "true", + }, + }); + }); + test("returns undefined when the previous image is a different stack (deliberate switch)", () => { expect( deriveRecreateOverrides({ id: "x", image: "localstack/snowflake:latest" }, "aws") diff --git a/src/lib/localstack/localstack.utils.ts b/src/lib/localstack/localstack.utils.ts index eeecca1..1114854 100644 --- a/src/lib/localstack/localstack.utils.ts +++ b/src/lib/localstack/localstack.utils.ts @@ -15,7 +15,7 @@ import { } from "../docker/docker.client"; import { buildLocalStackContainerSpec, - KNOWN_CONTAINER_NAMES, + LSTK_MANAGED_LABEL, resolveContainerName, type LocalStackContainerSpec, resolveVolume, @@ -339,6 +339,7 @@ export interface LaunchRuntimeOptions { imageOverride?: string; containerNameOverride?: string; volumeOverride?: VolumeResolution; + labelsOverride?: Record; /** Injectable for tests. */ dockerClient?: DockerApiClient; pollIntervalMs?: number; @@ -363,23 +364,56 @@ function specHostPorts(spec: LocalStackContainerSpec): Set { ); } -function conflictResponse(processLabel: string, containerName: string, image?: string) { +const EMULATOR_LABELS: Record = { + aws: "the AWS emulator", + snowflake: "the Snowflake emulator", + azure: "the Azure emulator", +}; + +/** + * A running container blocks this start. `sharedPorts` lists the host ports it holds + * that this start would bind, when the conflict is about ports rather than the name. + */ +function conflictResponse( + processLabel: string, + startingStack: LocalStackStack, + containerName: string, + image?: string, + sharedPorts?: number[] +) { const stack = stackFromImage(image); - const otherStack = - stack === "snowflake" - ? "the Snowflake emulator" - : stack === "azure" - ? "the Azure emulator" - : "another LocalStack stack (likely the AWS emulator)"; + const owner = + stack === undefined + ? "it belongs to another LocalStack stack (likely the AWS emulator)" + : stack === startingStack + ? `it runs ${EMULATOR_LABELS[stack]} too` + : `it belongs to ${EMULATOR_LABELS[stack]}`; + const ports = sharedPorts?.length + ? ` and holds port${sharedPorts.length > 1 ? "s" : ""} ${formatPorts(sharedPorts)} that this start needs` + : ""; return ResponseBuilder.error( "LocalStack container already running", `Starting ${processLabel} failed because a LocalStack container named "${containerName}"${ image ? ` (image: ${image})` : "" - } is already running — it belongs to ${otherStack}. ` + - `Stop it first with the localstack-management tool (action: stop), then retry this start.` + } is already running — ${owner}${ports}. ` + + `Stop it first with the localstack-management tool (action: stop), or with \`lstk stop\` ` + + `if lstk started it, then retry this start.` ); } +/** Ports as a short list, folding consecutive runs: `443, 4510-4559`. */ +function formatPorts(ports: number[]): string { + const sorted = [...new Set(ports)].sort((a, b) => a - b); + const runs: string[] = []; + for (let i = 0; i < sorted.length; i++) { + let j = i; + while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1) j++; + runs.push(i === j ? `${sorted[i]}` : `${sorted[i]}-${sorted[j]}`); + i = j; + } + return runs.join(", "); +} + /** * Start a LocalStack runtime flavor directly through the Docker Engine API (no * localstack/lstk CLI involved) and poll until it becomes available. @@ -483,13 +517,14 @@ async function launchRuntimeInner( serverVersion: SERVER_VERSION, imageOverride: options.imageOverride, containerNameOverride: options.containerNameOverride, + labelsOverride: options.labelsOverride, }); // Fail fast (or clean up) when the container name is taken. A running container is // an actionable conflict; a stopped one is a stale leftover we remove ourselves. - // lstk names its containers `localstack-{type}`, so a running container under + // lstk names its containers `localstack-{type}[-{tag}]`, so a running container under // another known name is a conflict too when it publishes a host port this start - // binds. One on other ports (a second emulator on its own GATEWAY_LISTEN) may keep + // binds. One on other ports (lstk in another project on its own `port`) may keep // running. // Short timeouts: this is pre-start housekeeping — a hung daemon should surface // as an error in seconds, not block the start for two minutes. @@ -497,17 +532,19 @@ async function launchRuntimeInner( const existing = await docker.findContainerByNameAnyState(spec.name); if (existing) { if (existing.running) { - return conflictResponse(processLabel, spec.name, existing.image); + return conflictResponse(processLabel, stack, spec.name, existing.image); } await docker.removeContainer(existing.id, 10000); await docker.waitForRemoval(existing.id, 10000); } const boundHostPorts = specHostPorts(spec); - for (const name of KNOWN_CONTAINER_NAMES) { - if (name === spec.name) continue; - const other = await docker.findContainerByNameAnyState(name); - if (other?.running && other.publicPorts.some((port) => boundHostPorts.has(port))) { - return conflictResponse(processLabel, name, other.image); + for (const other of await docker.listKnownLocalStackContainers()) { + if (other.name === spec.name) continue; + const sharedPorts = other.running + ? other.publicPorts.filter((port) => boundHostPorts.has(port)) + : []; + if (sharedPorts.length > 0) { + return conflictResponse(processLabel, stack, other.name, other.image, sharedPorts); } } } catch (error) { @@ -538,7 +575,7 @@ async function launchRuntimeInner( containerId = await docker.createAndStartContainer(spec); } catch (error) { if (error instanceof LocalStackContainerConflictError) { - return conflictResponse(processLabel, spec.name); + return conflictResponse(processLabel, stack, spec.name); } return ResponseBuilder.error( `Failed to start ${processLabel}`, @@ -656,14 +693,17 @@ export interface RecreateOverrides { imageOverride?: string; containerNameOverride?: string; volumeOverride?: VolumeResolution; + labelsOverride?: Record; } /** * Derive start overrides from a container we are about to recreate, so an - * externally-provisioned runtime (custom name/image/volume) is not silently replaced + * externally-provisioned runtime (custom name/image/volume, lstk's labels) is not + * silently replaced * by the defaults — that would strand its state. Reuse only applies when the previous * image matches the requested stack (restarting with a different `service` deliberately - * switches stacks). + * switches stacks). The gateway is published on LOCALSTACK_PORT, not the original + * container's port: the server's HTTP tools only reach it there. */ export function deriveRecreateOverrides( metadata: ContainerMetadata | undefined, @@ -686,6 +726,13 @@ export function deriveRecreateOverrides( overrides.volumeOverride = { type: "volume", name: volumeMount.name }; } + // Keep lstk's labels, so the recreated container still counts as lstk's (its name + // may be tagged or custom, which detection accepts only with the label). + const lstkLabels = Object.fromEntries( + Object.entries(metadata.labels || {}).filter(([key]) => key.startsWith(LSTK_MANAGED_LABEL)) + ); + if (Object.keys(lstkLabels).length > 0) overrides.labelsOverride = lstkLabels; + return overrides; } diff --git a/src/tools-tests/localstack-management.test.ts b/src/tools-tests/localstack-management.test.ts index ab8a95c..afff40d 100644 --- a/src/tools-tests/localstack-management.test.ts +++ b/src/tools-tests/localstack-management.test.ts @@ -78,52 +78,74 @@ describe("localstack-management", () => { expect(text(result)).not.toMatch(/Snowflake emulator health check did not pass/); }); - test("stop removes a stale stopped container holding the LocalStack name", async () => { + test("stop removes stale stopped containers holding this stack's names", async () => { const { LocalStackContainerNotFoundError } = jest.requireActual("../lib/docker/docker.client"); const removeContainer = jest.fn().mockResolvedValue(undefined); const waitForRemoval = jest.fn().mockResolvedValue(undefined); + const stopped = (id: string, name: string) => ({ + id, + name, + state: "exited", + running: false, + publicPorts: [], + labels: name === "localstack-main" ? undefined : { "cloud.localstack.lstk": "true" }, + }); mockDocker({ findLocalStackContainer: jest .fn() .mockRejectedValue(new LocalStackContainerNotFoundError("none running")), - findContainerByNameAnyState: jest.fn(async (name: string) => - name === "localstack-snowflake" - ? { id: "stale-1", name, state: "exited", running: false } - : null - ), + listKnownLocalStackContainers: jest.fn().mockResolvedValue([ + stopped("stale-main", "localstack-main"), + stopped("stale-aws", "localstack-aws"), + stopped("stale-snow", "localstack-snowflake"), + stopped("stale-snow-tag", "localstack-snowflake-1.4"), + // A Lambda container LocalStack named after its own container: no lstk label. + { ...stopped("fn", "localstack-snowflake-1.4-lambda-fn-1"), labels: undefined }, + ]), removeContainer, waitForRemoval, }); const result = await localstackManagement({ action: "stop", service: "snowflake" } as any); - expect(removeContainer).toHaveBeenCalledTimes(1); - expect(removeContainer).toHaveBeenCalledWith("stale-1"); - expect(waitForRemoval).toHaveBeenCalledWith("stale-1"); - expect(text(result)).toContain('Removed stopped LocalStack container "localstack-snowflake"'); + expect(removeContainer.mock.calls.map(([id]) => id)).toEqual([ + "stale-main", + "stale-snow", + "stale-snow-tag", + ]); + expect(waitForRemoval).toHaveBeenCalledWith("stale-snow-tag"); + expect(text(result)).toContain( + 'Removed stopped LocalStack containers "localstack-main", "localstack-snowflake", "localstack-snowflake-1.4"' + ); }); - test("stop leaves a stopped container of another stack alone", async () => { + test("stop leaves running containers and other stacks' stopped containers alone", async () => { const { LocalStackContainerNotFoundError } = jest.requireActual("../lib/docker/docker.client"); const removeContainer = jest.fn().mockResolvedValue(undefined); - const findContainerByNameAnyState = jest.fn(async (name: string) => - name === "localstack-snowflake" - ? { id: "stale-1", name, state: "exited", running: false, publicPorts: [] } - : null - ); mockDocker({ findLocalStackContainer: jest .fn() .mockRejectedValue(new LocalStackContainerNotFoundError("none running")), - findContainerByNameAnyState, + listKnownLocalStackContainers: jest.fn().mockResolvedValue([ + { + id: "snow", + name: "localstack-snowflake", + state: "exited", + running: false, + publicPorts: [], + }, + { + id: "aws", + name: "localstack-aws-2026.4", + state: "running", + running: true, + publicPorts: [5566], + }, + ]), removeContainer, }); mockedGetStatus.mockResolvedValue({ isRunning: false, isReady: false }); await localstackManagement({ action: "stop", service: "aws" } as any); - expect(findContainerByNameAnyState.mock.calls.map(([name]) => name)).toEqual([ - "localstack-main", - "localstack-aws", - ]); expect(removeContainer).not.toHaveBeenCalled(); }); @@ -131,17 +153,20 @@ describe("localstack-management", () => { process.env.MAIN_CONTAINER_NAME = "my-ls"; const { LocalStackContainerNotFoundError } = jest.requireActual("../lib/docker/docker.client"); const findContainerByNameAnyState = jest.fn().mockResolvedValue(null); + const listKnownLocalStackContainers = jest.fn().mockResolvedValue([]); mockDocker({ findLocalStackContainer: jest .fn() .mockRejectedValue(new LocalStackContainerNotFoundError("none running")), findContainerByNameAnyState, + listKnownLocalStackContainers, }); mockedGetStatus.mockResolvedValue({ isRunning: false, isReady: false }); await localstackManagement({ action: "stop", service: "aws" } as any); expect(findContainerByNameAnyState).toHaveBeenCalledTimes(1); expect(findContainerByNameAnyState).toHaveBeenCalledWith("my-ls"); + expect(listKnownLocalStackContainers).not.toHaveBeenCalled(); }); test("stop reports nothing to do when no container exists and the gateway is down", async () => { diff --git a/src/tools/localstack-management.ts b/src/tools/localstack-management.ts index 9638202..f960319 100644 --- a/src/tools/localstack-management.ts +++ b/src/tools/localstack-management.ts @@ -12,7 +12,8 @@ import { type ContainerMetadata, } from "../lib/docker/docker.client"; import { - stackContainerNames, + configuredContainerName, + isStackContainerName, stackFromImage, type VolumeResolution, } from "../lib/localstack/container-spec.logic"; @@ -117,6 +118,7 @@ interface StartOverrides { imageOverride?: string; containerNameOverride?: string; volumeOverride?: VolumeResolution; + labelsOverride?: Record; } /** Best-effort look at the running LocalStack container (null when none/undetectable). */ @@ -214,10 +216,17 @@ async function handleStop({ service }: { service: Service }) { // No RUNNING container found — check for stale stopped ones holding this stack's name. try { + const configured = configuredContainerName(process.env); + const candidates = configured + ? [await dockerClient.findContainerByNameAnyState(configured)] + : await dockerClient.listKnownLocalStackContainers(); const removed: string[] = []; - for (const name of stackContainerNames(process.env, service)) { - const stale = await dockerClient.findContainerByNameAnyState(name); - if (stale && !stale.running) { + for (const stale of candidates) { + if ( + stale && + !stale.running && + isStackContainerName(process.env, service, stale.name, stale.labels) + ) { await dockerClient.removeContainer(stale.id); await dockerClient.waitForRemoval(stale.id); removed.push(`"${stale.name}"`); From 35a87aa7f8b8049d7bf3314c91452864268ca7dc Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Wed, 18 Nov 2026 15:08:23 +0100 Subject: [PATCH 4/7] Test restarting an lstk container in the Docker smoke job lstk starts the AWS emulator with a pinned tag (localstack-aws-mcp-ci, a tag that exists only locally, so lstk falls back to the local image). The server image restarts it, and the test checks that the recreated container keeps lstk's name, image and label, publishes the gateway on LOCALSTACK_PORT, and that lstk status and lstk stop still find it. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/docker.yml | 21 ++++ docs/DOCKER.md | 6 + tests/docker/validate-lstk.mjs | 195 +++++++++++++++++++++++++++++++++ 3 files changed, 222 insertions(+) create mode 100644 tests/docker/validate-lstk.mjs diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index e45a67e..ba3b024 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -84,6 +84,27 @@ jobs: -v "$PWD/data:/work/data" \ ${{ env.IMAGE_NAME }}:ci + # Restart a container lstk started with a pinned tag. The tag exists only locally, + # so lstk's pull fails and it falls back to the local image (no second download). + - name: Integration test lstk interop + if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository + env: + LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} + HARNESS_LSTK_TAG: mcp-ci + HARNESS_LSTK_PORT: "4577" + run: | + npm install -g @localstack/lstk@1.4.5 + docker pull localstack/localstack-pro:latest + docker tag localstack/localstack-pro:latest localstack/localstack-pro:mcp-ci + node tests/docker/validate-lstk.mjs -- \ + docker run -i --rm \ + -v /var/run/docker.sock:/var/run/docker.sock \ + --add-host host.docker.internal:host-gateway \ + -e LOCALSTACK_AUTH_TOKEN \ + -e LOCALSTACK_HOSTNAME=host.docker.internal \ + -e LOCALSTACK_PORT=4577 \ + ${{ env.IMAGE_NAME }}:ci + push: name: Build & Push (multi-arch) needs: smoke diff --git a/docs/DOCKER.md b/docs/DOCKER.md index ca4a5d2..fa1c672 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -163,6 +163,12 @@ Use `HARNESS_SKIP` to skip scenarios, for example: HARNESS_SKIP=docs,cloudpods,ephemeral,replicator ``` +`tests/docker/validate-lstk.mjs` checks [lstk](../README.md#using-lstk) interop: lstk +starts the AWS emulator with a pinned tag on port 4577, the server restarts it, and lstk +still finds it. It needs `lstk` on `PATH` and free host ports 443 and 4510-4560, and the +server must get `LOCALSTACK_PORT=4577`. See the "Integration test lstk interop" step in +`.github/workflows/docker.yml` for the full command. + ## Tool versions in the image Each tool's version is pinned in one file, and Dependabot opens the update PRs once a diff --git a/tests/docker/validate-lstk.mjs b/tests/docker/validate-lstk.mjs new file mode 100644 index 0000000..5fca3e0 --- /dev/null +++ b/tests/docker/validate-lstk.mjs @@ -0,0 +1,195 @@ +#!/usr/bin/env node +/** + * Checks that the server manages a container lstk started: lstk starts the AWS emulator + * with a pinned tag (so its container is `localstack-aws-`), the server restarts + * it, and lstk still finds it afterwards. + * + * Usage: + * node tests/docker/validate-lstk.mjs -- [args...] + * + * The server command must pass LOCALSTACK_PORT= to the server, so its + * tools reach the gateway lstk publishes. Needs `lstk` on PATH, LOCALSTACK_AUTH_TOKEN, + * and free host ports 443 and 4510-4560 (lstk always publishes them). + * + * Env knobs: + * HARNESS_LSTK_TAG Image tag lstk runs (default "mcp-ci"). A tag that exists only + * locally works: lstk falls back to the local image when the pull fails. + * HARNESS_LSTK_PORT Gateway port lstk publishes (default 4577). + */ + +import { execFileSync, spawn } from "node:child_process"; +import { mkdtempSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +const argv = process.argv.slice(2); +const sep = argv.indexOf("--"); +if (sep === -1 || sep === argv.length - 1) { + console.error("Usage: node validate-lstk.mjs -- [args...]"); + process.exit(2); +} + +const TAG = process.env.HARNESS_LSTK_TAG || "mcp-ci"; +const PORT = process.env.HARNESS_LSTK_PORT || "4577"; +const NAME = `localstack-aws-${TAG}`; +const LSTK_LABEL = "cloud.localstack.lstk"; + +const configDir = mkdtempSync(join(tmpdir(), "lsmcp-lstk-")); +const configPath = join(configDir, "config.toml"); +writeFileSync(configPath, `[[containers]]\ntype = "aws"\ntag = "${TAG}"\nport = "${PORT}"\n`); + +// ---- helpers ---------------------------------------------------------------- +function run(cmd, args, timeoutMs = 300000) { + try { + const out = execFileSync(cmd, args, { + encoding: "utf8", + timeout: timeoutMs, + stdio: ["ignore", "pipe", "pipe"], + env: { ...process.env, LSTK_STARTUP_TIMEOUT: "180s" }, + }); + return { ok: true, out }; + } catch (error) { + return { ok: false, out: `${error.stdout || ""}${error.stderr || ""}${error.message}` }; + } +} +const lstk = (...args) => run("lstk", ["--config", configPath, ...args]); + +function inspect(name) { + const r = run("docker", ["inspect", name], 30000); + if (!r.ok) return undefined; + return JSON.parse(r.out)[0]; +} + +const results = []; +function record(name, ok, detail) { + results.push({ name, ok }); + console.log(`\n${ok ? "✅ PASS" : "❌ FAIL"} ${name}`); + if (detail) console.log(" " + String(detail).replace(/\n/g, "\n ").slice(0, 1200)); +} + +// ---- MCP stdio client ------------------------------------------------------- +const child = spawn(argv[sep + 1], argv.slice(sep + 2), { stdio: ["pipe", "pipe", "pipe"] }); +const pending = new Map(); +const serverLog = []; +let buf = ""; +let nextId = 1; +child.stdout.on("data", (chunk) => { + buf += chunk.toString(); + let nl; + while ((nl = buf.indexOf("\n")) !== -1) { + const line = buf.slice(0, nl).trim(); + buf = buf.slice(nl + 1); + if (!line) continue; + let msg; + try { + msg = JSON.parse(line); + } catch { + continue; + } + const waiter = msg.id !== undefined && pending.get(msg.id); + if (!waiter) continue; + pending.delete(msg.id); + if (msg.error) waiter.reject(new Error(JSON.stringify(msg.error))); + else waiter.resolve(msg.result); + } +}); +child.stderr.on("data", (c) => serverLog.push(c.toString().trimEnd())); + +function rpc(method, params, timeoutMs) { + const id = nextId++; + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + pending.delete(id); + reject(new Error(`timeout after ${timeoutMs}ms waiting for ${method}`)); + }, timeoutMs); + pending.set(id, { + resolve: (r) => (clearTimeout(timer), resolve(r)), + reject: (e) => (clearTimeout(timer), reject(e)), + }); + child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n"); + }); +} +async function callTool(name, args, timeoutMs) { + const res = await rpc("tools/call", { name, arguments: args }, timeoutMs); + const text = (res?.content || []).map((c) => c.text || "").join("\n"); + return { text, isError: res?.isError === true || text.trimStart().startsWith("❌") }; +} + +// ---- scenario --------------------------------------------------------------- +async function main() { + const started = lstk("start"); + const before = inspect(NAME); + record( + `lstk start runs ${NAME}`, + started.ok && before?.State?.Running && before.Config.Labels?.[LSTK_LABEL] === "true", + started.out.slice(-600) + ); + if (!before?.State?.Running) return; + + await rpc( + "initialize", + { + protocolVersion: "2024-11-05", + capabilities: {}, + clientInfo: { name: "ls-mcp-lstk-validator", version: "1.0.0" }, + }, + 60000 + ); + child.stdin.write( + JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }) + "\n" + ); + + const restart = await callTool("localstack-management", { action: "restart" }, 300000); + record("localstack-management restart succeeds", !restart.isError, restart.text.slice(0, 600)); + + const after = inspect(NAME); + const gateway = after?.HostConfig?.PortBindings?.["4566/tcp"]?.[0]?.HostPort; + record( + "the recreated container keeps lstk's name, image and label, on LOCALSTACK_PORT", + Boolean(after?.State?.Running) && + after.Id !== before.Id && + after.Config.Image === before.Config.Image && + after.Config.Labels?.[LSTK_LABEL] === "true" && + gateway === PORT, + `id changed: ${after?.Id !== before.Id}, image: ${after?.Config?.Image}, ` + + `label: ${after?.Config?.Labels?.[LSTK_LABEL]}, gateway host port: ${gateway}` + ); + + const status = lstk("status"); + record( + "lstk status finds the restarted container", + status.ok && !/not running/i.test(status.out), + status.out.slice(-400) + ); + + const stopped = lstk("stop"); + record( + "lstk stop stops the restarted container", + stopped.ok && !inspect(NAME)?.State?.Running, + stopped.out.slice(-400) + ); +} + +function finish(code) { + try { + child.stdin.end(); + child.kill("SIGTERM"); + } catch {} + run("docker", ["rm", "-f", NAME], 60000); + const failed = results.filter((r) => !r.ok); + console.log("\n" + "=".repeat(64)); + console.log(`SUMMARY: ${results.length - failed.length} passed, ${failed.length} failed`); + if (failed.length || code) { + console.log("\n--- recent server stderr (last 25 lines) ---"); + console.log(serverLog.slice(-25).join("\n")); + } + console.log("=".repeat(64)); + process.exit(code || (failed.length || results.length === 0 ? 1 : 0)); +} + +main() + .then(() => finish(0)) + .catch((e) => { + console.error("\nHARNESS ERROR:", e.message); + finish(1); + }); From a29010c65cf6a72540c224ea1eee359624ff5388 Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Wed, 18 Nov 2026 15:28:11 +0100 Subject: [PATCH 5/7] Run the lstk interop test by hand instead of in CI Keep CI lean for now: drop the workflow step and document the manual command for tests/docker/validate-lstk.mjs in docs/DOCKER.md. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/docker.yml | 21 --------------------- docs/DOCKER.md | 18 +++++++++++++++--- 2 files changed, 15 insertions(+), 24 deletions(-) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index ba3b024..e45a67e 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -84,27 +84,6 @@ jobs: -v "$PWD/data:/work/data" \ ${{ env.IMAGE_NAME }}:ci - # Restart a container lstk started with a pinned tag. The tag exists only locally, - # so lstk's pull fails and it falls back to the local image (no second download). - - name: Integration test lstk interop - if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository - env: - LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} - HARNESS_LSTK_TAG: mcp-ci - HARNESS_LSTK_PORT: "4577" - run: | - npm install -g @localstack/lstk@1.4.5 - docker pull localstack/localstack-pro:latest - docker tag localstack/localstack-pro:latest localstack/localstack-pro:mcp-ci - node tests/docker/validate-lstk.mjs -- \ - docker run -i --rm \ - -v /var/run/docker.sock:/var/run/docker.sock \ - --add-host host.docker.internal:host-gateway \ - -e LOCALSTACK_AUTH_TOKEN \ - -e LOCALSTACK_HOSTNAME=host.docker.internal \ - -e LOCALSTACK_PORT=4577 \ - ${{ env.IMAGE_NAME }}:ci - push: name: Build & Push (multi-arch) needs: smoke diff --git a/docs/DOCKER.md b/docs/DOCKER.md index fa1c672..4f1fde4 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -165,9 +165,21 @@ HARNESS_SKIP=docs,cloudpods,ephemeral,replicator `tests/docker/validate-lstk.mjs` checks [lstk](../README.md#using-lstk) interop: lstk starts the AWS emulator with a pinned tag on port 4577, the server restarts it, and lstk -still finds it. It needs `lstk` on `PATH` and free host ports 443 and 4510-4560, and the -server must get `LOCALSTACK_PORT=4577`. See the "Integration test lstk interop" step in -`.github/workflows/docker.yml` for the full command. +still finds it. It needs `lstk` on `PATH` and free host ports 443 and 4510-4560. A tag +that exists only locally avoids a second image download: + +```bash +docker tag localstack/localstack-pro:latest localstack/localstack-pro:mcp-ci +LOCALSTACK_AUTH_TOKEN="" \ +node tests/docker/validate-lstk.mjs -- \ + docker run -i --rm \ + -v /var/run/docker.sock:/var/run/docker.sock \ + --add-host host.docker.internal:host-gateway \ + -e LOCALSTACK_AUTH_TOKEN \ + -e LOCALSTACK_HOSTNAME=host.docker.internal \ + -e LOCALSTACK_PORT=4577 \ + localstack/localstack-mcp-server:latest +``` ## Tool versions in the image From 1b70d664f5f175569ff7d09de6742116db0baf3d Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Wed, 18 Nov 2026 17:44:22 +0100 Subject: [PATCH 6/7] Require LOCALSTACK_PORT for known containers when it is set With LOCALSTACK_PORT set, findLocalStackContainer returned a known container before checking the port. Since lstk's tagged and custom names became known, stop and restart could act on another project's lstk container, such as localstack-aws-dev on 4566, and restart moved it to LOCALSTACK_PORT. A known container must now publish the configured port; otherwise the lookup reports that none does. Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- src/lib/docker/docker.client.test.ts | 55 ++++++++++++++++++++++++++++ src/lib/docker/docker.client.ts | 13 +++++-- 3 files changed, 66 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4a4b4fa..7e01fa9 100644 --- a/README.md +++ b/README.md @@ -258,7 +258,7 @@ container_name = "localstack-main" Then lstk finds the container by name, whichever tool started it. -Without that setting, the server still finds and manages lstk's container: `stop` and `status` act on it, `restart` keeps its name, image, volume and lstk's labels (the gateway moves to `LOCALSTACK_PORT`, where the tools reach it), and `start` reports it as a conflict when it holds a port `start` needs. lstk, for its part, falls back to the first running container with a standard LocalStack image that publishes port 4566, so it may find the server's container, or another one when several run. +Without that setting, the server still finds and manages lstk's container: `stop` and `status` act on it, `restart` keeps its name, image, volume and lstk's labels (the gateway moves to `LOCALSTACK_PORT`, where the tools reach it), and `start` reports it as a conflict when it holds a port `start` needs. When `LOCALSTACK_PORT` is set, `stop` and `restart` act only on a container that publishes that port. lstk, for its part, falls back to the first running container with a standard LocalStack image that publishes port 4566, so it may find the server's container, or another one when several run. The two tools keep state in different directories, even under one container name. lstk uses `/lstk/volume/`, which does not change with `container_name`, and the server uses the LocalStack CLI's `/localstack/volume`. To share state, point one at the other: set `volume` in lstk's config, or `LOCALSTACK_VOLUME_DIR` for the server. diff --git a/src/lib/docker/docker.client.test.ts b/src/lib/docker/docker.client.test.ts index c82dbd3..266b279 100644 --- a/src/lib/docker/docker.client.test.ts +++ b/src/lib/docker/docker.client.test.ts @@ -487,6 +487,61 @@ describe("DockerApiClient", () => { await expect(client.findLocalStackContainer()).resolves.toBe("snow"); }); + test("findLocalStackContainer skips a known container off an explicit LOCALSTACK_PORT", async () => { + // Another lstk project on 4566 must not be stopped or recreated on 4567. + process.env.LOCALSTACK_PORT = "4567"; + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { + Id: "dev", + Names: ["/localstack-aws-dev"], + Image: "localstack/localstack-pro:latest", + Labels: { "cloud.localstack.lstk": "true" }, + Ports: [{ PrivatePort: 4566, PublicPort: 4566, Type: "tcp" }], + }, + ]); + + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).rejects.toThrow( + /none publishes the configured gateway port 4567/i + ); + }); + + test("findLocalStackContainer skips localstack-main off an explicit LOCALSTACK_PORT, even with a custom image", async () => { + process.env.LOCALSTACK_PORT = "4567"; + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { + Id: "mcp", + Names: ["/localstack-main"], + Image: "registry.example/ls:1", + Ports: [{ PrivatePort: 4566, PublicPort: 4566, Type: "tcp" }], + }, + ]); + + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).rejects.toThrow( + /none publishes the configured gateway port 4567/i + ); + }); + + test("findLocalStackContainer keeps a known container on an explicit LOCALSTACK_PORT", async () => { + process.env.LOCALSTACK_PORT = "4567"; + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { + Id: "tagged", + Names: ["/localstack-aws-mcp-ci"], + Image: "localstack/localstack-pro:mcp-ci", + Labels: { "cloud.localstack.lstk": "true" }, + Ports: [{ PrivatePort: 4566, PublicPort: 4567, Type: "tcp" }], + }, + ]); + + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).resolves.toBe("tagged"); + }); + test("findLocalStackContainer prefers localstack-main over lstk's localstack-aws", async () => { const mocks = getDockerMocks(); mocks.listContainers.mockResolvedValueOnce([ diff --git a/src/lib/docker/docker.client.ts b/src/lib/docker/docker.client.ts index 90216a3..0ec64a2 100644 --- a/src/lib/docker/docker.client.ts +++ b/src/lib/docker/docker.client.ts @@ -279,7 +279,15 @@ export class DockerApiClient { } if (!explicitName) { - const byKnownName = this.findByKnownLocalStackName(running || []); + const explicitPort = Boolean(process.env.LOCALSTACK_PORT?.trim()); + const knownNames = this.findByKnownLocalStackName(running || []); + // With LOCALSTACK_PORT set, a known container must publish that port. Otherwise + // stop and restart could act on another project's container, such as an lstk + // container on 4566, and restart would move it to LOCALSTACK_PORT. + const byKnownName = + knownNames && (!explicitPort || this.publishesConfiguredGatewayPort(knownNames)) + ? knownNames + : undefined; const localstackImages = (running || []).filter((c) => this.hasLocalStackImage(c)); const byGatewayPort = localstackImages.find((c) => this.publishesConfiguredGatewayPort(c)); // A known container off the gateway port loses to a LocalStack image on it: the @@ -290,8 +298,7 @@ export class DockerApiClient { if (byKnownName) return byKnownName.Id as string; if (byGatewayPort) return byGatewayPort.Id as string; - const explicitPort = Boolean(process.env.LOCALSTACK_PORT?.trim()); - if (explicitPort && localstackImages.length > 0) { + if (explicitPort && (knownNames || localstackImages.length > 0)) { throw new LocalStackContainerNotFoundError( `Found running LocalStack containers, but none publishes the configured gateway port ${process.env.LOCALSTACK_PORT}. ` + `Set MAIN_CONTAINER_NAME to the container name to use.` From bbb19b833eb6d7e6b3f8c9b8568807bbe7635d5b Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Wed, 18 Nov 2026 18:06:58 +0100 Subject: [PATCH 7/7] Match the gateway by host port and report containers off LOCALSTACK_PORT 1b70d66 required a known container to publish LOCALSTACK_PORT from container port 4566. A localstack-main started with GATEWAY_LISTEN=:4567 publishes 4567->4567, and one on the host network publishes nothing, so every Docker-based tool lost the server's own container. - Match the gateway by host port alone. - Accept a known container that publishes no ports. - Throw GatewayPortMismatchError, naming the containers and their gateway ports, when containers run but none is on LOCALSTACK_PORT. stop and restart report it instead of "not running". Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- src/lib/docker/docker.client.test.ts | 57 ++++++++++++++++- src/lib/docker/docker.client.ts | 61 ++++++++++++++++--- src/tools-tests/localstack-management.test.ts | 26 ++++++++ src/tools/localstack-management.ts | 7 +++ 5 files changed, 144 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 7e01fa9..6105e43 100644 --- a/README.md +++ b/README.md @@ -258,7 +258,7 @@ container_name = "localstack-main" Then lstk finds the container by name, whichever tool started it. -Without that setting, the server still finds and manages lstk's container: `stop` and `status` act on it, `restart` keeps its name, image, volume and lstk's labels (the gateway moves to `LOCALSTACK_PORT`, where the tools reach it), and `start` reports it as a conflict when it holds a port `start` needs. When `LOCALSTACK_PORT` is set, `stop` and `restart` act only on a container that publishes that port. lstk, for its part, falls back to the first running container with a standard LocalStack image that publishes port 4566, so it may find the server's container, or another one when several run. +Without that setting, the server still finds and manages lstk's container: `stop` and `status` act on it, `restart` keeps its name, image, volume and lstk's labels (the gateway moves to `LOCALSTACK_PORT`, where the tools reach it), and `start` reports it as a conflict when it holds a port `start` needs. When `LOCALSTACK_PORT` is set, the tools that use Docker (`stop`, `restart`, logs, the deployer and others) act only on a container that publishes that port, or that publishes no ports at all, such as one on the host network. lstk, for its part, falls back to the first running container with a standard LocalStack image that publishes port 4566, so it may find the server's container, or another one when several run. The two tools keep state in different directories, even under one container name. lstk uses `/lstk/volume/`, which does not change with `container_name`, and the server uses the LocalStack CLI's `/localstack/volume`. To share state, point one at the other: set `volume` in lstk's config, or `LOCALSTACK_VOLUME_DIR` for the server. diff --git a/src/lib/docker/docker.client.test.ts b/src/lib/docker/docker.client.test.ts index 266b279..61237dc 100644 --- a/src/lib/docker/docker.client.test.ts +++ b/src/lib/docker/docker.client.test.ts @@ -1,4 +1,8 @@ -import { DockerApiClient } from "./docker.client"; +import { + DockerApiClient, + isGatewayPortMismatchError, + isLocalStackContainerNotFoundError, +} from "./docker.client"; import { PassThrough } from "stream"; jest.mock("dockerode", () => { @@ -525,6 +529,57 @@ describe("DockerApiClient", () => { ); }); + test("findLocalStackContainer finds localstack-main started with GATEWAY_LISTEN on an explicit LOCALSTACK_PORT", async () => { + // GATEWAY_LISTEN=:4567 publishes the gateway as 4567->4567. + process.env.LOCALSTACK_PORT = "4567"; + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { + Id: "mcp", + Names: ["/localstack-main"], + Image: "localstack/localstack-pro:latest", + Ports: [{ PrivatePort: 4567, PublicPort: 4567, Type: "tcp" }], + }, + ]); + + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).resolves.toBe("mcp"); + }); + + test("findLocalStackContainer finds localstack-main on the host network with an explicit LOCALSTACK_PORT", async () => { + process.env.LOCALSTACK_PORT = "4566"; + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { Id: "mcp", Names: ["/localstack-main"], Image: "localstack/localstack-pro:latest", Ports: [] }, + ]); + + const client = new DockerApiClient(); + await expect(client.findLocalStackContainer()).resolves.toBe("mcp"); + }); + + test("findLocalStackContainer names the containers and their gateway ports when none is on LOCALSTACK_PORT", async () => { + process.env.LOCALSTACK_PORT = "4567"; + const mocks = getDockerMocks(); + mocks.listContainers.mockResolvedValueOnce([ + { + Id: "mcp", + Names: ["/localstack-main"], + Image: "localstack/localstack-pro:latest", + Ports: [ + { PrivatePort: 4566, PublicPort: 4566, Type: "tcp" }, + { PrivatePort: 4566, PublicPort: 4566, Type: "tcp" }, + ], + }, + ]); + + const client = new DockerApiClient(); + const error = await client.findLocalStackContainer().catch((e: Error) => e); + expect(isGatewayPortMismatchError(error)).toBe(true); + expect(isLocalStackContainerNotFoundError(error)).toBe(true); + expect((error as Error).message).toContain('"localstack-main" (gateway on 4566)'); + expect((error as Error).message).toContain("Set LOCALSTACK_PORT"); + }); + test("findLocalStackContainer keeps a known container on an explicit LOCALSTACK_PORT", async () => { process.env.LOCALSTACK_PORT = "4567"; const mocks = getDockerMocks(); diff --git a/src/lib/docker/docker.client.ts b/src/lib/docker/docker.client.ts index 0ec64a2..2e8198a 100644 --- a/src/lib/docker/docker.client.ts +++ b/src/lib/docker/docker.client.ts @@ -135,10 +135,31 @@ export class LocalStackContainerNotFoundError extends Error { } } +/** + * LocalStack containers run, but none publishes the configured LOCALSTACK_PORT. A + * not-found error for callers that only check that, but `stop` and `restart` report it + * instead of "not running", since a container does run. + */ +export class GatewayPortMismatchError extends LocalStackContainerNotFoundError { + constructor(message: string) { + super(message); + this.name = "GatewayPortMismatchError"; + } +} + export function isLocalStackContainerNotFoundError(error: unknown): boolean { return ( error instanceof LocalStackContainerNotFoundError || - (error instanceof Error && error.name === "LocalStackContainerNotFoundError") + (error instanceof Error && + (error.name === "LocalStackContainerNotFoundError" || + error.name === "GatewayPortMismatchError")) + ); +} + +export function isGatewayPortMismatchError(error: unknown): boolean { + return ( + error instanceof GatewayPortMismatchError || + (error instanceof Error && error.name === "GatewayPortMismatchError") ); } @@ -168,10 +189,33 @@ export class DockerApiClient { Ports?: Array<{ PrivatePort?: number; PublicPort?: number; Type?: string }>; }): boolean { const configuredPort = Number(process.env.LOCALSTACK_PORT || LOCALSTACK_PORT); + // Only the host port counts: with GATEWAY_LISTEN=:4567 the gateway listens on + // container port 4567, published as 4567->4567. return (container.Ports || []).some( - (port) => - port.Type === "tcp" && port.PrivatePort === 4566 && port.PublicPort === configuredPort + (port) => port.Type === "tcp" && port.PublicPort === configuredPort + ); + } + + /** + * Whether the tools may reach this container's gateway on LOCALSTACK_PORT. A container + * that publishes no ports, such as one on the host network, cannot be ruled out. + */ + private mayServeConfiguredGatewayPort(container: { + Ports?: Array<{ PrivatePort?: number; PublicPort?: number; Type?: string }>; + }): boolean { + const published = (container.Ports || []).some((port) => port.PublicPort !== undefined); + return !published || this.publishesConfiguredGatewayPort(container); + } + + private describeGatewayPorts(container: { + Names?: string[]; + Ports?: Array<{ PrivatePort?: number; PublicPort?: number; Type?: string }>; + }): string { + const name = this.normalizeContainerName(container.Names?.[0]) || "unnamed"; + const gateway = (container.Ports || []).find( + (port) => port.Type === "tcp" && port.PrivatePort === 4566 && port.PublicPort !== undefined ); + return gateway ? `"${name}" (gateway on ${gateway.PublicPort})` : `"${name}"`; } private hasLocalStackImage(container: { Image?: string }): boolean { @@ -285,7 +329,7 @@ export class DockerApiClient { // stop and restart could act on another project's container, such as an lstk // container on 4566, and restart would move it to LOCALSTACK_PORT. const byKnownName = - knownNames && (!explicitPort || this.publishesConfiguredGatewayPort(knownNames)) + knownNames && (!explicitPort || this.mayServeConfiguredGatewayPort(knownNames)) ? knownNames : undefined; const localstackImages = (running || []).filter((c) => this.hasLocalStackImage(c)); @@ -299,9 +343,12 @@ export class DockerApiClient { if (byGatewayPort) return byGatewayPort.Id as string; if (explicitPort && (knownNames || localstackImages.length > 0)) { - throw new LocalStackContainerNotFoundError( - `Found running LocalStack containers, but none publishes the configured gateway port ${process.env.LOCALSTACK_PORT}. ` + - `Set MAIN_CONTAINER_NAME to the container name to use.` + const found = [...new Set([knownNames, ...localstackImages].filter(Boolean))] + .map((c) => this.describeGatewayPorts(c!)) + .join(", "); + throw new GatewayPortMismatchError( + `Found running LocalStack containers (${found}), but none publishes the configured gateway port ${process.env.LOCALSTACK_PORT}. ` + + `Set LOCALSTACK_PORT to the gateway port of the container to use, or MAIN_CONTAINER_NAME to its name.` ); } diff --git a/src/tools-tests/localstack-management.test.ts b/src/tools-tests/localstack-management.test.ts index afff40d..335fcad 100644 --- a/src/tools-tests/localstack-management.test.ts +++ b/src/tools-tests/localstack-management.test.ts @@ -183,6 +183,32 @@ describe("localstack-management", () => { expect(text(result)).toMatch(/not running — no container to stop/); }); + test.each(["stop", "restart"])( + "%s reports a container off LOCALSTACK_PORT instead of 'not running'", + async (action) => { + const { GatewayPortMismatchError } = jest.requireActual("../lib/docker/docker.client"); + const removeContainer = jest.fn(); + mockDocker({ + findLocalStackContainer: jest + .fn() + .mockRejectedValue( + new GatewayPortMismatchError( + 'Found running LocalStack containers ("localstack-main" (gateway on 4566)), but none publishes the configured gateway port 4567.' + ) + ), + listKnownLocalStackContainers: jest.fn().mockResolvedValue([]), + removeContainer, + }); + mockedGetStatus.mockResolvedValue({ isRunning: false, isReady: false }); + + const result = await localstackManagement({ action, service: "aws" } as any); + expect(result.isError).toBe(true); + expect(text(result)).toMatch(/gateway on 4566.*configured gateway port 4567/); + expect(removeContainer).not.toHaveBeenCalled(); + expect(launchRuntime).not.toHaveBeenCalled(); + } + ); + test("requires the auth token", async () => { delete process.env.LOCALSTACK_AUTH_TOKEN; const result = await localstackManagement({ action: "status", service: "aws" } as any); diff --git a/src/tools/localstack-management.ts b/src/tools/localstack-management.ts index f960319..149fb6e 100644 --- a/src/tools/localstack-management.ts +++ b/src/tools/localstack-management.ts @@ -8,6 +8,7 @@ import { } from "../lib/localstack/localstack.utils"; import { DockerApiClient, + isGatewayPortMismatchError, isLocalStackContainerNotFoundError, type ContainerMetadata, } from "../lib/docker/docker.client"; @@ -213,6 +214,9 @@ async function handleStop({ service }: { service: Service }) { `Could not inspect Docker containers: ${error instanceof Error ? error.message : String(error)}` ); } + if (isGatewayPortMismatchError(error)) { + return ResponseBuilder.error("LocalStack container not on LOCALSTACK_PORT", (error as Error).message); + } // No RUNNING container found — check for stale stopped ones holding this stack's name. try { @@ -289,6 +293,9 @@ async function handleRestart({ }` ); } + if (isGatewayPortMismatchError(error)) { + return ResponseBuilder.error("LocalStack container not on LOCALSTACK_PORT", (error as Error).message); + } const status = await getLocalStackStatus(); if (status.isRunning) { return ResponseBuilder.error(