Skip to main content

Bun on Lambda Customer-Managed Runtimes: setup and benchmark

· 14 min read
Ivan Barlog
AWS Solutions Architect @ BeeSolve

AWS Lambda customer-managed runtimes (CMR) are generally available. I was part of the private beta and I used it to move my Bun runtime from a Lambda layer to a runtime Lambda actually knows about. Then I benchmarked it against the layer, a container image, SnapStart and the official nodejs24.x runtime.

The main reason to switch is updates, not speed: you publish a new runtime version, move an alias and your functions pick it up on the next cold start. The lower cold start is a bonus, and I measured that too.

Disclaimer

This article was put together by an LLM agent, not written by me word for word. The idea, the opinions and all the technical content are mine - I just did not have the time to write it up, so I asked an agent to assemble it from my earlier posts and from the benchmark results. The agent did not come up with any of this. As with every generated article on this blog, I have proofread and edited it myself before publishing.

AWS describes the concepts, the publisher and consumer roles, sharing and pricing in the announcement Control your AWS Lambda runtimes with customer-managed runtimes. I do not repeat that here. This article is about running Bun on it and what the benchmark shows. The CLI commands are in the lambda-core section of the AWS CLI reference.

What is a customer-managed runtime​

Until now you had two ways to run something that is not a managed runtime on Lambda. A custom runtime on provided.al2023 with the runtime in a layer, or a container image where you ship the whole function including the runtime.

CMR is a third one. The runtime becomes its own Lambda resource with immutable versions (container images from your ECR repository) and aliases pointing to them. Your function references the runtime alias and you ship only the handler zip as usual. The AWS post explains the resource model in detail.

The image has to contain /var/runtime/bootstrap and whatever the runtime needs. Mine is provided.al2023 with the Bun binary copied from the official oven/bun image and the small runtime that talks to the Lambda Runtime API. If you build the image yourself, read the gotchas below first, they will save you a few failed deploys.

Publishing it with the AWS CLI looks like this (shortened from the setup.sh in the benchmark repository):

aws lambda-core create-runtime --name bun-runtime --license-info "None"

aws lambda-core create-runtime-version \
--runtime-name bun-runtime \
--image-uri "${ECR_URI}:${IMAGE_TAG}" \
--name 1-4-4

aws lambda-core create-runtime-alias \
--runtime-name bun-runtime \
--name latest \
--runtime-version 1-4-4

And the function:

aws lambda create-function \
--function-name my-bun-function \
--runtime custom \
--runtime-config "{\"RuntimeArn\":\"${RUNTIME_ARN}\",\"RuntimeAlias\":\"latest\"}" \
--handler index.handler \
--zip-file fileb://function.zip \
--role "${ROLE_ARN}" \
--architectures arm64

The function itself looks like any other zip function. It just has a different runtime behind it.

The benchmark​

I wanted to know if this is worth it, so I built a small benchmark. The full source, scripts and raw results are in ivanbarlog/lambda-cmr-bench. Run it yourself, that is the point of having it public.

The matrix has two axes. How Bun is delivered:

  • cmr - Bun in a customer-managed runtime,
  • layer - Bun as a Lambda layer on provided.al2023 (this is what @beesolve/lambda-bun-runtime did until now),
  • docker - Bun and the handler baked into a container image function (called docker in the tables),
  • docker + SnapStart - the same image with SnapStart for container images.

And which S3 client the handler uses:

On top of that there is a baseline: the managed nodejs24.x runtime with the AWS SDK bundled into the zip (so the SDK costs are attributed to the function the same way as for the Bun variants).

The setup:

  • eu-west-1, arm64, 1024 MB, 60 s timeout, same role and bucket everywhere,
  • workload: write 100 files of 1 KB to S3, then read them all back,
  • 10 rounds per variant, where a round is one cold start followed by 10 warm invokes (1170 invokes per run, none failed; the two SnapStart functions need 10 extra invokes per round for the cold burst, more on that below),
  • Bun 1.4.4 (oven/bun:1.4.4 for the image and CMR, @beesolve/lambda-bun-runtime for the layer).

To force a cold start I used a fresh --tenant-id for every round. Functions with tenant isolation mode PER_TENANT get a separate execution environment per tenant, so a new tenant id means a cold start. SnapStart cannot be combined with tenancy, so those two functions get their cold starts from concurrent bursts and I classify each invoke from the Restore Duration in the REPORT line.

