LocalStack Administrator & Developer Guide

1. Architecture Overview

LocalStack is an AWS cloud service emulator built as a Python application that runs inside a Docker container. It provides a single gateway endpoint (default port 4566) that accepts AWS API requests via any standard SDK, CLI, or IaC tool, routes them to service-specific provider implementations, and returns AWS-compatible responses — all without connecting to real AWS infrastructure.

The system is designed around three core architectural principles: a plugin-based service model that loads services on demand, a gateway with a handler chain pattern for request processing, and a runtime lifecycle with hook points for extensibility.

Architecture Diagram

                    ┌─────────────────────────────────────────┐
                    │           Docker Container              │
                    │                                         │
  AWS SDK/CLI  ─────┤──► Gateway (:4566)                      │
  Terraform         │     │                                   │
  CDK               │     ├── Request Handlers (20+)          │
  Pulumi            │     │   ├── AccountID Extraction        │
                    │     │   ├── Service Router               │
                    │     │   └── Integration Handlers         │
                    │     │                                   │
                    │     ├── Service Plugin Manager           │
                    │     │   ├── S3 Provider                  │
                    │     │   ├── Lambda Provider              │
                    │     │   ├── DynamoDB Provider             │
                    │     │   ├── SQS Provider                 │
                    │     │   └── ... (30+ services)           │
                    │     │                                   │
                    │     ├── Exception Handlers (4)           │
                    │     ├── Response Handlers (8)            │
                    │     └── Finalizers (2)                   │
                    │                                         │
                    │  ┌── DNS Server (:53) ──────────────┐   │
                    │  │   Resolves *.amazonaws.com → GW  │   │
                    │  └──────────────────────────────────┘   │
                    │                                         │
                    │  ┌── Init Scripts ──────────────────┐   │
                    │  │   boot.d → start.d → ready.d     │   │
                    │  │   shutdown.d (on exit)            │   │
                    │  └──────────────────────────────────┘   │
                    │                                         │
                    │  /var/lib/localstack/                    │
                    │    ├── cache/    (downloaded deps)       │
                    │    ├── data/     (persistence snapshots) │
                    │    ├── tmp/      (transient state)       │
                    │    └── logs/     (service logs)          │
                    └─────────────────────────────────────────┘

Component Inventory

Technology Stack

Note

