Installing Apps

Tip

Looking for a quick overview of apps in the web UI? See Apps & the Sidebar in the User Guide.

Apps in NimbleBrain are MCP server bundles. Each bundle provides tools that the agent can use. You can install bundles from the mpak registry, from a remote URL, or from a local directory.

Three ways to install

CLI

From the mpak registry

1. Search for a bundle:

   nb bundle search granola

   Searching mpak registry for "granola"...
   Run: mpak search "granola"

2. Add it to your config:

   nb bundle add @nimblebraininc/granola

   Added "@nimblebraininc/granola" to config. Run nb reload to activate.

3. Reload to activate:

   nb reload

   Reload signal sent. Running runtime will pick up changes.

From a remote URL

nb bundle add --url https://mcp.example.com/mcp --name my-server

Added remote "my-server" (https://mcp.example.com/mcp) to config. Run nb reload to activate.

For authenticated remote servers:

nb bundle add --url https://mcp.example.com/mcp --name my-server --auth bearer --token sk-abc123

Web UI

In the web UI, the agent can install bundles for you. Ask it directly:

“Install the Granola bundle from mpak”

The agent uses nb__manage_app to install the bundle, which:

1. Downloads it from mpak
2. Reads the manifest
3. Starts the MCP server process
4. Records the trust score
5. Writes the config entry atomically

Config file

Edit nimblebrain.json directly. Each entry needs one of name, path, or url:

{
  "bundles": [
    { "name": "@nimblebraininc/granola" },
    { "path": "../mcp-servers/hello" },
    {
      "url": "https://mcp.example.com/mcp",
      "serverName": "my-server",
      "transport": {
        "auth": { "type": "bearer", "token": "sk-abc123" }
      }
    }
  ]
}

After editing, run nb reload or restart the server.

Bundle types

Type	Config field	How it resolves
Named (mpak)	name	Downloads via mpak install, cached at ~/.mpak/cache/
Local	path	Reads manifest.json from the directory. Path resolved relative to the config file.
Remote	url	Connects directly via HTTP transport (streamable-http or SSE). No download.

The agent can self-install

The agent has access to nb__search (with scope: "registry") and nb__manage_app. This means you can ask it to find and install what it needs:

“I need to search through meeting notes. Find a bundle for that and install it.”

The agent will:

1. Call nb__search with scope: "registry" to search mpak
2. Present options to you
3. Call nb__manage_app with action: "install" to install your choice

Caution

Bundles marked as protected: true in the config cannot be uninstalled via nb__manage_app. Use this for bundles that should always be available.

Setting bundle credentials

Most bundles need API keys or tokens. In most cases, exporting the env var the bundle already looks for is enough:

export ANTHROPIC_API_KEY=sk-ant-...

For workspace-scoped values or when env vars aren’t a good fit, use nb config set -w <wsId>. See Credentials for the full picture.

Passing non-credential environment variables

Sensitive values belong in Credentials. For non-secret env vars (log level, region, connection tuning), use the env field on the bundle entry:

{
  "bundles": [
    {
      "name": "@nimblebraininc/postgres",
      "env": {
        "PG_MAX_CONNECTIONS": "10",
        "PG_STATEMENT_TIMEOUT": "30000"
      }
    }
  ]
}

Values in env merge with the bundle’s own mcp_config.env and the filtered process environment; env takes precedence.

Verify the install

After installing, check that the bundle is running:

nb status

Bundles: 2 configured
  @nimblebraininc/granola
  @nimblebraininc/postgres

Skills: 2 loaded

Bundle health:
  granola: running (uptime: 120s, restarts: 0)
  postgres: running (uptime: 120s, restarts: 0)

What’s next

• Managing Apps — start, stop, and monitor installed bundles
• Chat — start using your newly installed apps
• Configuration: Bundles — full config reference for bundle entries