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/ipinfo (named)
  @nimblebraininc/granola (named)
  ../mcp-servers/hello (local)

For JSON output:

nb bundle list --json

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

API

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

{
  "apps": [
    {
      "name": "ipinfo",
      "bundleName": "@nimblebraininc/ipinfo",
      "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/ipinfo
  @nimblebraininc/granola
  @nimblebraininc/postgres

Skills: 2 loaded

Bundle health:
  ipinfo: 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": "ipinfo", "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_app 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. Clears the bundle’s credential file for this workspace (best-effort; a failure logs a warning but doesn’t block the uninstall)
6. Emits a bundle.uninstalled event

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.

Protected bundles

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

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

Attempting to uninstall a protected bundle produces an error:

Cannot uninstall "ipinfo": 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).

Credentials

See Credentials for setting API keys and secrets. Short version: export the env var the bundle declares, or run nb config set <bundle> <key>=<value> -w <wsId>.

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