# B4.run

B4.run is a TypeScript-first meta-framework for building graph-based AI agents with the ergonomics of Next.js: file-system routing, shared and route-local tools with inferred types, scenario testing, route-level agent features, durable threads, and B4.run HTTP runtimes for development and deployment.

## Install and activate the default basic starter
```
npm create b4-app@latest my-agent
cd my-agent
npm install
npm run check
npm test
export OPENAI_API_KEY=sk-...
npm run dev          # B4.run dev server on http://127.0.0.1:3000
```
The default basic starter is one package with a single `/hello` agent (`src/app/hello/index.ts`) and one typed `greet` tool (`src/app/hello/tools/greet.ts`). Its tests run offline; live runs require the real provider key.

## Install and activate the navlog starter
```
npm create b4-app@latest my-agent -- --template navlog
cd my-agent
npm install
npm run typegen
npm run check
npm run typecheck
npm test
npm run eval
cp server/.env.example server/.env
# Add a real OPENAI_API_KEY to server/.env
npm run verify
npm run dev:server   # agent server on http://127.0.0.1:3002
npm run dev:web      # B4.run Workbench UI on http://localhost:3010, in a second terminal
```
Requires Node.js 24 or later and npm 11. The navlog starter, a VFR flight planner, is a two-package npm workspace: `server/` is the B4.run app and `web/` is the B4.run Workbench, an AG-UI/CopilotKit browser client. Every command above runs at the workspace root and delegates into the package that owns it. The tests and eval need no key (the eval replays scripted fixtures while its weather tools reach aviationweather.gov); live activation requires the real provider key on the server.

## Project Shape
Paths below are relative to the B4.run app root: the generated project root in the default `basic` template, and the `server/` package in the navlog workspace.
- `b4.config.ts` at the app root. Supported keys include `appDir`, `backends`, `permissions`, `checkpointer`, `threadsStore`, `env`, `toolOutput`, `summarization`, `sandbox`, `memory`, and `build`.
- `src/app/**/index.ts`: route entry; exports exactly one of default `agent(...)`, named `workflow` (async function), named `graph` (LangGraph graph), or named `chain` (LangChain LCEL Runnable).
- `src/app/**/state.ts`: optional Zod route state schema.
- `src/tools/*.ts`: shared authored tools available to routes by default; the navlog scaffold keeps `computeNavlog`, `readDoc` and its weather tools here.
- `src/app/**/tools/*.ts`: route-local authored tools; visible only to that route and shadow same-named shared tools. Tool default exports are async functions and their types are inferred.
- `workspace/AGENTS.md`: optional app-workspace prompt guidance, re-read on every turn and shared by consuming agent routes and subagents; it is not route-local.
- `src/app/**/memory.md`: optional stable prompt memory for one route. The navlog scaffold includes it.
- `src/app/**/memory.ts`: optional typed long-term memory collection; contributes `recall` and `remember`. The navlog scaffold includes it.
- `src/app/**/plan.md`: optional route-local planning seed; contributes todo state, `writeTodos`, and `plan_update` but is not itself updated at runtime.
- `src/app/**/skills/<name>/SKILL.md`: optional route-local instructions loaded on demand through `readSkill`.
- `src/app/**/subagents/<name>/index.ts`: optional immediate child agent routes exposed through `task`; children get shared and their own route-local tools, not the parent's local tools.
- `agent({ reasoning })`: optional OpenAI-backed reasoning-effort configuration.
- `src/app/**/run.test.ts`: colocated scenario tests.
- `.b4/b4.generated.d.ts`: auto-generated ambient types. Never edit by hand.

## Pathname Rules
- Directory path becomes URL pathname.
- `(public)`: route group; excluded from pathname.
- `[tenant]`: dynamic segment preserved in the route id; provide the value in JSON input.
- Default basic scaffold example: `src/app/hello/index.ts` → `/hello`; agent route key `/hello#agent`.
- Navlog scaffold example: `src/app/navlog/index.ts` → `/navlog`; agent route key `/navlog#agent`.
- Route group plus dynamic segment example: `src/app/(public)/hello/[tenant]/index.ts` → `/hello/[tenant]`.

## Minimal Agent Route
```ts
import { agent } from "@b4run/sdk"

export default agent({
  model: "gpt-5-mini",
  systemPrompt: "You are a VFR flight-planning assistant for a Cessna 172N. Brief the weather, compute the navlog in code, and cite every POH figure.",
})
```

