Skip to content

fix: run awslocal against the gateway's container-side address - #138

Merged
joe4dev merged 2 commits into
mainfrom
devx-1338-mcp-localstack-aws-client-fails-when-localstacks
Nov 20, 2026
Merged

joe4dev merged 2 commits into
mainfrom
devx-1338-mcp-localstack-aws-client-fails-when-localstacks

Conversation

@joe4dev

@joe4dev joe4dev commented Nov 20, 2026

Copy link
Copy Markdown
Member

Motivation

localstack-aws-client and the deployer's CloudFormation actions run awslocal inside the LocalStack container. awslocal takes its endpoint from the container's LOCALSTACK_HOST, which names the host-side address. When the gateway is published on another host port (-p 4700:4566 with LOCALSTACK_HOST=localhost.localstack.cloud:4700), or GATEWAY_LISTEN moves it inside the container, awslocal calls a port nothing listens on, and every command fails with "Could not connect to the endpoint URL". The agentic IAM eval hit this because it runs LocalStack on a free port.

Solution

  • Each awslocal exec gets AWS_ENDPOINT_URL=http://localhost:<port>. The port is the first GATEWAY_LISTEN entry from the container's environment, parsed the way LocalStack does (LOCALSTACK_GATEWAY_LISTEN wins, a host-only entry means 4566, IPv6 brackets). The default is 4566. The pure logic lives in src/lib/aws/awslocal-endpoint.logic.ts, and src/lib/aws/awslocal.ts runs the exec.
  • The container's own configuration doesn't change, so URLs LocalStack returns (SQS queue URLs, S3 locations, API endpoints) still name the host side from LOCALSTACK_HOST.
  • Commands that build a URL or token for the caller without calling the gateway keep awslocal's own endpoint, so the URL stays reachable from the host. These are s3 presign, rds generate-db-auth-token and eks get-token; the dsql token commands are listed for newer CLIs.
  • The deployer removes its temporary template in a finally.
  • GATEWAY_LISTEN=:0 (a random port) can't be learned from the environment and falls back to 4566.

Running awslocal in the container is still a known deviation (target: lstk aws, #137). This PR fixes only its endpoint, and the call now lives in one helper, src/lib/aws/awslocal.ts, which the deviation rows should name. Once #137 lands, the new integration spec should keep running against the lstk aws path.

Testing

  • Unit tests: endpoint derivation (default, the server's own :4566,:443, a mapped host port, a custom GATEWAY_LISTEN, IPv6, host-only entries, prefix precedence, invalid values) and the URL-building command list, with global options and look-alikes.
  • Handler tests (real analytics and preflights; only PostHog and the gateway health mocked): the exec's argument array and environment in all three setups, presign, a failing container inspect, LocalStack not running, create-stack and delete-stack failures, a missing stackName, template cleanup, and a fake token in the container's env that must reach neither the exec, the response nor analytics.
  • tests/mcp/aws-client-ports.spec.mjs: three real LocalStack containers on free host ports (default in-container config, a mapped host port, GATEWAY_LISTEN). Each case runs SQS calls and a CloudFormation create-stack and delete-stack through the tools, checks that the queue URL names the host port, and, for the mapped cases, fetches an s3 presign URL from the host. It never publishes 4566. Before the fix, the two non-default cases failed with "Could not connect to the endpoint URL". The presign check needs localhost.localstack.cloud to resolve to 127.0.0.1, which some DNS-rebinding-protected resolvers block.
  • yarn build, yarn test (503 tests), tsc --noEmit and prettier on the changed files pass. test:mcp:tools now includes the new spec, with one worker.

Adversarial review

Two rounds. The first found a presign regression, a way for the test to capture a host LocalStack's 127.0.0.1:4566 on macOS, and missing handler tests; all are fixed. The second round passed. Tool descriptions and schemas are unchanged, so no model eval is needed.

Related

Fixes DEVX-1338. Related: #137 (DEVX-1330).

🤖 Generated with Claude Code

joe4dev and others added 2 commits November 20, 2026 09:40
localstack-aws-client and the deployer's create-stack/delete-stack run
awslocal inside the LocalStack container. awslocal derives its endpoint
from LOCALSTACK_HOST, which names the host-side address, unless
AWS_ENDPOINT_URL is set. With the gateway published on another host port
(-p 4700:4566, LOCALSTACK_HOST=localhost.localstack.cloud:4700) or moved
by GATEWAY_LISTEN, awslocal called a port nothing listens on inside the
container.

Each awslocal exec now gets AWS_ENDPOINT_URL=http://localhost:<port>,
where the port is the first GATEWAY_LISTEN entry of the container's
environment (LOCALSTACK_GATEWAY_LISTEN first, default 4566). Only the
exec's environment changes; the container keeps its LOCALSTACK_HOST, so
URLs LocalStack returns (SQS queue URLs) still name the host side.

The awslocal-in-container pattern itself stays a known deviation
(target: lstk aws, DEVX-1330); this only fixes its endpoint.

Tests: unit tests for the endpoint derivation, handler tests for both
tools, and tests/mcp/aws-client-ports.spec.mjs, which runs the aws-client
and the deployer against LocalStack on the default port, a remapped host
port and a custom GATEWAY_LISTEN. It runs in test:mcp:tools with one
worker, so its default case does not race tools.spec.mjs for port 4566.

Fixes DEVX-1338

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e caller

118299f pointed every in-container awslocal at the container-side
gateway, so `s3 presign` returned http://localhost:<container port>/...,
which the host cannot reach. Commands that sign a URL or token locally
and print it without calling the gateway (s3 presign,
rds generate-db-auth-token, eks get-token, dsql generate-db-connect-*)
now get no AWS_ENDPOINT_URL, so awslocal uses LOCALSTACK_HOST as before.
The decision lives in awslocal-endpoint.logic.ts (buildsClientUrl), and
those commands skip the container inspect.

The deployer now removes its temporary template in a finally block, so
it no longer stays in the container when the create-stack exec throws.

Tests:
- unit: URL-building commands with and without global options, and
  look-alikes that call the gateway
- handler tests run analytics and the preflights for real (PostHog and
  the gateway health probe mocked) and cover presign, a failing
  container inspect, LocalStack not running, create-stack and
  delete-stack failures, a missing stackName, the template cleanup, and
  a container auth token that must not reach the exec env, the response
  or analytics
- aws-client-ports.spec.mjs: every case uses a free host port (the
  default case keeps the in-container defaults), ports are picked when a
  case runs, and the mapped and GATEWAY_LISTEN cases check that a
  presigned URL names the host port and can be fetched from the host

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@joe4dev

joe4dev commented Nov 20, 2026 •

Copy link
Copy Markdown
Member Author

Good-to-know: The localstack container resolves localhost.localstack.cloud to an IPv6, which might cause compatibility issues?!
localhost.localstack.cloud (::1) 56 data bytes

This shouldn't be an issue given this PR uses localhost

This PR is anyway only a quickfix

@joe4dev
joe4dev marked this pull request as ready for review November 20, 2026 09:22
@joe4dev
joe4dev merged commit c0a0739 into main Nov 20, 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.

1 participant