Deploy a Bun app
Develop with bun --hot, ship one binary, on the same always-on VM.
Shelley handles the setup. About 10 minutes.
Prefer a terminal?
curl -fsSL https://exe.dev/deploy/bun/prompt.txt | ssh exe.dev new --prompt=/dev/stdinMost 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
https://my-bun.exe.xyz/
Your app, until you make it public
https://my-bun.exe.xyz:3000/
The dev server, reloading as you edit
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, ornewto start a fresh Bun app
Prefer a terminal?
curl -fsSL \
https://exe.dev/deploy/bun/prompt.txt \
| ssh exe.dev new --prompt=/dev/stdinWhat Shelley is told
REPO=<fill-this-in>
Set up Bun on this VM by following the exe.dev recipe at https://exe.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 --hoton the code in~/app, with its owndev.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.
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 answers403 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 aslocalhost. 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
.nodeaddons and code that reads its own source files may not compile; runbun run startfrom 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.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.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.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: checksystemctl is-active nginxand thatapp-dev.servicehasPORT=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-releasesaysFAILED: the new binary answers HTTP 000. It crashed or isn't listening on port 8000: readPORTfrom the environment instead of hard-coding a port. The previous binary is running again.lockfile had changes, but lockfile is frozen. Runbun installin~/appand commitbun.lock.- Changes to
~/app.envhave 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'sidleTimeout; raise it (up to 255 seconds), or callserver.timeout(req, 0)for that request. - Disk filling up.
du -sh ~/releases ~/backups ~/.bun;app-releasekeeps 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