### Clone and Setup Project

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/CONTRIBUTING.md

Commands to clone the repository, install dependencies for both API and web client, and initialize the environment configuration.

```bash
git clone https://github.com/NimbleBrainInc/nimblebrain.git
cd nimblebrain

# Install API dependencies
bun install

# Install web client dependencies
cd web && bun install && cd ..

# Copy the environment template and fill in at least one LLM provider key
cp .env.example .env
# Edit .env — set ANTHROPIC_API_KEY (or OPENAI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY / NEBIUS_API_KEY / XAI_API_KEY)
```

--------------------------------

### Production deployment command

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/cli/serve.mdx

Example of setting required environment variables and starting the server in a production environment.

```bash
export ANTHROPIC_API_KEY=sk-ant-api03-...
export ALLOWED_ORIGINS=https://app.example.com

bun run src/cli/index.ts serve --port 27247
```

--------------------------------

### Run Local Development Commands

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/README.md

Use these commands to install dependencies, start the development server, build for production, or preview the build.

```bash
bun install
bun run dev       # Start dev server at localhost:4321
bun run build     # Production build to dist/
bun run preview   # Preview the production build
```

--------------------------------

### Install web dependencies

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/installation.mdx

Navigate to the web directory and install its dependencies.

```bash
cd web && bun install && cd ..
```

--------------------------------

### Bundle Lifecycle Event

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/config/logging.mdx

Example of a bundle installation event including workspace ID and trust score.

```json
{"ts":"2026-03-25T14:30:00.123Z","event":"bundle.installed","wsId":"ws_product","serverName":"postgres","bundleName":"@nimblebraininc/postgres","version":"1.2.0","trustScore":92}
```

--------------------------------

### Install NimbleBrain Bundle SDK

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/packages/bundle-sdk-py/README.md

Commands to install the SDK using uv or pip.

```bash
uv add nimblebrain-bundle-sdk
# or
pip install nimblebrain-bundle-sdk
```

--------------------------------

### Server output example

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/cli/serve.mdx

Typical console output upon successful server startup.

```text
[nimblebrain] Starting runtime...
[nimblebrain] Runtime ready.
```

--------------------------------

### Install Synapse package

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/synapse.mdx

Install the Synapse library using npm.

```bash
npm install @nimblebrain/synapse
```

--------------------------------

### Clone and install dependencies

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/installation.mdx

Clone the repository and install project dependencies using Bun.

```bash
git clone https://github.com/NimbleBrainInc/nimblebrain.git
cd nimblebrain
bun install
```

--------------------------------

### Log file path examples

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/config/logging.mdx

Concrete examples of the daily rolling log file paths.

```text
~/.nimblebrain/logs/workspace/2026-03-25.jsonl
~/.nimblebrain/logs/workspace/2026-03-26.jsonl
```

--------------------------------

### Basic Dev Mode Usage

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/cli/dev.mdx

Syntax for starting the development environment.

```bash
bun run dev [flags]
```

--------------------------------

### Start services

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/deploy/docker.mdx

Launch the platform containers in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Initialize the UI project

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/local-dev.mdx

Commands to create the UI directory and install necessary React and Synapse dependencies.

```bash
mkdir ui && cd ui
npm init -y
npm install react react-dom
npm install -D @nimblebrain/synapse @vitejs/plugin-react vite vite-plugin-singlefile typescript @types/react @types/react-dom
```

--------------------------------

### Run Synapse Preview

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/local-dev.mdx

Start the development server for the UI to enable the standalone preview mode.

```bash
cd your-app/ui
npm run dev
# Open http://localhost:5173/__preview
```

--------------------------------

### Start Development Mode

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/cli/dev.mdx

Command to initiate the dual-process development environment and its typical output.

```bash
bun run dev
```

```text
[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/
```

--------------------------------

### Start development server without UI hot-reload

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/local-dev.mdx

Run the platform using the bundle path defined in the configuration.

```bash
bun run dev
```

--------------------------------

### Start NimbleBrain services

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/quickstart.mdx

Set the required API key environment variable and launch the containers.

```bash
export ANTHROPIC_API_KEY=sk-ant-api03-...
docker compose up
```

--------------------------------

### Start development server with UI hot-reload

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/local-dev.mdx

Run the platform with hot-reload enabled for a specific UI path.

```bash
cd nimblebrain    # the platform repo
bun run dev --app /path/to/your-app/ui
```

--------------------------------

### Run Development Servers

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/CONTRIBUTING.md

