Skip to content
Serverless plugin for running against LocalStack
Branch: master
Clone or download
Pull request Compare This branch is 4 commits ahead, 5 commits behind localstack:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Build Status

LocalStack Serverless Plugin

Serverless Plugin to support running against Localstack.

This plugin allows Serverless applications to be deployed and tested on your local machine. Any requests to AWS to be redirected to a running LocalStack instance.


  • LocalStack


The easiest way to get started is to install via npm.

npm install -g serverless
npm install --save-dev serverless-localstack

Installation (without npm)

If you'd like to install serverless-localstack via source:

Clone the repository

git clone
cd serverless-localstack
npm link      

Install the plugin

Use npm link to reference the plugin

cd project-path/
npm link serverless-localstack


There are two ways to configure the plugin, via a JSON file or via serverless.yml. There are two supported methods for configuring the endpoints, globally via the host property, or individually. These properties may be mixed, allowing for global override support while also override specific endpoints.

A host or individual endpoints must be configured or this plugin will be deactivated.

Configuration via serverless.yml

service: myService

  - serverless-localstack

    host: http://localhost
      # list of stages for which the plugin should be enabled
      - local
    autostart: true  # optional - start LocalStack in Docker on Serverless deploy
      # This section is optional - can be used for customizing the target endpoints
      S3: http://localhost:4572
      DynamoDB: http://localhost:4570
      CloudFormation: http://localhost:4581
      Elasticsearch: http://localhost:4571
      ES: http://localhost:4578
      SNS: http://localhost:4575
      SQS: http://localhost:4576
      Lambda: http://localhost:4574
      Kinesis: http://localhost:4568
      # Enable this flag to improve performance
      mountCode: True

Activating the plugin for certain stages

Note the stages attribute in the config above. The serverless-localstack plugin gets activated if either:

  1. the serverless stage (explicitly defined or default stage "dev") is included in the stages config; or
  2. serverless is invoked without a --stage flag (default stage "dev") and no stages config is provided

Mounting Lambda code for better performance

Note that the localstack.lambda.mountCode flag above will mount the local directory into the Docker container that runs the Lambda code in LocalStack. If you remove this flag, your Lambda code is deployed in the traditional way which is more in line with how things work in AWS, but also comes with a performance penalty: packaging the code, uploading it to the local S3 service, downloading it in the local Lambda API, extracting it, and finally copying/mounting it into a Docker container to run the Lambda.

Environment Configurations

  • LAMBDA_MOUNT_CWD: Allow users to define a custom working directory for Lambda mounts. For example, when deploying a Serverless app in a Linux VM (that runs Docker) on a Windows host where the -v <local_dir>:<cont_dir> flag to docker run requires us to specify a local_dir relative to the Windows host file system that is mounted into the VM (e.g., "c:/users/guest/...").

Configuring endpoints via JSON

service: myService

  - serverless-localstack

    endpointFile: path/to/file.json

Only enable serverless-localstack for the listed stages

  • serverless deploy --stage local would deploy to LocalStack.
  • serverless deploy --stage production would deploy to aws.
service: myService

  - serverless-localstack

      - local
      - dev
    endpointFile: path/to/file.json


For full documentation, please refer to


Setting up a development environment is easy using Serverless' plugin framework.

Clone the Repo

git clone

Setup your project

cd /path/to/serverless-localstack
npm link

cd myproject
npm link serverless-localstack

Optional Debug Flag

An optional debug flag is supported via serverless.yml that will enable additional debug logs.

    debug: true

Change Log

  • v0.4.12: Fix Lambda packaging for mountCode:false
  • v0.4.11: Add polling loop for starting LocalStack in Docker
  • v0.4.8: Auto-create deployment bucket; autostart LocalStack in Docker
  • v0.4.7: Set S3 path addressing; add eslint to CI config
  • v0.4.6: Fix port mapping for service endpoints
  • v0.4.5: Fix config to activate or deactivate the plugin for certain stages
  • v0.4.4: Add LAMBDA_MOUNT_CWD configuration for customizing Lambda mount dir
  • v0.4.3: Support local mounting of Lambda code to improve performance
  • v0.4.0: Add support for local STS
You can’t perform that action at this time.