Dev Server
b4 dev runs your app locally. It starts B4.run's HTTP runtime, watches your
files, regenerates types, and restarts the runtime when source files change.
If you're building a client, see the protocol guides linked below.
Starting the serverCopy link to section: Starting the server
b4 devThe server picks a free localhost port and prints a URL such as
B4.run dev ready at http://127.0.0.1:43127. Pass --port when you need a
fixed address:
b4 dev --port 3001The server always listens on 127.0.0.1.
Invoking a routeCopy link to section: Invoking a route
With the server running, call a route from another terminal:
echo '{"messages":[{"role":"user","content":"Hello"}]}' |
b4 run '/research' --url http://127.0.0.1:3001b4 run looks up the route's <routeId>#<kind> assistant id, creates a
thread for the call, sends the input through Agent Protocol, and prints the
final state.
Restart cycleCopy link to section: Restart cycle
When an app file changes, B4.run regenerates types and then starts a new
runtime. Changes under ignored paths such as .b4/, workspace/ and lockfiles
are skipped. For everything else, the restart log names the reason.
b4 dev runs two processes, a parent and a child:
- The parent owns the app root, watcher, session, selected port, and stable URL across restarts.
- The child owns the HTTP listener and route graph.
Each restart stops the child and its listener, then starts a fresh child on the same port. The parent never holds the listener.
The replacement child reloads the app and b4.config.ts, including store and
runtime configuration. Configuration edits take effect on that restart.
The default SQLite thread store and checkpointer keep your threads and checkpoints across restarts. Other durable stores preserve data too, once the new child reconnects. An in-memory store starts empty after each restart. Running work gets a short grace period before the old child is killed.
LoggingCopy link to section: Logging
The ready line shows the current URL, and each restart line shows what kind of
file changed. Set B4_DEV_SHUTDOWN_TIMEOUT_MS to change the grace period for
stopping the old child.
AG-UI endpointCopy link to section: AG-UI endpoint
Browser clients use the separate AG-UI endpoint and lifecycle.
TracingCopy link to section: Tracing
See Observability for the environment variables, trace setup, and how interrupts show up in traces.
MiddlewareCopy link to section: Middleware
See Middleware for how middleware gates route runs, and Security Architecture for the management routes that need authentication in front of the whole service.
Thread access is a second gate inside the runtime. It checks the thread rather than the route, and it covers every thread endpoint, including the ones middleware never sees. A request must pass both.