Skip to content
NimbleBrain NimbleBrain NimbleBrain

Credentials

Bundles usually need secrets — an Anthropic API key, a GitHub token, a Postgres connection string. The simplest thing that works is exporting the env var the bundle already looks for.

Set a credential

Section titled “Set a credential”

Export the env var

Section titled “Export the env var”

If you already have the relevant secret in your shell, start NimbleBrain and you’re done:

Terminal window
export ANTHROPIC_API_KEY=sk-ant-...
nb serve

This works because the bundle’s manifest declares the mapping between its user_config field and the env var it spawns with:

"mcp_config": {
  "env": { "ANTHROPIC_API_KEY": "${user_config.anthropic_api_key}" }
}

The resolver reads that declaration in both directions. At spawn time it fills ANTHROPIC_API_KEY on the child process from the resolved field. At resolve time, if your host already has ANTHROPIC_API_KEY set, it satisfies the field. Well-authored bundles use industry-standard names, so one export usually covers every workspace.

Store it per-workspace

Section titled “Store it per-workspace”

When you need different credentials per workspace, or env vars aren’t a good fit:

Terminal window
nb config set @nimblebraininc/webfetch anthropic_api_key=sk-ant-... -w ws_acme

The value lands in {workDir}/workspaces/{wsId}/credentials/{bundle-slug}.json with 0o600 permissions under a 0o700 directory. The slug is the bundle name with the leading @ stripped and / replaced by - — e.g. @nimblebraininc/webfetch becomes nimblebraininc-webfetch.json.

See nb config for get and clear.

Manifest default

Section titled “Manifest default”

Bundle authors can ship a default for non-secret fields like region codes or base URLs:

"user_config": {
  "region": { "type": "string", "default": "us-east-1" }
}

Never ship a secret as a default.

How resolution works

Section titled “How resolution works”

For each user_config field the resolver walks three tiers. First non-empty value wins:

  1. Workspace credential store — the file written by nb config set -w <wsId>.
  2. Host env alias — the env var declared by the bundle’s mcp_config.env.
  3. Manifest default — the field’s default.

If a required field is still unresolved, startup fails with an error listing both the nb config set command and the exact env vars the bundle accepts.

When things go wrong

Section titled “When things go wrong”

Missing required config on startup

Section titled “Missing required config on startup”
Missing required config "Anthropic API Key" for @nimblebraininc/webfetch.
Run one of:
  nb config set @nimblebraininc/webfetch anthropic_api_key=<value> -w ws_acme
  export ANTHROPIC_API_KEY=<value>  # satisfies "anthropic_api_key"

Pick whichever line fits your workflow. If no export line appears, the bundle didn’t declare an env alias for that field — use nb config set.

Section titled “Related”