# 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.

*One built Mathlib per version, shared by every project, run and trial. Dashed arrows are read-only links.*

```mermaid
flowchart TD
  subgraph builds["One build per Mathlib version, about 7 GB each"]
    found[("Your built checkouts")]
    installed[("/lean install<br/>prebuilt cache")]
  end
  found --> p1["Project A<br/>uses v4.28"]
  installed --> p2["Project B<br/>uses v4.33"]
  found -- "clone once" --> env[("Pinned environment<br/>copy-on-write clone<br/>almost no extra space")]
  env -.-> t1["Trial 1"]
  env -.-> t2["Trial 2"]
  env -.-> tn["Trial n"]
  t1 --> ck[("Verified checkpoints<br/>small .lean files")]
  t2 --> ck
  tn --> ck
```

## One 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 install` makes a shallow clone of a Mathlib release into `~/.theoria-cli/lean/mathlib/<version>` and runs `lake 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 config`](https://www.theoria.sh/docs/commands.md#lean) records 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 (a `lean-toolchain` and a lakefile) keeps its own toolchain and dependencies.
- **Removed when no longer needed.** `/lean remove` deletes a Mathlib that Theoria installed; checkouts you built yourself are never deleted.

```text
/lean status     # the Lean and Mathlib this project uses
/lean install    # add a Mathlib version (about 7 GB)
/lean remove     # delete one Theoria installed
```

## Shared, not copied, in long runs

- **Pinned environments are copy-on-write clones.** A [benchmark](https://www.theoria.sh/docs/commands.md#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](https://www.theoria.sh/docs/autoresearch.md) 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`](https://www.theoria.sh/docs/commands.md#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.

> Copy-on-write clones need APFS, so benchmark environments and Lean add-ons are macOS-only for now. `/lean`, `lean_check` and the proof workflows use your Mathlib directly and work on Linux too.

## Related

- [Quickstart](https://www.theoria.sh/docs/quickstart.md): Install Theoria-CLI, set up Lean and Mathlib, and prove a first theorem.
- [Slash commands](https://www.theoria.sh/docs/commands.md): Every Theoria-CLI slash command, with its forms and examples.
- [Autoresearch](https://www.theoria.sh/docs/autoresearch.md): Unattended, bounded research campaigns: the agent runs experiments, reads the evidence and improves a result.

Last updated 2026-11-10. Web page: https://www.theoria.sh/docs/lean-environments