## Minimal Tool
```ts
import type { B4ToolContext } from "@b4run/sdk"
// src/tools/readDoc.ts (shared; the navlog scaffold uses this location)
export default async (input: { readonly path: string }, ctx: B4ToolContext) => {
  return { content: await ctx.fs.readFile(input.path) }
}
```

## Commands
- `b4 add`: list the blueprint catalog; `b4 add <name-or-url>`: fetch and print an integration blueprint for an agent to apply
- `b4 build`: emit configured deployment targets (`node` + `langsmith` by default; `hono` opt-in)
- `b4 check`: validate app structure/config
- `b4 dev`: local Agent Protocol runtime server
- `b4 docs [topic]`: print local documentation snippets
- `b4 eval [path]`: run eval definitions
- `b4 inspect`: open the optional B4.run Inspector browser UI
- `b4 memory [subcommand] [args...]`: inspect and manage long-term memory
- `b4 routes`: list discovered routes
- `b4 run <routePath>`: execute a route with JSON stdin/stdout
- `b4 start`: serve the B4.run Node runtime in production (default `0.0.0.0:8000`)
- `b4 test [path]`: run scenarios
- `b4 typegen`: regenerate `.b4/b4.generated.d.ts`
- `b4 verify`: run five phases: app discovery, route discovery, type generation, dependency/environment advisories, and runtime readiness
- `echo '{"messages":[{"role":"user","content":"Say hello to Ada"}]}' | b4 run /hello`: execute the default basic scaffold route
- `echo '{"messages":[{"role":"user","content":"Plan a VFR flight from KSTP to KRST at 4500 feet, departing 1400Z, in N738ZU (172N, 2400 RPM, 50 gal usable)."}]}' | b4 run /navlog`: execute the navlog scaffold route (from `server/`)

## Agent Protocol
- `GET /healthz` (liveness)
- `GET /readyz` (readiness: probes the durable stores, 503 names the failing one)
- `POST /threads`
- `GET /threads/:thread_id`
- `DELETE /threads/:thread_id`
- `POST /threads/:thread_id/cancel`
- `POST /threads/:thread_id/runs/wait`
- `POST /threads/:thread_id/runs/stream`
- `GET /threads/:thread_id/state`
- `GET /threads/:thread_id/pending_interrupts`
- `GET /threads/:thread_id/turns`
- `GET /threads/:thread_id/events`
- `POST /threads/:thread_id/resume`
- `GET /memory/candidates`
- `POST /memory/candidates/:id/approve`
- `POST /memory/candidates/:id/reject`
- Run body: `{ "route": "/navlog#agent", "input": { "messages": [{ "role": "user", "content": "Plan a VFR flight from KSTP to KRST at 4500 feet, departing 1400Z." }] } }`
- Resume body: `{ "resume": [{ "interruptId": "<id>", "status": "resolved", "payload": "once" | "always" | "deny" }], "route": "/navlog#agent" }`; the strict envelope must address every currently pending interrupt exactly once. Nested interrupts resume through the root thread.
- App middleware gates execution routes, not the whole server. The middleware-bypassing management routes are thread create/read/delete/state/cancel plus all memory-candidate routes; candidate listing spans namespaces, while approve/reject mutate records. Health also bypasses middleware for readiness probes. Any non-local exposure requires reverse-proxy or platform authentication and network restrictions covering the entire service.

## Runtime Capabilities
- `toolOutput` offloads large tool results into `workspace/tool-outputs/` and keeps an in-context preview.
- `summarization` is opt-in and compresses older thread history when configured.
- `memory` enables typed long-term recall/write governance through route-local memory definitions.
- `sandbox` configures isolated execution for workspace commands where supported.