The gateway server type is configurable via GATEWAY_SERVER. The default twisted server provides stable HTTP/1.1 handling. The hypercorn alternative supports HTTP/2 but has known stability issues with Lambda creation (GitHub issue #13020) and connection reuse (GitHub issue #13039).

Request Processing Flow

1. Client sends request to http://localhost:4566 with AWS SigV4 headers
2. Gateway receives via Twisted/Hypercorn server
3. Request handler chain processes sequentially:
   • Account ID extraction from access key (AKIA/ASIA/LKIA/LSIA prefix decoding)
   • Service identification from request headers/path
   • Request parsing and validation
   • Route matching to service provider
4. Service plugin loaded on demand (lazy initialization via plux)
5. Provider processes request (moto delegation or custom ASF implementation)
6. Response handler chain transforms the response
7. Exception handlers catch and format errors as AWS-compatible XML/JSON
8. Finalizers complete the request lifecycle

2. System Requirements

Minimum Hardware

Software Dependencies

Platform Support

Important

Platform detection is handled by localstack/config.py which checks in_docker(), is_linux(), is_macos(), is_windows(), and is_wsl(). The WINDOWS_DOCKER_MOUNT_PREFIX variable (default: /host_mnt) handles Windows path translation for Docker volume mounts.

3. Configuration Reference

LocalStack exposes 153 environment variables for configuration. All are set via environment variables — there is no configuration file format. Variables are read at startup from localstack/config.py and localstack/constants.py.

Configuration Loading Order

1. Defaults defined in config.py
2. Profile file ~/.localstack/{CONFIG_PROFILE}.env loaded via dotenv
3. Shell environment variables (highest priority)

Core Configuration

Gateway Configuration

Warning

Setting LOCALSTACK_HOST incorrectly can break internal healthchecks (GitHub issue #13883). The value must be resolvable from within the container. For external access, configure your client's endpoint URL separately.

Persistence & Snapshot Configuration

Docker Configuration

DNS Configuration

Lambda Configuration

Lambda Limits

Lambda Init Binary Configuration

Lambda Event Source Mapping

DynamoDB Configuration

Tip

Error probability settings are useful for chaos testing. Set DYNAMODB_ERROR_PROBABILITY=0.05 to simulate a 5% failure rate in development environments.

Kinesis Configuration

CORS Configuration

Network & Proxy Configuration

Logging & Debug Configuration

Note

LOG_LEVEL_OVERRIDES accepts a JSON string mapping logger names to levels, e.g., {"botocore":"WARNING","urllib3":"WARNING"}. This reduces log noise from verbose libraries.

Service-Specific Configuration

Provider Override Configuration

Build & Version Information

Annotated Production Configuration

# Production-grade Docker Compose for CI/CD
docker run --rm -d \
  --name localstack-ci \
  -p 4566:4566 \
  -p 4510-4559:4510-4559 \
  -e SERVICES=s3,sqs,sns,lambda,dynamodb,cloudformation,iam \
  -e GATEWAY_SERVER=twisted \
  -e GATEWAY_WORKER_COUNT=1000 \
  -e LAMBDA_KEEPALIVE_MS=300000 \
  -e LAMBDA_DOCKER_NETWORK=ci-network \
  -e LAMBDA_REMOVE_CONTAINERS=1 \
  -e PERSISTENCE=0 \
  -e DNS_ADDRESS=0.0.0.0 \
  -e SKIP_INFRA_DOWNLOADS=0 \
  -e DEBUG=0 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ./init:/etc/localstack/init \
  localstack/localstack

4. Deployment & Scaling

Docker Deployment

Standalone Container

docker run --rm -d \
  --name localstack \
  -p 4566:4566 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ./data:/var/lib/localstack \
  localstack/localstack

Docker Compose

version: "3.8"
services:
  localstack:
    image: localstack/localstack
    container_name: localstack
    ports:
      - "4566:4566"
      - "4510-4559:4510-4559"
    environment:
      SERVICES: s3,sqs,sns,lambda,dynamodb
      GATEWAY_WORKER_COUNT: 1000
      LAMBDA_DOCKER_NETWORK: ${COMPOSE_PROJECT_NAME}_default
      PERSISTENCE: 1
    volumes:
      - localstack-data:/var/lib/localstack
      - /var/run/docker.sock:/var/run/docker.sock
      - ./init:/etc/localstack/init
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4566/_localstack/health"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  localstack-data:

Tip

Set LAMBDA_DOCKER_NETWORK to ${COMPOSE_PROJECT_NAME}_default so Lambda containers automatically join the compose network and can reach other services.

Kubernetes Deployment

LocalStack includes development tooling for Kubernetes via k3d and Helm:

# Development setup (from localstack/dev/kubernetes/)
python -m localstack.dev.kubernetes

Warning

The Kubernetes tooling in this repository is for development and testing of LocalStack itself, not for deploying LocalStack as a service in Kubernetes. For production K8s deployment, use the official Helm chart.

CI/CD Integration

GitHub Actions

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      localstack:
        image: localstack/localstack
        ports:
          - 4566:4566
        env:
          SERVICES: s3,sqs,lambda,dynamodb
    steps:
      - uses: actions/checkout@v4
      - run: |
          pip install awscli-local
          awslocal s3 mb s3://test-bucket
          # Run your tests

GitLab CI

test:
  services:
    - name: localstack/localstack
      alias: localstack
  variables:
    AWS_ENDPOINT_URL: http://localstack:4566
  script:
    - pip install awscli-local
    - awslocal s3 mb s3://test-bucket

Volume Mount Architecture

LocalStack uses a standardized directory structure inside the container:

The Directories class in config.py manages these paths with properties: static_libs, var_libs, cache, tmp, mounted_tmp, functions, data, config, init, logs.

5. Operations

Health Monitoring

The health endpoint provides service status:

# Basic health check
curl http://localhost:4566/_localstack/health

# Also available at legacy path
curl http://localhost:4566/health

{
  "services": {
    "s3": "available",
    "sqs": "available",
    "lambda": "running",
    "dynamodb": "available"
  },
  "features": {}
}

Service states:

Note

The health endpoint supports POST requests with action field for service control: restart to restart a service, kill to stop one.

Service Management via Health Endpoint

# Restart a specific service
curl -X POST http://localhost:4566/health \
  -H "Content-Type: application/json" \
  -d '{"action": "restart", "services": ["s3"]}'

# Kill a service
curl -X POST http://localhost:4566/health \
  -H "Content-Type: application/json" \
  -d '{"action": "kill", "services": ["lambda"]}'

Container Lifecycle Management

# Start in background
localstack start -d

# Check status
localstack status

# View logs
docker logs -f localstack-main

# Stop gracefully
localstack stop

# Force stop
docker rm -f localstack-main

Init Hook Lifecycle

Init hooks execute at specific points in the LocalStack lifecycle:

Scripts are discovered by InitScriptManager and executed by ShellScriptRunner (.sh) or PythonScriptRunner (.py).

Important

Init scripts that exit with a non-zero code raise an OSError with the message Script {path} returned a non-zero exit code {exit_code}. This does not halt LocalStack startup but is logged as an error.

Snapshot Operations

# Manual snapshot save (via internal API)
curl -X POST http://localhost:4566/_localstack/state/save

# Manual snapshot load
curl -X POST http://localhost:4566/_localstack/state/load

# Reset all state
curl -X POST http://localhost:4566/_localstack/state/reset

Log Management

Configure logging granularity:

# Global log level
LS_LOG=debug

# Per-module overrides (JSON string)
LOG_LEVEL_OVERRIDES='{"botocore":"WARNING","urllib3":"WARNING","docker":"INFO"}'

Tip

In production CI runs, set LS_LOG=warning and selectively enable debug for specific modules via LOG_LEVEL_OVERRIDES to reduce log volume while retaining diagnostic capability.

6. Performance

Gateway Server Tuning

Lambda Performance

JVM Service Tuning

Services backed by JVM processes (DynamoDB Local, Kinesis mock, OpenSearch) accept heap configuration:

# DynamoDB
DYNAMODB_HEAP_SIZE=512m

# Kinesis
KINESIS_MOCK_INITIAL_HEAP_SIZE=256m
KINESIS_MOCK_MAXIMUM_HEAP_SIZE=512m

Note

Each JVM-backed service starts a separate Java process. On a 4 GB container, running DynamoDB + Kinesis + OpenSearch simultaneously can consume 1.5-2 GB of heap alone. Size your container accordingly.

Service Loading Strategy

LocalStack uses lazy loading: services initialize on first API request, not at startup. This means:

• First request to a service incurs initialization latency (1-10 seconds depending on service)
• Subsequent requests are fast
• Use init hooks in ready.d/ to pre-warm services by making initial API calls

Port Range Management

The PortRange class manages dynamic port allocation for sub-services:

• EXTERNAL_SERVICE_PORTS_START / EXTERNAL_SERVICE_PORTS_END: External-facing ports (default: 4510-4559)
• SERVICE_INSTANCES_PORTS_START / SERVICE_INSTANCES_PORTS_END: Internal service instance ports

If you see PortNotAvailableException, expand the port range or reduce concurrent service instances.

7. Security

Authentication Model

LocalStack accepts any AWS credentials by default. There is no authentication enforcement in the Community Edition. The access key ID is used for account identification (multi-account isolation), not for access control.

Access key prefixes determine account routing:

Caution

LocalStack does not enforce IAM policies by default in the Community Edition. Do not rely on LocalStack for security testing of IAM permissions. Production IAM policy validation requires testing against real AWS.

Network Security

• Default bind: 0.0.0.0:4566 — accessible from all network interfaces
• DNS server: Binds to port 53 (privileged port, requires root or capabilities)
• Docker socket: Required for Lambda — grants full Docker API access
• Inter-container traffic: Lambda containers communicate via Docker networking

Hardening recommendations:

1. Bind to localhost only: GATEWAY_LISTEN=127.0.0.1:4566
2. Use Docker user namespaces to limit socket access
3. Run in an isolated Docker network: --network isolated-net
4. Never expose LocalStack to the public internet

SSL/TLS

Custom SSL certificates can be provided via CUSTOM_SSL_CERT_PATH. The CA bundle for outbound HTTPS requests is configurable via REQUESTS_CA_BUNDLE.

Privileged Port Handling

When GATEWAY_LISTEN specifies a port below 1024, LocalStack attempts to start a TCP proxy via sudo. If running in a non-TTY environment, this fails with cannot get sudo password from non-tty input. Solutions:

• Use ports above 1024 (default 4566)
• Run the container as root
• Use --cap-add NET_BIND_SERVICE

Secrets in Environment

No sensitive secrets are required for the Community Edition. Pro features require:

• LOCALSTACK_AUTH_TOKEN — authentication token for Pro services
• LOCALSTACK_API_KEY — legacy API key (deprecated)
• GITHUB_API_TOKEN — optional, for higher GitHub API rate limits

Warning

Never expose LOCALSTACK_AUTH_TOKEN in public CI logs. Use secret variables in your CI/CD system.

8. Developer Internals

Repository Structure

localstack-core/localstack/
├── aws/
│   ├── app.py              # LocalstackAwsGateway — main entry point
│   ├── scaffold.py         # ASF API stub generator
│   ├── client.py           # Internal AWS client
│   ├── connect.py          # AWS connection management
│   ├── mocking.py          # Response shape generation
│   └── handlers/           # Gateway request/response handlers
│       └── service_plugin.py  # Service lazy-loading handler
├── cli/
│   └── lpm.py              # LocalStack Package Manager CLI
├── config.py               # All 153 config variables
├── constants.py            # Constants (API_ENDPOINT, etc.)
├── deprecations.py         # Deprecation warnings
├── dns/
│   └── server.py           # Built-in DNS server
├── extensions/
│   └── api.py              # Extension lifecycle API
├── logging/
│   └── setup.py            # Logging configuration
├── runtime/
│   ├── main.py             # Runtime entry point
│   ├── runtime.py          # LocalstackRuntime class
│   ├── init.py             # InitScriptManager
│   ├── components.py       # Gateway server factory
│   ├── current.py          # Runtime singleton
│   └── legacy.py           # Legacy supervisor support
├── services/
│   ├── edge.py             # Gateway listener, HealthResource
│   ├── plugins.py          # Service plugin manager
│   ├── stores.py           # Multi-account/region store
│   ├── moto.py             # Moto integration layer
│   └── apigateway/         # API Gateway provider (example)
│       └── next_gen/
│           └── execute_api/
│               └── handlers/  # Request/response handlers
└── utils/
    ├── archives.py         # Archive download/extraction
    ├── batching.py         # Batcher/AsyncBatcher
    ├── bootstrap.py        # Container bootstrap utilities
    ├── checksum.py         # Download checksum verification
    ├── collections.py      # Dict navigation utilities
    ├── container_networking.py  # Container network resolution
    ├── diagnose.py         # Diagnostic information
    ├── docker_utils.py     # Docker volume/mount utilities
    ├── files.py            # File system utilities
    ├── functions.py        # Function utilities (recursion guard)
    ├── http.py             # HTTP download utilities
    ├── iputils.py          # IP address utilities
    ├── net.py              # Port management (PortRange)
    ├── objects.py          # Object utilities
    ├── patch.py            # Monkey-patching framework
    ├── platform.py         # OS detection
    ├── scheduler.py        # Task scheduling (Deadline)
    ├── serving.py          # Server lifecycle management
    ├── testutil.py         # Test utilities
    ├── time.py             # Timestamp parsing
    └── venv.py             # Virtual environment management

Architecture Deep Dive

Gateway Handler Chain

The LocalstackAwsGateway in aws/app.py orchestrates request processing through a chain of handlers:

Request Handlers (20+):

• Account ID extraction from SigV4 headers
• Service identification and routing
• Request parsing and validation
• API key validation (for API Gateway)
• Integration request transformation

Exception Handlers (4):

• AWS error response formatting
• Internal server error handling
• Unsupported media type errors
• Authentication errors

Response Handlers (8):

• CORS header injection
• Response transformation
• Content type negotiation

Finalizers (2):

• Metrics collection
• Connection cleanup

Service Plugin System

Services are loaded via the plux plugin framework using Python entry points. The ServicePluginManager in services/plugins.py handles:

1. Discovery: Scans entry points in the localstack.services namespace
2. Lazy loading: Services initialize only on first API request
3. State tracking: Services transition through states: disabled → starting → available → running → stopping
4. Error handling: Failed services raise ServiceStateException

# Service lifecycle
ServiceDisabled → ServiceStarting → ServiceAvailable → ServiceRunning
                                                     → ServiceStopping

Multi-Account/Region Store

The stores.py module provides AccountRegionBundle for service state isolation:

• Each service maintains state per (account_id, region) tuple
• Account IDs validated as 12-digit strings
• Region names validated against known AWS regions
• Cross-account and cross-region attributes supported via CrossAccountAttribute and CrossRegionAttribute

Moto Integration

Many services delegate to the moto library via services/moto.py:

• Request routing maps to moto backends
• CommonServiceException wraps moto errors as AWS-compatible responses
• Custom providers can override moto behavior per service

Code Patterns & Conventions

Monkey-Patching Framework

utils/patch.py provides a structured patching system:

from localstack.utils.patch import patch

@patch(target=SomeClass.some_method)
def custom_behavior(fn, self, *args, **kwargs):
    # pre-processing
    result = fn(self, *args, **kwargs)
    # post-processing
    return result

Restrictions: cannot patch classes implementing __getattr__.

Batcher Utilities

utils/batching.py provides Batcher and AsyncBatcher for collecting items and processing in batches. Raises ValueError if items are added after the batcher is stopped.

Safe Dict Navigation

utils/collections.py provides safe navigation into nested dicts using JSON Path-like syntax ($.key.subkey). Root node must start with $.

Port Management

utils/net.py provides PortRange for managing dynamic port allocation with reservation tracking. Raises PortNotAvailableException when no ports are available.

Testing Strategy

The codebase uses a comprehensive testing framework:

Test Types

Testing Rules (from CONTRIBUTING.md)

1. R01: Tests must be reproducible and deterministic
2. R02: Each test must clean up after itself
3. R03: Tests should not depend on execution order
4. R04: Use pytest fixtures for resource setup
5. R05-R14: Additional rules covering naming conventions, assertions, timeouts, and resource management

Parity/Snapshot Testing

The parity testing framework captures responses from both LocalStack and real AWS, then compares them via snapshot files. This ensures behavioral compatibility:

@markers.aws.validated
def test_s3_put_get(self, aws_client, s3_bucket):
    aws_client.s3.put_object(Bucket=s3_bucket, Key="test", Body=b"data")
    result = aws_client.s3.get_object(Bucket=s3_bucket, Key="test")
    snapshot.match("get_object", result)

Running Tests

# Unit tests
pytest tests/unit/

# Integration tests (requires running LocalStack)
pytest tests/aws/services/s3/

# With verbose output
pytest -v tests/unit/utils/

Extension API

The extensions system in extensions/api.py provides lifecycle hooks for custom plugins:

from localstack.extensions.api import Extension

class MyExtension(Extension):
    name = "my-extension"

    def on_extension_load(self):
        """Called when the extension is loaded."""
        pass

    def on_platform_start(self):
        """Called when LocalStack platform starts."""
        pass

    def update_gateway_routes(self, router):
        """Add custom routes to the gateway."""
        pass

    def update_request_handlers(self, handlers):
        """Add custom request handlers."""
        pass

    def update_response_handlers(self, handlers):
        """Add custom response handlers."""
        pass

    def on_platform_ready(self):
        """Called when all services are ready."""
        pass

    def on_platform_shutdown(self):
        """Called on shutdown."""
        pass

Scaffold Tool

The scaffold tool generates AWS Service Framework (ASF) API stubs from AWS service models:

# Generate stubs for a new service
localstack scaffold generate ec2 --doc --save --path ./localstack-core/localstack/aws/api

# Upgrade existing stubs to match latest service model
localstack scaffold upgrade --doc --path ./localstack-core/localstack/aws/api

Key Classes Reference

Contributing

From CONTRIBUTING.md:

• Pull requests: Fork, create feature branch, submit PR against main
• Coding style: Follow existing patterns; use black for formatting
• CLA: Contributors must sign the Contributor License Agreement
• Tests: All changes must include appropriate test coverage
• Documentation: Update relevant docs for user-facing changes

9. Integration Points

AWS SDK Integration

Any AWS SDK can be configured to use LocalStack by setting the endpoint URL:

IaC Tool Integration

Docker Integration

LocalStack interacts with Docker in multiple ways:

• Docker socket: Required for Lambda container management
• Docker networks: Configurable for inter-container communication
• Docker images: Custom images via LAMBDA_RUNTIME_IMAGE_MAPPING
• Docker flags: Passthrough via DOCKER_FLAGS and LAMBDA_DOCKER_FLAGS

DNS Integration

The built-in DNS server supports:

Operations available via DnsServerProtocol:

• add_host(name, ip) — Add A/AAAA record
• delete_host(name) — Remove record
• add_host_pointing_to_localstack(name) — Add record pointing to LocalStack gateway
• add_alias(source, target) — Add CNAME alias
• add_skip(name) — Skip resolution for name
• clear() — Remove all records

The DNS server starts at priority 20 (before Pro activation) and shuts down at priority -30 (after all services).

Runtime Hooks

Analytics & Telemetry

LocalStack tracks environment variable presence for analytics:

• TRACKED_ENV_VAR: 60+ variables whose values are reported
• PRESENCE_ENV_VAR: 25+ variables where only presence/absence is reported

This data helps the LocalStack team understand feature usage. No service data or request content is transmitted.

Known Compatibility Issues