Bun on AWS User Guide

Overview

This image runs Bun, the fast all-in-one JavaScript and TypeScript toolkit: a single native binary that is a runtime, a bundler, a transpiler, a test runner and an npm-compatible package manager. Bun runs JavaScript and TypeScript files directly, installs packages quickly, bundles for production and runs your tests, all from one command. The image is delivered as a ready-to-use development and runtime workstation, so an engineer can connect over SSH and start running, building and testing JavaScript and TypeScript projects with the bun command line immediately, with no setup.

This is a headless command-line image. There is no web interface, no service to log into and no credentials: you run the bun CLI against your own JavaScript and TypeScript projects, or use Bun.serve to run your own application server. The bun binary is installed at /opt/bun/bin/bun and symlinked onto the system path at /usr/local/bin/bun and /usr/local/bin/bunx, and was verified against the official Bun release checksum at build time.

The Bun global install root and package install cache are placed on a dedicated, independently resizable EBS data volume mounted at /var/lib/bun. The login profile exports BUN_INSTALL=/var/lib/bun and BUN_INSTALL_CACHE_DIR=/var/lib/bun/install/cache for every login shell, so packages downloaded by bun install download once and are shared across all your projects, and they persist on durable storage rather than the operating system disk. A self-contained offline demo project ships read-only at /opt/bun/demo so you can exercise the toolkit end to end with no third-party dependencies the moment you log in.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Bun. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Bun Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=bun}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

A welcome banner prints the most useful commands, and sudo cat /root/bun-info.txt shows the full getting-started notes: what is installed, the global install cache path on the data disk, and the location of the offline demo project.

Step 4: Verify the Install

Confirm the toolchain is installed and on the system path by printing the Bun version, which is pinned to Bun 1.3.14 on this image:

bun --version

You should see 1.3.14 reported. The same bun command exposes the full all-in-one workflow — run bun --help to list the subcommands, the most important of which are run, install, build and test. Confirm the binary and its bunx companion both resolve from the system path:

command -v bun bunx

Both resolve under /usr/local/bin; the binary itself lives at /opt/bun/bin/bun and the image links it onto the system path so it resolves from any login shell.

Step 5: Run the Demo Project

A self-contained offline demo project ships read-only at /opt/bun/demo. It uses only Bun's built-in APIs — the Bun.serve HTTP server and the bundled bun:test runner — so bun install, bun test and bun run all work offline with no third-party dependencies and no cloud credentials. The project pairs a tiny HTTP server with a test, so you can confirm the toolkit works end to end before pointing it at your own code.

Copy the demo somewhere writable and install its dependencies. The demo deliberately ships no third-party dependencies, so bun install resolves an empty tree quickly and populates the shared install cache on the data disk:

cp -r /opt/bun/demo ~/bun-demo
cd ~/bun-demo
bun install

bun install prints its version banner and completes in milliseconds. Now run the bundled test suite with Bun's built-in, Jest-compatible test runner:

cd ~/bun-demo
bun test

bun test discovers server.test.ts, runs the three cases, and ends with 3 pass and 0 fail, confirming the runtime, the TypeScript support and the test runner all work.

To exercise the runtime as an application server, start the demo HTTP server with Bun.serve and confirm it answers over the loopback interface. The following block starts the server in the background, waits for it to bind, queries the root and health endpoints, then stops it:

cd ~/bun-demo
PORT=3000 bun run server.ts &
BUN_DEMO_PID=$!
sleep 2
curl -s http://127.0.0.1:3000/
curl -s http://127.0.0.1:3000/health
kill "$BUN_DEMO_PID"

The root endpoint returns a Hello from Bun greeting and the health endpoint returns {"status":"ok","runtime":"bun","version":"1.3.14"}, proving the runtime serves HTTP correctly with only Bun's built-in Bun.serve API.

Step 6: Use Your Own Projects

To work on your own code, copy or clone your JavaScript or TypeScript project onto the instance and run the same workflow. bun install reads the package.json and lockfiles your team already uses and installs into the shared cache, bun run <script> and bun run <file> execute your scripts and TypeScript files directly with no separate transpiler step, bun build bundles for production, and bun test runs your test suite. Bun is npm-compatible, so existing projects work without changes, and bunx runs package binaries on demand the way npx does.

The package install cache lives on the dedicated data volume at /var/lib/bun/install/cache and is exported as BUN_INSTALL_CACHE_DIR for every login shell. Because the cache is shared, the first bun install in any project downloads each package once and every later project reuses the cached copy, which makes repeated installs fast and keeps the packages on durable, resizable storage rather than the operating system disk. You can confirm the cache environment is exported in your login shell:

echo "$BUN_INSTALL_CACHE_DIR"

That prints /var/lib/bun/install/cache. To run Bun as a long-lived application server, write a systemd unit that runs bun run against your entry point, or package your app into a container that copies in the bun binary.

Step 7: The Data Volume

The Bun global install root and package install cache live on a dedicated EBS volume mounted at /var/lib/bun. This keeps the downloaded packages off the operating system disk and lets you resize or snapshot the volume independently. Confirm the mount with:

df -h /var/lib/bun

To grow the volume, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. The install cache directory is group-writable by the ubuntu login user, so packages downloaded by any project are shared across the whole instance.

Support

This image is published and supported by cloudimg. Support covers project setup, dependency and lockfile management, bundling and build configuration, the test runner, running Bun as an application server, container packaging, CI integration and upgrade planning. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.