What Is LocalStack? Test AWS Without the AWS Bill

What Is LocalStack, Actually?

AWS — Amazon Web Services — is the cloud infrastructure that powers a huge chunk of the internet. When your app needs to store a file, it probably goes to S3. When it needs to run a piece of code on-demand, that's probably Lambda. When it needs to pass a message between services, that's likely SQS. AWS has over 200 services and most apps only use a handful of them, but those handful are critical.

The problem is that AWS is a real cloud service with real costs, real credentials, and real consequences for mistakes. If you mistype a configuration and leave something running, you might come back to a bill. If you accidentally make an S3 bucket public, that's a real security problem. And if you're just trying to test whether your code works before you even think about deployment, all of that overhead is unnecessary friction.

LocalStack is a tool that pretends to be AWS on your own machine. You run it, it starts up a local server, and your code connects to http://localhost:4566 instead of the real AWS endpoints. As far as your code is concerned, it's talking to S3. It's talking to Lambda. It's talking to DynamoDB. But it's all simulated, all local, all free, and all completely isolated from the real world.

Think of it like a flight simulator. Pilots train on simulators before they touch real planes — same controls, same instruments, same feedback, but no real consequences if something goes wrong. LocalStack is your flight simulator for AWS infrastructure.

If you're not yet familiar with what serverless functions or cloud infrastructure means in the first place, check out What Is Serverless? first — it'll give you the context that makes LocalStack make sense.

Why Vibe Coders Specifically Need This

Here's the situation that comes up constantly when you build with AI tools:

You ask Claude or Cursor to build a feature. Maybe it's a file upload system. Maybe it's a background job that processes orders. Maybe it's a notification system. The AI does what it does best — generates clean, reasonable-looking code — and a big chunk of that code talks to AWS services.

S3 for file storage. Lambda for the processing function. SQS for the queue. DynamoDB for the data. The AI knows these services cold. It's written this pattern ten thousand times across the training data. The code looks good.

Now what?

If you don't have a way to run this code locally, your options are:

• Set up a real AWS account, create the real resources, configure real IAM permissions, test it, then tear it down. Possible — but a lot of overhead for a feature you're not sure works yet.
• Just deploy it and hope. This works right up until the moment it doesn't, and then you're debugging in production with real user impact.
• Ask the AI to mock all the AWS calls and test the mocked version. This tests your logic but not whether your actual AWS integration works.

None of these are great. LocalStack gives you a fourth option: run the whole thing locally, with real AWS SDK calls hitting a real (simulated) endpoint. You catch the bugs before they touch a real account. You iterate fast. You don't pay anything.

This is especially valuable because AI-generated AWS code has a specific failure pattern: it gets the API calls right but the configuration wrong. The right method, wrong parameter. The right service, wrong permissions setup. LocalStack catches these issues immediately, where debugging in a real AWS environment would mean waiting for deployments and parsing CloudWatch logs.

What Services Does It Support?

LocalStack's free Community tier covers the services that most projects actually use:

S3 (Simple Storage Service) — file storage. Upload images, store documents, serve static assets. The LocalStack S3 implementation is one of the most mature and reliable parts of the project.

Lambda — serverless functions. Write a function, deploy it to LocalStack, trigger it with an event, and see what happens. LocalStack can actually run your Lambda code locally using Docker containers.

DynamoDB — NoSQL database. Create tables, put items, query them. DynamoDB local is actually a well-known pattern — Amazon even ships their own DynamoDB Local as a separate download, but LocalStack integrates it cleanly with everything else.

SQS (Simple Queue Service) — message queues. One service sends a message, another service picks it up. Essential for background jobs and async processing.

SNS (Simple Notification Service) — pub/sub messaging. Broadcast a message and have multiple subscribers receive it.

API Gateway — put an HTTP endpoint in front of your Lambda functions so they're callable like a regular API.

IAM (Identity and Access Management) — simulated permissions. LocalStack doesn't enforce these strictly by default (you can turn enforcement on), but the APIs work so your code doesn't blow up when it tries to create roles or assume permissions.

