Skip to content
NimbleBrain NimbleBrain NimbleBrain

Managing Apps

Once a bundle is installed, NimbleBrain tracks its lifecycle from startup through crashes and recovery. You inspect bundles and control their lifecycle through the web UI and the agent (the manage_connectors tool).

Bundle states

Section titled “Bundle states”

Every installed bundle is in one of five states:

starting ──→ running ──→ crashed ──→ dead
                │                     │
                └──→ stopped ←────────┘
                        │
                        └──→ starting (explicit restart)
StateMeaning
startingMCP server process is being spawned
runningProcess is alive and responding to tool calls
crashedProcess exited unexpectedly. The health monitor will attempt automatic restart.
deadRestart attempts exhausted. Must be explicitly restarted.
stoppedManually stopped by you. Will not auto-restart.

Listing bundles and checking health

Section titled “Listing bundles and checking health”

In the web UI, every installed app and its current status (running, starting, crashed) appears on the workspace Settings → About tab, alongside its version and tool count. Each app’s uptime and restart count are shown there too.

You can also ask the agent — “Which apps are installed and are they all running?” — and it reports the configured bundles and their live health.

Starting and stopping bundles

Section titled “Starting and stopping bundles”

Ask the agent to control a bundle’s lifecycle:

“Stop the Granola app”

“Restart the Postgres app”

The agent uses manage_connectors to stop, start, and restart bundles. There is no REST endpoint or nb subcommand for start/stop.

Removing bundles

Section titled “Removing bundles”

Uninstall a bundle through the agent or the web UI:

“Uninstall the Granola app”

The agent uses manage_connectors (the uninstall action). There is no CLI command for this.

Uninstalling a bundle:

  1. Stops the MCP server process
  2. Removes the source from the tool registry
  3. Removes the entry from nimblebrain.json atomically
  4. Clears the bundle’s credential file for this workspace (best-effort; a failure logs a warning but doesn’t block the uninstall)
  5. Emits a bundle.uninstalled event

Every connector is user-removable — install and uninstall are symmetric for all bundle classes, with no exempt or pinned bundles. Bundle data (Upjack entity state, bundle-owned files under {workDir}/workspaces/{wsId}/data/{bundle}) is preserved. Only credentials are cleared. Credentials in other workspaces are untouched.

Trust scores

Section titled “Trust scores”

When a bundle is installed from mpak, NimbleBrain records its MTF (mpak Trust Framework) trust score. The score is a number from 0 to 100, stored in the bundle’s config entry and shown in the web client.

Trust scores are fetched via mpak info <name> --json at install time and stored in the bundle’s config entry:

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

Local and remote bundles do not have trust scores (they report null).

Credentials

Section titled “Credentials”

See Credentials for setting API keys and secrets. Short version: export the env var the bundle declares, or set it from workspace settings in the web UI.

Applying config changes

Section titled “Applying config changes”

After changing nimblebrain.json (adding, removing, or modifying bundle entries), restart the server to pick up the changes. In development, bun run dev restarts the API automatically on source changes. On the managed platform, configuration changes are applied for you by the platform.

What’s next

Section titled “What’s next”