Navlog Example App

Navlog is the flagship B4.run example: a VFR flight planner for a Cessna 172N, with an agent server and a web client. Try it live, run it on your machine, deploy your own copy, or start a new app from it.

The demo is a learning tool, not a flight-planning service. Its weather is live, but its airport and navaid data is a dated snapshot. Never use it for real flight planning.

What does it show?#Copy link to section: What does it show?

A planning run uses most of B4.run's agent features in one route. The table maps what you see to the feature and the file behind it.

Run it locally#Copy link to section: Run it locally

You need Node.js 24, pnpm, and an OpenAI API key for live runs. The unit tests and evals run without a key.

1. 1

   Get the code

   Clone the repository and install from the root:

   bash

   git clone https://github.com/cacheplane/b4run.git
   cd b4run
   pnpm install
   pnpm build

2. 2

   Give the server a key

   The server holds the OpenAI key. The web client never sees it:

   bash

   cd examples/navlog
   cp server/.env.example server/.env
   # edit server/.env and set OPENAI_API_KEY

3. 3

   Start both apps

   bash

   pnpm dev

   This starts the B4.run server on port 3002 and the web client on port 3010. Open http://localhost:3010 and plan a route.

To start a new app from the example rather than work in the repository, scaffold it:

npm create b4-app@latest my-navlog -- --template navlog

The scaffold is the same code as examples/navlog, kept byte for byte in sync by a test. Build a Flight Planner walks through it from there.

How is it built?#Copy link to section: How is it built?

Navlog has two packages. server/ is a B4.run app, and web/ is a Next.js client that talks to it over AG-UI.

The request path#Copy link to section: The request path

A plan is one streaming request from the browser to the agent:

browser
  → POST /api/copilotkit/…           (web: CopilotKit runtime, the visitor guard)
  → B4HttpAgent({ responseSchema })   (web: adds the brief kit's JSON Schema)
  → POST /agui/%2Fnavlog%23agent      (server: the navlog route over AG-UI)
  → the coordinator, its subagents and tools
  ← streamed events: text, tool steps, the plan, an approval card

The client's other calls go through small, allowlisted proxies: /api/b4 for memory review and /api/waypoints for route autocomplete.

The server#Copy link to section: The server

The web client#Copy link to section: The web client

The map, the sheet and the chat all read from the same run. Each surface finds its data in the tool results with a pure selector. For example, latestNavlogResult returns the most recent computeNavlog result, so a replan updates everything at once.

Deploy your own#Copy link to section: Deploy your own

The live demo runs the server on Railway and the web client on Vercel. Each package's README has the full steps. The shape of the setup:

• Server (server/Dockerfile.railway, server/main.mjs): runs the b4 build output with Postgres for threads, checkpoints, permissions and memory. It refuses to boot in production without a shared secret.
• Web (web/vercel.json): a Vercel project rooted at examples/navlog/web, with an 800-second limit on the CopilotKit route because a plan streams for several minutes.

Use it as a starting point#Copy link to section: Use it as a starting point

Most of what makes navlog a flight planner lives in four places. To adapt it, change these:

• The aircraft and the corpus. server/workspace/aircraft/ and server/workspace/poh/ hold the airplane's data. The agent reads them through readDoc.
• The procedure. The coordinator's prompt in server/src/app/navlog/index.ts says what to do and in what order. The subagents' prompts say how to brief weather and performance.
• The tools. Each file in server/src/tools/ is one tool, typed from its input. Keep arithmetic in src/lib/ and out of the model.
• The answer's shape. web/app/brief/schema.ts declares the components the agent may answer with. The server binds that schema as the model's structured output.

The tests are the safety net. pnpm test in examples/navlog runs the server and web unit tests, and pnpm --filter ./server eval replays the recorded evals. Neither needs a key.

Related#Copy link to section: Related