CloudFormation — deploy infrastructure-as-code templates locally. If your AI is generating CloudFormation or CDK stacks, LocalStack can run them.

The paid Pro tier adds RDS (relational databases), Cognito (authentication), ECS (containers), Kinesis (data streams), and many more. For most vibe coder projects at the early stages, the free tier is everything you need.

Understanding the difference between APIs and services will help you understand why LocalStack's simulation works — your code just needs the right URL and the right response format, and LocalStack provides both.

Real Example: Testing an S3 File Upload Locally

Let's walk through exactly what this looks like in practice. You've got a Node.js app, the AI wrote a file upload function, and you want to test it without touching real AWS.

Step 1: Get LocalStack Running

The easiest way to run LocalStack is with Docker. If you have Docker installed, this is a single command:

docker run --rm -it \
  -p 4566:4566 \
  -e LOCALSTACK_AUTH_TOKEN=your-auth-token \
  localstack/localstack

Since LocalStack now requires an account, you get your auth token from their dashboard after signing up. The free tier token works fine for the Community services.

Once it's running, you'll see output confirming which services are ready. You'll see something like:

LocalStack version: 3.x.x
Ready.

That's your fake AWS running on port 4566.

Step 2: Create a Bucket Locally

You can use the AWS CLI — pointed at LocalStack instead of real AWS — to set things up:

aws --endpoint-url=http://localhost:4566 \
    --region us-east-1 \
    s3 mb s3://my-test-bucket

The key part is --endpoint-url=http://localhost:4566. That redirects the AWS CLI away from real AWS and to your local LocalStack instance. The bucket gets created instantly, for free, locally.

Step 3: The AI-Generated Upload Code

Here's the kind of code your AI might write for an S3 upload:

const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3');
const fs = require('fs');

// In production: no endpoint needed, it goes to real AWS
// In development: point to LocalStack
const s3Client = new S3Client({
  region: 'us-east-1',
  endpoint: process.env.AWS_ENDPOINT_URL || undefined,
  forcePathStyle: true, // Required for LocalStack
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID || 'test',
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || 'test',
  },
});

async function uploadFile(localPath, bucketName, key) {
  const fileContent = fs.readFileSync(localPath);

  const command = new PutObjectCommand({
    Bucket: bucketName,
    Key: key,
    Body: fileContent,
  });

  const result = await s3Client.send(command);
  console.log('Upload successful:', result);
  return result;
}

// Test it
uploadFile('./test-photo.jpg', 'my-test-bucket', 'uploads/test-photo.jpg')
  .then(() => console.log('Done!'))
  .catch(console.error);

Step 4: Run It Against LocalStack

You set one environment variable and run:

AWS_ENDPOINT_URL=http://localhost:4566 node upload.js

The code runs. It connects to LocalStack instead of real AWS. The file gets "uploaded" to your local fake S3 bucket. You see "Upload successful" in your terminal. You can verify the file is there:

aws --endpoint-url=http://localhost:4566 \
    s3 ls s3://my-test-bucket/uploads/

No AWS account. No credentials. No bill. No waiting. You've confirmed the code works in under two minutes.

Step 5: What You're Actually Testing

This local test catches the things AI code gets wrong most often:

• Does the S3Client constructor have the right parameters?
• Is the PutObjectCommand structured correctly?
• Does the async/await chain work without hanging?
• Is the file being read correctly before it's uploaded?
• Are the bucket name and key formatted right?

None of these require real AWS to test. LocalStack gives you real feedback on all of them.

Testing a Lambda Function Locally

S3 is the easy one. Lambda is where LocalStack really earns its keep — because deploying Lambda functions to real AWS takes time, and debugging them means reading CloudWatch logs. Locally, you get instant feedback.

Say your AI wrote a Lambda function that gets triggered by an S3 upload and generates a thumbnail. Here's how you'd test the whole chain with LocalStack:

# 1. Create the S3 bucket
aws --endpoint-url=http://localhost:4566 s3 mb s3://photo-uploads

