`localstack/localstack:latest` will require auth token from March 23 — docs & usage update needed

[HarshCasper]

Hey folks 👋

I'm Harsh from the LocalStack team. Wanted to flag an upcoming change that will directly affect users of this library.

What's changing: Starting March 23, 2026, localstack/localstack:latest on Docker Hub will consolidate into a single unified image that requires authentication via a LOCALSTACK_AUTH_TOKEN. The free Community image, as it exists today, will no longer be available under that tag without an auth token set.

What this means for this repo:

go-localstack spins up the LocalStack Docker container directly via localstack.NewInstance() and l.Start(). After March 23, any user calling l.Start() without a LOCALSTACK_AUTH_TOKEN configured in the container environment will get an authentication error, causing their tests to fail immediately.

The places most likely to need updating:

• The README examples (ExampleLocalstackSdkV2EndpointResolverV2, ExampleLocalstackSdkV2, TestWithLocalStack), which don't currently mention auth token setup
• The localstack.go implementation, where support for passing LOCALSTACK_AUTH_TOKEN as an environment variable to the container may need to be added or documented
• The CI/CD pipeline (.github/workflows/test.yml) if it pulls the community image without an auth token

What users will need to do:

1. Sign up for a free LocalStack account at localstack.cloud
2. Generate an auth token from the LocalStack Web App
3. Pass LOCALSTACK_AUTH_TOKEN as an environment variable when starting the LocalStack container

If the library supports passing custom environment variables to the container, the usage would look something like:

l, err := localstack.NewInstance(localstack.WithEnvironment(map[string]string{
    "LOCALSTACK_AUTH_TOKEN": os.Getenv("LOCALSTACK_AUTH_TOKEN"),
}))

If this option doesn't exist yet, it would be a valuable addition for users to make this transition smoothly.

The good news: A free tier is staying — no one has to pay. CI credits are now unlimited on all plans, including free, and open-source projects like this one can apply for free access to paid plans.

Full details in our announcements:

• https://blog.localstack.cloud/the-road-ahead-for-localstack/
• https://blog.localstack.cloud/localstack-single-image-next-steps/
• https://blog.localstack.cloud/2026-upcoming-pricing-changes/

Happy to help with any doc updates, review PRs, or answer questions. Let us know if there's anything we can do to make this easier — and thanks for maintaining this library for the Go community! 🙏

[elgohr]

Hi @HarshCasper ,

thank you for creating the issue!
Will have a deeper look.

By the way, it would be great if there could be some support/sponsoring for the project (e.g. #970).

[elgohr]

Should be addressed in a89f446
Do you see open topics?

[HarshCasper]

Hi @elgohr — Thanks for your prompt response and for working on this! 🙌 We'd love to sponsor the project. Can you please send a email at harsh@localstack.cloud from the email you have used to setup your LocalStack account and I'll have the appropriate license assigned to you (and any developers working on this project).