lambda-zig: A Custom Runtime for AWS Lambda

This is a custom runtime built in Zig (0.15). Simple projects will execute in <1ms, with a cold start init time of approximately 11ms.

Custom build steps are available for packaging and deploying Lambda functions:

• zig build awslambda_package: Package the Lambda function into a zip file
• zig build awslambda_iam: Create or verify IAM role for the Lambda function
• zig build awslambda_deploy: Deploy the Lambda function to AWS
• zig build awslambda_run: Invoke the deployed Lambda function

Build options:

• function-name: Name of the AWS Lambda function
• payload: JSON payload for function invocation (used with awslambda_run)
• region: AWS region for deployment and invocation
• profile: AWS profile to use for credentials
• role-name: IAM role name for the function (default: lambda_basic_execution)
• env-file: Path to environment variables file for the Lambda function

The Lambda function can be compiled for x86_64 or aarch64. The build system automatically configures the Lambda architecture based on the target.

A sample project using this runtime can be found at https://git.lerch.org/lobo/lambda-zig-sample

Environment Variables

Lambda functions can be configured with environment variables during deployment. This is useful for passing configuration, secrets, or credentials to your function.

Using the build system

Pass the -Denv-file option to specify a file containing environment variables:

zig build awslambda_deploy -Dfunction-name=my-function -Denv-file=.env

Using the CLI directly

The lambda-build CLI supports both --env flags and --env-file:

# Set individual variables
./lambda-build deploy --function-name my-fn --zip-file function.zip \
    --env DB_HOST=localhost --env DB_PORT=5432

# Load from file
./lambda-build deploy --function-name my-fn --zip-file function.zip \
    --env-file .env

# Combine both (--env values override --env-file)
./lambda-build deploy --function-name my-fn --zip-file function.zip \
    --env-file .env --env DEBUG=true

Environment file format

The environment file uses a simple KEY=VALUE format, one variable per line:

# Database configuration
DB_HOST=localhost
DB_PORT=5432

# API keys
API_KEY=secret123

Lines starting with # are treated as comments. Empty lines are ignored.

Using the Zig Package Manager

To add Lambda package/deployment steps to another project:

1. Fetch the dependency:

zig fetch --save git+https://git.lerch.org/lobo/lambda-zig

2. Update your build.zig:

const std = @import("std");
const lambda_zig = @import("lambda_zig");

pub fn build(b: *std.Build) !void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Get lambda-zig dependency
    const lambda_zig_dep = b.dependency("lambda_zig", .{
        .target = target,
        .optimize = optimize,
    });

    const exe_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Add lambda runtime to your module
    exe_module.addImport("aws_lambda_runtime", lambda_zig_dep.module("lambda_runtime"));

    const exe = b.addExecutable(.{
        .name = "bootstrap",
        .root_module = exe_module,
    });

    b.installArtifact(exe);

    // Add Lambda build steps
    try lambda_zig.configureBuild(b, lambda_zig_dep, exe);
}

Note: The build function return type must be !void or catch/deal with errors to support the Lambda build integration.