Commands to start the API, web client, or TUI in development mode.

```bash
bun run dev        # API (:27247, auto-restart) + web client (:27246, HMR) — single terminal
bun run dev:api    # API only
bun run dev:web    # Web client only
bun run dev:tui    # Interactive TUI (no web client)
```

--------------------------------

### Missing Web Directory Warning

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/cli/dev.mdx

Example output when the web directory is not found.

```text
[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.
```

--------------------------------

### Preview application in standalone mode

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/hello-world.mdx

Starts the development server for the UI independently of the NimbleBrain platform.

```bash
cd ui
npm run dev
# Open http://localhost:5173/__preview
```

--------------------------------

### Define workspace configuration

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Example of a workspace.json file defining workspace-specific agents, bundles, and overrides.

```json
{
  "id": "ws_product",
  "name": "Product",
  "members": [{ "userId": "usr_default", "role": "admin" }],
  "bundles": [
    { "name": "@nimblebraininc/ipinfo" },
    { "path": "../mcp-servers/hello" }
  ],
  "skillDirs": ["./skills"],
  "agents": {
    "researcher": {
      "description": "Research agent",
      "systemPrompt": "You are a research agent...",
      "tools": ["search__*"],
      "maxIterations": 8
    }
  },
  "models": { "default": "anthropic:claude-opus-4-6" },
  "identity": { "name": "Acme Copilot" }
}
```

--------------------------------

### Interact with the agent

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/quickstart.mdx

Example prompts for testing agent capabilities and managing connectors.

```text
What can you help me with?
```

```text
List the available connectors and install one for me
```

--------------------------------

### GET /v1/bootstrap

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Bootstraps the workspace context including user information, workspaces, and shell configuration.

```APIDOC
## GET /v1/bootstrap

### Description
Bootstraps the workspace context including user information, workspaces, and shell configuration.

### Method
GET

### Endpoint
/v1/bootstrap
```

--------------------------------

### Define bundle configuration

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/concepts.mdx

Example configuration for an MCP bundle, including environment variable definitions.

```json
{
  "name": "@nimblebraininc/postgres",
  "env": { "DATABASE_URL": "postgres://localhost/mydb" }
}
```

--------------------------------

### Configure Connector Providers

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/config/nimblebrain-json.mdx

Example configuration for enabling Composio and Smithery providers within the connectors block.

```json
{
  "connectors": {
    "providers": {
      "composio": {
        "apiKey": "…",
        "authConfigs": { "gmail": "ac_xxxxxxxx" },
        "baseUrl": "https://backend.composio.dev",
        "monitorEnabled": true
      },
      "smithery": {
        "namespace": "my-namespace",
        "monitorEnabled": true
      }
    }
  }
}
```

--------------------------------

### Configure named bundles from registry

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/config/bundles.mdx

Install bundles from a registered registry using their scoped name.

```json
{
  "bundles": [
    { "name": "@nimblebraininc/tasks" },
    { "name": "@nimblebraininc/postgres" }
  ]
}
```

--------------------------------

### Full manifest structure

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/manifest.mdx

Example of a complete manifest.json file including the required MCPB fields and the NimbleBrain host metadata extension.

```json
{
  "manifest_version": "0.4",
  "name": "@myorg/my-app",
  "version": "1.0.0",
  "description": "My NimbleBrain app",
  "author": {
    "name": "My Org",
    "email": "dev@myorg.com",
    "url": "https://myorg.com"
  },
  "server": {
    "type": "python",
    "mcp_config": {
      "command": "python",
      "args": ["-m", "my_app.server"]
    }
  },
  "_meta": {
    "ai.nimblebrain/host": {
      "host_version": "1.0",
      "name": "My App",
      "icon": "database",
      "placements": [
        {
          "slot": "main",
          "resourceUri": "ui://dashboard",
          "priority": 50,
          "label": "My App",
          "icon": "database",
          "route": "my-app",
          "size": "full"
        },
        {
          "slot": "settings",
          "resourceUri": "ui://settings",
          "label": "My App",
          "icon": "settings"
        }
      ]
    }
  }
}
```

--------------------------------

### Define full instance configuration

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

A comprehensive example of nimblebrain.json including model slots, providers, and system paths.

