Breviv0.28

Start

Quickstart for agents

View as Markdown

Brevi is the verified native runtime for the Python your agent writes. The agent writes plain Python; Brevi compiles it to a native binary, checks the run against CPython 3.13, and says so in one line of JSON whenever it cannot build or cannot check a program. This page is the whole loop, as your harness will drive it.

1. Install#

With [uv](https://docs.astral.sh/uv/) installed, one command installs Brevi and runs a program (step 2 writes `main.py`):
uvx --python 3.13 brevi run --verify main.py

It downloads brevi and CPython 3.13 (the version --verify checks against), and on the first build the Rust release Brevi is tested with, plus zig to link with when the machine has no C linker, each checked against a SHA-256 compiled into brevi. That is about 300 MB once and a minute or two; later builds take seconds. Fetching uses curl and tar (macOS and Windows have both; a bare Linux container needs curl, ca-certificates and xz-utils).

Nothing else is needed on Linux x86-64 and macOS, from v0.28.2. Linux ARM64 and Windows get the same from the next release; until then, install Rust with rustup first (on Windows it also asks for the Microsoft C++ build tools), then run the same command.

The commands below say brevi: write uvx --python 3.13 brevi instead, or keep it on your PATH with uv tool install --python 3.13 brevi. The install script, pip, npm, Docker and the release archives: Install.

--verify compares against CPython 3.13 and no other version. Brevi finds one as python3, python3.13 or python on PATH, through uv (so the CPython uvx --python 3.13 fetched counts), or named by BREVI_PYTHON.

$ brevi --version
brevi 0.28.2

2. The agent writes main.py#

Plain Python, nothing Brevi-specific. Here, a first draft with a typo on the last line:

import sys

def primes_below(n):
    sieve = [True] * n
    sieve[0:2] = [False, False]
    for i in range(2, int(n ** 0.5) + 1):
        if sieve[i]:
            for j in range(i * i, n, i):
                sieve[j] = False
    return [i for i, p in enumerate(sieve) if p]

n = int(sys.stdin.read())
ps = primes_below(n)
total = sum(ps)
print(len(ps), "primes below", n)
print("sum", totl)

3. Check it, read the JSON error#

$ brevi check main.py
{"line":16,"msg":"name 'totl' is not defined","fix":"did you mean total?"}

Brevi checks the whole program before anything runs. A sure mistake comes back as one line, with the line number and a fix; the MCP check and run tools answer with the same line. Feed it back to the model: it is the whole error, with no traceback to read.

If the agent skips the check and goes straight to brevi run --verify, Brevi cannot build the file, so it runs it with CPython and says so first, naming the line that stopped the build; CPython then raises the NameError where it reaches line 16:

$ echo 1000 | brevi run --verify main.py
{"path":"cpython","line":16,"why":"Brevi could not build it: name 'totl' is not defined","by":"python3"}
168 primes below 1000
NameError: name 'totl' is not defined. Did you mean: 'total'? (main.py line 16)

4. Fix the line, verify#

The agent changes line 16 to print("sum", total) and runs again:

$ echo 1000 | brevi run --verify main.py
168 primes below 1000
sum 76127
{"verify":"identical","file":"main.py","sha256":"…","inputs":["sha256:…"],"args":[],"path":"typed","exit":0,"stdout_same":true,"stderr_same":true,"brevi_ms":5,"cpython_ms":13,"speedup":2.6,"brevi":"0.28.2","cpython":"3.13.18"}

The answer is on stdout and the certificate on stderr: the native build and CPython 3.13 gave the same stdout, exit code and stderr on this input. Log it; it carries the hashes of the file and the input.

What --verify does when it cannot certify a run:

Verdict line on stderrMeaningWhat you get
{"verify":"identical",...}Native and CPython agree on this inputThe native answer
{"verify":"differs","on":"stdout","line":N,"brevi":...,"cpython":...,...}They disagree: almost always a Brevi bug (output CPython itself varies, such as a printed set of strings, can differ too; --strict runs CPython twice and reports unstable)CPython's answer and exit code; logged for brevi report
{"verify":"refused","why":"reads the clock",...}Running it twice could change the answer or repeat a side effect (clock, unseeded random, environment, file writes, network)The program's own answer, marked unchecked
{"verify":"timeout",...}CPython had not finished well after the native run, or hit the limitThe native answer, marked unverified
{"verify":"refused","why":"Brevi answers as CPython 3.13 does, so it runs only CPython 3.13, and ...",...}No CPython 3.13 was foundThe program's own answer, marked unchecked
{"path":"cpython",...}Brevi could not build it nativelyCPython ran it; the line says which line and function stopped the build

identical, differs and timeout come after the program's output; refused and {"path":"cpython"} come before it.

So your harness never gets an unchecked answer presented as checked. --verify costs one CPython run per call; on heavy programs, verify on the test inputs and then run with plain brevi run or a built binary (brevi build main.py -o app --release).

5. Wire it into the harness#

What it is, and is not#