Blackfyre is open source and free to self-host forever. Every guide here links straight into the repository — from a ~15-minute local stack to production on your own AWS, plus the architecture decisions and policies behind it. Nothing is behind a login.
What's documented
22
Guides
4
ADRs
2
Deploy tiers
Free
Apache-2.0
Stand up the full stack locally with no cloud account or API keys, then graduate to production on your own AWS when you're ready.
Verified ~15-minute local setup (Docker Compose Postgres/Redis/LocalStack + API/portal/admin via npm), seeded dev logins, worker pollers, reset flow, and real troubleshooting. No cloud account or API keys needed.
The two deployment tiers side by side: local/evaluation via Docker Compose (free) vs production on your AWS account via SST (what gets provisioned, secret setup, deploy + migrate steps, stage semantics, and rough monthly costs).
Every environment variable and the 11 SST secrets: what each is for, whether it's required/optional, safe ways to generate local values, and which features gracefully no-op when a secret is left blank.
# Full local stack — no cloud account or API keys needed.
git clone https://github.com/blackfyre-security/blackfyre.git
cd blackfyre/platform
docker compose up -d postgres redis localstack
npm install && npm run build
cp packages/api/.env.example packages/api/.env # edit per the local-dev guide
npm run db:migrate && npm run dev # API on :4000
# Then in two more terminals:
NEXT_PUBLIC_API_URL=http://localhost:4000 npm run dev --workspace=packages/portal # :3001
NEXT_PUBLIC_API_URL=http://localhost:4000 npm run dev --workspace=packages/admin # :3003
# Log in at http://localhost:3001 — seeded dev user admin@acme.com / password123Full walkthrough, troubleshooting, and reset flow → Local development guide ↗
How the packages fit together, how the Fastify API is composed, how migrations and tests run, how code ships, and where the AI provider routing lives.
Every package explained — api, portal, admin, shared, ui, cli, plus platform/infra (SST) and the standalone website — with key files, what each owns, and the strict dependency direction.
How packages/api is composed (Fastify app order, DB handles, plugins, routes), the three-layer auth model (JWT/API-key + CSRF + request-scoped RLS binding), where Zod contracts live, and the recipe for adding an endpoint.
How the plain-SQL migrations run (filename-tracked, idempotent), the app.env-guarded dev-only seeds, numbering/ordering rules, RDS managed-Postgres gotchas (no superuser), and the required RLS-in-migration pattern for tenant tables.
The Vitest unit suite CI runs on every PR (offline, fully mocked) vs the integration suite that needs the Docker services (with the DATABASE_URL gotcha), plus the opt-in Playwright browser and staging-smoke suites, and where a new test belongs.
How code reaches each environment for a self-hoster: the CI/CD pipeline shape (preferred) and manual laptop deploys (fallback) to your own AWS + Cloudflare accounts.
Where the API talks to a Claude model and how it chooses between the Anthropic direct API and AWS Bedrock, driven by whether ANTHROPIC_API_KEY is set.
The deployment topology plus the four architecture decision records — tenant isolation, the queue design, scanner orchestration, and AI model routing — written down and defensible.
Single-page deployment topology: three sized-alike stacks (demo/staging/prod), static frontends on Cloudflare Pages, backend on AWS Lambda + RDS + SQS + S3 via SST, why the shape, and the key infra invariants (e.g. frontends stay static exports).
Why tenant isolation is enforced by the database below the ORM: a non-owner app_user role, FORCE ROW LEVEL SECURITY, and a request-scoped connection binding that fails closed — plus the two earlier inert attempts it replaced.
Why background work runs on four SQS queues (scan/monitor/AI/evidence), each with a dead-letter queue and SQS-triggered Lambda workers, the no-secrets-on-a-queue rule, and the at-least-once idempotency requirement.
Why lightweight SDK auditors run in-process in the scan worker while heavy OSS tools (Prowler, Checkov/Semgrep/Bandit) run as container-image Lambdas, and how both normalize through one findings ingest path — the seed of the future scanner plugin API.
The cost-driven tiering of AI work (deterministic heuristics / fast small model / frontier model), the fail-down-never-up rule so features degrade to heuristics without a key, and the provider-agnostic client — with an honest status note that tier 2 isn't wired yet.
Roadmap, how to contribute, governance, the security and data-collection policies, the code of conduct, trademark terms, and the license — the social contract of the repo.
What each scanner agent collects and, explicitly, what it never touches — minimum data for posture assessment, no PII, customer records, or business content. Useful for a trust/privacy page.
Near/mid/long-term direction (contributor experience, community releases, scanner coverage, a scanner plugin API, more frameworks as data, non-AWS deployment) and how to propose work via an issue.
The fork-and-PR flow, mandatory DCO sign-off, Conventional Commits style, the pre-PR build + unit-test gate, and what CI checks — the source for a /contribute page.
The current BDFL model, how decisions are made, and the path from contributor to committer.
Private vulnerability disclosure process, response SLAs, in-scope vs out-of-scope, security practices, and compliance posture.
Contributor Covenant v2.1 covering all project spaces, with the enforcement contact and escalation ladder.
What the Apache-2.0 license does and does not grant: code is free to use/modify/redistribute, but the Blackfyre name and logo are trademarks and forks must rename.
The full Apache License 2.0 text governing the source code (see NOTICE for attribution).
Every card on this page opens a file in the source tree. The complete, always-current docs live in the repository — versioned alongside the code they describe, never stale. Clone it, audit it, self-host it for free.
Guides, ADRs, and policies sit next to the code in a public, Apache-2.0 tree — the source of truth this page mirrors.
Browse /docs