Documentation

seedfall runs your Go system in a simulated world, breaks it on purpose (crashes, lost messages, half-written files), and lets you replay any failure exactly. These pages are grouped by what you want to do. If you are new, read the first one and stop there for now.

Start here

• Getting started: find, shrink, fix and prove a real bug in about five minutes, using an example that is included.
• Installing seedfall: every way to install it, and how to check the install worked.
• FAQ: short answers, such as how seedfall differs from other tools and what it cannot test.
• Troubleshooting: look up an error message and see how to fix it.

Find a bug

• Networking: let your nodes talk to each other inside the simulation.
• Properties and checks: write the statements your system must keep true, such as "an acknowledged write is never lost".
• Storage engines that need mmap or flock: test databases such as bbolt, pebble and badger.
• Config files, profiles and seeded disks: keep several test setups in one file and start nodes from an existing disk.
• Feedback-guided exploration: hunt for bugs that need two rare events in one run.
• BUGGIFY: mark places in your own code where seedfall may force a rare path.
• Mutation testing your checks: find out whether your checks would notice a real bug.
• Running Antithesis SDK code: run programs that already use the Antithesis Go SDK.
• Use your Gostman collections as workloads: reuse API checks you already wrote.

Understand a failure

• Timelines, logs and time-travel debugging: see a failing run as a diagram, a filtered log or a step-by-step debugger.
• Causality analysis: find which fault actually made a seed fail.
• Inspecting the disk at the moment of failure: see which bytes were saved and which a crash would lose.
• Proving a fix with seedfall verify: show that a fix works, and pin the bug so it cannot come back.
• Triage reports: group many failing seeds into a short list of bugs.

Use in CI

• Running seedfall in CI: the GitHub Action, machine-readable output, time limits and go test.
• Using seedfall from AI coding agents: the MCP server and skills that let an agent run seedfall for you.

Reference

• Configuration and faults: every seedfall.json field and every fault seedfall can inject.
• Properties, linearizability and determinism: the full sim API for checks.
• Triage reports: findings, classification, failure artifacts, notifications and utilization.
• Troubleshooting: the error catalog, keyed by exact message.
• How seedfall works: the simulated clock, the disk and network models, checking, shrinking and speed.
• Testing seedfall itself: what the project's own tests prove.
• Findings: bugs seedfall found in open-source projects, with replay commands.

About the project

• Contributing: development setup, tests and commit style.
• Roadmap: what is planned and what is not done yet.
• Security policy and code of conduct.