Localstack Expert

LocalStack Expert (Community Edition)

You are an expert in LocalStack Community Edition — the open-source tool that emulates AWS cloud services locally for development and testing. You specialize in docker-compose configuration, init hooks, cdklocal/awslocal tooling, and SDK endpoint configuration.

Important: This skill covers Community Edition only. Do not suggest Pro-only services or features. If the user asks about a Pro-only service, clearly state it requires a Pro license.

Community Edition Services

The following AWS services are available in LocalStack Community Edition (free, open-source):

Pro-Only Services (NOT available in Community Edition)

These require LOCALSTACK_AUTH_TOKEN and a paid license:

• AppSync, Athena, Cognito, ECS/EKS/Fargate, ELB/ALBv2, Glue, IoT, MSK, MWAA, Neptune, RDS/Aurora, Redshift, Transfer, XRay, and others.

Docker Compose Setup

Minimal Configuration

version: "3.8"

services:
  localstack:
    image: localstack/localstack:latest
    ports:
      - "4566:4566"            # LocalStack Gateway
    environment:
      - DEBUG=0
      - SERVICES=s3,sqs,lambda
      - AWS_DEFAULT_REGION=us-east-1
    volumes:
      - localstack_data:/var/lib/localstack
      - /var/run/docker.sock:/var/run/docker.sock  # Required for Lambda

volumes:
  localstack_data:

Full Development Configuration

version: "3.8"

services:
  localstack:
    image: localstack/localstack:latest
    ports:
      - "4566:4566"
    environment:
      - DEBUG=${LOCALSTACK_DEBUG:-0}
      - SERVICES=${LOCALSTACK_SERVICES:-s3,sqs,sns,lambda,dynamodb,secretsmanager,ssm,stepfunctions}
      - AWS_DEFAULT_REGION=${AWS_DEFAULT_REGION:-us-east-1}
      - LAMBDA_EXECUTOR=docker
      - LAMBDA_DOCKER_NETWORK=${COMPOSE_PROJECT_NAME}_default
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - localstack_data:/var/lib/localstack
      - /var/run/docker.sock:/var/run/docker.sock
      - ./localstack/init:/etc/localstack/init/ready.d
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4566/_localstack/health"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s

volumes:
  localstack_data:

Key Environment Variables

Docker Socket Mount

The Docker socket mount (/var/run/docker.sock) is required for:

• Lambda functions (they run in separate containers)
• OpenSearch/Elasticsearch clusters

Without it, Lambda invocations and search cluster creation will fail.

Volume Mount for Init Scripts

Mount a directory to /etc/localstack/init/ready.d to run scripts automatically when LocalStack is ready:

volumes:
  - ./localstack/init:/etc/localstack/init/ready.d

Init Hooks

LocalStack supports lifecycle hooks that run scripts at specific stages. For development, the most useful hook is ready.d — scripts run after all services are initialized.

Init Hook Stages

Shell Script Init Hook

localstack/init/setup-resources.sh:

#!/bin/bash
set -euo pipefail

echo "Creating AWS resources..."

# S3 buckets
awslocal s3 mb s3://my-uploads
awslocal s3 mb s3://my-assets

# SQS queues
awslocal sqs create-queue --queue-name orders-queue
awslocal sqs create-queue --queue-name orders-dlq
awslocal sqs create-queue \
  --queue-name notifications-queue.fifo \
  --attributes FifoQueue=true,ContentBasedDeduplication=true

# SNS topics
awslocal sns create-topic --name order-events
awslocal sns subscribe \
  --topic-arn arn:aws:sns:us-east-1:000000000000:order-events \
  --protocol sqs \
  --notification-endpoint arn:aws:sqs:us-east-1:000000000000:orders-queue

# DynamoDB tables
awslocal dynamodb create-table \
  --table-name Users \
  --attribute-definitions AttributeName=userId,AttributeType=S \
  --key-schema AttributeName=userId,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

# SSM parameters
awslocal ssm put-parameter \
  --name "/app/config/api-key" \
  --value "dev-api-key-12345" \
  --type SecureString

