# Timeout Configurations and Limits for Theorem Proving Attempts in LeanAgent

> Explore LeanAgent's timeout configurations for theorem proving. Learn about the 600-second default limit, expansion options, and a 1-second buffer to optimize attempts.

- Repository: [LeanDojo/leanagent](https://github.com/lean-dojo/leanagent)
- Tags: how-to-guide
- Published: 2026-03-05

---

**LeanAgent enforces a default 600-second wall-clock timeout per theorem, with optional expansion limits and a 1-second tolerance buffer to prevent premature termination.**

The `lean-dojo/leanagent` repository implements strict runtime controls to balance thoroughness against computational budget. Understanding these timeout configurations and limits for theorem proving attempts is essential for optimizing proof search strategies and resource allocation.

## Core Timeout Settings in LeanAgent

LeanAgent employs a dual-control mechanism that terminates proof searches based on either elapsed time or node expansions.

### Wall-Clock Timeout (`timeout`)

The primary limit is a **wall-clock timeout** measured in seconds. By default, this is set to `600` seconds (10 minutes) in [`leanagent.py`](https://github.com/lean-dojo/leanagent/blob/main/leanagent.py) and [`prover/evaluate.py`](https://github.com/lean-dojo/leanagent/blob/main/prover/evaluate.py).

In [`prover/proof_search.py`](https://github.com/lean-dojo/leanagent/blob/main/prover/proof_search.py), the `BestFirstSearchProver` class stores this value and checks it after every search step:

```python
self.total_time = time.monotonic() - time_start + tolerance
if self.total_time > self.timeout:
    # Search terminates

```

The check occurs at line 175-180, where `self.total_time` is compared against `self.timeout`.

### Expansion Limits (`max_expansions`)

Optionally, you can constrain the search space using **`max_expansions`**, which limits the number of tree node expansions. By default, this is `None` (unlimited).

The termination logic checks both conditions:

```python
if self.total_time > self.timeout or (
    self.max_expansions is not None
    and self.num_expansions > self.max_expansions
):
    # Stop search

```

This allows you to set a hard ceiling on computational effort regardless of time elapsed.

### Tolerance Constants

To prevent premature termination due to floating-point rounding errors, LeanAgent adds a **`tolerance`** of `1` second to the measured time. This fixed constant is defined in [`proof_search.py`](https://github.com/lean-dojo/leanagent/blob/main/proof_search.py) and added to `total_time` before comparison with the timeout limit.

## Where Timeout Configurations Are Defined

The timeout configurations flow through three critical files in the repository:

- **[`prover/proof_search.py`](https://github.com/lean-dojo/leanagent/blob/main/prover/proof_search.py)**: Core implementation of `BestFirstSearchProver` containing the timeout checking logic (lines 175-180) and the `tolerance` constant
- **[`leanagent.py`](https://github.com/lean-dojo/leanagent/blob/main/leanagent.py)**: High-level driver that instantiates `DistributedProver` with the default `timeout=600` (around line 1332)
- **[`prover/evaluate.py`](https://github.com/lean-dojo/leanagent/blob/main/prover/evaluate.py)**: CLI wrapper exposing `--timeout` and `--max_expansions` arguments with defaults of `600` and `None` respectively (around line 172)

The values propagate from the CLI or main driver down through `DistributedProver.__init__` to `BestFirstSearchProver.__init__`, where they are stored as instance variables.

## Configuring Timeouts via Command Line

When running evaluation scripts, you can override the default 600-second limit using the `--timeout` flag:

```bash
python -m prover.evaluate \
    --data_path data/lean4 \
    --timeout 300 \
    --max_expansions 5000

```

This configuration passes the 300-second limit and 5,000 expansion cap to the underlying `BestFirstSearchProver`.

## Programmatic Configuration in Python

For custom integrations, instantiate `DistributedProver` directly with your desired limits:

```python
from prover.proof_search import DistributedProver

prover = DistributedProver(
    use_vllm=False,
    ckpt_path="path/to/checkpoint.ckpt",
    indexed_corpus_path=None,
    tactic=None,
    module=None,
    num_workers=4,
    num_gpus=4,
    timeout=1200,              # 20 minutes

    max_expansions=50_000,     # Stop after 50k expansions

    num_sampled_tactics=64,
    raid_dir="/raid",
    checkpoint_dir="checkpoints",
    debug=False,
)

```

During a search, you can inspect the current limits and progress through the prover's attributes:

```python

# Inside a proof search callback or debug context

print(f"Timeout limit: {prover.timeout}s")
print(f"Max expansions: {prover.max_expansions}")
print(f"Current expansions: {prover.num_expansions}")
print(f"Elapsed time: {prover.total_time}s")

```

## Summary

- **Default timeout**: 600 seconds (10 minutes) defined in [`leanagent.py`](https://github.com/lean-dojo/leanagent/blob/main/leanagent.py) and [`prover/evaluate.py`](https://github.com/lean-dojo/leanagent/blob/main/prover/evaluate.py)
- **Optional expansion limit**: `max_expansions` defaults to `None` but can cap node expansions
- **Tolerance buffer**: 1-second constant in [`proof_search.py`](https://github.com/lean-dojo/leanagent/blob/main/proof_search.py) prevents rounding errors
- **Termination logic**: Located in [`prover/proof_search.py`](https://github.com/lean-dojo/leanagent/blob/main/prover/proof_search.py) lines 175-180, checks both time and expansion limits
- **Configuration**: Pass via CLI (`--timeout`, `--max_expansions`) or programmatically to `DistributedProver`

## Frequently Asked Questions

### What happens when a theorem proving attempt reaches the timeout limit?

When the elapsed wall-clock time exceeds the configured `timeout` value (default 600 seconds), the `BestFirstSearchProver` immediately terminates the search loop and returns the best partial result found so far. The check occurs after every search step in [`prover/proof_search.py`](https://github.com/lean-dojo/leanagent/blob/main/prover/proof_search.py), ensuring responsive termination even during deep searches.

### Can I set different timeout configurations for different theorems?

Yes, since the `timeout` and `max_expansions` parameters are passed per `DistributedProver` instance, you can create separate prover instances with different limits for different theorem batches. However, within a single `DistributedProver` instance, all worker processes share the same timeout configuration, so you would need to instantiate multiple provers to vary limits across individual theorems.

### What is the difference between `timeout` and `max_expansions` in LeanAgent?

The `timeout` parameter limits the **wall-clock time** in seconds, protecting against infinite loops or computationally expensive proof branches regardless of search depth. The `max_expansions` parameter limits the **number of tree nodes expanded**, providing a deterministic ceiling on computational effort independent of hardware speed. Use `timeout` for time-budget constraints and `max_expansions` for reproducible resource limits across different machines.