```json
{
  "$schema": "https://schemas.nimblebrain.ai/v1/nimblebrain-config.schema.json",
  "version": "1",
  "models": {
    "default":   "anthropic:claude-sonnet-4-6",
    "fast":      "anthropic:claude-haiku-4-5-20251001"
  },
  "providers": {
    "anthropic": { "apiKey": "sk-ant-..." },
    "openai":    { "apiKey": "sk-..." }
  },
  "http":      { "port": 27247, "host": "127.0.0.1" },
  "logging":   { "dir": "~/.nimblebrain/logs", "level": "normal", "retentionDays": 30 },
  "store":     { "type": "jsonl", "dir": "~/.nimblebrain/conversations" },
  "telemetry": { "enabled": true },
  "files":     { "maxFileSize": 26214400, "maxFilesPerMessage": 10 },
  "features":  { "bundleManagement": true },
  "maxIterations": 25,
  "maxInputTokens": 500000,
  "maxOutputTokens": 16384,
  "workDir": "~/.nimblebrain"
}
```

--------------------------------

### Handle missing configuration errors

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/config/credentials.mdx

Example of the error message displayed when required configuration fields are not provided.

```text
Missing required config "Anthropic API Key" for @nimblebraininc/webfetch.
Set it in workspace settings, or export:
  export ANTHROPIC_API_KEY=<value>  # satisfies "anthropic_api_key"
```

--------------------------------

### Define Per-toolkit Auth Configs

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/config/nimblebrain-json.mdx

Example of mapping toolkit slugs to their respective Composio auth-config IDs.

```jsonc
"authConfigs": { "gmail": "ac_xxxxxxxx", "posthog": "ac_yyyyyyyy" }
```

--------------------------------

### Define workspace configuration

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/config/workspace-json.mdx

Example structure for a workspace.json file, including member roles, bundles, skill directories, and agent definitions.

```json
{
  "id": "ws_a1b2c3d4e5f60718",
  "name": "Product",
  "about": "Product team workspace — roadmap, metrics, and customer research.",
  "members": [
    { "userId": "usr_default", "role": "admin" },
    { "userId": "usr_alex01",  "role": "member" }
  ],
  "bundles": [
    { "name": "@nimblebraininc/ipinfo" },
    { "name": "@nimblebraininc/granola", "env": { "API_KEY": "grn_..." }, "trustScore": 85 },
    { "path": "../mcp-servers/hello" }
  ],
  "skillDirs": ["./skills", "/opt/nimblebrain/skills"],
  "agents": {
    "researcher": {
      "description": "Deep research agent with search tools",
      "systemPrompt": "You are a research agent. Use search tools to find information.",
      "tools": ["granola__*", "nb__*"],
      "maxIterations": 8,
      "model": "fast"
    }
  },
  "models": { "default": "anthropic:claude-opus-4-6" },
  "identity": "You are the Acme Product Copilot. Be concise. Prefer data-backed answers.",
  "createdAt": "2026-03-05T10:00:00.000Z",
  "updatedAt": "2026-04-15T09:15:00.000Z"
}
```

--------------------------------

### Deploy Nimblebrain with Docker Compose

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Set required environment variables and start the services using Docker Compose.

```bash
export ANTHROPIC_API_KEY=sk-ant-...
export ALLOWED_ORIGINS=http://localhost:27246  # for cookie-based auth
docker compose up
# Platform: internal only (API), Web: localhost:27246 (UI)
```

--------------------------------

### GET /v1/health

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/deploy/observability.mdx

Retrieves the health and readiness status of the platform and its installed bundles.

```APIDOC
## GET /v1/health

### Description
Returns the build identity and the lifecycle state of each installed bundle instance.

### Method
GET

### Endpoint
/v1/health

### Response
#### Success Response (200)
- **status** (string) - "ok" once the server is serving
- **version** (string) - The platform version
- **buildSha** (string) - The build commit SHA
- **bundles** (array) - List of bundle instances and their lifecycle states

#### Response Example
{
  "status": "ok",
  "version": "1.2.3",
  "buildSha": "abc1234",
  "bundles": [
    { "name": "@nimblebraininc/ipinfo", "state": "healthy" },
    { "name": "@nimblebraininc/ipinfo", "state": "restarting" }
  ]
}
```

--------------------------------

### Build and preview the application

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/local-dev.mdx

Commands to build the UI and launch the preview server.

```bash
cd ui && npm run build && cd ..
npx @nimblebrain/synapse preview --server "uv run uvicorn mcp_myapp.server:app --port 8001" --ui ./ui
```

--------------------------------

### View Bundle Trust Score Configuration

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/using/managing-apps.mdx

Example of the JSON structure used to store the MTF trust score for an installed bundle.

```json
{
  "name": "@nimblebraininc/granola",
  "trustScore": 85
}
```