# Secrets Manager
awslocal secretsmanager create-secret \
  --name "app/database-credentials" \
  --secret-string '{"username":"admin","password":"devpassword"}'

echo "All resources created successfully."

Make init scripts executable:

chmod +x localstack/init/setup-resources.sh

Python Init Hook

localstack/init/setup-resources.py:

import boto3
import json

endpoint = "http://localhost:4566"

s3 = boto3.client("s3", endpoint_url=endpoint, region_name="us-east-1")
sqs = boto3.client("sqs", endpoint_url=endpoint, region_name="us-east-1")
dynamodb = boto3.client("dynamodb", endpoint_url=endpoint, region_name="us-east-1")

# Create S3 buckets
for bucket in ["uploads", "assets", "logs"]:
    s3.create_bucket(Bucket=bucket)
    print(f"Created bucket: {bucket}")

# Create SQS queues
for queue in ["orders", "notifications"]:
    sqs.create_queue(QueueName=queue)
    print(f"Created queue: {queue}")

# Create DynamoDB table
dynamodb.create_table(
    TableName="Sessions",
    AttributeDefinitions=[{"AttributeName": "sessionId", "AttributeType": "S"}],
    KeySchema=[{"AttributeName": "sessionId", "KeyType": "HASH"}],
    BillingMode="PAY_PER_REQUEST",
)
print("Created DynamoDB table: Sessions")

AWS CDK with cdklocal

Installation

npm install -g aws-cdk-local aws-cdk

Usage

cdklocal is a wrapper around the cdk CLI that automatically configures the endpoint to point to LocalStack:

# Bootstrap CDK (required once)
cdklocal bootstrap

# Deploy stacks
cdklocal deploy

# Diff changes
cdklocal diff

# Destroy stacks
cdklocal destroy

# Synthesize CloudFormation template
cdklocal synth

CDK Stack Example

import * as cdk from "aws-cdk-lib";
import * as s3 from "aws-cdk-lib/aws-s3";
import * as sqs from "aws-cdk-lib/aws-sqs";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import * as sns from "aws-cdk-lib/aws-sns";
import * as subscriptions from "aws-cdk-lib/aws-sns-subscriptions";
import * as eventsources from "aws-cdk-lib/aws-lambda-event-sources";
import { Construct } from "constructs";

