Matterbridge on Bun

Bun local development in container

docker pull oven/bun:latest && docker run -dit --network matterbridge -p 8283:8283 --name bun-development oven/bun:latest bash
docker exec -it bun-development bash

inside the container clone, build and run matterbridge

apt-get update && apt-get install -y git
git clone --depth 1 --single-branch --no-tags --branch dev https://github.com/Luligu/matterbridge.git && cd matterbridge
bun install
bun run build
cd apps/frontend
bun install
bun run build
cd ../..
bun link
matterbridge --docker --logger debug --debug

Bun docker hub image (experimental — for test and development only)

The image (tag bun 69 MB) includes only Matterbridge, using the latest release published on npm. This image is based on oven/bun:slim. Plugins are not included in the image: they will be reinstalled on first run.

Bun local image (experimental — for test and development only)

The bun image runs Matterbridge directly from the local source files with Bun runtime.

• Base image: oven/bun:slim (Debian trixie slim + Bun).
• Install dependencies and link only (no build!) with Bun:
  • bun install --omit=dev
  • bun link

Files

Scripts

npm run docker:build:localbun   # build the image (matterbridge:local-bun)
npm run docker:run:localbun     # run it (container matterbridge-local-bun, port 8283)
npm run docker:exec:localbun    # open a shell in the running container
npm run docker:log:localbun     # follow the container logs

Status

The core bridge runs on Bun: it creates its directories, initializes the Matter node storage, and brings up the server node and endpoints. The web frontend is built and served. See the TODO list below for the known limitations.

Bun port status

The approach is to detect if running in bun with isBun() and switch the package-manager command and global-modules paths to Bun where needed.

Done

• Global package resolution. bun link (in Dockerfile.bun) registers the local build as the global matterbridge package — and installs all CLI bins and their exec bits — so plugins resolve import 'matterbridge'. This is the full npm link replacement.
• npm root -g discovery. getGlobalNodeModules() returns getGlobalBunModules() when running on Bun (there is no bun root -g; the path is derived from $BUN_INSTALL / ~/.bun). (npmPrefix.ts, runtimeBun.ts)
• Plugin path resolution. PluginManager resolves plugins from the Bun global modules dir when running on Bun. (pluginManager.ts)
• Runtime-aware package management. Plugin installation, uninstallation, uploaded tarball installation, Matterbridge updates, and Docker-recreate recovery use Bun commands when running on Bun. The SpawnCommand worker also supports Bun on Windows and through sudo. (pluginManager.ts, frontend.ts, backendExpress.ts, spawnCommand.ts)
• Auto-reinstall on Docker recreate. Uses isBun() ? 'bun' : 'npm'. (matterbridge.ts)
• --add local plugin. When running on Bun, the plugin is no longer treated as "local", so the npm link matterbridge step is skipped (bun link already provides resolution). (matterbridge.ts)
• The threads doesn't flag no running after exit.
• Bun node:worker_threads module is unstable The runtime randomly crashes on worker exit. See Worker thread crash (SIGTRAP) on ARM64 for the full analysis and captured log.
• Bun needs process.exit() or worker.terminate(). If not called the memory is not released.

Known issue

• Bun cannot resolve the container user name. In the official Bun images, both node:os and bun:os return username: "unknown" and shell: "unknown" from os.userInfo(), even though they correctly return the UID, GID, and home directory. Consequently, Matterbridge sends User: unknown to the frontend system-information view instead of the container account (for example, root). Reproduce with bun -e "import * as os from 'bun:os'; console.log(os.userInfo())".
• Matter.js atomic writes fail under Bun on windows. Repro with bun --eval "import { mkdir, open, rename, rm, readFile } from 'node:fs/promises'; const dir='C:/Users/lligu/.matterbridge/bun-rename-repro'; await rm(dir,{recursive:true,force:true}); await mkdir(dir,{recursive:true}); const final=dir+'/final'; await Bun.write(final,'old'); for (let i=0;i<1000;i++){ const tmp=final+'.tmp'; const handle=await open(tmp,'w'); const writer=handle.createWriteStream({encoding:'utf8',flush:true}); await new Promise((resolve,reject)=>{writer.on('finish',resolve);writer.on('error',reject);writer.write('new '+i);writer.end();}); await handle.close(); await rename(tmp,final); } console.log(await readFile(final,'utf8')); await rm(dir,{recursive:true,force:true});"

  // Change: FileStorageDriver.js
  async #writeAndMoveFile(filepath, valueOrStream) {
    const tmpName = `${filepath}.tmp`;
    await writeFile(tmpName, valueOrStream, { encoding: "utf8", flush: true });
    await rename(tmpName, filepath);
  }

TODO

• Validate Bun/Node compatibility of the full runtime over a longer run (commissioning, mDNS, plugin behaviors) — only short smoke starts verified.