--------------------------------

### Initialize project directory

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/installation.mdx

Create and enter the directory for the NimbleBrain project.

```bash
mkdir nimblebrain && cd nimblebrain
```

--------------------------------

### Run Local Development Environment

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Set up the development environment using Bun, mpak, and Node.js 22+.

```bash
# Prerequisites: Bun (https://bun.sh), mpak CLI (https://mpak.dev), Node.js 22+
export ANTHROPIC_API_KEY=sk-ant-...

bun install
bun run dev
# API on http://localhost:27247 (auto-restarts on file changes)
# Web on http://localhost:27246 (Vite HMR, proxies /v1/* to :27247)
```

```bash
bun run dev:api
```

--------------------------------

### Implement Hello World with AppProvider

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/hello-world.mdx

Recommended approach for new applications using AppProvider and the connect API for an event-driven model.

```tsx
// ui/src/App.tsx
import { useState, useEffect } from "react";
import {
  AppProvider,
  useApp,
  useToolResult,
  useConnectTheme,
} from "@nimblebrain/synapse/react";

function HelloApp() {
  const [name, setName] = useState("");
  const [greeting, setGreeting] = useState("Type a name and click Greet.");
  const [count, setCount] = useState<number | null>(null);

  const app = useApp();
  const theme = useConnectTheme();

  // The latest tool result delivered by the host (agent-initiated calls).
  // `useToolResult()` takes no arguments and returns the most recent result.
  const lastResult = useToolResult();
  useEffect(() => {
    if (lastResult) setGreeting(String(lastResult.content));
  }, [lastResult]);

  async function greet() {
    const result = await app.callTool("get_greeting", { name: name.trim() });
    setGreeting(String(result.data));
    const countResult = await app.callTool("get_greet_count", {});
    setCount(Number(countResult.data));
  }

  return (
    <div style={{ maxWidth: 420, margin: "0 auto", padding: "2rem" }}>
      <h1>Hello 👋</h1>
      <div style={{ display: "flex", gap: "0.5rem" }}>
        <input
          value={name}
          onChange={(e) => setName(e.target.value)}
          onKeyDown={(e) => e.key === "Enter" && greet()}
          placeholder="Enter a name…"
        />
        <button onClick={greet}>
          Greet
        </button>
      </div>
      <div style={{ marginTop: "1rem" }}>{greeting}</div>
      {count !== null && <div>Greetings sent: {count}</div>}
    </div>
  );
}

export function App() {
  return (
    <AppProvider name="hello" version="0.1.0">
      <HelloApp />
    </AppProvider>
  );
}
```

--------------------------------

### Install workspace-scoped apps

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/using/workspaces.mdx

Install MCP bundles to a specific workspace to make tools available only to its members.

```text
Install @nimblebraininc/tasks in this workspace
```

--------------------------------

### GET /v1/auth/callback

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Handles the OAuth callback.

```APIDOC
## GET /v1/auth/callback

### Description
Handles the OAuth callback.

### Method
GET

### Endpoint
/v1/auth/callback
```

--------------------------------

### Implement Hello World with SynapseProvider

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/hello-world.mdx

Uses SynapseProvider for stable integration with tool calling and data synchronization hooks.

```tsx
// ui/src/App.tsx
import { useState } from "react";
import {
  SynapseProvider,
  useCallTool,
  useDataSync,
  useTheme,
} from "@nimblebrain/synapse/react";

function HelloApp() {
  const [name, setName] = useState("");
  const [greeting, setGreeting] = useState("Type a name and click Greet.");
  const [count, setCount] = useState<number | null>(null);

  const greetTool = useCallTool<string>("get_greeting");
  const countTool = useCallTool<string>("get_greet_count");
  const theme = useTheme();

  // Auto-refresh when the agent calls our tools
  useDataSync(() => refreshCount());

  async function refreshCount() {
    const result = await countTool.call({});
    setCount(Number(result.data));
  }

  async function greet() {
    const result = await greetTool.call({ name: name.trim() });
    setGreeting(String(result.data));
    refreshCount();
  }

  return (
    <div style={{ maxWidth: 420, margin: "0 auto", padding: "2rem" }}>
      <h1>Hello 👋</h1>
      <div style={{ display: "flex", gap: "0.5rem" }}>
        <input
          value={name}
          onChange={(e) => setName(e.target.value)}
          onKeyDown={(e) => e.key === "Enter" && greet()}
          placeholder="Enter a name…"
        />
        <button onClick={greet} disabled={greetTool.isPending}>
          Greet
        </button>
      </div>
      <div style={{ marginTop: "1rem" }}>{greeting}</div>
      {count !== null && <div>Greetings sent: {count}</div>}
    </div>
  );
}

export function App() {
  return (
    <SynapseProvider name="hello" version="0.1.0">
      <HelloApp />
    </SynapseProvider>
  );
}
```

