I Got GitLab and Airbyte Running Locally in Under 30 Minutes, then Built BootProof to Prove It
Every developer knows the weird optimism of cloning a new repo.
You find something useful on GitHub. The project looks active. The README looks clear enough. There is a neat little “Getting Started” section, and for a few seconds you believe this is going to be one of those rare, beautiful moments where the commands just work.
git clone ...
npm install
npm run dev
Then the real project reveals itself.
Your Node version is wrong. Or your pnpm version is wrong. Or Docker is running, but not in the way the project expects. Postgres exists, but the role does not. Redis is missing. A migration fails halfway through. The app starts, but the browser shows nothing. A container is technically “up”, but the service is not healthy. A command exits cleanly, but there is no proof that the application actually booted.
This is the point where the README stops being a guide and becomes more like an archaeological clue.
I hit this problem again and again while trying to run larger open-source projects locally. GitLab. Airbyte. Real projects with real complexity. These are not badly made repos. They are serious pieces of software. But serious software accumulates assumptions: local services, exact versions, database state, orchestration tools, environment variables, ports, health checks, hidden setup steps, and maintainer knowledge that is obvious only after you already know it.
What bothered me was not just that things failed. Developers can handle failure. What bothered me was how unclear the truth was.
Did the app fail because my machine was wrong? Because the docs were out of date? Because I used the wrong command? Because a service was missing? Because a dependency was skipped? Because a process started but the app never actually became usable?
And the worst version of that problem is when a tool, or an AI agent, confidently tells you it worked.
Because “a command ran” is not the same as “the app booted”.
That gap is what made me build BootProof.
GitHub: https://github.com/bootproof/bootproof
BootProof is a CLI for one painfully simple question:
Can this repo be proven to boot?
Not guessed. Not assumed. Not “probably running”. Proven.
The idea came out of the GitLab and Airbyte tests because they exposed the real problem so clearly. Getting a big repo running locally is not just about finding the right command. It is about building a chain of evidence. What does the repo declare? What does the environment actually have? What did we run? What failed? What responded? What can we safely say happened?
With Airbyte, for example, the answer was not a simple package install and dev command. It involved a more specific local orchestration path with abctl, Kind, Helm, Temporal, containers, and actual service health. With GitLab, the local setup exposed a different kind of complexity: system dependencies, database expectations, build steps, service assumptions, and all the little pieces of hidden knowledge that usually live in someone’s head.
Those experiences made one thing obvious to me: a fake green check is worse than a failure.
A failure tells you there is still work to do. A fake success wastes your time, corrupts your confidence, and sends you in the wrong direction. That is even more dangerous now that AI agents are starting to clone repos, install dependencies, run apps, make changes, and tell us things are done.
Done according to what?
Did the app actually respond? Did it pass a health check? Did the tool skip the install? Did it invent a missing .env value? Did it silently assume a port? Did it mistake a long-running process for a working application?
BootProof is my attempt to put a hard boundary around that moment.
The rule is simple:
No proof, no green check.
BootProof inspects a repository, builds a run plan from the evidence it can see, runs only what it can justify, checks for real HTTP health, and writes an attestation of what actually happened.
A good result should not just be:
command completed
It should be something closer to:
BOOTED
Observed HTTP 200
Evidence written to .bootproof/attestation.json
And when BootProof cannot prove the repo booted, it should say so clearly:
NOT VERIFIED - package_manager_version_mismatch
or:
NOT VERIFIED - remote_code_execution_blocked
or:
NOT VERIFIED - orchestration_not_supported
That might sound less exciting than a tool that claims to run everything, but I think it is much more useful. BootProof is designed to be useful even when it refuses. Especially when it refuses. A clear refusal with evidence is a better developer experience than another vague terminal failure or a confident lie.
That is the part I think a lot of developers will recognise.
The pain is not just that repos fail to run. The pain is that the failure has no shape. You are left staring at logs trying to work out whether you are one command away from success or three hours deep in the wrong setup path. You do not know whether to fix your machine, change the command, read more docs, open an issue, or give up.
BootProof tries to make that failure legible.
It is not magic. It is not finished. It is not claiming to run every repo on GitHub. It is not a replacement for good documentation, Docker, CI, or maintainers who know their projects inside out. I see it more as a truth layer for repo onboarding.
The workflow I want is:
inspect
plan
run
observe
attest
If it boots, prove it. If it does not, explain why.
You can run it against a local repo like this:
bootproof up .
For CI-style output:
bootproof up . --ci --json
For local execution with explicit consent:
bootproof up . --provider local --unsafe-local --install
The output is intended to be useful to humans, but also structured enough for machines. That matters because I think AI coding agents need something like this. If an agent says “the repo runs”, I do not want vibes. I want a receipt.
I want to know what it inferred, what it ran, what it refused, what responded, and where the evidence is.
That is the bigger idea behind BootProof. It is not just a local run helper. It is a way of making repo bootstrapping auditable. Not in a heavy enterprise way. In a practical developer way. The kind of thing you wish you had when you are 40 minutes into a broken setup and can no longer tell whether you are making progress or just generating new errors.
I am posting this because I want BootProof tested on real repos, not just clean examples.
Try it on the repo that annoyed you last month. Try it on the project you starred but never managed to run. Try it on the monorepo where the README is nearly right but not quite. Try it on the app that starts a process but never opens in the browser. Try it on the thing you gave up on because you could not tell what was missing.
The repo is here:
https://github.com/bootproof/bootproof
Clone it:
git clone https://github.com/bootproof/bootproof.git
cd bootproof
npm install
npm run build
npm test
Then point it at something painful:
bootproof up /path/to/that/repo
If it boots, I want to know.
If it refuses correctly, I want to know.
If it gets confused, I really want to know, because that is where the next detector should be built.
Drop a repo in the comments that has been painful to run locally, and I will try to run it through BootProof.
Because repo onboarding should not depend on hope, terminal archaeology, or fake green checks.
It should have proof.
Proof, not vibes.