Learn LocalStack - CLI & Lifecycle Management

#Introduction

In episode 3 your emulator was running and verified via localstack status and awslocal sts get-caller-identity. Now we level up: managing the emulator lifecycle professionally and controlling its behavior through environment variables.

This capability is what separates "just trying it out" from "operating": knowing when a restart is needed, how to read logs when errors occur, how to ensure state isn't lost, and how to restrict the emulator to only the services you need. All of it will be used in almost every upcoming episode.

#Basic CLI Commands

The following table summarizes the main lifecycle commands:

#start, stop, and restart

The most basic cycle. When the emulator runs in the background, stop halts it and restart starts it again quickly:

localstack status
localstack restart
localstack stop

#status and services

To know the emulator's state, these two commands are your go-to:

localstack status
localstack services

localstack status gives you container information (running or stopped, image version, endpoint address). localstack services lists the active services — this is where you can confirm, for example, that s3 and dynamodb are ready to use.

#logs

When an error occurs, localstack logs is the first source of truth:

localstack logs

#config

The config command displays the currently active configuration and validates it:

localstack config show
localstack config validate

#Environment Variable Configuration

LocalStack is configured almost entirely through environment variables. Here are the most commonly used ones:

#PERSISTENCE

By default, emulator state (buckets, tables, items) is lost when the container stops. With PERSISTENCE=1, state is saved to a volume and restored automatically on restart. It's important to remember: this makes development easier, but don't rely on it as a backup — full coverage is in episode 12.

#DEBUG

Turn on DEBUG=1 when something goes wrong. The log output becomes much more detailed, including per-service request traces. On a stable workload, keep it off so the logs don't flood your output.

#SERVICES

The default emulator loads many services. With SERVICES=s3,dynamodb, only two services are loaded — booting is faster, the container is lighter, and no providers are "noisy" in the logs.

#LOCALSTACK_API_KEY (Pro)

Pro features (Cloud Pods, AWS Replicator, Web Application) are enabled by injecting your API key into this variable. Because the image has been a single one since v2026.03.0, you don't need to switch images — just add the key.

#LAMBDA_EXECUTOR

Determines how Lambda functions execute: docker (each function runs in its own container — closest to production) or local (faster, runs directly in the emulator process). The Lambda material is in episode 7.

#Practice: Restricting Services

Let's apply a combination of env vars in Docker Compose. Create an emulator that only runs S3 and DynamoDB with persistence enabled:

services:
  localstack:
    image: localstack/localstack:stable
    container_name: localstack-main
    ports:
      - "4566:4566"
    environment:
      - PERSISTENCE=1
      - SERVICES=s3,dynamodb
    volumes:
      - "./.localstack:/var/lib/localstack"

After docker compose up -d, verify that only two services are active:

localstack services

#Closing

• Master the lifecycle: localstack start, stop, restart, status, logs, and config.
• PERSISTENCE=1 saves state across restarts; DEBUG=1 is for troubleshooting.
• SERVICES=s3,dynamodb keeps the emulator light and fast.
• LOCALSTACK_API_KEY enables Pro; LAMBDA_EXECUTOR sets the Lambda execution mode.

Your emulator is now ready and well-managed. In the next episode, episode 5, we start using real services: mastering S3 on LocalStack — creating buckets and objects, versioning, presigned URLs, lifecycle, and advanced parity features. Turn on your emulator and follow along!