# Deploy Bun

> Deploy Bun apps (Hono, Bun.serve, TypeScript) with Falak — built on the builder, supervised on each server behind Caddy, Bun installed on first use.

Source: https://falak.sh/docs/deploy/bun/

Falak runs Bun apps the same way as Node apps: built once on the builder, started as a supervised process on each server, and proxied by Caddy. Bun itself is installed on a server the first time a Bun site targets it.

## Prerequisites

- A server of type **app**, **web** or **worker**.
- A `package.json` with a **`start` script**, and a Bun lockfile (`bun.lock` or `bun.lockb`) or `"packageManager": "bun@…"`.
- Your app listens on `process.env.PORT`.

```ts title="src/index.ts (Hono)"
import { Hono } from 'hono';

const app = new Hono();
app.get('/', (c) => c.text('Hello from Bun on Falak'));

export default {
  port: Number(process.env.PORT ?? 3000),
  hostname: process.env.HOST ?? '127.0.0.1',
  fetch: app.fetch,
};
```

```json title="package.json"
{
  "scripts": { "start": "bun run src/index.ts" },
  "dependencies": { "hono": "^4" }
}
```

## Deploy

1. **+ Create → Git repository**, pick the repository.
2. Choose the **Generic Node** preset and set the runtime to **Bun**. Falak also picks Bun when it detects `bun.lock`.
3. Pick servers and a domain, then **Deploy**.

If a server is not ready for Bun yet, the deployment shows **Waiting for servers** while the agent installs Bun, then continues on its own.

## How it runs

| Aspect | Value |
|---|---|
| Bun version | 1.4.2 (`FALAK_BUN_VERSION`), from Bun's official release binaries (SHA-256 verified) |
| Build | `bun install --frozen-lockfile`, `bun run build` if defined, then `bun install --production` |
| Web process | `bun run start` in the current release |
| Environment | Site variables + `PORT`, `HOST=127.0.0.1`, `NODE_ENV=production` (unless set) |
| Entry point without a `start` script | The builder's detection looks for `index.ts`, `src/index.ts`, `server.ts`, then JavaScript entry files, but the web process still runs `bun run start`, so **define `start`**. |

TypeScript runs directly; no build step is required.

## APM

`Bun.serve` is not auto-instrumented. Wrap your handler with `withFalakRequest` from `@falak/apm-node`. See [APM for Node, Bun and Deno](/docs/observability/apm-node/).

## Air-gapped servers

Set `FALAK_BUN_MIRROR` on the control plane to download Bun from your own mirror. See [Configuration](/docs/operations/configuration/#runtime-download-mirrors).

## Next steps