# 2. Deploy the Lambda function (LocalStack runs it in a Docker container)
aws --endpoint-url=http://localhost:4566 lambda create-function \
  --function-name thumbnail-generator \
  --runtime nodejs20.x \
  --role arn:aws:iam::000000000000:role/lambda-role \
  --handler index.handler \
  --zip-file fileb://function.zip

# 3. Set up the S3 trigger
aws --endpoint-url=http://localhost:4566 s3api put-bucket-notification-configuration \
  --bucket photo-uploads \
  --notification-configuration file://notification.json

# 4. Upload a test photo — this should trigger the Lambda
aws --endpoint-url=http://localhost:4566 \
    s3 cp test-photo.jpg s3://photo-uploads/uploads/test-photo.jpg

# 5. Check the Lambda logs to see what happened
aws --endpoint-url=http://localhost:4566 logs \
    get-log-events \
    --log-group-name /aws/lambda/thumbnail-generator \
    --log-stream-name latest

This whole chain — upload triggers Lambda, Lambda does its thing, you check logs — runs locally in seconds. On real AWS, getting all of this wired up for the first time easily takes an hour. And if something's wrong? You iterate immediately instead of waiting for deployments.

LocalStack even runs the actual Lambda code in a real Docker container (if you have Docker available), which means you're testing your actual runtime, not a simulation of it. The trigger wiring is simulated, but the function execution is real.

The Controversy: What Happened to the Open-Source Repo?

In 2025, LocalStack made a move that upset a significant chunk of their community: they archived their main GitHub repository.

Archiving a GitHub repo means it goes read-only. You can still see the code, but you can't open issues, submit pull requests, or contribute. It signals that the project is no longer accepting community involvement in that form.

For a tool that built its entire reputation on being a free, open, community-driven alternative to expensive cloud testing, this felt like a betrayal to a lot of developers. Hacker News threads ran hot. The complaints were real: LocalStack was now effectively requiring an account sign-up just to download and run what used to be a simple Docker image. The community-contributed fixes and features that had made LocalStack what it was would no longer be accepted.

LocalStack's position is understandable from a business perspective. Running a successful open-source project that's also a commercial product is genuinely hard. The free tier users cost money to support, and if they don't convert to paying customers at a sufficient rate, the business model doesn't work. Many open-source companies have navigated versions of this same tension — HashiCorp with Terraform, Elastic with Elasticsearch, Redis with their license change.

But understanding the business logic doesn't make it sting less if you were used to pulling a Docker image and being done with it.

The practical impact for most users right now is minimal: you sign up for a free account, get a token, include it in your Docker run command, and LocalStack works exactly as it always did. The free tier still covers S3, Lambda, DynamoDB, SQS, and the services that matter for most projects. But the direction of travel is clear — LocalStack is moving toward a more controlled distribution model, and that makes some developers want to hedge their bets with alternatives.

Alternatives to LocalStack

If the account requirement bothers you, or if you only need to simulate one or two specific services, there are targeted alternatives worth knowing about.

MinIO — For S3

MinIO is an open-source object storage server that implements the S3 API. Fully open source, no account required, runs in Docker in one command:

docker run -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  minio/minio server /data --console-address ":9001"

Point your AWS SDK at http://localhost:9000 with forcePathStyle: true and your S3 code works against MinIO without any changes. MinIO also comes with a web dashboard at http://localhost:9001 where you can browse buckets visually.

The catch: MinIO only does S3. If your project also uses Lambda or SQS, you'll need something else for those. But if 80% of your AWS usage is S3, MinIO is a clean, account-free solution.

ElasticMQ — For SQS

ElasticMQ is an in-memory message queue that implements the SQS API. If your project uses queues for background jobs — and AI-generated backends use SQS constantly — ElasticMQ lets you test that queue logic without any real AWS infrastructure.

docker run -p 9324:9324 -p 9325:9325 softwaremill/elasticmq-native

Point your SQS client at http://localhost:9324 and your queue code works as expected. It's fast, it's fully open source, and there's no account to create.

DynamoDB Local — For DynamoDB

Amazon actually ships their own local DynamoDB implementation. It's a JAR file (Java) but there's also a Docker image:

docker run -p 8000:8000 amazon/dynamodb-local

