Installation

Docker Compose
Development (Bun)

Docker Compose runs the platform and web UI as two containers. This is the recommended method for single-machine deployments.

Create a project directory
Terminal window
```
mkdir nimblebrain && cd nimblebrain
```

Create nimblebrain.json

{
  "$schema": "https://schemas.nimblebrain.ai/nimblebrain.json",
  "bundles": [
    { "name": "@nimblebraininc/bash" }
  ]
}

Create docker-compose.yml

services:
  platform:
    image: nimblebrain/platform:latest
    restart: unless-stopped
    volumes:
      - workspace:/data
      - ./nimblebrain.json:/app/nimblebrain.json:ro
      - ./skills:/app/skills:ro
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      - GOOGLE_GENERATIVE_AI_API_KEY=${GOOGLE_GENERATIVE_AI_API_KEY:-}
      - NB_API_KEY=${NB_API_KEY}

  web:
    image: nimblebrain/web:latest
    restart: unless-stopped
    ports:
      - "27246:8080"
    environment:
      - PLATFORM_URL=http://platform:27247
    depends_on:
      platform:
        condition: service_healthy

volumes:
  workspace:

The platform image is based on oven/bun:1.3-alpine and includes Python 3.13, Node.js, and the mpak CLI for running MCP server bundles.

Start the services
Terminal window
```
export ANTHROPIC_API_KEY=sk-ant-api03-...
export NB_API_KEY=my-secret-key-at-least-8-chars
docker compose up
```
The platform API runs on port 27247 (internal). The web UI is exposed on port 27246.

Run from source for development. Requires Bun 1.1+.

Clone and install

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

Install web dependencies
Terminal window
```
cd web && bun install && cd ..
```

Set your API key

export ANTHROPIC_API_KEY=sk-ant-api03-...

Start development mode
Terminal window
```
bun run dev
```
```
[api] NimbleBrain API listening on http://127.0.0.1:27247
[web] VITE v6.x  ready in 200ms
[web]   ➜  Local:   http://localhost:27246/
```
This starts both the API server (with file watching and auto-restart) and the web client (with Vite HMR) in a single terminal. Output is prefixed [api] / [web].

The development workdir is .nimblebrain/ (project-local). No NB_API_KEY is required in dev mode — CORS is open.

Other dev commands:

bun run dev:api    # API server only (watched, port 27247)
bun run dev:web    # Web client only (Vite HMR, port 27246)
bun run dev:empty  # Empty state — default bundles only, fresh workdir (:27249/:27248)
bun run dev:minimal # Minimal — default bundles, no external MCPs (:27251/:27250)
bun run dev:tui    # Interactive TUI with project-local workdir
bun run test       # Run unit tests
bun run verify     # Full CI: lint → typecheck → test → smoke

Environment variables

Variable	Required	Description
`ANTHROPIC_API_KEY`	Yes	Your Anthropic API key for Claude
`NB_API_KEY`	Production	API authentication key (min 8 characters). When unset, CORS allows all origins (dev mode)
`NB_WORK_DIR`	No	Working directory for runtime state. Default: `~/.nimblebrain`
`NB_HOST`	No	Host to bind the API server. Default: `127.0.0.1` (`0.0.0.0` in Docker)
`ALLOWED_ORIGINS`	No	Comma-separated allowed CORS origins for cookie-based auth
`NB_TELEMETRY_DISABLED`	No	Set to `1` to disable anonymous telemetry
`DO_NOT_TRACK`	No	Set to `1` to disable anonymous telemetry

Minimal config file

NimbleBrain reads nimblebrain.json at startup. Config resolution order:

--config <path> flag (explicit path)
--workdir <dir> flag resolves to <dir>/nimblebrain.json
./nimblebrain.json (current working directory)
~/.nimblebrain/nimblebrain.json (global fallback)

A minimal config:

{
  "$schema": "https://schemas.nimblebrain.ai/nimblebrain.json",
  "bundles": [
    { "name": "@nimblebraininc/bash" }
  ]
}

See the configuration reference for all options.

What’s next

Core Concepts Agent loop, bundles, skills, tools, conversations

nimblebrain.json Reference Full configuration file reference

Docker Deployment Production Docker Compose configuration