Cold start in the tables below is Init Duration (or Restore Duration for SnapStart) plus Duration, taken from the CloudWatch REPORT line. All numbers are p50 in milliseconds.

Results​

Cold start​

DeliveryBun S3 clientAWS SDK S3 client
cmr4801583
docker4661466
layer6201770
docker + SnapStart8081772
node (nodejs24.x)-1652

Three things stand out.

CMR beats the layer. With the Bun client the cold start is 480 ms against 620 ms (23% less), with the AWS SDK 1583 ms against 1770 ms (11% less). The Init Duration tells the same story: 88 ms for CMR and 175 ms for the layer with the Bun client. I did not dig into why the layer inits slower.

CMR is as quick as a container image. The container image function is within a few percent of CMR (466 vs 480 ms). You get that without shipping your whole function as an image: the heavy runtime is a separate, versioned thing and your deploy is still a zip with a few KB of code.

The Bun S3 client is the real win. Same runtime, same delivery, 480 ms against 1583 ms. That is 3.3x less. It is a bundle size thing, partly: the minified handler with the Bun client is 2.3 KB, with the AWS SDK it is 479 KB (554 KB for Node). But init is not where most of the time goes. The AWS SDK init is only about 140 ms slower (229 vs 88 ms). Most of the gap is in the first requests - writing the 100 files took 275 ms cold with the Bun client and 954 ms with the AWS SDK. I did not profile that part so I cannot tell you which piece of the SDK is responsible.

Warm​

DeliveryBun S3 clientAWS SDK S3 client
cmr210376
layer169357
docker172346
node (nodejs24.x)-459

Warm invokes are about the same for all delivery methods. Yes, layer/bun (169 ms) and docker/bun (172 ms) are faster than cmr/bun (210 ms) here, but in the Bun 1.4.0 run it was the other way around (cmr 159 ms, layer 167 ms), so I treat the 40 ms gap as noise. What delivery changes is the cold start, not the warm path. What changes the warm path is the S3 client: 210 ms vs 376 ms.

Bun against Node.js​

With the same AWS SDK, Bun on CMR is on par with the official nodejs24.x runtime: 1583 vs 1652 ms cold, 376 vs 459 ms warm. The Bun layer is behind on the cold start (1770 ms). The p95 values of the cold starts overlap (1847 vs 1791 ms), and with 10 cold samples I would not call this a win. Call it a tie.

Where Bun clearly outperforms Node is when you take advantage of what Bun ships: the native S3 client. That is 480 ms against 1652 ms cold. And because it is part of the runtime, there is nothing to bundle and nothing to load.

What the Bun S3 client does not do​

Bun's S3 client takes static credentials only, there is no AWS credential provider chain. On Lambda that is fine because the execution role credentials are in the environment variables. It is not fine if you need AssumeRole chains or SnapStart (where the static variables are not refreshed after the restore). Part of the speed is simply less functionality. It also does not have the SDK's retry strategy and all of the other middleware, so check you can live without it.

SnapStart​

I also tried SnapStart (for container images, since that is the one available for a custom runtime) and I would not recommend it for functions with a short init, like the ones in this benchmark.

Cold startInit / Restore
docker46685
docker + SnapStart808369

The restore alone (369 ms) takes longer than the whole init of a Bun function (85 ms). There is nothing to save when the init is already tiny, so SnapStart makes the cold start worse (808 vs 466 ms with the Bun client, 1772 vs 1466 ms with the AWS SDK).

It also costs money. SnapStart bills for caching the snapshot and for every restore, see the Lambda pricing. In eu-west-1 the restore is $0.0001397998 per GB, so 1 million cold starts of a 1 GB function add about $140. The whole 480 ms cold invoke of the CMR function at 1 GB costs roughly $0.0000064 in compute (arm64, $0.0000133334 per GB-s), so the restore alone costs about 22 times as much.

SnapStart makes sense when your init is seconds long (big JVM, ML models). For small functions with few KB of code it is more expensive and slower. Pick a smaller bundle instead. If you do not know how long your init takes, measure it before you pay for a snapshot.

What changed between Bun versions​

I ran the benchmark in the beta and again at GA, and with Bun 1.4.0 and 1.4.4. Beta to GA changed nothing meaningful, the numbers moved within the noise of 10 samples per variant.

Bun 1.4.0 to 1.4.4 did change something. The variants with the AWS SDK are about 10% faster on every Bun delivery, and the Node baseline did not move:

VariantBun 1.4.0Bun 1.4.4
cmr + AWS SDK17711583
docker + AWS SDK16201466
layer + AWS SDK19911770
docker + SnapStart + AWS SDK20121772
node + AWS SDK16461652

The Bun client variants are within noise (CMR 444 -> 480 ms, layer 660 -> 620 ms). The ranking between delivery methods did not change. My guess is the 1.4.1 change that makes the first TLS connection in a process up to 3x faster, but I did not verify it.

Caveats​

  • 10 cold samples per variant. Medians are fine, treat p95 as rough.
  • Two outliers in the data: the first cmr/bun run had a client-side stall (it took up to 235 s to get the response back), and docker + SnapStart had one 27 s warm invoke. Medians barely move, means and p95 do.
  • The first cold round is not discarded in my results. In the Bun 1.4.0 run it was slower than the rest (1717 ms vs a 380-570 ms range for cmr/bun, 2575 ms vs about 1700 ms for cmr/aws-sdk), in the 1.4.4 run only slightly (761 ms for cmr/bun, nothing unusual for cmr/aws-sdk). I did not isolate the cause.
  • This is S3 only, 100 small files. A function that talks to DynamoDB, or one that is mostly CPU bound, will look different.
  • It is one region, one memory size, one architecture.

Gotchas when building a runtime image​

If you want to build your own runtime image, these are the things that cost me time.

  • No ENTRYPOINT in the image. I tested three variants of the same image against the same function at GA: ENTRYPOINT with CMD [], ENTRYPOINT alone, and neither. Only the one with neither worked. With an ENTRYPOINT the _HANDLER environment variable is empty and the runtime fails with Invalid handler format. Without it, _HANDLER is set (I checked with a debug bootstrap that printed it). The beta guide said the ENTRYPOINT is ignored, which is not what happens at GA.
  • Use the glibc Bun image, not Alpine. The Alpine (musl) binary cannot be executed on provided:al2023, the runtime fails at cold start with exit status 127.
  • Deleting a runtime is soft. The resource is scheduled for deletion and the name stays reserved for the waiting period (30 days in my tests). Use a fresh name if you recreate it. Functions using a deleted alias become Inactive, see the AWS post for the guardrails.
  • Sharing across accounts works with a resource policy on the runtime ARN (aws lambda put-resource-policy, action lambda:AssociateRuntimeAlias). I tested it with a specific account and with Principal: "*", including an account outside my AWS Organization. A policy on the alias or version ARN is rejected. The consumer needs an identity-based policy allowing lambda:AssociateRuntimeAlias too, but no ECR permissions.

What it means for the Bun runtime​

If you want to use Bun on Lambda today, CMR is the better way to deliver it. Updating Bun is one new runtime version and one alias move, while a layer means redeploying every function that uses it and a container image means rebuilding and redeploying the whole function.

You can also build the image yourself, pin the Bun version, add other tools you need, or share it with your other accounts.

CloudFormation supports CMR with AWS::Lambda::Runtime, AWS::Lambda::RuntimeVersion and AWS::Lambda::RuntimeAlias, and the function has a RuntimeConfig property. CDK has no generated constructs for them yet (aws-cdk-lib 2.277.0 has no runtime resources and no runtimeConfig on CfnFunction), so in CDK you need CfnResource and property overrides for now.

That is why I am going to update @beesolve/lambda-bun-runtime soon. The plan is:

  • I will publish the Bun runtime as a public CMR, and the layer as before, in a few regions - Stockholm, Frankfurt, Ireland, N. Virginia and Oregon - so you can reference it right away without building anything,
  • the package will ship scripts so you can publish your own CMR with Bun in your own account, and in any other region,
  • the CDK construct will follow once CDK supports CMR.

Conclusion​

The main reason to use CMR for Bun is updates, and the benchmark shows that you do not pay for it in speed:

  • CMR cuts the cold start of a Bun function against the layer by 23% with the Bun S3 client and by 11% with the AWS SDK, and it is as quick as a container image,
  • the native Bun S3 client is 3.3x faster on the cold start than the AWS SDK, and it ships with the runtime,
  • with the same AWS SDK, Bun and the official nodejs24.x are on par,
  • SnapStart does not pay off when the init is already short, and it costs money.

If you have a use case where I did not test the performance or you find a mistake in my benchmark, I would like to know. The benchmark repository is open - send me an issue or a pull request, or just ping me directly. Same goes for the runtime package, which I am about to update: tell me what you need from it.