REFERENCE
Lean environments
How Theoria finds, installs and shares Lean and Mathlib, and keeps long Lean runs light on disk.
A built Mathlib takes about 7 GB, and a long research or benchmark run may need several versions at once. Theoria keeps one built copy per Mathlib version and has every project, run and trial share it, instead of giving each its own.
flowchart TD
subgraph builds["One build per Mathlib version, about 7 GB each"]
found[("Your built checkouts")]
installed[("/lean install
prebuilt cache")]
end
found --> p1["Project A
uses v4.28"]
installed --> p2["Project B
uses v4.33"]
found -- "clone once" --> env[("Pinned environment
copy-on-write clone
almost no extra space")]
env -.-> t1["Trial 1"]
env -.-> t2["Trial 2"]
env -.-> tn["Trial n"]
t1 --> ck[("Verified checkpoints
small .lean files")]
t2 --> ck
tn --> ckOne build per Mathlib version#
- Found, not duplicated. Theoria uses the Lean toolchains elan has installed and the built Mathlib checkouts it finds up to three folders below your home directory (
lean.discovery.homeScanDepth), keeping one per version. A checkout you built yourself is used as it is. - Installed from the cache.
/lean installmakes a shallow clone of a Mathlib release into~/.theoria-cli/lean/mathlib/<version>and runslake exe cache get, which downloads Mathlib's prebuilt files instead of compiling them. A quick check then compiles only what the cache missed, normally nothing. - Chosen per project.
/lean configrecords the version in the project's.theoria/lean.json, with a global default for the rest. A folder that is a Lean project of its own (alean-toolchainand a lakefile) keeps its own toolchain and dependencies. - Removed when no longer needed.
/lean removedeletes a Mathlib that Theoria installed; checkouts you built yourself are never deleted.
/lean status # the Lean and Mathlib this project uses
/lean install # add a Mathlib version (about 7 GB)
/lean remove # delete one Theoria installedShared, not copied, in long runs#
- Pinned environments are copy-on-write clones. A benchmark pins an exact Mathlib commit. Theoria prepares that environment once as an APFS copy-on-write clone of the matching built checkout. The clone shares every file with the original until one changes, so it costs almost no extra space, and Lake can write its own caches there without touching your checkout. Every later run, trial and autoresearch campaign on that commit reuses it.
- Each trial is a small project. A trial or compression attempt gets its own Lake project holding only its proof files; Mathlib and its dependencies are linked in read-only, not copied. Parallel trials therefore add kilobytes, not gigabytes, and none of them can modify the shared build.
- Add-ons reuse the build too. LeanHammer (
/lean extras install hammer) is built in a copy-on-write clone of the matching Mathlib, so only Hammer's own dependencies take extra space.
Temporary files are cleaned up#
Each Lean and Lake command gets a fresh temporary folder, removed when it exits, whether it succeeded, failed, timed out or was cancelled; parallel checks never share one. When a benchmark run completes or is cancelled, Theoria also removes the Lake metadata its workers left behind. Proofs, logs, transcripts and results are kept.
Verified checkpoints#
Long workflows keep their progress as small Lean files rather than environments. /compress and compression benchmarks record each round's best proof that Lean verified as a checkpoint; the next round starts from it, and a run that hits its time, turn or cost limit keeps that last verified checkpoint. A restored checkpoint is checked by Lean again before it is used.
/lean, lean_check and the proof workflows use your Mathlib directly and work on Linux too.