brokr 1.5.0

Local credential broker for AI agents with per-agent secret scoping.

brokr

Local credential broker for AI agents — scoped secret access per agent, no cloud required.

Your deploy bot shouldn't have access to your database password. brokr lets you control which agent can use which credential, locally, with zero cloud dependency.

pip install brokr
brokr init
brokr set OPENAI_API_KEY
brokr set GITHUB_TOKEN
brokr project init my-app
brokr project add OPENAI_API_KEY
brokr agent add deploy-bot
brokr grant deploy-bot OPENAI_API_KEY
brokr run --as deploy-bot -- python deploy.py
# ^ only OPENAI_API_KEY is injected. Nothing else.

Why brokr?

	.env files	brokr
Encrypted at rest	No	Yes (AES-256-GCM)
Per-agent scoping	No — everything sees everything	Yes — grant specific secrets per agent
Git-safe	Gets committed constantly	Nothing to commit
Per-project association	.env, .env.local, .env.prod...	One store, project-scoped injection
Works with any language	Needs dotenv library	Injects env vars natively

Install

pip install brokr

Requires Python 3.10+.

Quickstart

# 1. Create your encrypted store
brokr init

# 2. Store secrets
brokr set OPENAI_API_KEY
brokr set GITHUB_TOKEN
brokr set DB_URL --value "postgres://localhost/mydb"

# 3. Run with all secrets injected
brokr run -- python app.py

Inside app.py, read env vars as usual:

import os
key = os.environ["OPENAI_API_KEY"]

Project Scoping

Associate secrets with specific projects. brokr run in a project directory injects only that project's secrets.

cd ~/my-app
brokr project init my-app       # creates .brokr file (add to .gitignore)
brokr project add OPENAI_API_KEY
brokr project add DB_URL
brokr run -- python app.py      # only OPENAI_API_KEY and DB_URL injected

Agent Scoping

Control which agent gets which secrets. The LLM orchestrating the agent never sees raw values — brokr is an opaque broker.

brokr agent add deploy-bot
brokr agent add research-agent
brokr grant deploy-bot GITHUB_TOKEN
brokr grant research-agent OPENAI_API_KEY

brokr run --as deploy-bot -- python deploy.py
# ^ only GITHUB_TOKEN injected

brokr run --as research-agent -- python research.py
# ^ only OPENAI_API_KEY injected

CLI Reference

# Store management
brokr init                              # Create encrypted store (~/.brokr)
brokr set KEY_NAME                      # Store a secret (prompts for value)
brokr set KEY_NAME --value "sk-..."     # Store inline
brokr get KEY_NAME                      # Print to stdout
brokr list                              # List keys (masked)
brokr list --show                       # List keys (revealed)
brokr rm KEY_NAME                       # Remove (cascades to projects/agents)

# Project management
brokr project init <name>               # Register project, create .brokr file
brokr project add <SECRET>              # Link secret to current project
brokr project rm <SECRET>               # Unlink (cascades to agent grants)
brokr project list                      # List all projects (or current project's secrets)
brokr project show                      # Show current project details

# Agent management
brokr agent add <name>                  # Create agent in current project
brokr agent rm <name>                   # Remove agent and its grants
brokr agent list                        # List agents in current project
brokr grant <agent> <secret>            # Grant secret to agent
brokr revoke <agent> <secret>           # Revoke grant

# Run with injection
brokr run -- <command>                  # Inject secrets as env vars
brokr run --as <agent> -- <command>     # Inject only agent's granted secrets
brokr run --only KEY1,KEY2 -- <cmd>     # Inject only specific keys

# Maintenance
brokr doctor                            # Health check (permissions, refs, projects)
brokr passwd                            # Change passphrase
brokr export                            # Export as KEY="value" to stdout
brokr export --format json              # Export as JSON to stdout
brokr --version                         # Show version

SDK

from brokr import get

# Basic (returns any secret)
api_key = get("OPENAI_API_KEY")

# Project-scoped (must be linked to project)
api_key = get("OPENAI_API_KEY", project="my-app")

# Agent-scoped (must be granted to agent)
token = get("GITHUB_TOKEN", agent="deploy-bot", project="my-app")
# Raises PermissionError if not granted

How it works

brokr derives an encryption key from your passphrase using scrypt, then encrypts all secrets with AES-256-GCM. Everything lives in a single file at ~/.brokr/store.enc with 0600 permissions. Projects and agent grants are stored in the same encrypted blob. The passphrase never touches disk.

License

MIT — see LICENSE.