If you're only using DynamoDB and don't need S3 or Lambda, this is the official option and it's very accurate to the real service.

Mixing and Matching

One valid strategy: use LocalStack for Lambda (since LocalStack's Lambda simulation is genuinely hard to replicate elsewhere), MinIO for S3 (since it's simpler and fully open), and ElasticMQ for SQS. Yes, you're running three tools instead of one. But you've eliminated the account requirement for most of your stack, and each tool is focused and reliable at its specific job.

How to Actually Use LocalStack Day-to-Day

Once you've got LocalStack running, here are the patterns that make it work smoothly in a real project.

Use Environment Variables to Switch Between Local and Real AWS

The cleanest approach is a single environment variable that switches your AWS clients between LocalStack and real AWS:

const { S3Client } = require('@aws-sdk/client-s3');

const isLocal = process.env.USE_LOCALSTACK === 'true';

const s3 = new S3Client({
  region: 'us-east-1',
  ...(isLocal && {
    endpoint: 'http://localhost:4566',
    forcePathStyle: true,
    credentials: {
      accessKeyId: 'test',
      secretAccessKey: 'test',
    },
  }),
});

In your local development, you run with USE_LOCALSTACK=true. In production, you don't set that variable and your client uses real AWS credentials automatically. Same code, same logic — the only thing that changes is where it points.

Use a .env File for Development

Keep a .env.local file (which should be in your .gitignore) with your LocalStack settings:

USE_LOCALSTACK=true
AWS_ENDPOINT_URL=http://localhost:4566
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test

Load it with something like dotenv in Node.js or python-dotenv in Python. Your app boots in local mode, talks to LocalStack, and your production environment variables point to real AWS.

Use Docker Compose to Start Everything Together

If your project already uses Docker Compose, add LocalStack as a service so it starts automatically:

services:
  localstack:
    image: localstack/localstack
    ports:
      - "4566:4566"
    environment:
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN}
    volumes:
      - localstack_data:/var/lib/localstack
      - /var/run/docker.sock:/var/run/docker.sock

  app:
    build: .
    environment:
      - USE_LOCALSTACK=true
      - AWS_ENDPOINT_URL=http://localstack:4566
    depends_on:
      - localstack

volumes:
  localstack_data:

Run docker compose up and your whole development stack — app and fake AWS — starts together. This is the setup that makes local development feel seamless.

Understanding Docker Compose in detail makes this click — see What Is Docker? if you want that foundation.

Seed Your Local Resources at Startup

Add a startup script that creates the S3 buckets, SQS queues, and DynamoDB tables your app expects. LocalStack doesn't persist data between restarts by default (you need the Pro tier for that), so having a seed script means your environment is always in the right state:

#!/bin/bash
# scripts/localstack-seed.sh
echo "Creating local AWS resources..."

aws --endpoint-url=http://localhost:4566 \
    s3 mb s3://my-app-uploads 2>/dev/null || true

aws --endpoint-url=http://localhost:4566 \
    sqs create-queue --queue-name job-queue 2>/dev/null || true

aws --endpoint-url=http://localhost:4566 \
    dynamodb create-table \
    --table-name users \
    --attribute-definitions AttributeName=id,AttributeType=S \
    --key-schema AttributeName=id,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST 2>/dev/null || true

echo "Done."

Run this script whenever LocalStack starts (or add it to your Docker Compose startup sequence) and you always have a clean, pre-configured local environment waiting for you.

What to Learn Next

LocalStack sits at the intersection of several concepts that are worth understanding more deeply as you build with AWS services:

• What Is Docker? — LocalStack runs inside Docker. Understanding what Docker actually does helps you understand why LocalStack works the way it does — and how to run it reliably.
• What Is Serverless? — Lambda is a serverless compute service. Understanding the serverless model explains why Lambda is designed the way it is and why testing it locally is non-trivial.
• What Is an API? — LocalStack works because AWS services communicate through APIs. Your code calls the S3 API, LocalStack listens on that API, and responds. Understanding APIs explains why the endpoint swap works transparently.

Frequently Asked Questions