nimblebrain.json

NimbleBrain reads its configuration from a single nimblebrain.json file. This page documents every field, the resolution order, and validation behavior.

Config resolution

NimbleBrain looks for the config file in this order, stopping at the first match:

1. --config <path> — Explicit path passed as a CLI flag
2. --workdir <dir>/nimblebrain.json — Inside the working directory (flag or NB_WORK_DIR env var)
3. ./nimblebrain.json — Current working directory

If no config file exists at the resolved path, NimbleBrain auto-creates a default one (empty bundles and skills) as long as the parent directory exists.

Tip

The nb dev command defaults its working directory to ./.nimblebrain (project-local), while nb serve and nb default to ~/.nimblebrain (global). You can override either with --workdir.

Complete annotated example

{
  "$schema": "https://schemas.nimblebrain.ai/nimblebrain.json",
  "version": "1",
  "model": {
    "provider": "anthropic",
    "apiKey": "sk-ant-..."
  },
  "defaultModel": "claude-sonnet-4-5-20250929",
  "maxIterations": 10,
  "maxInputTokens": 500000,
  "maxOutputTokens": 16384,
  "bundles": [
    { "name": "@nimblebraininc/tasks" },
    { "path": "../mcp-servers/hello" },
    {
      "url": "https://mcp.example.com/mcp",
      "serverName": "example",
      "transport": {
        "type": "streamable-http",
        "auth": { "type": "bearer", "token": "sk-..." }
      }
    }
  ],
  "noDefaultBundles": false,
  "skillDirs": ["./skills", "/opt/nimblebrain/skills"],
  "skills": [],
  "store": {
    "type": "jsonl",
    "dir": "~/.nimblebrain/conversations"
  },
  "logging": {
    "dir": "~/.nimblebrain/logs",
    "disabled": false
  },
  "http": {
    "port": 3000,
    "host": "127.0.0.1"
  },
  "agents": {
    "researcher": {
      "description": "Deep research agent with search tools",
      "systemPrompt": "You are a research agent. Use search tools to find information.",
      "tools": ["rfpsearch__*", "nb__*"],
      "maxIterations": 8,
      "model": "claude-sonnet-4-5-20250929"
    }
  },
  "workDir": "~/.nimblebrain",
  "telemetry": {
    "enabled": true
  },
  "home": {
    "enabled": true,
    "userName": "Mat",
    "timezone": "Pacific/Honolulu",
    "cacheTtlMinutes": 30,
    "model": null
  }
}

Top-level fields

Field	Type	Default	Description
$schema	string	—	JSON Schema URI. Set to "https://schemas.nimblebrain.ai/nimblebrain.json" for editor autocompletion.
version	string	—	Config file version. Must be "1".
model	object	{ "provider": "anthropic" }	Model provider configuration. See model.
defaultModel	string	"claude-sonnet-4-5-20250929"	Default model ID for agent requests.
maxIterations	integer	10	Max agentic iterations per request. Range: 1—25.
maxInputTokens	integer	500000	Max input tokens per request. The engine stops when this budget is exceeded.
maxOutputTokens	integer	16384	Max output tokens per LLM call.
bundles	array	[]	MCP bundles to spawn. See Bundle Configuration.
noDefaultBundles	boolean	false	Skip default bundles (e.g., @nimblebraininc/bash).
skillDirs	string[]	[]	Directories to scan for skill markdown files.
skills	array	[]	Inline skill definitions.
store	object	{ "type": "memory" }	Conversation storage backend. See store.
logging	object	{ "disabled": false }	Structured logging config. See Logging.
http	object	{ "port": 3000, "host": "127.0.0.1" }	HTTP server config. Omit for programmatic-only use.
agents	object	{}	Named agent profiles for delegation. See Agent Profiles.
workDir	string	"~/.nimblebrain"	Working directory for runtime state (conversations, logs, cache).
telemetry	object	{ "enabled": true }	Anonymous usage telemetry. See telemetry.
home	object	{ "enabled": true }	Home dashboard configuration. See home.

model

Configure the LLM provider. Only "anthropic" is supported in the config file.

{
  "model": {
    "provider": "anthropic",
    "apiKey": "sk-ant-..."
  }
}

Field	Type	Required	Description
provider	string	Yes	Must be "anthropic".
apiKey	string	No	Anthropic API key. Falls back to the ANTHROPIC_API_KEY environment variable.

Caution

Avoid putting API keys directly in the config file. Use the ANTHROPIC_API_KEY environment variable instead, especially in production.

store

Choose where conversations are persisted.

JSONL (file-based)

{
  "store": {
    "type": "jsonl",
    "dir": "~/.nimblebrain/conversations"
  }
}

The CLI defaults to JSONL storage with conversations in {workDir}/conversations/.

In-memory

{
  "store": {
    "type": "memory"
  }
}

Conversations are lost when the process exits. This is the default for programmatic use.

Field	Type	Required	Description
type	"jsonl" | "memory"	Yes	Storage backend.
dir	string	JSONL only	Directory for conversation JSONL files.

telemetry

Control anonymous usage telemetry. NimbleBrain collects anonymized, aggregate usage data with no PII — no bundle names, tool names, error messages, or file paths are sent.

{
  "telemetry": {
    "enabled": false
  }
}

You can also disable telemetry with the NB_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1 environment variables, or with nb telemetry off. Any of these methods takes effect immediately.

home

Configure the Home dashboard — a personalized activity briefing shown on the landing page.

{
  "home": {
    "enabled": true,
    "userName": "Mat",
    "timezone": "Pacific/Honolulu",
    "cacheTtlMinutes": 30,
    "model": null
  }
}

Field	Type	Default	Description
enabled	boolean	true	Enable the Home dashboard. When false, / redirects to /chat.
userName	string	"there"	Your first name for the greeting (e.g., “Good morning, Mat”).
timezone	string	"" (system)	IANA timezone for time-aware greetings (e.g., "Pacific/Honolulu"). Empty string uses the system timezone.
cacheTtlMinutes	number	30	How long to cache the briefing before regenerating. Minimum: 1.
model	string | null	null	Model override for briefing generation. null uses the workspace default.

Validation

NimbleBrain validates nimblebrain.json at startup against a JSON Schema (draft-07) using AJV.

• Unknown keys produce a warning to stderr and are ignored.
• Structural errors (wrong types, missing required fields) throw an error and prevent startup.

[config] Warning: unknown key "foo" in /home/user/.nimblebrain/nimblebrain.json (ignored)

Error: Invalid config in /home/user/.nimblebrain/nimblebrain.json:
  - /maxIterations: must be integer

CLI flag overrides

CLI flags take precedence over values in the config file:

Flag	Overrides
--config <path>	Config file location
--workdir <dir>	workDir field and config file location
--model <id>	defaultModel field
--port <n>	http.port field
--debug	Enables verbose debug event logging

Minimal config

The smallest valid config file:

{
  "$schema": "https://schemas.nimblebrain.ai/nimblebrain.json",
  "version": "1",
  "bundles": [],
  "skills": []
}

This uses all defaults: Anthropic provider (key from ANTHROPIC_API_KEY), default model, the @nimblebraininc/bash default bundle, in-memory conversation storage, and structured logging enabled.