# 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.

```bash
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

```bash
pip install brokr
```

Requires Python 3.10+.

## Quickstart

```bash
# 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:

```python
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.

```bash
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.

```bash
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

```bash
# 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

```python
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](LICENSE).
