Create and deploy AWS lambdas written in Crystal
HEAD Latest release released


A small library to simplify running lambdas written in crystallang. Not production ready, just an evening hack!


You can include this as a dependency in your project in shards.yml file

    github: spinscale/crystal-aws-lambda
    branch: main

Now run the the shards command to download the dependency. You can now create your own lambda handlers like this

require "lambda_builder"

runtime =

runtime.register_handler("httpevent") do |input|
  req =
  user = req.query_params.fetch("hello", "World")
  response =, "Hello #{user} from Crystal")
  # not super efficient, serializing to JSON string and then parsing, simplify this
  JSON.parse response.to_json

runtime.register_handler("scheduledevent") do |input|
  runtime.logger.debug("Hello from scheduled event, input: #{input}")
  JSON.parse "{}"

runtime.register_handler("snsevent") do |input|"SNSEvent input: #{input}")
  JSON.parse "{}"

The input variable is of type JSON::Any and represents the JSON handed over by the lambda event.

There is a helper class to create a HTTP request from the input, no need to do that manually.


Make sure the serverless framework is set up properly. The next step is to create a proper serverless configuration file like this

service: crystal-hello-world

  name: aws
  runtime: provided

  artifact: ./

    handler: httpevent
      - http:
          memorySize: 128
          path: hello
          method: get

    handler: snsevent
    memorySize: 128
      - sns: my-sns-topic

    handler: scheduledevent
    memorySize: 128
      - schedule:
          rate: rate(10 minutes)
            hello: world

If you are using osx, make sure you are building your app using docker, as an AWS lambda runtime environment is based on Linux. You can create a linux binary using docker like this

docker run --rm -it -v $PWD:/app -w /app crystallang/crystal:latest crystal build src/ -o bin/bootstrap --release --static --no-debug

Now package the zip file required for deployment and deploy

zip -j bin/bootstrap
sls deploy

In order to monitor executions you can check the corresponding function logs like this

sls logs -f httpevent -t
sls logs -f snsevent -t
sls logs -f scheduledevent -t

you can also get some very simple metrics per functions (this might require additional permissions)

sls metrics -f httpevent
sls metrics -f snsevent
sls metrics -f scheduledevent

Compiling with shared libraries

While often it's easy to compile with just static linking on a host system like Alpine, sometimes it's more convenient to deploy a dynamically linked binary. To do this, all the required linked dependencies have to be copied into the zip file. The binary itself needs to be modified using patchelf to find them too.

The required libraries can be obtained automatically using ldd bin/bootstrap. An example build and packaging process looks like this:

shards build --release bootstrap
mkdir -p build/lib

# copy the main binary
cp bin/bootstrap build

# copy the libraries
cp $(ldd bin/bootstrap | awk '/ => / {print $3}') build/lib
# copy the loader
cp /lib64/ build/lib
# update the library lookup paths to use ./lib rather than the system copies
patchelf --set-interpreter ./lib/ --set-rpath ./lib --force-rpath build/bootstrap

# zip it all up for deployment
(cd build && zip -r ../ *)


If you want to get up and running with an example, run the following commands

git clone
cd crystal-aws-lambda/example
# download dependencies
# built binary (using docker under osx) and creates the zip file
# deploy to AWS, requires the serverless tool to be properly set up
sls deploy

This will start a sample runtime, that includes a HTTP endpoint, a scheduled event and an SQS listening event.


  1. Fork it (
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature'), also run bin/ameba
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request
  6. Don't forget to add proper tests, if possible


  github: spinscale/crystal-aws-lambda
License MIT
Crystal 1.6.2


Dependencies 0

Development Dependencies 2

  • ameba 1.3.1
    {'github' => 'crystal-ameba/ameba', 'version' => '1.3.1'}
  • webmock 0.14.0
    {'github' => 'manastech/', 'version' => '0.14.0'}

Dependents 0

Last synced .
search fire star recently