Managing Apps

Once a bundle is installed, NimbleBrain tracks its lifecycle from startup through crashes and recovery. You can start, stop, and inspect bundles through the CLI, API, or web UI.

Bundle states

Every installed bundle is in one of five states:

starting ──→ running ──→ crashed ──→ dead
                │                     │
                └──→ stopped ←────────┘
                        │
                        └──→ starting (explicit restart)

State	Meaning
starting	MCP server process is being spawned
running	Process is alive and responding to tool calls
crashed	Process exited unexpectedly. The health monitor will attempt automatic restart.
dead	Restart attempts exhausted. Must be explicitly restarted.
stopped	Manually stopped by you. Will not auto-restart.

Note

A crashed bundle transitions to dead after the health monitor exhausts its restart attempts. A dead bundle must be explicitly restarted — it will not recover on its own.

Listing bundles

CLI

nb bundle list

Configured bundles:

  @nimblebraininc/bash (named)
  @nimblebraininc/granola (named)
  ../mcp-servers/hello (local)

For JSON output:

nb bundle list --json

[{"name":"@nimblebraininc/bash"},{"name":"@nimblebraininc/granola"},{"path":"../mcp-servers/hello"}]

API

curl http://localhost:27247/v1/apps

{
  "apps": [
    {
      "name": "bash",
      "bundleName": "@nimblebraininc/bash",
      "version": "0.3.0",
      "status": "running",
      "type": "plain",
      "toolCount": 1,
      "trustScore": 95,
      "ui": null
    }
  ]
}

Checking health

The nb status command shows live health data when the server is running:

nb status

Bundles: 3 configured
  @nimblebraininc/bash
  @nimblebraininc/granola
  @nimblebraininc/postgres

Skills: 2 loaded

Bundle health:
  bash: running (uptime: 7200s, restarts: 0)
  granola: running (uptime: 7200s, restarts: 0)
  postgres: crashed (uptime: n/a, restarts: 3)

The health endpoint is also available unauthenticated:

curl http://localhost:27247/v1/bundles/health

[
  {"name": "bash", "state": "running", "uptime": 7200000, "restartCount": 0},
  {"name": "granola", "state": "running", "uptime": 7200000, "restartCount": 0},
  {"name": "postgres", "state": "crashed", "uptime": null, "restartCount": 3}
]

Starting and stopping bundles

API

Stop a running bundle:

curl -X POST http://localhost:27247/v1/apps/granola/stop

Start a stopped or dead bundle:

curl -X POST http://localhost:27247/v1/apps/granola/start

Web UI

Ask the agent:

“Stop the Granola app”

“Restart the Postgres app”

The agent uses nb__manage_bundle to control bundle lifecycle.

Tip

Stopping a bundle kills its MCP server process but keeps it registered. Its tools become unavailable until you start it again. The bundle’s data is not deleted.

Removing bundles

CLI

nb bundle remove @nimblebraininc/granola

Removed "@nimblebraininc/granola" from config. Run nb reload to apply.

API

curl -X DELETE http://localhost:27247/v1/apps/granola

Uninstalling a bundle:

1. Checks the protected flag — rejects if protected
2. Stops the MCP server process
3. Removes the source from the tool registry
4. Removes the entry from nimblebrain.json atomically
5. Emits a bundle.uninstalled event

Data is not deleted during uninstall.

Protected bundles

Mark a bundle as protected in nimblebrain.json to prevent removal via nb__manage_bundle or the API:

{
  "bundles": [
    {
      "name": "@nimblebraininc/bash",
      "protected": true
    }
  ]
}

Attempting to uninstall a protected bundle produces an error:

Cannot uninstall "bash": bundle is protected

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 config and available in the GET /v1/apps response.

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).

Configuration

Set per-bundle config values (typically API keys):

nb config set @nimblebraininc/granola api_key=grn_abc123

View current config:

nb config get @nimblebraininc/granola

api_key: gr****

Values are stored in ~/.mpak/config.json with 0600 permissions. See Installing Apps for details.

Hot-reloading

After changing nimblebrain.json (adding, removing, or modifying bundle entries), signal the running server to reload:

nb reload

Reload signal sent. Running runtime will pick up changes.

This writes a timestamp to ~/.nimblebrain/.reload. The running runtime watches for this sentinel and reloads bundles and skills without restarting the process.

What’s next

• Installing Apps — add new bundles
• Skills — control which tools the agent uses per-request
• Configuration: Bundles — full config reference