breakpilot-compliance/INFISICAL_SETUP.md

# Infisical Setup for Local Development

This is the per-developer onboarding for accessing the `breakpilot-compliance` secrets while developing locally. Once this is done, **everything you launch through `make dev` (or `infisical run …`) gets the dev secrets injected as environment variables** — including any Claude Code session that spawns those commands.

Secrets live in the self-hosted Infisical instance at **`secrets.meghsakha.com`**. The project link is committed in `.infisical.json`, so you don't need to know the project ID.

---

## 1. Install the Infisical CLI

**macOS (recommended):**

```bash
brew install infisical/get-cli/infisical
```

**Other platforms / manual install:**

See <https://infisical.com/docs/cli/overview>. Verify with:

```bash
infisical --version
# infisical version 0.43.x (or newer)
```

---

## 2. Log in to the self-hosted instance

```bash
infisical login --domain https://secrets.meghsakha.com
```

This opens a browser for SSO. The login is persisted to your OS keychain — you only do this once per machine.

Sanity check:

```bash
cd ~/projects/breakpilot-compliance   # wherever you cloned the repo
infisical --domain https://secrets.meghsakha.com secrets --env=dev
```

You should see a table of secret names + values. If you get an auth error, re-run `infisical login`.

---

## 3. Verify the project link

The repo already contains `.infisical.json` pointing at the `breakpilot-compliance` project:

```bash
cat .infisical.json
# { "workspaceId": "996bda36-9e01-4071-ae8d-69a9f9ff5a23", ... }
```

If the file is missing (rare — only if you reset the repo), recreate it:

```bash
infisical init --domain https://secrets.meghsakha.com
```

Pick the `breakpilot-compliance` project from the picker.

---

## 4. Launch the stack

```bash
make dev
```

This runs `infisical run --env=dev -- docker compose up`. Every service in the compose stack sees its secrets as normal env vars — no `.env` file ever touches disk.

Other targets:

| Target | What it does |
|--------|--------------|
| `make dev-build` | Same as `make dev` but rebuilds images first |
| `make dev-down` | Stop the stack (no secrets needed) |
| `make dev-logs` | Tail logs |
| `make dev-ps` | List running containers |
| `make secrets` | Print all secrets in `dev` (read-only) |
| `make secrets-set KEY=FOO VALUE=bar` | Add or update a secret in `dev` |

To target a different environment:

```bash
make dev ENV=staging
make secrets ENV=prod
```

---

## 5. Using secrets from Claude Code

When Claude Code runs commands in this repo via its Bash tool, the commands inherit your shell's environment. Two patterns:

**Pattern A — let Claude launch the stack normally**

Claude just runs `make dev`. The Infisical CLI inside that command resolves secrets at run time and passes them to docker compose. Claude doesn't see plaintext secrets in its context, but the running services do.

**Pattern B — let Claude run a one-off script with secrets**

If Claude needs to execute a Python/Go script that requires secrets, wrap the command:

```bash
infisical run --env=dev -- python scripts/some_one_off.py
```

This works for any subprocess: pytest, alembic, go run, npm scripts. If Claude proposes a command that reads env vars and runs raw, ask it to wrap it in `infisical run --env=dev --` first.

**What Claude should not do:**

- `infisical export --env=dev > .env` — defeats the whole point and the `.gitignore` will still try to keep the file out.
- `infisical secrets get KEY --env=dev --raw` and pasting the value into a code edit — secrets must stay out of the repo.

If you want Claude to never accidentally dump secrets, add this to your `.claude/settings.json` permissions (project-level or user-level):

```json
{
  "permissions": {
    "deny": [
      "Bash(infisical export*)",
      "Bash(infisical secrets get*)"
    ]
  }
}
```

---

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| `please either run infisical init or pass --projectId` | `.infisical.json` is missing or unreadable — re-run `infisical init` |
| `unauthorized` / `please log in` | Re-run `infisical login --domain https://secrets.meghsakha.com` |
| `make dev` says secret is empty | Check the name in `make secrets` matches what docker-compose expects, then update the service config or rename the secret in Infisical |
| Browser SSO doesn't open | Use `infisical login --domain https://secrets.meghsakha.com --method=user` and paste the URL manually |

---

## What the dev env contains

Run `make secrets` to see the live list. As of this writing the dev env includes (at minimum):

- `BREAKPILOT_DB_PASSWORD`
- `BREAKPILOT_QDRANT_API_KEY`
- `LITELLM_API_KEY`

Every other variable in `.env.example` either has a sane default in `docker-compose.yml` or needs to be added to Infisical. To add one:

```bash
make secrets-set KEY=ANTHROPIC_API_KEY VALUE=sk-ant-xxxx
```

Or via the web UI: <https://secrets.meghsakha.com>.