---
title: "Deploy a Bun app"
description: "Run Bun on an exe.dev VM: a private dev server with hot reloading, bun:sqlite on a real disk, and your app compiled to one binary under systemd."
url: https://exe.dev/deploy/bun
category: "Frameworks"
published: 2026-11-21
updated: 2026-11-21
---

# Deploy a Bun app

> **For agents:** with your user's OK, this sets up Bun on a new exe.dev VM in their account: `curl -fsSL https://exe.dev/deploy/bun/prompt.txt | ssh exe.dev new --prompt=/dev/stdin` (or open https://exe.dev/deploy/bun/new). Already on the VM? Skip this.

Develop with bun --hot, ship one binary, on the same always-on VM.

- **Software:** Bun (https://bun.com)
- **Source:** https://github.com/oven-sh/bun
- **License:** MIT
- **Time:** 10 minutes
- **Example VM name:** `my-bun` (yours will differ; on the VM, `hostname` prints it)
- **Machine-readable:** https://exe.dev/deploy/bun/manifest.json
- **File:** https://exe.dev/deploy/bun/app-backup
- **File:** https://exe.dev/deploy/bun/app-release
- **File:** https://exe.dev/deploy/bun/app.test.ts
- **File:** https://exe.dev/deploy/bun/app.ts
- **File:** https://exe.dev/deploy/bun/bun-dev.conf
- **File:** https://exe.dev/deploy/bun/client.ts
- **File:** https://exe.dev/deploy/bun/db.ts
- **File:** https://exe.dev/deploy/bun/index.html
- **File:** https://exe.dev/deploy/bun/server.ts
- **File:** https://exe.dev/deploy/bun/style.css

## What you get

- Bun 1.4.5, pinned, where your shell, scripts, and systemd all find it.
- The app's code in ~/app, served by bun --hot as app-dev.service at port 3000, with hot reloading through exe.dev's proxy.
- The same code compiled to one binary and running as app.service on port 8000, shipped with ~/bin/app-release, which puts the old binary back if the new one doesn't answer.
- Settings and secrets in ~/app.env (mode 600) and data in ~/data, backed up nightly and before each release, with the newest backup opened and checked.
- With REPO=new, a guestbook on Bun.serve, bun:sqlite, and WebSockets, with tests.

Running on the VM:

- **Your app, in production**: One binary from bun build --compile, as app.service, port 8000, data in `~/releases/current → the newest of five kept binaries`
- **The dev server**: bun --hot in ~/app as app-dev.service, behind nginx, port 3000, data in `~/app, with its own dev.db`
- **Bun 1.4.5**: Pinned, in /usr/local/bin where systemd finds it
- **SQLite**: Bun's built-in bun:sqlite; settings in ~/app.env, data in `~/data`
- **Releases and backups**: app-release tests, compiles, switches, and rolls back; app-backup.timer runs nightly, data in `~/backups`

How it is reached:

- https://my-bun.exe.xyz/ (private): Your app, until you make it public
- https://my-bun.exe.xyz:3000/ (private): The dev server, reloading as you edit

## Deploy with Shelley

Open https://exe.dev/deploy/bun/new to create a VM whose agent, Shelley, follows this recipe. From a terminal:

```sh
curl -fsSL https://exe.dev/deploy/bun/prompt.txt | ssh exe.dev new --prompt=/dev/stdin
```

Or follow the steps below by hand.

Most platforms run your Bun app; an exe.dev VM is also where you build
it. `bun --hot` serves your code at a private HTTPS address as you edit,
`bun:sqlite` keeps data on a real disk, and one command tests the app,
compiles it to a single binary, and swaps it in as a systemd service on
the same VM. Shelley, the agent on the VM, works in the same directory.

Bring a Bun app from GitHub (`Bun.serve`, Hono, or Elysia), or start
from a small guestbook on `Bun.serve`, `bun:sqlite`, and WebSockets.

## Open your app

The VM serves two copies of your app, both private until you share them:

- `https://my-bun.exe.xyz/`: **production**, the compiled binary, with
  data in `~/data/app.db`.
- `https://my-bun.exe.xyz:3000/`: the **dev server**, `bun --hot` on the
  code in `~/app`, with its own `dev.db`.

Sign the guestbook in production: the message carries your exe.dev name
and shows up on every open page at once, over a WebSocket.

<figure>
<img src="https://exe.dev/deploy/bun/guestbook.png" alt="The starter app: a guestbook titled Guestbook with a text box, a Sign button, two signed messages, and the note 'Live: new messages appear without a reload.'" width="800" height="300" loading="lazy">
<figcaption>The new app's guestbook, at https://my-bun.exe.xyz/.</figcaption>
</figure>

## Change it, watch it reload

Edit `~/app` however you like: ask Shelley, use SSH
(`ssh my-bun.exe.xyz`), or open it in VS Code, Cursor, or Zed over
remote SSH. With port 3000 open, saving a stylesheet restyles the page,
saving client code updates it in place, and saving server code swaps the
routes without a restart, so WebSockets stay up. Logs, including the
browser's console: `journalctl -u app-dev -f`.

> [!NOTE]
> Bun's dev server serves pages only to requests addressed to
> `localhost`, so through the proxy it answers `403 Blocked: Host header
> does not match the dev server`. Setup puts nginx on port 3000 in front
> of Bun (on 3001) to pass requests on as `localhost`. The proxy has
> already checked who you are.

## Ship it

When the dev server looks right, on the VM:

```bash
cd ~/app
git add -A && git commit -m "Describe the change"
~/bin/app-release
```

`app-release` runs `bun install` and `bun test`, compiles the
`"module"` entry in `package.json` to one binary with the frontend
inside, backs up `~/data`, points `~/releases/current` at the new
binary, restarts `app.service`, and checks port 8000. If tests fail,
nothing changes; if the new binary doesn't answer, the previous one goes
back. It keeps five, named after their commit; to roll back by hand,
`ln -sfn ~/releases/<older> ~/releases/current && sudo systemctl restart app`.

On restart, the starter closes WebSockets (code 1001) and finishes
requests in flight; pages reconnect within a second. Do the same in your
app: `server.stop()` alone waits for every WebSocket, so systemd kills
the process after 30 seconds.

To push to GitHub as well, attach the repository with the
[GitHub integration](/docs/integrations-github) and push to
`https://github.int.exe.xyz/OWNER/NAME.git`; no token lands on the VM.

## Settings and secrets

Production reads `~/app.env` (`KEY=value` per line, mode 600); after a
change, `sudo systemctl restart app`. The dev server reads `~/app/.env`
like any `bun` command; the binary is built not to, so a stray `.env`
can't change production.

Keys to outside APIs can stay off the VM entirely: an
[HTTP proxy integration](/docs/integrations-http-proxy) adds them on the
way out, and the app calls `https://<name>.int.exe.xyz/` with no key. For
a prototype that calls a model, the [LLM gateway](/docs/integrations-llm)
answers at `https://llm.int.exe.xyz/v1/messages` (Anthropic) and
`/v1/responses` (OpenAI) with no key at all.

## Your database

`bun:sqlite` is built into Bun and the binary. The starter's
`src/db.ts` opens `DATABASE_PATH`, turns on WAL and
`synchronous = NORMAL`, and runs migrations from a list, tracked in
`user_version`: add a statement to the end and the dev server applies it
to `dev.db`, the next release to production, after a backup. Those two
pragmas took 19,200 concurrent writes from 38 seconds to 2. More in
[SQLite](/deploy/sqlite).

For PostgreSQL, [install it on the VM](/deploy/postgres#connect-an-app-on-this-vm),
put `DATABASE_URL` in `~/app.env`, and use Bun's built-in client:

```ts
import { sql } from "bun";
const [message] = await sql`INSERT INTO messages (author, body) VALUES (${author}, ${text}) RETURNING *`;
```

## Hono, Elysia, and Vite

Any server that listens on `PORT` works: the services set 3001 for dev,
8000 for production. **Hono** needs only `export default app`;
**Elysia**, `.listen(Number(process.env.PORT))`. `app-release` compiles
`"module"` (or `"main"`) from `package.json`, or the file you pass it.

Bun's HTML imports replace Vite for many apps (`bun init --react`
starts one). To keep Vite, build with relative paths and import the
result, which Bun embeds in the binary; without `--base ./` the compile
fails with `Could not resolve`.

```bash
bunx --bun vite build --base ./   # then: import index from "./dist/index.html"
```

## Make it public, add a domain

Both ports are private: only people you've [shared it with](/docs/sharing)
can open them. **On your computer**:

```bash
ssh exe.dev share set-public my-bun
```

That opens port 8000 only; port 3000 stays private, so a teammate you
share the VM with can watch the dev server while the world sees
production. For your own domain, point a CNAME at `my-bun.exe.xyz` and run
`ssh exe.dev domain add my-bun app.example.com` ([custom domains](/docs/cnames)).

## Sign-in and scripts

The proxy adds `X-ExeDev-Email` to requests from people signed in to
exe.dev ([login with exe](/docs/login-with-exe)); on a public app, send
others to `/__exe.dev/login?redirect=/`. The guestbook signs messages
this way.

Scripts can call the private app with a [VM token](/docs/https-tokens-for-vms)
(`ssh exe.dev ssh-key generate-api-key --vm=my-bun --label=scripts`):

```bash
curl -H "X-Exedev-Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"body":"Signed from a script"}' https://my-bun.exe.xyz/api/messages
```

## Keep your data

`~/bin/app-backup` runs nightly and before each release: SQLite in
`~/data` (through `.backup`, then checked), `~/app.env`, and `~/app`'s
git history, into `~/backups`, 14 of each kind. Copy them off now and
then; they hold your secrets. **On your computer**:

```bash
scp -r my-bun.exe.xyz:backups ./my-bun-backups
```

## Ask Shelley

Shelley, at `https://my-bun.shelley.exe.xyz/`, works in `~/app` and can
check port 3000 in its browser. Try: "Add markdown to guestbook messages
and show me on port 3000", or "Why did the last release roll back?"

## Limits

- Production and the dev server share one VM; for a busy app, develop on
  [another VM](/deploy/dev-test-prod).
- A release restarts the process: WebSockets reconnect, with no
  overlap between old and new.
- Native `.node` addons and code that reads its own source files may not
  compile; run `bun run start` from a copy instead.
- The binary is Linux x64: it runs on VMs, not on your Mac.

## The nuts and bolts

Happy with what Deploy set up? You can stop here. These are the setup
steps Shelley follows, which you can run by hand, and the commands for
later.

<details id="create-the-vm" data-manual-setup class="dp-details">
<summary>Set up by hand</summary>

### Create the VM

On your computer (pick another name if `my-bun` is taken):

```bash
ssh exe.dev new --name=my-bun
ssh my-bun.exe.xyz
```

Everything else runs **on the VM**, as `exedev`.

### Install Bun

Install Bun 1.4.5, pinned, and link it into `/usr/local/bin`, where
systemd finds it:

```bash
sudo apt-get install -y unzip sqlite3 nginx
curl -fsSL https://bun.com/install | bash -s "bun-v1.4.5"
sudo ln -sf ~/.bun/bin/bun /usr/local/bin/bun
sudo ln -sf ~/.bun/bin/bun /usr/local/bin/bunx
bun --version
```

Expect `1.4.5`.

### Get the code

**Start a new app** (`REPO=new`) in `~/app`, with the guestbook's files
([server.ts](https://exe.dev/deploy/bun/server.ts), [app.ts](https://exe.dev/deploy/bun/app.ts), [db.ts](https://exe.dev/deploy/bun/db.ts), [client.ts](https://exe.dev/deploy/bun/client.ts), [index.html](https://exe.dev/deploy/bun/index.html), [style.css](https://exe.dev/deploy/bun/style.css), [app.test.ts](https://exe.dev/deploy/bun/app.test.ts)):

```bash
mkdir -p ~/app/src && cd ~/app
git init -q -b main
bun init -y
rm -f index.ts
for f in server.ts app.ts db.ts client.ts index.html style.css app.test.ts; do
  curl -fsSL -o src/$f https://exe.dev/deploy/bun/$f
done
bun pm pkg set module=src/server.ts scripts.dev="bun --hot src/server.ts"
echo 'dev.db*' >> .gitignore
bun test && bun check
git add -A && git commit -qm "New Bun app" && git log --oneline
```

Expect `3 pass`, `No type errors`, and one commit.

**Or bring your GitHub repository** (replace `OWNER/NAME`):

```bash
git clone https://github.com/OWNER/NAME.git ~/app
cd ~/app && bun install
bun -p 'const p = require("./package.json"); [p.module ?? p.main, p.scripts?.dev]'
```

The last line prints the entry point `app-release` compiles and the dev
script; set missing ones with `bun pm pkg set module=src/index.ts
scripts.dev="bun --hot src/index.ts"`. For a **private** repository,
attach it with the [GitHub integration](/docs/integrations-github).
On your computer:

```bash
ssh exe.dev integrations add github --name bun-repo --repository OWNER/NAME --attach vm:my-bun
```

Then, on the VM:

```bash
git clone https://github.int.exe.xyz/OWNER/NAME.git ~/app
```

### Settings, data, and the production service

Create the directories and a private settings file (an existing
`~/app.env` is left alone):

```bash
mkdir -p ~/data ~/releases ~/backups ~/bin
if [ ! -e ~/app.env ]; then
  install -m 600 /dev/null ~/app.env
  cat >> ~/app.env <<'EOF'
# Settings and secrets for app.service: KEY=value, one per line.
# After changing it: sudo systemctl restart app
DATABASE_PATH=/home/exedev/data/app.db
EOF
fi
stat -c '%a %n' ~/app.env
```

Expect `600 /home/exedev/app.env`. A cloned app's settings from its
`.env.example` go there too, with any database path in `~/data`. The
service runs the binary `~/releases/current` points at, on port 8000:

```bash
sudo tee /etc/systemd/system/app.service >/dev/null <<'EOF'
[Unit]
Description=Bun app (the binary in ~/releases/current) on port 8000
After=network-online.target
Wants=network-online.target

[Service]
User=exedev
WorkingDirectory=/home/exedev/data
Environment=NODE_ENV=production PORT=8000
# Lines in app.env override the two above.
EnvironmentFile=/home/exedev/app.env
ExecStart=/home/exedev/releases/current
Restart=always
RestartSec=3
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable app.service
```

### The dev server

`app-dev.service` runs `bun run dev` on port 3001, and nginx on port
3000 passes requests to it (see [the note](#change-it-watch-it-reload)).
exeuntu's default nginx site would take port 8000, so it goes:

```bash
sudo tee /etc/systemd/system/app-dev.service >/dev/null <<'EOF'
[Unit]
Description=Bun dev server (bun run dev in ~/app) on port 3001, behind nginx on 3000
After=network-online.target
Wants=network-online.target

[Service]
User=exedev
WorkingDirectory=/home/exedev/app
Environment=PORT=3001
ExecStart=/usr/local/bin/bun run dev
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF
sudo curl -fsSL -o /etc/nginx/sites-available/bun-dev https://exe.dev/deploy/bun/bun-dev.conf
sudo rm -f /etc/nginx/sites-enabled/default
sudo ln -sf /etc/nginx/sites-available/bun-dev /etc/nginx/sites-enabled/bun-dev
sudo nginx -t
sudo systemctl daemon-reload
sudo systemctl enable --now app-dev nginx
sudo systemctl restart nginx
sleep 2
curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: my-bun.exe.xyz:3000' http://localhost:3000/
```

Expect `syntax is ok` and `200`.

### Releases and backups

Fetch the two scripts, [app-release](https://exe.dev/deploy/bun/app-release) and
[app-backup](https://exe.dev/deploy/bun/app-backup) ([Ship it](#ship-it) and
[Keep your data](#keep-your-data) say what they do), and run the backup
nightly:

```bash
for f in app-release app-backup; do
  curl -fsSL -o ~/bin/$f https://exe.dev/deploy/bun/$f
done
chmod +x ~/bin/app-release ~/bin/app-backup
```

```bash
sudo tee /etc/systemd/system/app-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up the app (~/data, ~/app.env, ~/app's history) to ~/backups

[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/bin/app-backup nightly
EOF
sudo tee /etc/systemd/system/app-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up the app every night

[Timer]
OnCalendar=*-*-* 03:00:00 UTC
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now app-backup.timer
```

### Release and check

Ship the first release:

```bash
~/bin/app-release
```

Expect `==> Released app-...: HTTP 200 on port 8000`. Check the services
and, for a new app, sign the guestbook as a signed-in visitor would:

```bash
for s in app app-dev nginx app-backup.timer; do echo "$s $(systemctl is-enabled $s) $(systemctl is-active $s)"; done
curl -s -H 'X-ExeDev-Email: setup@example.com' -H 'Content-Type: application/json' \
  -d '{"body":"Hello from setup"}' http://localhost:8000/api/messages; echo
sqlite3 ~/data/app.db 'PRAGMA user_version; DELETE FROM messages'
```

Expect `enabled active` four times, a message by `setup`, and `1` (the
migration ran); the last command removes the test message.

### Check the backup

Take a backup and open it in a scratch directory:

```bash
latest=$(~/bin/app-backup manual)
rm -rf /tmp/restore-check && mkdir /tmp/restore-check
tar -xzf "$latest" -C /tmp/restore-check
ls -A /tmp/restore-check /tmp/restore-check/data
git -C ~/app bundle verify /tmp/restore-check/app.bundle
find /tmp/restore-check/data -type f -name '*.db' |
  while read -r db; do echo "$db: $(sqlite3 "$db" 'PRAGMA integrity_check')"; done
rm -rf /tmp/restore-check
```

Expect `app.bundle`, `app.env`, and `data`; `The bundle records a
complete history`; and `ok` for each database.

Setup is done. Continue with [Open your app](#open-your-app).

</details>

<details id="restore" class="dp-details">
<summary>Restore a backup</summary>

### On the same VM

On the VM, pick the archive (`ls -lt ~/backups`), unpack it, and swap
its `data` in while the app is stopped. The current data is kept aside:

```bash
backup=~/backups/app-nightly-20261120-031204.tar.gz   # the one you want
rm -rf /tmp/restore && mkdir /tmp/restore && tar -xzf "$backup" -C /tmp/restore
sudo systemctl stop app
mv ~/data ~/data.before-restore-$(date +%s)
cp -a /tmp/restore/data ~/data
sudo systemctl start app
```

The app applies newer migrations as it starts. Delete
`~/data.before-restore-*` when you're sure.

### On a new VM

Create the VM and follow [Set up by hand](#create-the-vm) through
"Install Bun". Copy the archive over from your computer
(`scp app-nightly-20261120-031204.tar.gz my-bun.exe.xyz:`), then on the
VM:

```bash
rm -rf /tmp/restore && mkdir /tmp/restore && tar -xzf ~/app-nightly-20261120-031204.tar.gz -C /tmp/restore
git clone /tmp/restore/app.bundle ~/app && git -C ~/app remote remove origin
cd ~/app && bun install
mkdir -p ~/releases ~/backups ~/bin
install -m 600 /tmp/restore/app.env ~/app.env
rm -rf ~/data && cp -a /tmp/restore/data ~/data
```

Then follow the rest of the setup from "Settings, data, and the
production service" (it leaves the restored `~/app.env` alone).

</details>

<details id="update" class="dp-details">
<summary>Update Bun and your dependencies</summary>

**Dependencies** belong to your app. On the VM:

```bash
cd ~/app
bun outdated
bun update
bun test && git commit -am "Update dependencies" && ~/bin/app-release
```

**Bun** itself: read the [release notes](https://bun.com/blog), rerun
the installer with the new tag, and release, which compiles the new
runtime in:

```bash
curl -fsSL https://bun.com/install | bash -s "bun-v1.4.6"   # the version you want
bun --version
sudo systemctl restart app-dev
~/bin/app-release
```

</details>

<details id="troubleshooting" class="dp-details">
<summary>Something not working?</summary>

On the VM, production's logs and the dev server's:

```bash
journalctl -u app -n 100 --no-pager
journalctl -u app-dev -n 100 --no-pager
```

- **Port 3000 says `Blocked: Host header does not match the dev
  server`.** You reached Bun directly, not nginx: check `systemctl
  is-active nginx` and that `app-dev.service` has `PORT=3001`.
- **nginx won't start: `bind() to 0.0.0.0:8000 failed`.** exeuntu's
  default site is still enabled; `sudo rm /etc/nginx/sites-enabled/default`.
- **`app-release` says `FAILED: the new binary answers HTTP 000`.** It
  crashed or isn't listening on port 8000: read `PORT` from the
  environment instead of hard-coding a port. The previous binary is
  running again.
- **`lockfile had changes, but lockfile is frozen`.** Run `bun install`
  in `~/app` and commit `bun.lock`.
- **Changes to `~/app.env` have no effect.** `sudo systemctl restart
  app`. The dev server reads `~/app/.env`, not `~/app.env`.
- **Streams or slow requests are cut after 10 seconds.** That's
  `Bun.serve`'s `idleTimeout`; raise it (up to 255 seconds), or call
  `server.timeout(req, 0)` for that request.
- **Disk filling up.** `du -sh ~/releases ~/backups ~/.bun`;
  `app-release` keeps five binaries of about 100 MB each.

</details>

## Frequently asked questions

### Which Bun version does this install?

Bun 1.4.5 (November 19, 2026), pinned so the VM doesn't change under you. To move on, rerun the installer with a newer tag; see [Update](#update).

### Why compile to a binary instead of running bun in production?

Production can't change when you edit or `bun install` in `~/app`: it runs a fixed binary, with the frontend, dependencies, and runtime inside. Rolling back is pointing a symlink at the previous one.

### Do WebSockets and Server-Sent Events work?

Yes, on both ports, through exe.dev's [HTTPS proxy](/docs/proxy). Mind `Bun.serve`'s `idleTimeout`, 10 seconds by default; call `server.timeout(req, 0)` for a long-lived stream.

### How big a VM does a Bun app need?

The default (2 vCPUs, 8 GB, 25 GB of disk) is plenty. The starter's binary uses about 30 MB of memory idle and 50 MB under load; the dev server about 40 MB more. Each kept binary is about 100 MB.

### I'm coming from Railway, Render, or Fly. What changes?

Your app still reads `PORT`, so it runs as it is. You gain a dev server next to production, a SQLite file without a volume, and Shelley beside your code. Environment variables move to `~/app.env`; a deploy is `~/bin/app-release`.


## Related

- [Deploy a Node.js app](https://exe.dev/deploy/nodejs.md): Your Express app on a server of its own. git push to deploy.
- [SQLite in production](https://exe.dev/deploy/sqlite.md): One file on a real disk, streamed to your own bucket every second.
- [Self-host PostgreSQL](https://exe.dev/deploy/postgres.md): Your own Postgres on a real disk, with backups you've actually restored.
- [Deploy a Go web app](https://exe.dev/deploy/go.md): One Go binary on a VM of its own. git push to deploy.
- [Dev, Test, Prod: Choose One, Two, or Three](https://exe.dev/deploy/dev-test-prod.md): You can build, test, and deploy on exe.dev.
- [Run Claude Code on a remote server](https://exe.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop.