--------------------------------

### GET /v1/auth/authorize

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Redirects the user for OAuth authorization.

```APIDOC
## GET /v1/auth/authorize

### Description
Redirects the user for OAuth authorization.

### Method
GET

### Endpoint
/v1/auth/authorize
```

--------------------------------

### GET /v1/health

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Performs a health check on the service.

```APIDOC
## GET /v1/health

### Description
Performs a health check on the service.

### Method
GET

### Endpoint
/v1/health
```

--------------------------------

### GET /v1/conversations/:id/events

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

SSE stream for per-conversation events.

```APIDOC
## GET /v1/conversations/:id/events

### Description
Provides a Server-Sent Events (SSE) stream for multi-participant chat events within a specific conversation.

### Method
GET

### Endpoint
/v1/conversations/:id/events

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the conversation.
```

--------------------------------

### Server startup commands

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/cli/serve.mdx

Basic commands to launch the NimbleBrain runtime and HTTP API server.

```bash
bun run start                            # simple case
bun run src/cli/index.ts serve [flags]   # explicit form (config / production)
```

```bash
bun run start
```

--------------------------------

### GET /v1/events

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Provides an SSE workspace event stream.

```APIDOC
## GET /v1/events

### Description
Provides an SSE workspace event stream.

### Method
GET

### Endpoint
/v1/events
```

--------------------------------

### GET /v1/files/:fileId

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Serves an uploaded file by its ID.

```APIDOC
## GET /v1/files/:fileId

### Description
Serves an uploaded file by its ID.

### Method
GET

### Endpoint
/v1/files/:fileId
```

--------------------------------

### GET /.well-known/oauth-protected-resource

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

MCP OAuth discovery endpoint (RFC 9728).

```APIDOC
## GET /.well-known/oauth-protected-resource

### Description
MCP OAuth discovery endpoint (RFC 9728).

### Method
GET

### Endpoint
/.well-known/oauth-protected-resource
```

--------------------------------

### GET /v1/shell

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Retrieves shell configuration including placements and endpoints.

```APIDOC
## GET /v1/shell

### Description
Retrieves shell configuration including placements and endpoints.

### Method
GET

### Endpoint
/v1/shell
```

--------------------------------

### Connect and interact with Synapse

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/synapse.mdx

Examples for integrating Synapse across different environments.

```typescript
import { connect } from '@nimblebrain/synapse';

const app = await connect({ name: 'my-app', version: '1.0.0' });

// Receive tool results from the host
app.on('tool-result', (data) => {
  console.log('Tool output:', data.content);
});

// Call tools on your app's MCP server
const result = await app.callTool('create_task', { title: 'Review Q2' });
console.log(result.data);
// { id: "tsk_01BXX...", title: "Review Q2", status: "active" }

// Tell the agent what the user sees
app.updateModelContext(
  { filter: 'overdue', selectedCount: 3 },
  'User is viewing 3 overdue tasks'
);

// Send a message into the conversation
app.sendMessage('Show me the Q2 report');
```

```tsx
import {
  AppProvider,
  useToolResult,
  useCallTool,
  useConnectTheme,
} from '@nimblebrain/synapse/react';

function App() {
  return (
    <AppProvider name="my-app" version="1.0.0">
      <TaskBoard />
    </AppProvider>
  );
}

function TaskBoard() {
  const result = useToolResult();
  const { call, isPending, data } = useCallTool('create_task');
  const theme = useConnectTheme();

  if (result) {
    console.log('Last tool result:', result.content);
  }

  return (
    <button
      onClick={() => call({ title: 'New task' })}
      disabled={isPending}
    >
      Create Task
    </button>
  );
}
```

```html
<script src="node_modules/@nimblebrain/synapse/dist/connect.iife.global.js"></script>
<div id="root">Loading...</div>
<script>
  Synapse.connect({
    name: 'my-widget',
    version: '1.0.0',
    autoResize: true,
  }).then(app => {
    app.on('tool-result', (data) => {
      document.getElementById('root').innerHTML = render(data.content);
    });
  });
</script>
```

--------------------------------

