npx nimblebrain
npx nimblebrain installs NimbleBrain on your machine from the release images, starts it, and connects your coding agent to it. Run it yourself in a terminal, or hand it to a coding agent: the same command works for both.
npx nimblebrainIt checks your machine, starts NimbleBrain in Docker at http://127.0.0.1:27246, asks whether NimbleBrain’s agents run on a hosted model (your API key) or a local one (see On a local model), and connects the coding agent you choose to a workspace over MCP. Run it again any time: on a machine that already has NimbleBrain it reports what is there and changes nothing.
You need Docker with Compose v2, about 2 GB of memory for Docker, and Node.js 20 or later. It runs on x86_64 and arm64, Apple Silicon included.
From a coding agent
Section titled “From a coding agent”Tell your agent:
Install NimbleBrain with
npx nimblebrain
An agent runs it with --yes --agent <its name> --json and reads the result. When no model key is set, everything else still starts, and the result says MODEL_KEY_MISSING. The agent then asks you to run npx nimblebrain key in your own terminal, so the key never passes through the agent.
The agent never decides whether usage data is sent. The result carries telemetry.state: "undecided" and the question to ask you; the agent runs npx nimblebrain telemetry on or off with your answer. See Telemetry.
Commands
Section titled “Commands”| Command | Does |
|---|---|
init (the default) |
Checks the machine, starts NimbleBrain, connects the agent named by --agent, and installs the nimblebrain skill for it. |
doctor |
Checks Docker, Compose v2, CPU architecture, memory and the port. Installs nothing. |
status |
Version, health, URL, each workspace’s MCP URL, the connected agent, whether a model key is set, and whether this release can reach a server on your machine (host_loopback). |
key |
Takes the model key at a hidden prompt and restarts NimbleBrain so it takes effect. A person runs this. |
local-model [model] |
Runs NimbleBrain’s agents on a model served by Ollama instead of a hosted key: prepares the model (default gemma4:e4b) and restarts NimbleBrain. See On a local model. |
up / down |
Starts or stops NimbleBrain. Your data survives down. |
logs |
Recent log lines from the runtime. |
update |
Moves to the newest NimbleBrain release, or the one --runtime names, keeping your data. It never moves backwards. |
uninstall |
Removes the containers, the images, every conversation, and the files init wrote. Asks first. |
telemetry [on|off|status] |
Whether this install sends anonymous usage data. Changing it needs NimbleBrain running. See Telemetry. |
mcp add <url> |
Adds an MCP server you run on this machine to a workspace, by its loopback URL. See Developing a server. |
mcp list |
The servers in a workspace: name, URL and status. |
mcp remove <serverName> |
Removes a server from a workspace. |
| Flag | Meaning |
|---|---|
--json |
One JSON object on stdout. Progress goes to stderr. |
--yes, -y |
Take every default. With no terminal attached, the CLI acts as if this were set and fails rather than wait for input. |
--agent <name> |
claude-code, cursor, codex or none. |
--port <n> |
The local port (default 27246). |
--provider <name> |
For key: anthropic (default), openai, google, greenpt, nebius or xai. |
--local-model <model> |
For init: run on this Ollama model instead of a hosted key, without asking. |
--home <dir> |
Where the install lives (default ~/.nimblebrain-local, or NIMBLEBRAIN_HOME). A home whose folder has another name is a separate install. See A second install. |
--runtime <tag> |
For init and update: the NimbleBrain release to install, such as v0.74.0. Default: the newest release. |
--telemetry <on|off> |
For init: your answer to sending anonymous usage data. Without it, init asks you, or, with no one at the terminal, leaves it undecided and sends nothing. |
--name <serverName> |
For mcp add: the name to add the server under. Default: the name in its Server Card, else the URL’s host and port. |
--workspace <id> |
For mcp: the workspace to act in. Default: the first workspace status lists, the one init connected your agent to. |
Versions
Section titled “Versions”The CLI and NimbleBrain are versioned separately. nimblebrain --version is the CLI’s own version; status reports both, the running NimbleBrain as version and the CLI as cli_version. The CLI installs the newest NimbleBrain release unless you name one with --runtime, and supports releases from v0.73.0. A newer NimbleBrain does not need a newer CLI: npx nimblebrain update moves you to the newest release.
Connecting an agent
Section titled “Connecting an agent”init --agent <name> registers the workspace’s MCP URL, http://127.0.0.1:27246/mcp/<workspaceId>, with the agent: through claude mcp add for Claude Code, codex mcp add for Codex, and ~/.cursor/mcp.json for Cursor. The local instance needs no login. If the agent’s own CLI is not installed, init still succeeds and returns manual: the exact command or setting to add by hand. An agent loads a new MCP server when its next session starts. status reports the skill as the agent has it now, read from the agent’s own skills folder, so a skill added later with npx skills add nimblebraininc/skills --skill nimblebrain --agent <agent> -g counts. Connecting an agent gives it NimbleBrain’s tools; it does not change the model NimbleBrain runs on. NimbleBrain’s own agents run on the model key you entered, billed by that provider, or on the local model you chose.
To connect another client by hand, take the MCP URL from npx nimblebrain status and follow Connecting External Clients.
Developing a server
Section titled “Developing a server”The loop for building an MCP server against your local NimbleBrain:
-
Run your server over HTTP on
127.0.0.1, for example athttp://127.0.0.1:8000/mcp. -
Add it, once:
Terminal window npx nimblebrain mcp add http://127.0.0.1:8000/mcp -
Ask the agent in the workspace to use it. Restart your server as often as you like; NimbleBrain reconnects at the same URL, and the server stays added across
down,upandupdate.
NimbleBrain reads the server’s Server Card at <url>/server-card for its title, description, icon and sidebar placements (Host manifest). Without a card, the server is named from its URL unless you pass --name, shown under the name it reports when it connects, and gets no placements. The server need not be running when you add it: the answer then carries a warning, and it connects once you start it and reconnect it from the Connectors page.
{"ok": true, "serverName": "notes", "url": "http://127.0.0.1:8000/mcp", "dialed": "http://host.docker.internal:8000/mcp", "placements": [], "wsId": "ws_..."}url is the URL as you gave it, and dialed is where NimbleBrain, inside Docker, connects: the same port and path on host.docker.internal, the name Docker gives your machine. Only localhost, 127.0.0.1 and ::1 URLs are accepted, and only on an install made by npx nimblebrain. An install from before this feature reports host_loopback: false in status, and mcp add answers UPDATE_REQUIRED until you run npx nimblebrain update.
The JSON
Section titled “The JSON”Every command answers {"ok": true, ...} or {"ok": false, "error": "<CODE>", "message": "...", "fix": "..."}. The exit code is 0 when ok is true, 1 when it is false, and 2 for an unknown command or flag. The model key never appears in any output.
error |
Means |
|---|---|
DOCKER_MISSING, DOCKER_NOT_RUNNING, DOCKER_PERMISSION, COMPOSE_MISSING |
Docker is missing, stopped, not usable by this user, or lacks Compose v2. |
ARCH_UNSUPPORTED, LOW_MEMORY, PORT_IN_USE |
No image for this CPU, under 2 GB for Docker, or the port is taken. |
NOT_INSTALLED, NOT_OURS |
No install here, or files, containers or data this CLI did not make are in the way. |
NETWORK, START_FAILED, HEALTH_TIMEOUT |
A download failed, Compose could not start it, or it did not become healthy in time. |
MODEL_KEY_MISSING |
NimbleBrain is running; chat needs a key (npx nimblebrain key). |
NEEDS_TERMINAL, CANCELLED, AGENT_UNSUPPORTED, USAGE |
key needs a person, the action was declined, an unknown agent, or a bad command or flag. |
RUNTIME_UNSUPPORTED |
The release --runtime names is older than this CLI supports, or its Compose file cannot be driven. |
LOCAL_MODEL_UNREACHABLE, LOCAL_MODEL_MISSING, LOCAL_MODEL_NO_TOOLS, LOCAL_CONTEXT_SMALL |
Ollama does not answer, the model is not on it (or its download was declined or failed), the model cannot call tools, or its context window is below the 32k NimbleBrain needs. |
INTERRUPTED |
The CLI was stopped (a signal, Ctrl-C) before it finished; exit_code says how. Check status, then run the command again. |
NOT_RUNNING |
The command needs NimbleBrain running (telemetry on/off, every mcp command); run npx nimblebrain up. |
UPDATE_REQUIRED |
mcp add on a release that cannot reach your machine; run npx nimblebrain update. |
WORKSPACE_NOT_FOUND, SERVER_NOT_FOUND |
No such workspace (the answer lists the ones there are in workspaces), or no server by that name in it. |
URL_INVALID, URL_NOT_LOOPBACK |
The URL is not an http/https URL NimbleBrain accepts, or is not on this machine. |
INVALID_SERVER_NAME, NAME_TAKEN, NAME_IS_CATALOG_ENTRY |
The name cannot name a server, the workspace already has one by that name, or a catalog connector owns it. Pass another --name. |
DIRECT_URL_NOT_ALLOWED |
The instance is not a local install with the dev sign-in, so it adds servers only from its catalog. |
REQUEST_FAILED |
NimbleBrain refused the request for another reason; message carries its text. |
Each error’s fix is the next thing to do.
On a local model
Section titled “On a local model”NimbleBrain’s agents can run on a model served by Ollama on this machine, with no key and no per-call cost. Install Ollama and start it, then answer local when init asks, or run:
npx nimblebrain --local-model gemma4:e4b # a new installnpx nimblebrain local-model gemma4:e4b # an install that has one alreadyThe CLI checks that Ollama answers on 127.0.0.1:11434, downloads the model if it is missing (it asks first), refuses a model that cannot call tools, and creates nimblebrain-<model> from it: the same model with a 32k context window, so Ollama never picks a smaller one and cuts the prompt. It then writes NB_LOCAL_MODEL_URL, NB_LOCAL_MODEL and NB_LOCAL_MODEL_CONTEXT to .env, and the runtime reaches Ollama at host.docker.internal. doctor checks all of this again, and status reports local_model.
Gemma 4 E4B is the smallest model run end to end on NimbleBrain’s tasks (reliable on everyday ones, partial on scheduled tasks); Local Models lists what has been tested, what failed, and what has not been tried. It needs about 7 GB of memory beside NimbleBrain’s 2 GB. On Linux, Ollama listens on 127.0.0.1 by default, which a container cannot reach: set OLLAMA_HOST=0.0.0.0. This needs a NimbleBrain release that takes a local model; an older one answers RUNTIME_UNSUPPORTED.
A second install
Section titled “A second install”Each home is its own install: its own containers, data volume and port. The Compose project takes the home folder’s name, so ~/.nimblebrain-local stays nimblebrain-local and ~/nb-rc becomes nimblebrain-nb-rc. To try a release candidate beside the NimbleBrain you use every day:
npx nimblebrain init --home ~/nb-rc --port 27300 --runtime vX.Y.Z-rc.N --agent nonenpx nimblebrain status --home ~/nb-rcnpx nimblebrain uninstall --home ~/nb-rc --yesPass the same --home to every command for that install. The name is chosen once, at init, so moving the folder later changes nothing. Two homes whose folders share a name would share a project; the second init refuses with NOT_OURS. An agent has one nimblebrain server, so --agent on the second install points that agent at it instead of the first, and that install’s uninstall removes the registration; --agent none leaves your agent on the first.
What it writes
Section titled “What it writes”Everything lives in ~/.nimblebrain-local: the installed release’s docker-compose.yml, downloaded from that release, an instance.json naming the dev sign-in, a .env that only your user can read (the release, the port, and your model key or local model), and install.json. Your conversations live in the Docker volume nimblebrain-local_workspace, named after the install’s Compose project, which install.json and .env record. A key exported in your shell is not used: .env is the only source, so the key you entered with key is the one that runs.