Dev mode

bun run dev starts a supervised dual-process development environment. It runs the API server with automatic restart on source changes and the Vite web dev server with hot module replacement – all in a single terminal.

Usage

bun run dev [flags]

Flags

Flag	Description	Default
`--port <number>`	API server port	`27247`
`--no-web`	Skip the web dev server (API only)	Off
`--app <path>`	Path to an app directory to serve with a Vite HMR dev server	None
`--app-port <number>`	Vite dev server port for `--app`	`5173`
`--debug`	Verbose logging	Off

Starting dev mode

bun run dev

[dev] Starting API server with file watching...
[dev] Starting web dev server...
[api] [nimblebrain] Starting runtime...
[api] [nimblebrain] Runtime ready.
[web]   VITE v6.0.0  ready in 340 ms
[web]
[web]   ➜  Local:   http://localhost:27246/

If the workdir has no instance.json, the launcher first writes the dev adapter there ({"auth":{"adapter":"dev"}}), because serve does not start without one. An existing instance.json is left alone, so a workdir can run a real provider under bun run dev.

Both processes share the terminal. Output is prefixed with [api] or [web] so you can tell which process logged each line. Press Ctrl+C to stop both.

Dual-process architecture

bun run dev runs two child processes:

API server (bun --watch) – runs bun run src/cli/index.ts serve with Bun’s file watcher. When you change any source file, Bun automatically restarts the server.
Web dev server (bun run dev in web/) – runs the Vite development server with HMR. Changes to web client files are applied instantly in the browser without a full reload.

Both processes are supervised. When you press Ctrl+C:

A SIGTERM is sent to both processes
If they don’t exit within 5 seconds, they receive SIGKILL
A second Ctrl+C forces an immediate exit

API-only mode

If you only need the API server (no web client), skip the Vite process (bun forwards args after the script name):

bun run dev --no-web

[dev] Starting API server with file watching...
[api] [nimblebrain] Starting runtime...
[api] [nimblebrain] Runtime ready.

Custom port

Override the API server port:

bun run dev --port 8080

The web dev server port is controlled by NB_WEB_PORT. The standard npm scripts pre-configure all ports:

Script	API	Web
`bun run dev`	:27247	:27246
`bun run dev:empty`	:27249	:27248
`bun run dev:minimal`	:27251	:27250

Developing an app

To iterate on a Synapse app’s UI with hot module replacement, point bun run dev at the app directory with --app. The CLI reads the app’s local manifest.json for its name, registers that name in dev mode so its ui:// resources are served from Vite, and starts the dev server (default port 5173). Run the app’s MCP server yourself and point the workspace at its URL — see Local Development:

bun run dev --app ../synapse-apps/synapse-crm

Use --app-port to run the app’s Vite server on a different port:

bun run dev --app ../synapse-apps/synapse-crm --app-port 5180

The app dev server runs alongside the API and web processes; its output is prefixed with [app]. If the app directory has no manifest.json, bun run dev logs a warning and skips the app dev server.

Working directory

bun run dev starts the server (bun run src/cli/index.ts serve) under the hood, so it uses the same default work directory: ~/.nimblebrain. Development data (config, conversations, logs) lives there unless you point somewhere else.

Override the work directory by setting NB_WORK_DIR or passing --config to target a specific config file:

NB_WORK_DIR=./my-project/.nimblebrain bun run dev

What happens when the web directory is missing

If web/package.json does not exist, bun run dev logs a warning and runs in API-only mode:

[dev] Starting API server with file watching...
[dev] Warning: web/package.json not found. Skipping web dev server.
[api] [nimblebrain] Starting runtime...
[api] [nimblebrain] Runtime ready.

Running the server – production server (no file watching)
CLI Overview – global flags and config resolution