Learn LocalStack - Core Concepts & Main Architecture

#Introduction

In episode 1 we understood why LocalStack exists: solving the problems of cost, speed, and reproducibility by mimicking AWS APIs locally. Now the question shifts from "why" to "how" — how can a single emulator pretend to be dozens of AWS services at once?

Understanding this architecture matters because it will shape your mental model. When you later debug why S3 behaves slightly differently from DynamoDB, or why IAM isn't as strict as real AWS, the answer lies in the architecture we're about to discuss.

#One Gateway for All Services

LocalStack's underlying principle is simple: all AWS requests come in through a single endpoint, then get routed to the right provider based on the requested service and action.

Historically, LocalStack listened on many ports numbered 457x — one port per service. The modern architecture replaces that with a single gateway endpoint at http://localhost:4566: one address, dozens of APIs.

How does the gateway know which service is being requested? It detects it from the request path and headers. For example, a request to a bucket path with the S3 service Host header is treated as an S3 operation, while a request to a DynamoDB path is routed to the DynamoDB provider. You don't need to care about the routing details — what matters is the consistency:

• A single endpoint for everything: http://localhost:4566.
• Port 4566 handles both HTTP and HTTPS protocols for all services.
• A health check is available at /_localstack/health to verify status.

awslocal s3 ls
awslocal dynamodb list-tables
awslocal sts get-caller-identity

All three commands above hit the same endpoint (http://localhost:4566), yet each is executed by a different provider.

#The Provider-Based Architecture

This is the most important concept in this episode. LocalStack is built with a provider-based pattern: each AWS service is implemented as a provider (plugin) that adheres to the AWS API contract. The gateway only handles routing — the service logic lives in each provider.

Think of it like extensions in VS Code: the core editor only provides the framework, and each extension adds capabilities. Likewise with LocalStack: the emulator framework handles routing, configuration, and lifecycle, while the s3, dynamodb, lambda, and other providers implement the API details of each service.

The consequences of this architecture show up in two ways:

• Services can be activated one by one. With SERVICES=s3,dynamodb, only two providers are loaded — the container is lighter and boots faster.
• Parity can be uneven across services. Mature providers (S3, DynamoDB, Lambda, SQS) are very close to AWS; other providers may still simplify their behavior.

You can easily inspect the service coverage via the CLI:

localstack services

The output shows the recognized service names — from s3, dynamodb, lambda, sqs, sns, to apigateway — along with indicators of their support level.

#Stateful Emulation vs Mock

Because each provider is written separately, the implementation approaches vary too. The two poles are:

This difference matters for setting expectations. A DynamoDB table created with create-table genuinely stores items — you can put-item and then get-item and get your data back. IAM, on the other hand, only validates policies superficially: it doesn't enforce permissions as strictly as real AWS. For development and integration testing, stateful services are the most valuable; for mock services, just be aware of their limitations.

#Core Components

LocalStack isn't a single program, but an interconnected ecosystem. Get to know its five core components.

#1. The localstack CLI

The localstack CLI is the primary interface for controlling the emulator: localstack start, localstack status, localstack logs, and so on. This CLI is what starts the Docker container and waits until it's ready. Without the CLI, managing the emulator means holding onto Docker directly — the CLI makes it more convenient and consistent.

#2. The localstack/localstack Docker Image

The entire emulator runs inside the localstack/localstack image. Since v2026.03.0 this image is a single one for Community and Pro — enabling Pro features is done through the LOCALSTACK_API_KEY variable, not a different image. Tags are also available for development workflows:

For everyday work use stable; nightly is only for trying features before an official release. The latest stable release at the time this article was written is 2026.07.0.

#3. awslocal

awslocal is an AWS CLI wrapper that automatically adds --endpoint-url=http://localhost:4566. It saves you from typing the endpoint over and over and makes commands easier to read.

#4. Web Application

The LocalStack Web Application (at app.localstack.cloud) is a graphical dashboard for viewing emulator state: containers, active services, and logs. Advanced features like Cloud Pods and AWS Replicator (Pro) are operated through this interface. For Community, the terminal remains the main interface.

#5. Configuration via Environment Variables

The emulator is configured almost entirely through environment variables. Some of the most commonly used:

All of these variables will be practiced in depth in episode 4.

#The Flow of a Single Request

To solidify your understanding, let's follow a single awslocal s3 mb s3://bucket request:

1. awslocal calls the AWS CLI with --endpoint-url=http://localhost:4566.
2. The HTTP request arrives at the gateway on port 4566.
3. The gateway identifies the action (CreateBucket) and service (s3).
4. The router forwards the request to the S3 provider.
5. The provider creates the bucket in the emulator and returns a response.
6. The AWS CLI formats the response and displays the output.

This whole flow happens in milliseconds on your local machine — no network to the cloud, no cost.

#Closing

• A single gateway http://localhost:4566 replaces the many 457x ports — one endpoint for all services.
• Provider-based architecture: each service is a plugin with an AWS API contract, routed by the gateway.
• There's stateful emulation (S3, DynamoDB, SQS) and mocking (IAM, Route 53, STS) — know the difference so your expectations stay realistic.
• Core components: the localstack CLI, the localstack/localstack image, awslocal, the Web Application, and env var configuration.
• A single request flows through: CLI → gateway → router → provider → response, all on your local machine.

In the next episode, episode 3, we start hands-on: running LocalStack for the first time with localstack start and Docker Compose, waiting for the running status, then verifying with localstack status, localstack services, and awslocal sts get-caller-identity. Get your Docker ready now!