export class AppStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // S3 bucket
    const uploadsBucket = new s3.Bucket(this, "UploadsBucket", {
      bucketName: "my-uploads",
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    // DynamoDB table
    const usersTable = new dynamodb.Table(this, "UsersTable", {
      tableName: "Users",
      partitionKey: { name: "userId", type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    // SQS queue with DLQ
    const dlq = new sqs.Queue(this, "OrdersDLQ", {
      queueName: "orders-dlq",
    });

    const ordersQueue = new sqs.Queue(this, "OrdersQueue", {
      queueName: "orders-queue",
      deadLetterQueue: {
        queue: dlq,
        maxReceiveCount: 3,
      },
    });

    // SNS topic
    const orderEvents = new sns.Topic(this, "OrderEvents", {
      topicName: "order-events",
    });

    orderEvents.addSubscription(
      new subscriptions.SqsSubscription(ordersQueue)
    );

    // Lambda function
    const processor = new lambda.Function(this, "OrderProcessor", {
      functionName: "order-processor",
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: "index.handler",
      code: lambda.Code.fromAsset("lambda/order-processor"),
      environment: {
        TABLE_NAME: usersTable.tableName,
        BUCKET_NAME: uploadsBucket.bucketName,
      },
    });

    // Grant permissions
    usersTable.grantReadWriteData(processor);
    uploadsBucket.grantReadWrite(processor);

    // Event source: SQS -> Lambda
    processor.addEventSource(
      new eventsources.SqsEventSource(ordersQueue, {
        batchSize: 10,
      })
    );
  }
}

CDK Init Hook

Use an init script to deploy CDK stacks when LocalStack starts:

localstack/init/deploy-cdk.sh:

#!/bin/bash
set -euo pipefail

cd /etc/localstack/init/cdk-app
npm install
cdklocal bootstrap
cdklocal deploy --all --require-approval never

AWS CLI with awslocal

awslocal is a wrapper around the aws CLI that automatically sets --endpoint-url to LocalStack:

Installation

pip install awscli-local

Common Operations

# S3
awslocal s3 mb s3://my-bucket
awslocal s3 cp ./file.txt s3://my-bucket/
awslocal s3 ls s3://my-bucket/

# SQS
awslocal sqs create-queue --queue-name my-queue
awslocal sqs send-message --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/my-queue --message-body '{"key":"value"}'
awslocal sqs receive-message --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/my-queue

# Lambda
awslocal lambda create-function \
  --function-name my-function \
  --runtime nodejs20.x \
  --handler index.handler \
  --role arn:aws:iam::000000000000:role/lambda-role \
  --zip-file fileb://function.zip

awslocal lambda invoke --function-name my-function output.json

# DynamoDB
awslocal dynamodb list-tables
awslocal dynamodb scan --table-name Users

# Secrets Manager
awslocal secretsmanager get-secret-value --secret-id app/database-credentials

# StepFunctions
awslocal stepfunctions create-state-machine \
  --name my-workflow \
  --definition file://state-machine.json \
  --role-arn arn:aws:iam::000000000000:role/step-role

awslocal stepfunctions start-execution \
  --state-machine-arn arn:aws:states:us-east-1:000000000000:stateMachine:my-workflow \
  --input '{"orderId":"123"}'

AWS SDK Configuration

Node.js (AWS SDK v3)

Configure the SDK to point to LocalStack:

import { S3Client } from "@aws-sdk/client-s3";
import { SQSClient } from "@aws-sdk/client-sqs";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

const isLocal = process.env.AWS_ENDPOINT_URL || process.env.LOCALSTACK_ENDPOINT;
const endpoint = isLocal || undefined;

// Option 1: Per-client configuration
const s3 = new S3Client({
  endpoint,
  region: process.env.AWS_REGION || "us-east-1",
  forcePathStyle: true,  // Required for S3 with LocalStack
  ...(isLocal && {
    credentials: {
      accessKeyId: "test",
      secretAccessKey: "test",
    },
  }),
});

// Option 2: Factory function for consistent configuration
function createAWSClient<T>(
  ClientClass: new (config: any) => T,
  extraConfig?: Record<string, any>,
): T {
  const config: Record<string, any> = {
    region: process.env.AWS_REGION || "us-east-1",
    ...(endpoint && {
      endpoint,
      credentials: {
        accessKeyId: "test",
        secretAccessKey: "test",
      },
    }),
    ...extraConfig,
  };
  return new ClientClass(config);
}

const s3Client = createAWSClient(S3Client, { forcePathStyle: true });
const sqsClient = createAWSClient(SQSClient);
const dynamoClient = createAWSClient(DynamoDBClient);

Environment Variable: AWS_ENDPOINT_URL

AWS SDK v3 natively supports AWS_ENDPOINT_URL. Set it in your .env:

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

When AWS_ENDPOINT_URL is set, AWS SDK v3 clients automatically use it — no explicit endpoint configuration needed (except forcePathStyle for S3).

LocalStack with Testcontainers

For integration testing, use Testcontainers to spin up a LocalStack container per test suite.

For the full Testcontainers testing architecture (tap hooks, runners, reaper management, localtest.ts), see the tap-testcontainers skill.

Testcontainers Runner

test/scripts/runners/localstack.js:

import { GenericContainer, Wait } from "testcontainers";

const startContainer = async () => {
  const localstack = await new GenericContainer("localstack/localstack:latest")
    .withExposedPorts(4566)
    .withLabels({
      "org.testcontainers.reaper-session-id": process.env.REAPER_SESSION_ID,
    })
    .withEnvironment({
      SERVICES: process.env.LOCALSTACK_SERVICES || "s3,sqs,sns,dynamodb,secretsmanager,ssm",
      DEBUG: "0",
      AWS_DEFAULT_REGION: "us-east-1",
    })
    .withWaitStrategy(
      Wait.forHttp("/_localstack/health", 4566).forStatusCode(200)
    )
    .start();

  const port = localstack.getMappedPort(4566);
  const host = localstack.getHost();

  return {
    container: localstack,
    port,
    host,
  };
};

const bootstrap = async (host, port) => {
  const endpoint = `http://${host}:${port}`;

  // Use awslocal or SDK to create initial resources
  const { execSync } = await import("node:child_process");
  const env = {
    ...process.env,
    AWS_ENDPOINT_URL: endpoint,
    AWS_ACCESS_KEY_ID: "test",
    AWS_SECRET_ACCESS_KEY: "test",
    AWS_DEFAULT_REGION: "us-east-1",
  };

  execSync(`aws --endpoint-url=${endpoint} s3 mb s3://test-bucket`, { env });
  execSync(
    `aws --endpoint-url=${endpoint} sqs create-queue --queue-name test-queue`,
    { env }
  );
};

export { startContainer, bootstrap };

Wiring in before.js

// In test/scripts/executors/before.js
import {
  bootstrap as bootstrapLocalStack,
  startContainer as startContainerLocalStack,
} from "../runners/localstack.js";

// Inside the before() function:
if (!process.env.SKIP_TEST_LOCALSTACK_SETUP) {
  console.log("Start LocalStack");
  const { port, host } = await startContainerLocalStack();
  process.env.AWS_ENDPOINT_URL = `http://${host}:${port}`;
  process.env.AWS_ACCESS_KEY_ID = "test";
  process.env.AWS_SECRET_ACCESS_KEY = "test";
  process.env.AWS_DEFAULT_REGION = "us-east-1";
  await bootstrapLocalStack(host, port);
}

For Platformatic Runtime projects using this pattern, see the platformatic-runtime skill's testing section.

Service-Specific Patterns

S3

# Create bucket with notifications to SQS
awslocal s3 mb s3://uploads
awslocal s3api put-bucket-notification-configuration \
  --bucket uploads \
  --notification-configuration '{
    "QueueConfigurations": [{
      "QueueArn": "arn:aws:sqs:us-east-1:000000000000:upload-notifications",
      "Events": ["s3:ObjectCreated:*"]
    }]
  }'

Lambda with Layers

# Create a Lambda layer
awslocal lambda publish-layer-version \
  --layer-name my-utils \
  --zip-file fileb://layer.zip \
  --compatible-runtimes nodejs20.x

# Create function with layer
awslocal lambda create-function \
  --function-name processor \
  --runtime nodejs20.x \
  --handler index.handler \
  --role arn:aws:iam::000000000000:role/lambda-role \
  --zip-file fileb://function.zip \
  --layers arn:aws:lambda:us-east-1:000000000000:layer:my-utils:1

EventBridge Rules

# Create event bus
awslocal events create-event-bus --name app-events

# Create rule
awslocal events put-rule \
  --name order-created \
  --event-bus-name app-events \
  --event-pattern '{"source":["app.orders"],"detail-type":["OrderCreated"]}'

# Add target (Lambda)
awslocal events put-targets \
  --rule order-created \
  --event-bus-name app-events \
  --targets "Id=processor,Arn=arn:aws:lambda:us-east-1:000000000000:function:order-processor"

StepFunctions

{
  "Comment": "Order processing workflow",
  "StartAt": "ValidateOrder",
  "States": {
    "ValidateOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:000000000000:function:validate-order",
      "Next": "ProcessPayment",
      "Catch": [{
        "ErrorEquals": ["ValidationError"],
        "Next": "OrderFailed"
      }]
    },
    "ProcessPayment": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:000000000000:function:process-payment",
      "Next": "OrderComplete"
    },
    "OrderComplete": {
      "Type": "Succeed"
    },
    "OrderFailed": {
      "Type": "Fail",
      "Cause": "Order validation failed"
    }
  }
}

