Report a bug
A good report is one we can act on the day it arrives. FoundryOS makes that easy: the OS gathers its own evidence — you describe what you saw.
Security vulnerability? Don't file it here — email [email protected] privately.
Three steps
Capture the build identity
Every report needs the exact image it happened on — the commit is stamped into the system at build time.
cat /usr/lib/foundryos/build-infoLet the OS gather the evidence
One command produces a redacted diagnostic bundle: change journal, boot health, ranked findings — with hostnames, IPs, serials, and tokens already stripped. Nothing is sent anywhere; you attach it yourself.
foundryos-diagnose --format text
foundryos-bundle --tier 1 --output foundryos-bundle.jsonWrite it up and send it
Summary, reproduction steps, expected vs. actual, the bundle attached. Email it — subject line “[bug] one-line summary”.
[email protected]What makes a report actionable: the build commit, numbered reproduction steps from a fresh boot, expected vs. actual behavior with verbatim output, and the bundle. If it involves an update or a boot problem, say whether Snapshots/self-heal recovered you — that's diagnostic signal, not just a happy ending.
AI-assisted reports: yes, please
FoundryOS is built and released through AI-driven pipelines, and we're glad to receive reports the same way. AI-written reports are welcome and first-class — what we care about is that the evidence in them is real.
So we publish a report contract: a plain-text context statement your agent reads before formatting your report. It tells the agent exactly what evidence to gather, the section order our triage expects, what it must never fabricate, and the attestation you — the human — sign off on before sending.
Use it with any capable agent
Paste this into your AI assistant along with your description of the problem:
Read https://foundrylinux.com/bug-report-context.txt and follow it exactly
to prepare my FoundryOS bug report. Here is what happened: …Why a contract, not a form
Your agent does the structuring work at your side, against a published spec — so what arrives here is already in the shape our triage runs on. Use the strongest model you have access to; the contract is the quality bar either way, and a hand-written report that satisfies it is just as welcome.
The attestation is the point
The failure mode of AI reports isn't formatting — it's confident fabrication. The contract requires the human to confirm every command was actually run and no output was reconstructed. Reports without a completed attestation are treated as unverified.
The contract is versioned (currently v1). When triage tooling changes, the file changes — your agent always fetches the current requirements from the canonical URL.
What happens to your report
Reports are triaged against the contract, reproduced where possible in the same VM pipeline that gates releases, and fixes land behind those same gates — a release that fails the install gate cannot ship, including one that "fixes" your bug. There's no public tracker yet; the source repository and issue tracker open publicly alongside the 1.0 release, and this page will link them.