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-...
bun run start

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, set them from workspace settings in the web UI. Stdio bundles that declare user_config fields surface those fields on the app’s Configure page; saving a value writes it to the workspace credential store.

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.

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 from workspace settings in the web UI.
  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 the exact env vars the bundle accepts; set anything else from workspace settings in the web UI.

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.
Set it in workspace settings, or export:
  export ANTHROPIC_API_KEY=<value>  # satisfies "anthropic_api_key"

Export the env var if it fits your workflow. If no export line appears, the bundle didn’t declare an env alias for that field — set it from workspace settings in the web UI.

Section titled “Related”