### Build the Application

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/hello-world.mdx

Command to build the application and generate the distribution file.

```bash
cd ui && npm run build
```

--------------------------------

### Run the runtime

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Commands to start the NimbleBrain runtime in production or development modes.

```bash
bun run start    # serve: HTTP API server (production)
bun run dev      # dev mode: API with file watching + web HMR
```

--------------------------------

### Session-miss error response

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/connect/mcp-endpoint.mdx

Example of the JSON-RPC error returned when a session is not found or unavailable.

```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Session not found",
    "data": { "reason": "not_found" }
  },
  "id": null
}
```

--------------------------------

### Verification and Build Commands

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/README.md

Commands for running tests, linting, and building the project using Bun.

```bash
bun install
bun run verify           # lint → typecheck → test → test:web → test:integration

# Or individually:
bun run test             # Unit + integration tests
bun run lint             # Biome linter
bun run check            # TypeScript strict mode

# Web client — build verification
cd web && bun install
bun run build            # TypeScript + Vite build → dist/

# Docker — validate configs
docker compose config    # Validate compose file
```

--------------------------------

### Create skills directory

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/using/skills.mdx

Initializes the directory where custom skill files are stored.

```bash
mkdir -p ~/.nimblebrain/skills
```

--------------------------------

### Resource Request Routing

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/ui-resources.mdx

Examples of how resource requests are mapped to specific application bundles.

```text
GET /v1/apps/home/resources/primary   → home bundle's ui:// resource
GET /v1/apps/files/resources/primary  → files bundle's ui:// resource
```

--------------------------------

### Resource Proxy Request

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/ui-resources.mdx

Example request to the resource proxy for a specific resource path.

```http
GET /v1/apps/synapse-crm/resources/crm/main
```

--------------------------------

### Build and Verify Commands

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/AGENTS.md

Use these Bun scripts to manage dependencies, run development servers, and execute verification suites.

```bash
bun install                # Install dependencies
bun run dev                # API (:27247) + Web (:27246) with watch/HMR
bun run dev:worktree       # Run from any worktree against an isolated workdir on alt ports — see "Worktree dev" below
bun run dev:api            # API only with auto-restart
bun run verify             # Full CI parity — runs every subscript below
bun run verify:static      # format:check + lint + check + check:cycles
bun run verify:test-unit   # test:unit + test:web + test:bundles

bun run test               # Unit then integration (stops at the first failing suite)
bun run test:unit          # Unit tests only (fast, ~10s)
bun run test:integration   # Integration tests only
bun run lint               # Biome linter
bun run format:check       # Biome format diff (no writes) — matches CI
bun run check              # TypeScript strict mode
bun run format             # Biome auto-format (writes)

cd web && bun install      # Web client dependencies (separate package.json)
cd web && bun run build    # Web production build → web/dist/

bun run install:bundles    # Bundle UI deps (each a separate package.json) — the exact command CI runs
bun run build:bundles      # Rebuild every src/bundles/*/ui (vite single-file)
```

--------------------------------

### User Message Event Structure

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/using/conversations.mdx

An example of a user message event appended to the conversation log.

```json
{
  "ts": "2026-03-25T10:30:00.000Z",
  "type": "user.message",
  "content": [{"type": "text", "text": "Summarize my meetings from this week"}]
}
```

--------------------------------

### Using custom configuration

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/cli/serve.mdx

Commands to specify a custom configuration file path or working directory.

```bash
bun run src/cli/index.ts serve --config /etc/nimblebrain/nimblebrain.json
```

```bash
NB_WORK_DIR=/opt/nimblebrain bun run src/cli/index.ts serve
```

--------------------------------

### connect()

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/synapse.mdx

Initializes the application connection and provides access to the theme object.

```APIDOC
## connect(options)

### Description
Initializes the connection to the Synapse host. Returns an App object that provides access to the current theme and event listeners.

### Parameters
- **options** (object) - Required - Configuration object containing `name` and `version`.

### Example
```typescript
const app = await connect({ name: 'my-app', version: '1.0.0' });
console.log(app.theme);
```
```

--------------------------------

### Accessing Multiple Resources via Proxy

Source: https://github.com/nimblebraininc/nimblebrain/blob/main/docs/src/content/docs/apps/ui-resources.mdx

Example requests for accessing different registered resources.

```http
GET /v1/apps/synapse-crm/resources/crm/main
GET /v1/apps/synapse-crm/resources/crm/settings
GET /v1/apps/synapse-crm/resources/crm/contact-detail
```