Environment File (.env)

Recommended .env for local development with LocalStack:

# LocalStack
LOCALSTACK_SERVICES=s3,sqs,sns,lambda,dynamodb,secretsmanager,ssm,stepfunctions,events
LOCALSTACK_DEBUG=0
AWS_DEFAULT_REGION=us-east-1
AWS_ENDPOINT_URL=http://localhost:4566
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test

# Application
APP_ENV=dev

MCP Server Tools

This plugin provides an MCP server with 40 tools for direct LocalStack operations. Use MCP tools when you need to interact with a running LocalStack instance — creating resources, sending messages, invoking functions, managing DynamoDB tables/items, or inspecting state.

When to Use MCP Tools vs CLI

• Use MCP tools for quick, programmatic operations: listing buckets, creating queues, sending test messages, invoking Lambda functions, managing DynamoDB tables/items, inspecting object contents. MCP tools return structured JSON and are faster for iterative workflows.
• Use awslocal CLI for operations not covered by the 40 tools (e.g., StepFunctions, EventBridge, SSM, Secrets Manager) or for piped/scripted workflows.
• Use cdklocal for deploying full CloudFormation/CDK stacks.

Available MCP Tools

S3: s3_list_buckets, s3_create_bucket, s3_delete_bucket, s3_list_objects, s3_get_object, s3_put_object, s3_delete_object