## Documentation map
- [Getting Started](https://b4.run/docs/getting-started): scaffold, verify offline, and make the first keyed live run.
- [Add a Tool](https://b4.run/docs/recipes/add-a-tool): build the first typed application feature.
- [Memory](https://b4.run/docs/memory): choose prompt context, typed long-term memory, retrieval, episodes, or distillation.
- [Agent Protocol](https://b4.run/docs/dev-server/agent-protocol): integrate a client with thread and run endpoints.
- [Embed the Runtime](https://b4.run/docs/embedding): host B4.run inside an existing server.
- [Fixtures and Recording](https://b4.run/docs/testing-agents/fixtures): replay deterministic fixtures or record local model calls.
- [Persistence and Tenancy](https://b4.run/docs/persistence): choose durable stores and tenant boundaries.
- [Production Topology](https://b4.run/docs/production-topology): place runtimes, stores, proxies, and workers.
- [Security Architecture](https://b4.run/docs/security-architecture): review trust boundaries before exposure.
- [Deployment Options](https://b4.run/docs/deployment): select Node and Docker, Kubernetes, LangSmith, or edge deployment.
- [Configuration Reference](https://b4.run/docs/configuration): inspect every supported configuration key.
- [CLI Reference](https://b4.run/docs/cli): use the local development, test, build, and operations commands.
- [API Reference](https://b4.run/docs/api): inspect exported application-facing types and functions.

## Packages
- `@b4run/sdk`: authoring contract (types, `RuntimeContext`, test helpers)
- `@b4run/langgraph`: LangGraph graphs/workflows adapter
- `@b4run/langchain`: LangChain LCEL adapter and provider-aware agent materialization
- `@b4run/cli`: the `b4` CLI

## Deployment
Choose targets with `build.targets` (the list replaces the defaults). `node` emits a Node >=24 B4.run HTTP server plus a marker-managed Dockerfile for self-hosting; the navlog scaffold's `npm start` script loads `.env` before serving the emitted artifact, while bare `b4 start` does not load `config.env`. Supply secrets in the runtime environment when invoking the CLI directly or running the emitted image. `hono` is opt-in for compatible edge apps after `B4_E1005` capability validation; it serves Agent Protocol and AG-UI with generated Postgres stores, but no filesystem, shell, sandbox, tool-output offloading, skills, or typed long-term memory, and its run/cancel registry is isolate-local. `langsmith` emits `langgraph.json` and generated graph entries rather than the B4.run HTTP server; middleware, AG-UI, and the sandbox manager are absent, and its current `node_version: "22"` conflicts with B4.run packages' Node >=24 requirement.

## Task-Specific Prompts
Copy-ready prompts for common tasks:
- Scaffold: https://b4.run/prompts/scaffold
- Add a tool: https://b4.run/prompts/add-a-tool
- Write a route: https://b4.run/prompts/write-a-route
- Write a test: https://b4.run/prompts/write-a-test
- Deploy: https://b4.run/prompts/deploy

## Agent Config Templates
Drop-in agent configuration for a B4.run project:
- https://b4.run/AGENTS.md

## Brand Assets
Official B4.run logos, icons, favicons, and social assets:
- Asset manifest: https://b4.run/brand/assets.json
- Full brand kit ZIP: https://b4.run/brand/b4-run-brand-assets.zip

## Full Reference
https://b4.run/llms-full.txt

## Source
https://github.com/cacheplane/b4run
## Blog

- [B4.run 0.13: A sandbox per thread](https://b4.run/blog/b4-0-13-a-sandbox-per-thread): Learn what 0.13 adds for threads that need their own environment: per-thread images and permissions, staged workspaces and HTTP reads.
- [B4.run 0.9 to 0.12: The answer the user sees](https://b4.run/blog/b4-0-12-the-answer-the-user-sees): Learn what 0.9 through 0.12 changed about the final answer: response schemas, an after hook, returnDirect tools and streamed tool arguments.
- [What is a software factory?](https://b4.run/blog/what-is-a-software-factory): Software factory is a buzzword again. Here is what the term meant in 1968, what it means in 2026, and what we learned building one with B4.run.
- [Build a code-fixing agent you can read](https://b4.run/blog/build-a-code-fixing-agent-you-can-read): Follow a B4.run agent from a failing CLI test through a Docker workspace, independent checks, and approval of the exact change.
- [B4.run 0.8: The framework around the agent](https://b4.run/blog/b4-0-8-framework-around-the-agent): Learn what 0.5 through 0.8 added around the agent: evals, tool permissions, sandboxes, delegation, typed memory, AG-UI clients and production builds.
- [B4.run at the edge: The Hono target](https://b4.run/blog/b4-at-the-edge): B4.run's opt-in Hono target emits a Node-free Cloudflare Workers entry with request-scoped Postgres stores and a tested workerd subset.
- [Eve and B4.run: Choosing an agent framework](https://b4.run/blog/eve-validates-the-shape): Eve and B4.run both organize agents as files. Here is what that structure gives us, and how to compare the client, runtime and deployment choices.
- [B4.run 0.4: Start with an agent test](https://b4.run/blog/b4-0-4-release): Learn how the offline agent test added to the starter in 0.4 works, and what a scripted model response can verify.
- [The App Router for AI Agents](https://b4.run/blog/app-router-for-ai-agents): Learn how B4.run uses file-system routes, typed tools, planning, skills and subagents to organize a LangGraph.js agent application.
- [Why we built B4.run](https://b4.run/blog/why-we-built-b4): B4.run is a TypeScript framework for LangGraph.js agents. Here is the problem it solves and its conventions: file-system routes, local tools and typegen.