Attach to externally-started LS container by carole-lavillonniere · Pull Request #190 · localstack/lstk

carole-lavillonniere · 2026-04-14T12:15:44Z

Summary

lstk start now attaches to an already-running LocalStack container instead of failing. It fails if the port is different than the configured one.
lstk stop locates and stops an externally-started container
lstk status returns status of an externally-started container if any

Towards DRG-553

Started outside of `lstk` (eg CLI v1, or locally built and ran in docker):

Already running on a different port:

Status command shows details about the version and container name:

Possible improvement:

Add interactivity and let user decide if the existing container should be picked up or replaced

When `lstk start` is run and a LocalStack container is already running (started outside lstk, e.g. via docker run or Compose), lstk now attaches to it rather than failing or trying to start a duplicate. Detection uses two complementary strategies: - Docker API: `FindRunningByImage` filters by image repo + bound host port via the `ancestor` filter, returning the running container regardless of its name or tag - HTTP fallback: if the Docker filter misses it (different image name, mid-restart), `/_localstack/info` is probed on the configured port Behaviour on attach: - Same version as config: "LocalStack is already running" (exit 0) - Different version: warning with both versions shown (exit 0) - Port in use by non-LocalStack process: existing error (exit 1) `lstk stop` also gains the same fallback: if no container matches the configured name, `FindRunningByImage` is used to locate and stop the externally-started container. `ContainerRemove` conflict/not-found errors (e.g. container started with --rm) are now silently ignored since removal was already in progress.

claude

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

gtsiolis · 2026-04-16T11:05:30Z

Looking at this now! 👀

gtsiolis

Nice one, @carole-lavillonniere! 💯

Added a first round of comments in some relevant lines of code, let me know if something does not make sense. 🙏

carole-lavillonniere · 2026-04-21T09:28:40Z

Nice one, @carole-lavillonniere! 💯

Added a first round of comments in some relevant lines of code, let me know if something does not make sense. 🙏

Thanks for testing extensively @gtsiolis
I addressed your comments and would appreciate another round of testing.

anisaoshafi

Was easy to follow the changes; tested and LGTM 🚀
Good decision to simplify start/stop commands by dismissing the tag/port and informing the user accordingly!

gtsiolis

Left some more comments, @carole-lavillonniere! What do you think?

gtsiolis · 2026-04-23T07:36:43Z

+			if found.BoundPort != c.Port {
+				output.EmitError(sink, output.ErrorEvent{
+					Title:   fmt.Sprintf("LocalStack is already running on port %s", found.BoundPort),
+					Summary: fmt.Sprintf("Config expects port %s. Only one instance can run at a time.", c.Port),


thought: We previously didn't have this restriction.

Only one instance can run at a time.

I'd expect to be able to spin up more than one instance as long as the port is different. This is how it works now, you can set GATEWAY_LISTEN="0.0.0.0:4567" and start a second instance side by side. See also relevant feedback.

gtsiolis · 2026-04-23T07:42:23Z

+		}
+		if conflictPort, err := ports.CheckAvailable(extraSpecs...); err != nil {
+			output.EmitError(sink, output.ErrorEvent{
+				Title:   fmt.Sprintf("Port %s is already in use", conflictPort),


praise: This works as expected, even if it's another service running! 💯

gtsiolis · 2026-04-23T07:44:20Z

+		if conflictPort, err := ports.CheckAvailable(extraSpecs...); err != nil {
+			output.EmitError(sink, output.ErrorEvent{
+				Title:   fmt.Sprintf("Port %s is already in use", conflictPort),
+				Summary: "LocalStack requires this port. Another instance may be running.",


thought: This might not be true when another service is using the port you configured. Could show this line only when port 4566 is configured?

# When configured to use port 4566 ✗ Port 4566 already in use > LocalStack may already be running. # When configured to use port any other port other than 4566 ✗ Port 4568 already in use

gtsiolis · 2026-04-23T08:01:23Z

+		if found != nil {
+			if found.BoundPort != c.Port {
+				output.EmitError(sink, output.ErrorEvent{
+					Title:   fmt.Sprintf("LocalStack is already running on port %s", found.BoundPort),


issue: If you are running two instances, on port 4566 and port 4567, this message now is partially true as it captures only one instance. Since we're doing plain port check for now, I'd highlight the port conflict and only assume LS is running when the config is using 4566.

gtsiolis · 2026-04-23T08:04:44Z

+				emitEmulatorStartError(ctx, tel, c, telemetry.ErrCodePortConflict, fmt.Sprintf("running on port %s, configured port %s", found.BoundPort, c.Port))
+				return nil, output.NewSilentError(fmt.Errorf("LocalStack already running on port %s", found.BoundPort))
+			}
+			output.EmitInfo(sink, "LocalStack is already running")


issue: If you are running another service on 4566 or the same port, this message is quite misleading. ⚠️

Another service on port 4566 Trying to start LS on port 4566

carole-lavillonniere changed the title ~~feat: attach to externally-started LocalStack containers~~ Attach to externally-started LS container Apr 14, 2026

carole-lavillonniere force-pushed the attach-to-running branch from e9dc1e9 to 470cc59 Compare April 15, 2026 12:44

carole-lavillonniere changed the base branch from otel-tracing to main April 15, 2026 12:46

carole-lavillonniere force-pushed the attach-to-running branch from 470cc59 to 9e2a2b4 Compare April 15, 2026 12:46

carole-lavillonniere marked this pull request as ready for review April 15, 2026 12:47

carole-lavillonniere requested review from anisaoshafi and silv-io as code owners April 15, 2026 12:47

claude Bot reviewed Apr 15, 2026

View reviewed changes

carole-lavillonniere requested a review from gtsiolis April 15, 2026 12:54

gtsiolis requested changes Apr 16, 2026

View reviewed changes

Comment thread internal/container/running.go

Comment thread internal/container/start.go Outdated

Comment thread internal/runtime/docker.go

Comment thread internal/container/start.go Outdated

Comment thread internal/container/start.go

Comment thread test/integration/start_test.go

carole-lavillonniere added 3 commits April 21, 2026 10:16

check all required ports for conflict

a3e11e7

also check for localstack/localstack image (not only pro)

aee75ff

remove warning when running different version

813cd32

anisaoshafi approved these changes Apr 21, 2026

View reviewed changes

Comment thread test/integration/start_test.go Outdated

address comments

868d212

carole-lavillonniere force-pushed the attach-to-running branch from 31e00ab to 868d212 Compare April 21, 2026 13:14

gtsiolis reviewed Apr 23, 2026

View reviewed changes

Conversation

carole-lavillonniere commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Started outside of lstk (eg CLI v1, or locally built and ran in docker):

Already running on a different port:

Status command shows details about the version and container name:

Possible improvement:

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Claude Code Review

Uh oh!

gtsiolis commented Apr 16, 2026

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

carole-lavillonniere commented Apr 21, 2026

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gtsiolis left a comment

Choose a reason for hiding this comment

Uh oh!

gtsiolis Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

gtsiolis Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

gtsiolis Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

gtsiolis Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

gtsiolis Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

carole-lavillonniere commented Apr 14, 2026 •

edited

Loading

Started outside of `lstk` (eg CLI v1, or locally built and ran in docker):

gtsiolis left a comment •

edited

Loading

anisaoshafi left a comment •

edited

Loading