Skip to content

fix(kit): allow the LocalStack hostnames in the network policy so that sbx resolves them - #2

Open
plafond wants to merge 9 commits into
mainfrom
fix/localstack-hostname-dns
Open

plafond wants to merge 9 commits into
mainfrom
fix/localstack-hostname-dns

Conversation

@plafond

@plafond plafond commented Nov 13, 2026 •

Copy link
Copy Markdown

Fixes #1.

Problem

sbx 0.51.0 resolves a name only if a network rule allows it, and it refuses the DNS lookup of a name that a deny rule lists. Two kit rules then break LocalStack hostnames:

  1. The kit denies localhost.localstack.cloud and **.localhost.localstack.cloud, so these names do not resolve in the sandbox. NO_PROXY does not help, because a client must resolve the name before it connects directly.

  2. The kit does not allow localstack.cloud. LocalStack looks up this name to find an upstream DNS server. The lookup fails, so the LocalStack DNS server does not start, and the names do not resolve in the LocalStack container or in Lambda containers. The LocalStack log shows:

    Unable to determine fallback DNS. Please check if 'localstack.cloud' is reachable by your configured DNS servers
    Error starting the DNS server: No upstream dns server found.
    

The AWS client of the LocalStack MCP server runs awslocal in the LocalStack container with the endpoint localhost.localstack.cloud, so every call fails with Could not connect to the endpoint URL.

I found no earlier note about this in the repo, its history, or its issues. The smoke check "LocalStack hostnames reach the sandbox emulator" expects the name to resolve, and the kit comments name sbx 0.45, so this looks like a change in sbx.

Change

The fix is in the network rules of kits/localstack/localstack.yaml. No script changes.

  • Allow localhost.localstack.cloud and **.localhost.localstack.cloud, and remove them from the deny rules. They resolve to 127.0.0.1, which is the sandbox for a direct connection.
  • Allow localstack.cloud:443, so that the LocalStack DNS server finds its upstream and starts.
  • Keep the deny rules for localhost, 127.0.0.0/8, ::1/128, and host.docker.internal.

The deny rules for the names existed to keep a client that ignores NO_PROXY away from a LocalStack on the host. That protection stays: sbx 0.51 checks the address that a name resolves to against the CIDR rules, so the rule for 127.0.0.0/8 refuses the names at the proxy. See "Isolation test" below.

Also in this PR:

  • scripts/smoke.sh has four new checks: a LocalStack subdomain resolves in the sandbox, the LocalStack DNS server resolves a subdomain in its container, the MCP AWS client reaches LocalStack, and the name answers after a sandbox restart.
  • Docs: docs/security.md, a new section in docs/troubleshooting.md, and lessons in AGENTS.md.

Earlier versions of this PR wrote the name to /etc/hosts and set LOCALSTACK_DNS_SERVER in the lstk wrapper. Both are gone. The hosts file had no wildcards, so subdomains did not resolve in the sandbox.

Isolation test

A listener ran on the host at 127.0.0.1:4555. From the sandbox, curl --noproxy '' sent requests through the proxy.

Target through the proxy Default policy With a sandbox rule that allows **
localhost.localstack.cloud:4555 403 403
x.localhost.localstack.cloud:4555 403 403
localhost:4555, 127.0.0.1:4555, host.docker.internal:4555 403 403
127.0.0.1.nip.io:4555 not tested 403

The host listener got no request from the sandbox. sbx policy log shows the reason for the LocalStack names: denied: rule "kit:...:deny" matched op(action=net:connect:tcp, resource=net:cidr:127.0.0.1).

Limits

  • The protection for the allowed names depends on the address check of sbx 0.51. docs/security.md says to use sbx 0.51 or later. I did not test an earlier sbx.
  • The sbx help says that behind an upstream proxy that resolves the name, sbx checks the name only. I did not test that setup.
  • A user policy that denies the LocalStack names or localstack.cloud brings the problem back. The troubleshooting section shows how to find the rule.

Tests

Platform: Linux (Arch, x86_64, KVM), sbx 0.51.0, local sandboxes, Docker, agent claude only. Codex and macOS are not tested.

  • make lint: no findings.
  • Before the fix: scripts/smoke.sh claude --registry docker.io --tag 0.1.0 from the first version of this branch. 16 checks pass and 3 fail: "LocalStack hostnames reach the sandbox emulator" (an old check), the MCP AWS client check, and the hostname check after a restart.
  • After the fix: I did not run make smoke, make project-config, or make e2e on the changed kit. They need the local registry and a trusted certificate, and I could not add the trust on this machine. I made sandboxes with sbx create docker.io/docker/sbx-kit-claude:2.1.278 --kit ./kits/localstack and ran the checks by hand. No hosts entry and no DNS_SERVER setting was in place.
Check localstack-pro:latest, kit config localstack-pro:2026.10.6, project config
Sandbox resolves the name and test.localhost.localstack.cloud to 127.0.0.1 pass pass
AWS CLI through localhost.localstack.cloud, and an S3 subdomain URL pass pass
LocalStack log has no No upstream dns server found pass pass
Container resolves the name, a subdomain, and pypi.org; not example.com pass not run
A Python Lambda function resolves the name to the LocalStack container not run pass
MCP localstack-aws-client call pass pass
Proxy answers 403 for the name and a subdomain pass pass
The same after lstk restart pass not run
The same after sbx stop and a new session pass not run

lstk start no longer prints Could not resolve localhost.localstack.cloud, falling back to 127.0.0.1.

Please run make smoke for both agents on macOS before the merge.

@plafond plafond changed the title fix(kit): resolve localhost.localstack.cloud from /etc/hosts because sbx refuses its DNS lookup fix(kit): resolve LocalStack hostnames with the LocalStack DNS server because sbx refuses their DNS lookup Nov 15, 2026
@plafond plafond changed the title fix(kit): resolve LocalStack hostnames with the LocalStack DNS server because sbx refuses their DNS lookup fix(kit): allow the LocalStack hostnames in the network policy so that sbx resolves them Nov 16, 2026
@plafond
plafond requested a review from HarshCasper November 16, 2026 03:38
@plafond

plafond commented Nov 16, 2026

Copy link
Copy Markdown
Author

@HarshCasper - sorry for all the noise - Claude needed quite a bit of wrangling (and my first time playing with sbx) but I think I finally got it in a decent spot..

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.

localhost.localstack.cloud does not resolve in the sandbox, so the MCP server AWS client cannot reach LocalStack

1 participant