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):

brew install infisical/get-cli/infisical

Other platforms / manual install:

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

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

---

2. Log in to the self-hosted instance

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:

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:

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

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

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

Pick the breakpilot-compliance project from the picker.

---

4. Launch the stack

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:

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:

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):

{
  "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:

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

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