Run on your own fork
// GUIDE · YOUR OWN FORK
Run Vivarium on your own fork.
Fork this repo, add your own bug reproductions, and publish them to your own GitHub Pages site. Without ever opening a PR upstream, you can curate a recipe collection of your own and share the URL.
// 0 · WHAT THIS GETS YOU
Your bugs at <user>.github.io/vivarium/.
In this flow you fork aletheia-works/vivarium, add and edit
reproduction recipes on your own copy, and publish your fork as your own
GitHub Pages site. You're not contributing upstream —
your fork itself is the destination.
Layer 1 (in-browser WASM) works end-to-end on your fork. Layer 2 / 3 (Docker, record-replay) ride on upstream's GHCR images and stay upstream-only; on a fork, only Layer 1 is deployed.
The intended use case is a personal collection of reproductions, not a mirror of upstream. To share, hand out
https://<you>.github.io/vivarium/.
// 1 · FORK THE REPO
One click in the GitHub UI.
Hit Fork on
aletheia-works/vivarium
to copy it under your account or org. The repository name can stay as
vivarium or be renamed (in which case substitute your name
for vivarium below).
Then clone it locally:
git clone https://github.com/<you>/vivarium.git
cd vivarium// 2 · INSTALL THE TOOLCHAIN
mise wires it all up.
The project pins tool versions through mise. From the clone root:
mise installThat installs bun (docs and the MCP server),
opentofu (Infrastructure-as-Code for the GitHub repo
settings), uv (native Python re-verification), and the
Layer 1 native interpreters. A Rust toolchain (rustup) is
also needed if you plan to add Rust recipes.
// 3 · ISSUE A FINE-GRAINED PAT
The token OpenTofu uses to read/write your fork's settings.
Create a token at
Settings → Developer settings → Personal access tokens → Fine-grained
scoped to your fork.
- Resource owner: your account or org.
- Repository access: just the forked repo.
- Repository permissions: Administration (RW), Contents (RW), Metadata (R), Issues (RW), Pull requests (RW), Actions (RW), Workflows (RW), Variables (RW), Webhooks (RW).
Never commit token values.
terraform.tfvarsis in the repo's.gitignorefor the same reason.
// 4 · APPLY THE OPENTOFU CONFIG
Labels, Pages, branch protection in one go.
cp infra/github/terraform.tfvars.example infra/github/terraform.tfvars and set github_owner = "<you>". Leave create_phase_milestones at its default of false — phase milestones are upstream-only context and forks skip them.
export GITHUB_TOKEN=github_pat_xxxxxxxx. Disappears when the shell exits.
cd infra/github && tofu init && tofu plan, then tofu apply once the diff looks right. Pages, labels, and branch protection roll out on your fork.
// 5 · ENABLE PAGES DEPLOY
One repository variable.
The deploy-docs.yml workflow ships
off by default on forks — its if guard
blocks the build for any owner other than upstream. To opt in on your
own fork, add a single repository variable.
Pick the "Variables" tab (not "Secrets").
Name: VIVARIUM_FORK_DEPLOY, value: true.
The deploy fires on the next push to main, or from Actions → Deploy docs to GitHub Pages → Run workflow.
Removing the variable later turns the deploy back off. Layer 2 (Docker / GHCR) cannot push from a fork's token, so fork deploys automatically ship Layer 1 only.
// 6 · ADD A RECIPE
One directory under src/layer1_wasm/<slug>/.
The minimum unit of a Layer 1 recipe is one directory per upstream bug:
src/layer1_wasm/<slug>/index.html— the recipe page skeleton.src/layer1_wasm/<slug>/repro.ts— runs the reproduction in Pyodide / Ruby.wasm / php-wasm / Rust and sets the verdict.src/layer1_wasm/<slug>/README.md— what the recipe is.
The fastest path is to copy an existing recipe like
pandas-56679
or
regex-779,
change the slug (<project>-<issue> is the convention),
and rewrite the reproduction script.
The contract a recipe satisfies is Contract v1. Emit
<meta name="vivarium-contract" content="v1">and a#verdictelement withdata-verdict="reproduced|unreproduced|pending"and you're conformant.
// 7 · PUSH AND VERIFY
Open your Pages URL.
Push the recipe to main; with
VIVARIUM_FORK_DEPLOY=true set, the deploy-docs
workflow runs. Once green, the site is at:
https://<you>.github.io/vivarium/Individual recipes land at
/repro/<project>/<issue>/. The URLs in
recipes.json are built from
GITHUB_REPOSITORY_OWNER and GITHUB_REPOSITORY
at deploy time, so a fork lands the right URLs without editing source.
// 8 · SHARE
Hand out the URL.
Drop your fork URL
(https://<you>.github.io/vivarium/) in an issue, PR,
or chat — whoever opens it can confirm the reproduction in their browser.
Because every recipe satisfies Contract v1, third-party tooling, including
AI agents, can read the verdict mechanically.
If you later want to upstream a recipe you built here, the directory you created on the fork can be PR'd as-is into
aletheia-works/vivarium. The contract is the same; verdicts captured on the fork carry over.