Skip to content

Deploy a Bun app

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

Deploy on exe.dev

Shelley handles the setup. About 10 minutes.

Prefer a terminal?
curl -fsSL https://exe-staging.dev/deploy/bun/prompt.txt | ssh exe.dev new --prompt=/dev/stdin

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.

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.
What's running, and where
Private https://my-bun.exe.xyz/ Your app, until you make it public
Private https://my-bun.exe.xyz:3000/ The dev server, reloading as you edit
my-bun.exe.xyz exe.dev VM
Your app, in production One binary from bun build --compile, as app.service :8000~/releases/current → the newest of five kept binaries
The dev server bun --hot in ~/app as app-dev.service, behind nginx :3000~/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
Releases and backups app-release tests, compiles, switches, and rolls back; app-backup.timer runs nightly ~/backups

Deploy with Shelley#

Click Deploy and Shelley will set up Bun on a new VM, then check that it works. No config-file wrangling required.

Have these ready; Shelley asks for them:

  • REPO: the GitHub repository to run, as owner/name or a URL, or new to start a fresh Bun app
Prefer a terminal?
curl -fsSL \
  https://exe-staging.dev/deploy/bun/prompt.txt \
  | ssh exe.dev new --prompt=/dev/stdin
What Shelley is told
REPO=<fill-this-in>

Set up Bun on this VM by following the exe.dev recipe at https://exe-staging.dev/deploy/bun.md?via=deploy from top to bottom.

The values at the top of this message are mine:
- REPO: the GitHub repository to run, as owner/name or a URL, or `new` to start a fresh Bun app
Ask me for any that still say <fill-this-in> before you need them.

The recipe's example VM name is my-bun. This VM's name is the output of `hostname`: use it wherever the recipe writes my-bun. Skip the step that creates the VM; you are on it.

You are done when all of these are true. Check each one yourself:
- 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.

Read the whole recipe, including the closed details. Follow "Set up by
hand" from "Install Bun" to the end of it, as exedev; the walkthrough
above it is for the owner afterwards. Do not run Restore or Update, and
do not reboot. Leave public sharing off.
REPO picks one path in "Get the code": `new` starts a fresh app;
anything else is a GitHub repository (turn URLs into owner/name). If a
clone fails, follow the private-repository steps, and if that fails
too, give the owner the integration command and wait for them.
For a cloned app, fill ~/app.env from its .env.example (or README):
generate secrets with openssl, ask the owner for keys to outside
services, and never invent values. Don't commit to a cloned
repository; if the app can't run here without a code change (a
hard-coded port, say), make the smallest one, leave it uncommitted,
and tell the owner. If its dev server is Vite, follow "Hono, Elysia, and
Vite". If app-release fails, read its output, fix what you can,
and run it again.
Finish with both URLs, port 8000 and port 3000, and how the owner
works from here: edit in ~/app (or ask Shelley), watch port 3000, then
run ~/bin/app-release.

Finish with the URLs I should open.

Also at /deploy/bun/prompt.txt. The recipe it follows is /deploy/bun.md.

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.

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.'
The new app's guestbook, at https://my-bun.exe.xyz/.

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:

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 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 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 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.

For PostgreSQL, install it on the VM, put DATABASE_URL in ~/app.env, and use Bun's built-in client:

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.

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 can open them. On your computer:

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).

Sign-in and scripts#

The proxy adds X-ExeDev-Email to requests from people signed in to exe.dev (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 (ssh exe.dev ssh-key generate-api-key --vm=my-bun --label=scripts):

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:

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.
  • 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.

Set up by hand

Create the VM#

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

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:

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, app.ts, db.ts, client.ts, index.html, style.css, app.test.ts):

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-staging.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):

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. On your computer:

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

Then, on the VM:

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):

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:

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). exeuntu's default nginx site would take port 8000, so it goes:

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-staging.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 and app-backup (Ship it and Keep your data say what they do), and run the backup nightly:

for f in app-release app-backup; do
  curl -fsSL -o ~/bin/$f https://exe-staging.dev/deploy/bun/$f
done
chmod +x ~/bin/app-release ~/bin/app-backup
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:

~/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:

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:

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.

Restore a backup

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:

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 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:

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).

Update Bun and your dependencies

Dependencies belong to your app. On the VM:

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

Bun itself: read the release notes, rerun the installer with the new tag, and release, which compiles the new runtime in:

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
Something not working?

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

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.

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.

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. 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.

Published Nov 21, 2026 · Updated Nov 21, 2026 · tested end to end Nov 20, 2026 · Markdown · manifest.json · Something wrong? Tell us