AWS Lambda

BoxLang Runtime for AWS Lambda! Serverless for the win!

What is AWS Lambda?

AWS Lambda is a serverless computing service provided by Amazon Web Services (AWS) that lets you run code without provisioning or managing servers. It automatically scales applications by running code in response to events and allocates compute resources as needed, allowing developers to focus on writing code rather than managing infrastructure (

The BoxLang AWS Runtime allows you to run a Lambda.bx function in this ecosystem. We provide you a nice template so you can work with serverless:

BoxLang Default Lambda Handler

The runtime provides a handler for lambda already configured to accept JSON in as a BoxLang Struct and then output either by returning a simple or complex object or using our response convention struct. The default handler is:

You can see the code for the handler here:

The handler is Java, but you can easily build it with BoxLang. However, we have done the hard parts for you so you can focus on your lambda function.

Environment Variables

The following are the env variables available in the runtime:



Absolute path to the lambda to execute. The default path is:

Which is your lambda deployed within your zip file.


Turn runtime debug mode or not.


Absolute path to a custom boxlang.json configuration for the runtime.

BoxLang Default Template

The BoxLang default template for AWS lambda can be found here: It is a Gradle project for now, it will be migrated to CommandBox soon. The structure of the project is the following

/.vscode - Some useful vscode tasks and settings
/build - Not in source control, where your build and distributions happen
/gradle - The gradle runtime, keep in source control
  + main
    + bx
      + Lambda.bx (Your BoxLang Lambda function)
  + test
    + java
      + com
        + myproject
          + (An integration test for your Lambda)
          + (A testing context for lambda)
          + (A testing logger for lambda)
/workbench - Tons of AWS lambda utilities
/box.json - Your project's dependency descriptor for CommandBox
/build.gradle - The gradle build
/ - Where you store your version and metadata
/gradlew - The gradle shell executor, keep in source control
/gradlew.bat - The gradle shell executor, keep in source control
/settings.gradle - The project settings

The BoxLang AWS Lambda runtime will look for a Lambda.bx in your project and execute it by default. Run the following commands to prep for coding:

# Download the runtime, later it will be automatic via maven
./gradlew downloadBoxLang

# Run the tests
./gradlew test

# Build the project, create the lambda zip
# The location is /build/distributions/
./gradlew build

# Mess up? No problem, remove the /build folder or run
./gradlew clean


The Lambda function is a BoxLang class with a single function called run().

 * My BoxLang Lambda

	function run( event, context, response ){
		response.body = {
			"error": false,
			"messages": [],
			"data": "====> Incoming event " & event.toString()
		response.statusCode = 200;


It accepts three arguments:




All the incoming JSON as a BoxLang struct




A BoxLang struct convention for a response.

You can find more information about the AWS Context object here:


The event structure is a snapshot of the input to your lambda. We deserialize the incoming JSON for you and give you a nice struct.


This is an Amazon Java class that provides extensive information about the request. For more information, check out the API in the Amazon Docs (

Context methods

  • getRemainingTimeInMillis() – Returns the number of milliseconds left before the execution times out.

  • getFunctionName() – Returns the name of the Lambda function.

  • getFunctionVersion() – Returns the version of the function.

  • getInvokedFunctionArn() – Returns the Amazon Resource Name (ARN) that's used to invoke the function. Indicates if the invoker specified a version number or alias.

  • getMemoryLimitInMB() – Returns the amount of memory that's allocated for the function.

  • getAwsRequestId() – Returns the identifier of the invocation request.

  • getLogGroupName() – Returns the log group for the function.

  • getLogStreamName() – Returns the log stream for the function instance.

  • getIdentity() – (mobile apps) Returns information about the Amazon Cognito identity that authorized the request.

  • getClientContext() – (mobile apps) Returns the client context that's provided to Lambda by the client application.

  • getLogger() – Returns the logger object for the function.


The response argument is our convention to help you build a nice return structure. However, it is completely optional. You can easily return a simple or complex object from your lambda, and we will convert it to JSON.

response : {
  statusCode : 200,
  headers : {
    content-type :  "application/json",
    access-control-allow-origin : "*",
  body : results
 * My BoxLang Lambda Simple Return

  function run( event, context, response ){
    return "Hello World!"

 * My BoxLang Lambda Complex Return

  function run( event, context, response ){
    return {
      age : 1,
      when : now(),
      data : [ 12,3234,23423 ]

Now you can go ahead and build your function. You can use TestBox to unit test your Lambda.bx or we even include a src/test folder in Java, that simulates the full life-cycle of the runtime. Just run gradle test or use VSCode BoxLang IDE to run the tests. Now we go to production!

Deploy to AWS

Log in to the Lambda Console and click on Create function button.

Now let's add the basic information about our deployment:

  • Add a function name

  • Choose Java 21 as your runtime

  • Choose x86_64 as your architecture

Now, let's upload our test code. You can choose a zip/jar or s3 location. We will do a simple zip from our template:

Now important, let's choose the AWS Lambda Runtime Handler in the Edit runtime settings

And make sure you use the following handler address: This is inside the runtime to execute our Lambda.bx function.

Testing in AWS

Now click on the Test tab and an event name MyTestEvent. You can also add anything you like in the Event JSON to test the input of your lambda. Then click on Test and watch it do its magic. Now go have some good fun!

Runtime Source Code

The AWS Runtime source code can be found here:

We welcome any pull requests, testing, docs, etc.

Last updated


Copyright & Register Trademark by Ortus Solutions, Corp & Ortus Software, LLC