Repository navigation
Find lstk's LocalStack containers next to localstack-main - #119
Merged
Merged
Conversation
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
joe4dev
force-pushed
the
default-container-name-localstack-aws
branch
from
November 18, 2026 17:11
69d0c15 to
bbb19b8
Compare
joe4dev
marked this pull request as ready for review
November 19, 2026 08:44
anisaoshafi
approved these changes
Nov 19, 2026
anisaoshafi
left a comment
There was a problem hiding this comment.
Thanks for putting this together. It is going to help mitigate some common pain points, and the label check looks good! 👏🏼
Nothing to suggest at this point.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
lstk names its container
localstack-{type}, orlocalstack-{type}-{tag}for a pinned tag. This server createslocalstack-main. This PR keeps that default and makes the server find and manage containers lstk started.Refs #25 and #10. Linear: DEVX-1319
lstk(localstack-aws) and MCP (localstack-main) #25: settingcontainer_name = "localstack-main"in lstk's config makes both tools use one container. The README recommends it.MAIN_CONTAINER_NAME, unless lstk started the container.FYI: The suggested approach is more of a quick-fix for a deeper MCP-lstk alignment issue we need to tackle holistically
Changes
localstack-main, lstk'slocalstack-{type},localstack-{type}-{tag}, any other lstk container, then a LocalStack image on the gateway port. When several match, the one on the gateway port wins. WithLOCALSTACK_PORTset, a known container must publish that port as a host port, or publish no ports (host network), sostopandrestartleave another project's lstk container alone. When containers run but none is on that port, the tools name them and their gateway ports instead of saying LocalStack is not running.cloud.localstack.lstk=truelabel lstk sets. LocalStack names its Lambda containers<container>-lambda-…, so a name alone would match them.startreports a conflict when a running recognized container holds a port it needs. The message names the ports. It used to fail on a raw port bind error.stopcleanup removes stalelocalstack-mainand the stack's labeled lstk containers. It leaves an unlabeledlocalstack-aws, such as a compose service, alone.restartkeeps the name, image, volume and lstk's labels. The gateway moves toLOCALSTACK_PORT.docs/DOCKER.mdandserver.jsonare updated.No tool arguments change, and the created container is still
localstack-main.Review focus
localstack-{type}names are still accepted without it, for detection only (not cleanup), as before. Older lstk versions without the label lose tagged-name detection; the image fallback still applies.stopcleanup and therestartrecreate remove containers. Check thatisStackContainerNameandfindLocalStackContainercannot select a container this server should not touch.restartmoves lstk's gateway. An lstk container onport = 4567comes back onLOCALSTACK_PORT, because the server's tools only reach the gateway there. Keeping 4567 maderestarttime out.container_name, lstk falls back to the first running container with a standard LocalStack image and port 4566. With several running,lstk stopmay stop another one. This is an lstk issue, not fixed here.restartdrops lstk's environment. The recreate builds the environment from the server's own environment andenvVars, not from the old container. Settings from lstk's env profiles, such asAPP_INSPECTORorENFORCE_IAM, are lost on a serverrestart. This was already the case before; the PR makes more lstk containers restartable.LOCALSTACK_PORTmatching is loose in two edge cases. Any host port equal toLOCALSTACK_PORTcounts as the gateway, so a misconfiguredLOCALSTACK_PORT=4510matches a service port. A known container with no published ports is accepted, so an lstk container on the host network is too;restartwould then recreate it on the bridge network.stopandrestartact on the detected container and ignoreservice, as before.Testing
mcp-direct-testsand the Docker runtime integration test pass.tests/docker/validate-lstk.mjs:localstack-aws-mcp-ci.LOCALSTACK_PORT.lstk statusandlstk stopstill find it.docs/DOCKER.mdshows how to run the script by hand.localstack-aws-devthat has Lambda containers:startreports the conflict. The previous commit failed withport is already allocated.lstk stopwithcontainer_name = "localstack-main"stopped a stand-inlocalstack-maincontainer.LOCALSTACK_PORTset, stand-in containers are found on that port (4597→4597, as withGATEWAY_LISTEN), on the host network, and refused with the port message on a mismatch.🤖 Generated with Claude Code