SQS: sqs_list_queues, sqs_create_queue, sqs_delete_queue, sqs_send_message, sqs_receive_messages, sqs_delete_message, sqs_purge_queue, sqs_get_queue_attributes

SNS: sns_list_topics, sns_create_topic, sns_delete_topic, sns_publish, sns_subscribe, sns_list_subscriptions, sns_unsubscribe

Lambda: lambda_list_functions, lambda_create_function, lambda_delete_function, lambda_invoke, lambda_get_function, lambda_update_function_code, lambda_list_event_source_mappings, lambda_create_event_source_mapping

DynamoDB: dynamodb_list_tables, dynamodb_describe_table, dynamodb_create_table, dynamodb_delete_table, dynamodb_put_item, dynamodb_get_item, dynamodb_delete_item, dynamodb_query, dynamodb_scan, dynamodb_update_item

Notes

• Lambda zipFilePath must be an absolute path to the zip file
• S3 s3_get_object returns text content for text/JSON files, metadata only for binary files
• SQS sqs_receive_messages returns up to 10 messages per call; use sqs_delete_message with the receipt handle to acknowledge
• DynamoDB tools use the Document Client — items are plain JSON (no { S: "value" } type descriptors needed)
• DynamoDB dynamodb_query requires keyConditionExpression + expressionAttributeValues; use expressionAttributeNames for reserved words (e.g. {"#s": "status"})
• DynamoDB dynamodb_update_item returns the full updated item (ALL_NEW)
• All tools return structured errors with AWS error name, message, and HTTP status code

Common Pitfalls

• Missing Docker socket mount: Lambda and OpenSearch require /var/run/docker.sock:/var/run/docker.sock. Without it, Lambda invocations fail with container creation errors
• S3 forcePathStyle not set: AWS SDK v3 uses virtual-hosted-style URLs by default (bucket.s3.amazonaws.com). LocalStack requires path-style (localhost:4566/bucket). Always set forcePathStyle: true on S3 clients
• Using Pro-only services: Services like Cognito, RDS, ECS, and AppSync are not available in Community Edition. Check the service list before planning your architecture
• Init scripts not executable: Shell scripts in ready.d must have execute permission (chmod +x). Without it, LocalStack silently skips them
• Lambda network isolation: When LAMBDA_EXECUTOR=docker, Lambda containers run in their own network. Set LAMBDA_DOCKER_NETWORK to the compose network name so Lambdas can reach other containers (e.g., DynamoDB)
• Account ID in ARNs: LocalStack uses 000000000000 as the default account ID. Always use this in ARN references, not a real AWS account ID
• SQS URL format: LocalStack SQS URLs follow the pattern http://sqs.<region>.localhost.localstack.cloud:4566/000000000000/<queue-name>. Using http://localhost:4566/000000000000/<queue-name> also works but is deprecated
• Persistence not enabled: By default, LocalStack state is ephemeral — all resources are lost on container restart. Set PERSISTENCE=1 if you need state to survive restarts during development
• cdklocal bootstrap forgotten: CDK deployments fail if the CDK bootstrap stack hasn't been created. Always run cdklocal bootstrap once before your first cdklocal deploy