Skip to content

Find lstk's LocalStack containers next to localstack-main - #119

Merged
joe4dev merged 7 commits into
mainfrom
default-container-name-localstack-aws
Nov 19, 2026
Merged

joe4dev merged 7 commits into
mainfrom
default-container-name-localstack-aws

Conversation

@joe4dev

@joe4dev joe4dev commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Motivation

lstk names its container localstack-{type}, or localstack-{type}-{tag} for a pinned tag. This server creates localstack-main. This PR keeps that default and makes the server find and manage containers lstk started.

Refs #25 and #10. Linear: DEVX-1319

FYI: The suggested approach is more of a quick-fix for a deeper MCP-lstk alignment issue we need to tackle holistically

Changes

  • Detection prefers, in order: localstack-main, lstk's localstack-{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. With LOCALSTACK_PORT set, a known container must publish that port as a host port, or publish no ports (host network), so stop and restart leave 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.
  • lstk's label: a tagged or custom name counts only with the cloud.localstack.lstk=true label lstk sets. LocalStack names its Lambda containers <container>-lambda-…, so a name alone would match them.
  • start reports 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.
  • stop cleanup removes stale localstack-main and the stack's labeled lstk containers. It leaves an unlabeled localstack-aws, such as a compose service, alone.
  • restart keeps the name, image, volume and lstk's labels. The gateway moves to LOCALSTACK_PORT.
  • Docs: a new README section, "Using lstk"; docs/DOCKER.md and server.json are updated.

No tool arguments change, and the created container is still localstack-main.

Review focus

  • The label is the safety boundary. Tagged and custom lstk names are trusted only with lstk's label, because of the Lambda containers. The exact 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.
  • Destructive paths. stop cleanup and the restart recreate remove containers. Check that isStackContainerName and findLocalStackContainer cannot select a container this server should not touch.
  • restart moves lstk's gateway. An lstk container on port = 4567 comes back on LOCALSTACK_PORT, because the server's tools only reach the gateway there. Keeping 4567 made restart time out.
  • lstk can stop the wrong container. Without container_name, lstk falls back to the first running container with a standard LocalStack image and port 4566. With several running, lstk stop may stop another one. This is an lstk issue, not fixed here.
  • restart drops lstk's environment. The recreate builds the environment from the server's own environment and envVars, not from the old container. Settings from lstk's env profiles, such as APP_INSPECTOR or ENFORCE_IAM, are lost on a server restart. This was already the case before; the PR makes more lstk containers restartable.
  • LOCALSTACK_PORT matching is loose in two edge cases. Any host port equal to LOCALSTACK_PORT counts as the gateway, so a misconfigured LOCALSTACK_PORT=4510 matches a service port. A known container with no published ports is accepted, so an lstk container on the host network is too; restart would then recreate it on the bridge network.
  • Not changed: stop and restart act on the detected container and ignore service, as before.

Testing

  • CI: unit tests (456), mcp-direct-tests and the Docker runtime integration test pass.
  • lstk compatibility (passing run, step "Integration test lstk interop"), with tests/docker/validate-lstk.mjs:
    • lstk starts the AWS emulator with a pinned tag on port 4577, as localstack-aws-mcp-ci.
    • The server image restarts it. The recreated container keeps lstk's name, image and label, and publishes the gateway on LOCALSTACK_PORT.
    • lstk status and lstk stop still find it.
    • The run used a temporary CI step, removed again to keep CI lean. docs/DOCKER.md shows how to run the script by hand.
  • Manual, against Docker, beside a running lstk container localstack-aws-dev that has Lambda containers:
    • Detection finds it and skips the Lambda containers.
    • start reports the conflict. The previous commit failed with port is already allocated.
    • The cleanup filter and the label-based listing behave as described.
    • lstk stop with container_name = "localstack-main" stopped a stand-in localstack-main container.
    • With LOCALSTACK_PORT set, stand-in containers are found on that port (4597→4597, as with GATEWAY_LISTEN), on the host network, and refused with the port message on a mismatch.

🤖 Generated with Claude Code

@joe4dev joe4dev changed the title Name the LocalStack container like lstk: localstack-{stack} Find lstk's LocalStack containers next to localstack-main Nov 17, 2026
joe4dev and others added 7 commits November 18, 2026 17:24
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
joe4dev force-pushed the default-container-name-localstack-aws branch from 69d0c15 to bbb19b8 Compare November 18, 2026 17:11
@joe4dev
joe4dev marked this pull request as ready for review November 19, 2026 08:44
@joe4dev
joe4dev requested a review from a team November 19, 2026 08:44

@anisaoshafi anisaoshafi left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@joe4dev
joe4dev merged commit b9363e8 into main Nov 19, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants